Difference between revisions of "CGI"
m (Undo revision 2070 by A2 (talk) doc for v6/7 so it's allright to keep it here, we'll write CGI doc for v7!)
|Line 13:||Line 13:|
'''Directories and files'''
'''Directories and files'''
[[File:.jpg|thumb|right|Files and directories on 1&1.]]
Revision as of 00:19, 27 April 2016
|Language:||English • français|
- 1 1&1 hosting, GeneWeb 5 and 6
- 2 Windows
- 3 An alternative installation on 1&1
- 4 Script to upload a copy of a base
- 5 Debugging your remote server
When daemon mode of GeneWeb is forbidden or cannot be activated, you must use CGI mode. It's mostly the case on a shared hosting account.
When running in CGI mode, GeneWeb sits behind a general purpose HTTP server such as Apache, and is launched by the server as a CGI command. As such, the first step in installing GeneWeb consists in verifying the operation of the HTTP server and of its CGI calling function.
The OS version is generally a stable version, but not the latest version. You must fit in the server environment : OS version, libraries, installed packages. Download the goode a GeneWeb package.
1&1 hosting, GeneWeb 5 and 6
The following applies to 1&1 hosting, and may differ on other hostings. On this web site, we can easily switch between two versions of GeneWeb: 5.00 and 6.00.
Directories and files
- mybases: The bases directory, beside the CGI-root directory.
- root: The CGI-root directory.
- basesxg: An alternative bases directory.
- css: A copy of the gw/css directory. This directory is used by the Apache server.
- gw: The gw directory of the GeneWeb distribution.
- gwenv: The gw directory of the Geneweb-5 distribution.
- igw: The images directory for Geneweb-5.
- images: A directory with copies of
- pub: A directory where are readable copies of the CGI scripts (this website is a demo site).
- gw6.cgi: The CGI script which launches GenWeb-6.
- gw5.cgi: The CGI script which launches GenWeb-5.
- issue6.cgi: A test script which displays information about the environment of the server and checks size and md5sum for the gwd binary file.
- issue5.cgi: The same script, but for the GeneWeb-5 version
You need the “exec” permission on the files
gw/gwsetup, and files used by gwsetup (gw/gwc*, gw/gwu,gw/consang, gw/update_nldb). The
gwd.arg file is empty.
The databases folder
bases must be protected either by a .htaccess file, either by a location out of the HTTP server scope. It does not need to be accessible by the HTTP server.
Description of the CGI script
PWD=$(pwd) LNG="fr" GENEWEBSHARE=$PWD/gw GENEWEBDOC=$PWD/gw/doc GENEWEBDB=$PWD/../bases DAEMON=$GENEWEBSHARE/gwd LOGFILE=$GENEWEBDB/gw.log
The CGI working directory. The language for the user interface. The programs folder. The documentation folder (obsolete). The databases folder. The program gwd itself. Gwd log file, it helps to solve problems.
Note that although called DAEMON, gwd does not run in
-daemon mode but in
Be carefull when using a log file, its size can increase quickly, don’t forget to delete it from time to time.
OPTIONS="-blang -robot_xcl 40,70 -max_clients 15 -conn_tmout 120 -min_disp_req 30 -images_url http://myserver.net/gw/images" # -allowed_tags $GENEWEBDB/tags.txt cd $GENEWEBSHARE $DAEMON -hd$GENEWEBSHARE -dd$GENEWEBDOC -bd$GENEWEBDB -lang$LNG -log$LOGFILE -cgi $OPTIONS 2>/dev/null
- robot_xcl: To protect your data from HTTrack or WebSite Extractor.
- conn_tmout: For statistics on the bottom line.
- images_url: Icons and images are not sent by GeneWeb, but by your HTTP server (not CGI).
- allowed_tags: Usefull option if you use HTML tags not in default_good_tag_list.
Under Windows calling a CGI script using batch and cmd.exe can be tricky. An alternative is to directly call a copy of
gwd.exe with its arguments file
gwd.arg in Apache /cgi-bin/ directory file.
Gwd will work behind Apache calling http://localhost/cgi-bin/gwd.exe.
gwd.arg to point your local GeneWeb installation, for example if it is
C:\Program Files (x86)\geneweb\:
-hd C:\Program Files (x86)\geneweb\gw -bd C:\Program Files (x86)\geneweb\bases -log C:\Program Files (x86)\geneweb\geneweb.log -images_dir C:\Program Files (x86)\geneweb\gw\images -cgi
Problems to solve: - Portrait (all images with m=IMH) are not shown or are corrupted (#103). - Minor problems in 7.00 with loading of new .css/.js files, specialy for templm (#356).
-images_dir parameter create links to local image files like
file:///c:\path\to\myimage.jpg that are not shown for security reason under some browser (like Chrome for ex.). An alternative to previous configuration is to switch to
-images_url parameter so that gwd uses relatives paths for images and to create a virtual directory in your httpd server.
In gwd.arg, modify:
If you use Apache, edit httpd.conf to have those lines, then restart httpd.exe:
LoadModule access_compat_module modules/mod_access_compat.so LoadModule alias_module modules/mod_alias.so Alias /images " C:\Program Files (x86)\geneweb\gw\images" <Directory " C:\Program Files (x86)\geneweb\gw\images"> Options None AllowOverride All Order allow,deny Allow from all </Directory>
An alternative installation on 1&1
Installing GeneWeb on a remote shared server is a little bit (but not that much) more complex than on a personal computer. GeneWeb is a totally self-contained package, therefore does not depend on additional libraires. On a server, GeneWeb cannot execute in daemon mode (Unix aficionados will understand), and must be launched in CGI mode. To that extent, a server based installation requires prior installation of a (standard) HTTP server (typically Apache), access to the CGI repository of this server and some control over the access rights to the various folders and files. Installing or verifying your HTTP server is not part of this discussion.
A second restriction of GeneWeb on a server is that gwsetup cannot be used (mainly for security reasons). It is therefore necessary to use command lines on the remote server through a
ssh window or any other remote access tool of your choice.
It is also necessary to have access to an upload mechanism from your personal machine to the server through classical Unix/Linux command lines, or through a
ftp client such as Filezilla. A section below will describe in detail a shell script performing upload to the server of a complete fresh copy of a base sitting on your personal computer.
Folders and files
The first important file for your installation is the welcome page of your HTTP server, by default
index.html sitting at the root of your server. After personalization of this welcome page, you should verify that you can view it by typing the name (or IP address) of your server in the URL window of your browser.
The second important item is the CGI folder containing the executable files invoqued through URLs.
This folder is typically called
cgi-bin and also sits at the root of your HTTP server.
Another possibility (it all depends on your hosting service) is that your CGI files must have extension
.cgi, in which case, replace
.cgi in the example below.
cgi-bin contains an executable file named
test-cgi.sh as shown below:
(uiserver):u723:~ > cd cgi-bin (uiserver):u723:~/cgi-bin > cat test-cgi.sh #!/bin/sh echo 'Content-type: text/html' echo echo '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" ' echo ' "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> ' echo '<html xmlns="http://www.w3.org/1999/xhtml"> ' echo '<body>' echo 'This is a test for cgi commands' echo '</body>' echo '</html>' (uiserver):u723:~/cgi-bin > chmod 755 test-cgi.sh # turn this file into executable (uiserver):u723:~/cgi-bin >./test-cgi.sh Content-type: text/html <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <body> This is a test for cgi commands </body> </html> (uiserver):u723:~/cgi-bin >
then typing in the URL window of your browser the following text
should result in the text This is a test for cgi commands appearing in your browser window (provided you have done
chmod 755 test-cgi.sh on the remote server as shown above).
You must reach this level of functionality to proceed.
At the root of your server, create two additional folders
- The first folder will contain all GeneWeb related files (binaries, bases, images, ...) and need not or should not be accessible with the HTTP server,
- The second folder will contain any other documents that you may want to share with the visitors of your site.
At this time, we have the following situation:
(uiserver):u723:~ > cd (uiserver):u723:~ > ls -al total 554088 drwx---r-t 23 u723 ftpusers 4096 Oct 7 06:58 . drwxr-xr-t 7 root root 4096 Oct 23 00:21 .. -rw------- 1 u723 ftpusers 8319 Oct 10 09:30 .bash_history drwxr-xr-x 3 u723 ftpusers 4096 Sep 24 21:24 Documents drwxr-xr-x 10 u723 ftpusers 4096 Sep 24 21:24 GeneWeb drwxr-xr-x 3 u723 ftpusers 4096 Oct 7 06:58 cgi-bin -rw-r--r-- 1 u723 ftpusers 3535 May 22 14:30 index.html -rw-r--r-- 1 u723 ftpusers 27 Nov 6 2013 robots.txt (uiserver):u723:~ >
The GeneWeb folder
The GeneWeb folder contains one or more versions of GeneWeb (
geneweb-7.00 in our example), and the
geneweb-x.yy folder has the same structure, containing a copy of the
distribution folder resulting from the compilation of GeneWeb. You can upload with
ftp this folder, or you can compile yourself GeneWeb directly on your server, but this necessitates the installation of Ocaml and camlp5 (see Ocaml).
(uiserver):u723:~/GeneWeb > cd geneweb-6.08 (uiserver):u723:~/GeneWeb/geneweb-6.08 > ls -al total 204 drwx---r-x 3 u723 ftpusers 82 Jan 12 2015 . drwxr-xr-x 10 u723 ftpusers 4096 Sep 24 21:24 .. -rw----r-- 1 u723 ftpusers 160302 Jan 12 2015 CHANGES.txt -rw----r-- 1 u723 ftpusers 18007 Jan 12 2015 LICENSE.txt -rw----r-- 1 u723 ftpusers 10345 Jan 12 2015 START.htm drwx---r-x 8 u723 ftpusers 4096 Dec 17 2014 gw -rw---r-x 1 u723 ftpusers 108 Dec 17 2014 gwd.command -rw---r-x 1 u723 ftpusers 1117 Dec 17 2014 gwsetup.command (uiserver):u723:~/GeneWeb/geneweb-6.08 > (uiserver):u723:~/GeneWeb/geneweb-6.08 > cd gw (uiserver):u723:~/GeneWeb/geneweb-6.08/gw > ls -al total 13268 drwx---r-x 8 u723 ftpusers 4096 Dec 17 2014 . drwx---r-x 3 u723 ftpusers 82 Jan 12 2015 .. -rw----r-- 1 u723 ftpusers 15280 Jan 12 2015 a.gwf -rwx---r-x 1 u723 ftpusers 529764 Jan 12 2015 consang drwx---r-x 12 u723 ftpusers 4096 Dec 2 2014 etc -rwx---r-x 1 u723 ftpusers 1182404 Jan 12 2015 ged2gwb -rwx---r-x 1 u723 ftpusers 1200900 Jan 12 2015 ged2gwb2 -rwx---r-x 1 u723 ftpusers 552100 Jan 12 2015 gwb2ged -rwx---r-x 1 u723 ftpusers 631844 Jan 12 2015 gwc -rwx---r-x 1 u723 ftpusers 861434 Jan 12 2015 gwc1 -rwx---r-x 1 u723 ftpusers 630084 Jan 12 2015 gwc2 -rwx---r-x 1 u723 ftpusers 2422372 Jan 12 2015 gwd -rw----r-- 1 u723 ftpusers 12 Jan 12 2015 gwd.arg -rw----r-- 1 u723 ftpusers 0 Jan 12 2015 gwd.log -rw----r-- 1 u723 ftpusers 42 Oct 10 2014 gwd.xcl -rw----r-- 1 u723 ftpusers 3851203 Jan 12 2015 gwdl.log -rwx---r-x 1 u723 ftpusers 358308 Jan 12 2015 gwsetup drwx---r-x 3 u723 ftpusers 68 Jan 3 2015 gwtp_tmp -rwx---r-x 1 u723 ftpusers 589028 Jan 12 2015 gwu drwx---r-x 3 u723 ftpusers 4096 Nov 20 2014 images drwx---r-x 2 u723 ftpusers 140 Jan 12 2015 lang drwx---r-x 2 u723 ftpusers 6 Sep 24 2014 old -rw----r-- 1 u723 ftpusers 10 Jan 12 2015 only.txt drwx---r-x 3 u723 ftpusers 33 Sep 24 2014 setup -rw----r-- 1 u723 ftpusers 104 Dec 17 2014 tags.txt -rwx---r-x 1 u723 ftpusers 497028 Jan 12 2015 update_nldb (uiserver):u723:~/GeneWeb/geneweb-6.08/gw >
The cgi folder
cgi-bin folder contains the cgi commands launching the gwd server software for each request from a browser client.
(uiserver):u723:~ > cd cgi-bin/ (uiserver):u723:~/cgi-bin > ls -al total 144 drwxr-xr-x 3 u723 ftpusers 4096 Oct 7 06:58 . drwx---r-t 23 u723 ftpusers 4096 Oct 7 06:58 .. lrwxrwxrwx 1 u723 ftpusers 8 Jan 12 2015 Gwd -> Gwd-7.00 -rwxr-xr-x 1 u723 ftpusers 183 Oct 10 2014 Gwd-6.08 -rwx---r-x 1 u723 ftpusers 183 Jan 12 2015 Gwd-7.00 -rwx---r-x 1 u723 ftpusers 183 Jan 15 2015 test-cgi.sh (uiserver):u723:~/cgi-bin >
Gwd is a symbolic link to the current version of GeneWeb (7.00 in our example).
Each of the
gwd-x.yy file is a shell script that launches
gwd with the appropriate parameters:
#!/bin/sh DIR=~/GeneWeb/geneweb-6.08/gw BASE_DIR=~/GeneWeb/bases OPTIONS="-robot_xcl 19,60 -allowed_tags ./tags.txt -hd ./" cd $DIR ./gwd -cgi $OPTIONS -bd ../../bases > ./gwd.log 2>&1
To change your server to another version of GeneWeb (7.00 for instance), you should do the following:
cd cgi-bin rm -f Gwd ln -s Gwd-7.00 Gwd
The bases folder
The base folder should contain the same information structure as in the case of installation on a personal computer:
- one or several base.gwb folders.
- one or several base.gwf files.
- cnt containing access count data.
- etc containing template text files used in priority over the generic
gw/etcfiles (see header).
- images containing for each base photos associated with each person (
- lang containing some base specific language relates template text files (lexicon for instance).
- src containing for each base text files and image files inserted in notes with the m=SRC command.
- wiz.auth as many wizards and friends authorization files as specified for each base in their respective .gwf parameter file.
(Note that the picture on the right has been taken off a personnal computer where the bases are stored in a folder names
GeneWeb-Bases, as opposed to
bases in the remote server structure proposed here).
Script to upload a copy of a base
(Test and report for errors or improvements are welcome.)
base-upload.sh (download it) takes a
base_name as an argument, and optionally
src. It uploads a fresh base on your server, or a fresh copy of the
src/base folders. It performs the following steps:
- creates a fresh base.gw file from the base on your personal computer.
- extracts a listing of the content of
- creates a
remote.shfile (see below).
- creates a tar file containing $BASE.gw, history remote.sh and the three
- sends the tar file to the remote server.
- triggers on the remote server unfolding of the tar file and execution of
remote.sh. The result of this remote execution should be a mail containing the
remote.logand three diff between images folders.
This procedure saves the previous folder of the base or its images and src folders with a "yyyy-mm-dd-hh:mm:ss" date tag. As time progresses, you may want to clean-up this accumulation of saves.
remote.sh for base update
The shell script below is executed on your remote server, and installs your base at the proper location (according to the overall set-up described here).
#!/bin/sh # BASE BASES_SERVER BIN_DIR_SERVER and ADDRESS will be replaced by the appropriate values by sed cd DATE=$(date +"%Y-%m-%d-%T") echo 'Error log of update for base: BASE' > ~/remote.log echo $DATE >> ~/remote.log # Save current version cd BASES_SERVER 2>> ~/remote.log if [ -d ./BASE.gwb ] # do it only if folder exists then mv ./BASE.gwb ./BASE-$DATE.gwb 2>> ~/remote.log fi # Extract new base from .tar file tar xf ~/BASE.tar 2>> ~/remote.log # rebuild BASE from .gw file BIN_DIR_SERVER/gwc1 -f -o BASE BASE.gw 2>> ~/remote.log BIN_DIR_SERVER/updnldb BASE 2>> ~/remote.log if [ -f ./BASE-$DATE.gwb/history ] # do it only if file exists then cp -f ./BASE-$DATE.gwb/history ./BASE.gwb 2>> ~/remote.log fi if [ -f ./BASE-$DATE.gwb/forum ] # do it only if file exists then cp -f ./BASE-$DATE.gwb/forum ./BASE.gwb 2>> ~/remote.log fi # done cd >> ~/remote.log # Create a link to css.txt in the bases/src folder ln -s -f ~/GeneWeb/geneweb-$VERS/gw/etc/css.txt BASES_SERVER/src/BASE/css.txt 2>> ~/remote.log # compute diffs between server and personal computer for image folders echo '' >> ~/remote.log if [ -d BASES_SERVER/images/BASE ] # do it only if folder exists then ls BASES_SERVER/images/BASE > ./ls-personnes-serveur.txt echo 'Personnes diff serveur vs local' >> ~/remote.log diff ./ls-personnes-serveur.txt ./ls-personnes.txt >> ~/remote.log else echo "No folder BASES_SERVER/images/BASE" >> ~/remote.log fi echo '' >> ~/remote.log if [ -d BASES_SERVER/src/BASE/ ] # do it only if folder exists then ls BASES_SERVER/src/BASE > ./ls-src-files-serveur.txt echo 'Src files diff serveur vs local' >> ~/remote.log diff ./ls-src-files-serveur.txt ./ls-src-files.txt >> ~/remote.log else echo "No folder BASES_SERVER/src/BASE" >> ~/remote.log fi echo '' >> ~/remote.log if [ -d BASES_SERVER/src/BASE/images ] # do it only if folder exists then ls BASES_SERVER/src/BASE/images > ./ls-images-serveur.txt echo 'Images diff serveur vs local' >> ~/remote.log diff ./ls-images-serveur.txt ./ls-images.txt >> ~/remote.log else echo "No folder BASES_SERVER/src/BASE/images" >> ~/remote.log fi rm ./ls-*.txt /usr/bin/mail -s 'Update error log' 'ADDRESS' < ~/remote.log rm -f ~/remote.*
remote.sh for images or src update
The shell script below is executed on your remote server, and installs the
src/images folders for your base at the proper location (according to the overall set-up described here).
Depending on the size of your images folders, and on the number of new images requiring upload, you may prefer to upload images individually with your preferred
ftp client rather than doing the bulk upload proposed here. Remember that the base upload script performs a comparison between the images folders on your personal computer and your server.
#!/bin/sh # BASE BASES_SERVER and ADDRESS will be replaced by the appropriate values by sed DATE=$(date +"%Y-%m-%d-%T") if [ -e ./images.tmp ] then FILES="images" rm -f ./images.tmp fi if [ -e ./src.tmp ] then FILES="src" rm -f ./src.tmp fi echo "Error log of update for $FILES of base: BASE" > ~/remote.log echo "`date`" >> ~/remote.log # Save current version then move new version if [ -d BASES_SERVER/$FILES/BASE ] # do it only if folder exists then mv BASES_SERVER/$FILES/BASE BASES_SERVER/$FILES/BASE-$DATE 2>> ~/remote.log fi mv ./BASE BASES_SERVER/$FILES 2>> ~/remote.log /usr/bin/mail -s 'Update error log' 'ADDRESS' < ~/remote.log rm -f ~/remote.*
Debugging your remote server
Debugging your remote server may be tricky, but some systematic approach and several tools will help.
- Verify first that your HTTP server works properly. This is achieved by typing
your_server_namein the URL window of your browser which should return the content of
- Verify that the cgi mechanism works. This is achieved by typing
your_server_name/cgi-bin/test-cgi.shas seen above (see #Folders and files).
- If your server returns a "Internal server error", several hypothesis should be examined:
- Your script test-cgi.sh does not work properly. Run it directly on a terminal window by typing
./test-cgi.sh(see #Folders and files).
- Your server accepts only files with extension
test-cgi.cgiand try again.
- The first two lines returned by your test-cgi.sh script are not exactly as shown (the second one should be a blank line, Note also that "Content-type text/html\n\n" did not work in my tests).
- You also may want to verify that your "End-of-Lines" are correct for your server environment. Remember that there are three different such
EOLencoding for Windows, Mac, and Linux!!
- Examine the HTTP server log file on your server by typing:
- (your environment may store access logs somewhere else, but this is the most likely place)
- Examination of the log file may give you a hint as to the nature of your problem.
- Your script test-cgi.sh does not work properly. Run it directly on a terminal window by typing
- Another typical issue is that of ownership of the various files associated with GeneWeb. In the case described here, ownership is
userand group ownership is
ftpusers. Depending on the specific method you have used to install GeneWeb, this may vary. Some discussions on the Yahoo! group forum about GeneWeb mentions geneweb for group ownership!
- You may also want to look at the gwd log file if your GeneWeb server works only partially (welcome page is ok, but other pages do not work properly). This log file is specified in the gwd launch command. In our example, it sits at
$DIR/gwd.logwhere $DIR depends on the specific version of GeneWeb you are currently running (see details in #The cgi folder section above).
- Remember that some of the files needed for proper display are fetched by the HTTP server rather than by GeneWeb.
Access rights and protections
In CGI mode, gwd runs behind a standard HTTP server, typically Apache. As such, the owner of the gwd process is the owner of the HTTP server. For instance, with Apache, this owner is defined in the http.conf file and its default value is set to
user: _www and
group: —www. When running within a hosting environment, such as 1&1, you typically do not have access to this parameter. You must therefore organise the protection level of the various folders involved with GeneWeb appropriately:
- read access is usually allowed by default
- for wizards, gwd needs write access to
bases/cnt/robot(if you have activated the -robot_xcl parameter)
- and when modifications are performed, gwd needs write access to
Creating those files, and doing a
sudo chown _www filename seems to be sufficient.
Access problems are reported in the HTTP error log file, unfortunately not always available in the case of shared hosting services!!
Access to various files through your hosted HTTP server is also controlled by your hosting service and through .htaccess files spread across your folders. Managing a coherent set of .htaccess files is not trivial and error prone!! The examples below apply to Apache version 2.4 only (earlier versions have different directives!!).
Options +FollowSymLinks should allow following symbolic links
Require all denied prevents access to this folder to all users.
Require all granted allows access to this folder to all users.
AllowOverride AuthConfig AuthType Basic AuthName "Username/Password required" AuthUserFile /Users/Name/SomeFolder/htfriends.auth Require valid-user
should restrict access to this folder to users supplying a valid password as defined by the
htpasswd /Users/Name/SomeFolder/htfriends.auth UserName will trigger the process to add a new user to the list.
- Download and install GeneWeb program under GNU/Linux, Mac OS X, Microsoft Windows, FreeBSD; on Mac OS X, Linux or Windows using Docker; or in CGI mode behind a web server.
- Understand GeneWeb server, homonym, consanguinity.
Use and manage genealogical databases
- Import Gedcom
.gwfiles with gwsetup or in command-line.
- Update datas (add/remove individuals and families), merge duplicates, type dates.
- Use wikitext syntax, macros, keyboard shortcuts.
- Clean, recover, rename, save, archive a database.
- Merge and split multiples databases.
- Personalize CSS, header and trailer, templates, lexicon and declension.
- Configuration file
.gwf(for templm), wizard notes, passwords for friends/wizards and access restrictions to databases.
- Add images in notes, further remarks for experts.