Difference between revisions of "gwd"

From GeneWeb
Jump to: navigation, search
(no trailing spaces in tags.txt)
m (Starting the gwd server)
 
(8 intermediate revisions by 3 users not shown)
Line 21: Line 21:
  
 
GeneWeb server '''gwd''' is a web server listening for requests on TCP port 2317 by default, in the same way a standard HTTP server, such as Apache, would do on port 80 or 8080. Gwd accepts a specific set of URL following a precise syntax (see below) describing all the commands it can perform.  Results are returned as text and if the URL request was sent from a web browser or any HTTP compatible program, the text will be treated as HTML code.
 
GeneWeb server '''gwd''' is a web server listening for requests on TCP port 2317 by default, in the same way a standard HTTP server, such as Apache, would do on port 80 or 8080. Gwd accepts a specific set of URL following a precise syntax (see below) describing all the commands it can perform.  Results are returned as text and if the URL request was sent from a web browser or any HTTP compatible program, the text will be treated as HTML code.
 +
 +
Note that the parameters {{c|-allowed_tags}}, {{c|-auth}} and {{c|-log}}, are pointing to existing <file>s that can be moved or renamed using either absolute or relative path depending on your configuration and how you launch gwd itself. The file(s) associated with {{c|-add_lexicon}} for supplementary lexicon(s) must be placed in a {{c|lang}} folder.
  
 
  Usage: gwd [options] where options are:
 
  Usage: gwd [options] where options are:
   -hd <dir>
+
   -a <ADDRESS>           Select a specific address (default = any address of this computer).
      Directory where the directory lang is installed.
+
  -add_lexicon <FILE>    Add file as lexicon.
   -bd <dir>
+
  -allowed_tags <FILE>  HTML tags which are allowed to be displayed. One tag per line in file.
      Directory where the databases are installed.
+
  -auth <FILE>          Authorization file to restrict access.
   -wd <dir>
+
                        The file must hold lines of the form "user:password".
      Directory for socket communication (Windows) and access count.
+
   -bd <DIR>             Directory where the databases are installed.
   -cgi
+
   -blang                Select the user browser language if any.
      Force [[CGI|CGI mode]].
+
  -cache_langs          Lexicon languages to be cached.
   -images_url <url>
+
   -cgi                   Force CGI mode.
      URL for GeneWeb images (default: gwd send them)
+
   -conn_tmout <SEC>     Connection timeout (default 120s; 0 means no limit).
   -images_dir <dir>
+
   -daemon                Unix daemon mode.
      Same than previous but directory name relative to current
+
  -debug                Enable debug mode
   -a <address>
+
  -digest                Use Digest authorization scheme (more secure on passwords)
      Select a specific address (default = any address of this computer)
+
  -friend <PASSWD>       Set a friend password.
   -p <number>
+
  -hd <DIR>              Directory where the directory lang is installed.
      Select a port number (default = 2317); > 1024 for normal users.
+
  -images_dir <DIR>      Same than previous but directory name relative to current.
   -setup_link
+
   -images_url <URL>     URL for GeneWeb images (default: gwd send them).
      Display a link to local [[Gwsetup|gwsetup]] in bottom of pages.
+
   -lang <LANG>           Set a default language (default: fr).
  -allowed_tags <file>
+
   -log <FILE>            Log trace to this file. Use "-" or "<stdout>" to redirect output to stdout
      [[Tags|HTML tags]] which are allowed to be displayed. One tag per line in file, no trailing space!.
+
                        or "<stderr>" to output log to stderr.
  -wizard <passwd>
+
   -log_level <N>        Send messages with severity <= <N> to syslog (default: 7).
      Set a wizard [[password]]: access to all dates and updating.
+
   -login_tmout <SEC>    Login timeout for entries with passwords in CGI mode (default 1800s).
   -friend <passwd>
+
   -max_clients <NUM>     Max number of clients treated at the same time (default: no limit) (not cgi).
      Set a friend [[password]]: access to all dates.
+
  -min_disp_req          Minimum number of requests in robot trace (default: 6).
   -wjf
+
   -no_host_address      Force no reverse host by address.
      Wizard just friend (permanently)
+
  -nolock                Do not lock files before writing.
   -lang <lang>
+
   -only <ADDRESS>        Only inet address accepted.
      Set a default [[Lexicon#Language codes|language]] (default: fr).
+
   -p <NUMBER>           Select a port number (default = 2317).
   -blang
+
  -plugin <PLUGIN>.cmxs  load a safe plugin.
      Select the user browser language if any.
+
                        Combine with -force to enable for every base.
   -only <address>
+
                        Combine with -unsafe to allow unverified plugins. e.g. "-plugin -unsafe -force".
       Only inet address accepted.
+
   -plugins <DIR>        load all plugins in <DIR>.
   -auth <file>
+
                        Combine with -force to enable for every base.
      Authorization file to restrict [[access]]. The file must hold lines
+
                        Combine with -unsafe to allow unverified plugins. e.g. "-plugins -unsafe -force".
      of the form "user:password".
+
   -redirect <ADDR>       Send a message to say that this service has been redirected to <ADDR>.
   -no_host_address
+
   -robot_xcl <CNT>,<SEC> Exclude connections when more than <CNT> requests in <SEC> seconds.
      Force no reverse host by address
+
   -setup_link            Display a link to local gwsetup in bottom of pages.
  -digest
+
   -trace_failed_passwd   Print the failed passwords in log (except if option -digest is set).  
      Use Digest authorization scheme (more secure on passwords)
+
   -wd <DIR>             Directory for socket communication (Windows) and access count.
  -add_lexicon <lexicon>
+
   -wizard <PASSWD>       Set a wizard password.
      Add file as [[lexicon]].
+
  -wjf                  Wizard just friend (permanently).
   -log <file>
+
   -help                  Display this list of options
      Redirect log trace to this file.
+
   --help                Display this list of options
   -robot_xcl <cnt>,<sec>
+
 
      Exclude connections when more than <cnt> requests in <sec> seconds.
+
Note that when running with {{c|-debug}}, GeneWeb will add begin/end html comments in the returned document providing the full path of the various included files such as:
   -min_disp_req
+
&#60;!-- begin include /Users/Henri/Genea/GeneWeb/GeneWeb-7.0h-Mac/gw/plugins/welcome/assets/etc/welcome.txt --&#62;
      Minimum number of requests in robot trace (default: 6)
+
  -login_tmout <sec>
+
      Login timeout for entries with passwords in CGI mode (default 1800s)
+
  -redirect <addr>
+
      Send a message to say that this service has been redirected to <addr>
+
   -trace_failed_passwd
+
      Print the failed passwords in log (except if option -digest is set)
+
  -nolock
+
      Do not lock files before writing.
+
   -max_clients <num>
+
      Max number of clients treated at the same time (default: no limit)
+
      (not cgi).
+
   -conn_tmout <sec>
+
      Connection timeout (default 120s; 0 means no limit)
+
   -daemon
+
      Unix daemon mode.
+
   -chwd <comm>
+
      Call command when wdoc changed
+
  
 
== Requests to gwd server ==
 
== Requests to gwd server ==
Line 129: Line 113:
  
 
=== Cancel GeneWeb links, cgl=on/off ===
 
=== Cancel GeneWeb links, cgl=on/off ===
Use the {{c|1=cgl=off}} ('''''c'''ancel '''g'''eneweb '''l'''inks'') option to cancel GeneWeb links in a given page. This may be useful for printing, or to do a copy/paste operation of a page into some other document where you don not want to transport the various GeneWeb links.
+
Use the {{c|1=cgl=on}} ('''''c'''ancel '''g'''eneweb '''l'''inks'') option to cancel GeneWeb links in a given page. This may be useful for printing, or to do a copy/paste operation of a page into some other document where you don not want to transport the various GeneWeb links.
  
 
=== Names for one person, opt=misc ===
 
=== Names for one person, opt=misc ===

Latest revision as of 19:26, 1 January 2022

150px-Geographylogo svg.png Language: English • français

gwd is the GeneWeb server that accepts requests and returns results. Its interfaces are entirely web-based: it behaves like a HTTP server.

All query parameters are directly available in the URL window of your web browser to build links to GeneWeb pages.

They may be useful both to GeneWeb users, and to persons who, without knowledge of GeneWeb, may want to insert in some of their web documents a link to a page produced by a GeneWeb server that they may have found on the Web.

Welcome page of a GeneWeb database

The welcome page of a GeneWeb base can be found at an URL of the form http://server:port/base where:

  • server is the IP address or DNS name of the server hosting the GeneWeb daemon;
  • port is the TCP port on which the daemon is listening, the default value being 2317 for base access with gwd and 2316 for management with gwsetup (these two parameters may be changed at launch time of these two programs);
  • base is the name of the GeneWeb database.

To ease things, gwd opens up by displaying the standard page welcome.txt on which a multiplicity of text capture zones and clickable buttons provides a convenient way to build a complex request.

When further navigating with GeneWeb, you will discover that your requests translate into URL which contains a command (action) and related parameters (data).

Starting the gwd server

GeneWeb server gwd is a web server listening for requests on TCP port 2317 by default, in the same way a standard HTTP server, such as Apache, would do on port 80 or 8080. Gwd accepts a specific set of URL following a precise syntax (see below) describing all the commands it can perform. Results are returned as text and if the URL request was sent from a web browser or any HTTP compatible program, the text will be treated as HTML code.

Note that the parameters -allowed_tags, -auth and -log, are pointing to existing <file>s that can be moved or renamed using either absolute or relative path depending on your configuration and how you launch gwd itself. The file(s) associated with -add_lexicon for supplementary lexicon(s) must be placed in a lang folder.

Usage: gwd [options] where options are:
 -a <ADDRESS>           Select a specific address (default = any address of this computer).
 -add_lexicon <FILE>    Add file as lexicon.
 -allowed_tags <FILE>   HTML tags which are allowed to be displayed. One tag per line in file.
 -auth <FILE>           Authorization file to restrict access. 
                        The file must hold lines of the form "user:password".
 -bd <DIR>              Directory where the databases are installed.
 -blang                 Select the user browser language if any.
 -cache_langs           Lexicon languages to be cached.
 -cgi                   Force CGI mode.
 -conn_tmout <SEC>      Connection timeout (default 120s; 0 means no limit).
 -daemon                Unix daemon mode.
 -debug                 Enable debug mode
 -digest                Use Digest authorization scheme (more secure on passwords)
 -friend <PASSWD>       Set a friend password.
 -hd <DIR>              Directory where the directory lang is installed.
 -images_dir <DIR>      Same than previous but directory name relative to current.
 -images_url <URL>      URL for GeneWeb images (default: gwd send them).
 -lang <LANG>           Set a default language (default: fr).
 -log <FILE>            Log trace to this file. Use "-" or "<stdout>" to redirect output to stdout 
                        or "<stderr>" to output log to stderr.
 -log_level <N>         Send messages with severity <= <N> to syslog (default: 7).
 -login_tmout <SEC>     Login timeout for entries with passwords in CGI mode (default 1800s).
 -max_clients <NUM>     Max number of clients treated at the same time (default: no limit) (not cgi).
 -min_disp_req          Minimum number of requests in robot trace (default: 6).
 -no_host_address       Force no reverse host by address.
 -nolock                Do not lock files before writing.
 -only <ADDRESS>        Only inet address accepted.
 -p <NUMBER>            Select a port number (default = 2317).
 -plugin <PLUGIN>.cmxs  load a safe plugin.
                        Combine with -force to enable for every base.
                        Combine with -unsafe to allow unverified plugins. e.g. "-plugin -unsafe -force".
 -plugins <DIR>         load all plugins in <DIR>.
                        Combine with -force to enable for every base.
                        Combine with -unsafe to allow unverified plugins. e.g. "-plugins -unsafe -force".
 -redirect <ADDR>       Send a message to say that this service has been redirected to <ADDR>.
 -robot_xcl <CNT>,<SEC> Exclude connections when more than <CNT> requests in <SEC> seconds.
 -setup_link            Display a link to local gwsetup in bottom of pages.
 -trace_failed_passwd   Print the failed passwords in log (except if option -digest is set). 
 -wd <DIR>              Directory for socket communication (Windows) and access count.
 -wizard <PASSWD>       Set a wizard password.
 -wjf                   Wizard just friend (permanently).
 -help                  Display this list of options
 --help                 Display this list of options

Note that when running with -debug, GeneWeb will add begin/end html comments in the returned document providing the full path of the various included files such as:

<!-- begin include /Users/Henri/Genea/GeneWeb/GeneWeb-7.0h-Mac/gw/plugins/welcome/assets/etc/welcome.txt -->

Requests to gwd server

Requests to gwd server are formulated as URLs loaded with parameters. The question mark ? after the base address marks the beginning of the request: http://server:port/base?request.

It may sometimes be necessary to manually edit the URL to obtain the desired effect because some parameters aren’t available for selection and/or clicking for all pages of the interface.

The request in itself is the sum of all query parameters added to the end of the URL after the question mark. The gwd server analyse the different parameters and will render a specific page. Depending on the situation, the delimiter between the query parameters in the URLs may change between ; and &. Both can be used simultaneously.

The gwd server assumes that the URL request comes from a standard HTTP client (a browser or any other HTTP compatible program), and returns its result page accordingly (i.e. prefixed by the standard Content-type text/html header).

Links to persons, access_by_key and opt=no_index

Within GeneWeb, persons can be identified through two main methods, names and id:

  • p=first_name;n=last_name (exact match);
  • p=first_name;n=last_name;oc=occurrence if there are homonyms;
  • i=1234 GeneWeb internal id.

GeneWeb id numbers are unique across a base, but may change over time after clean up for instance.

Obtaining permanent links is achieved through two methods:

  • using option access_by_key=yes in the .gwf configuration file of your base, which will prevent the use of internal ids for URL construction;
  • adding opt=no_index to an URL containing id numbers will return the URL with unique but bulkier keys of individuals p=firstname;n=lastname;oc=occurence instead of id numbers.
Link to use without i=, obtained adding opt=no_index in the URL.

This last remark applies to all GeneWeb queries, particularly those about parental relationship where many individuals are referenced.

Language

lang=

Template

templ=

Pedigree collapse, dag=on

Ascendants tree with dag=on: common ancestors are merged.

On ascendant and descendant trees, dag=on will merge common ancestors.

Origin of a person, opt=from

The opt=from option is used to determine which source file a particular person’s data comes from. See merging bases for details. This information appears in italic after the family of the person, and is visible only to wizards.

Cancel GeneWeb links, cgl=on/off

Use the cgl=on (cancel geneweb links) option to cancel GeneWeb links in a given page. This may be useful for printing, or to do a copy/paste operation of a page into some other document where you don not want to transport the various GeneWeb links.

Names for one person, opt=misc

The opt=misc option will display at the end of the page all the first_name last_name alias combinations considered valid to call a particular person.

Hidden titles, all_titles

all_titles=on

Refresh modified pages, escache

escache=0

Insert images and text files

  • m=IMH insert image
  • m=SRC insert text file (typically HTML code)

For example, to display an image in notes we use <a href="%sm=IMH;s=image.jpg">Displayed text</a>. In this example, the “command” is the m=IMH part, %s is a macro transformed into the server address, and the rest of the URL being the parameters passed to the command, here the name of the image.


GeneWeb Manual

Rembrandt Old Man Reading a Book.jpg

Use and manage genealogical databases

Technical annex