From: Adam Dickmeiss Date: Sun, 13 Mar 2005 21:43:00 +0000 (+0000) Subject: Renamed ztest-options.xml to gfs-options.xml. Added GFS common synopsis X-Git-Tag: YAZ.2.1.0~9 X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=commitdiff_plain;h=02e5bbc0d685b1f565cbd71bc7c61858e74c4382 Renamed ztest-options.xml to gfs-options.xml. Added GFS common synopsis to gfs-synopsis.xml. Initial work on GFS virtual hosts. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index ba7fab7..de7ecd6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,11 +1,11 @@ -## $Id: Makefile.am,v 1.58 2004-12-15 09:10:12 adam Exp $ +## $Id: Makefile.am,v 1.59 2005-03-13 21:43:00 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ XMLFILES=yaz.xml.in introduction.xml installation.xml indexdata.xml \ asn.xml tools.xml odr.xml comstack.xml frontend.xml license.xml \ - future.xml client.xml zoom.xml credits.xml ztest-options.xml \ - yaz-client-commands.xml soap.xml + future.xml client.xml zoom.xml credits.xml gfs-options.xml \ + yaz-client-commands.xml soap.xml gfs-virtual.xml gfs-synopsis.xml HTMLFILES = \ asn.external.html asn.html asn.oid.html asn.pdu.html asn.preparing.html \ @@ -19,7 +19,8 @@ HTMLFILES = \ license.html license.other.html odr.debugging.html odr.html \ odr.programming.html odr.use.html server.backendfunctions.html \ server.backend.html server.frontend.html server.html server.invocation.html \ - server.main.html soap.html soap.http.html soap.xml.html soap.srw.html \ + server.main.html server.vhosts.html \ + soap.html soap.http.html soap.xml.html soap.srw.html \ tools.html tools.marc.html tools.nmem.html tools.log.html tools.oid.html \ yaz.html zoom.events.html zoom.html zoom.options.html zoom.query.html \ zoom.records.html zoom.resultsets.html zoom.scan.html @@ -43,7 +44,7 @@ EXTRA_DIST = $(XMLFILES) $(SUPPORTFILES) $(man_MANS) $(REFFILES) \ yaz-client.1: $(srcdir)/yaz-client-man.xml $(srcdir)/yaz-client-commands.xml docbook2man $(srcdir)/yaz-client-man.xml -yaz-ztest.8: yaz-ztest-man.xml ztest-options.xml +yaz-ztest.8: yaz-ztest-man.xml gfs-options.xml gfs-synopsis.xml gfs-virtual.xml docbook2man $(srcdir)/yaz-ztest-man.xml yaz-config.8: yaz-config-man.xml diff --git a/doc/frontend.xml b/doc/frontend.xml index 2ff6ed9..7ab9e83 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,4 +1,4 @@ - + Generic server Introduction @@ -726,31 +726,13 @@ typedef struct bend_scan_rr { The finished application has the following invocation syntax (by way of statserv_main()): - - - appname - - - - - - - - - - - - - - - - listener-spec - + + &gfs-synopsis; The options are: - &ztest-options; + &gfs-options; @@ -832,6 +814,9 @@ typedef struct bend_scan_rr { + Virtual hosts + &gfs-virtual; + + + + + -a + file + + Specify a file for dumping PDUs (for diagnostic purposes). + The special name - (dash) sends output to + stderr. + + + -S + + Don't fork or make threads on connection requests. This is good for + debugging, but not recommended for real operation: Although the + server is asynchronous and non-blocking, it can be nice to keep + a software malfunction (okay then, a crash) from affecting all + current users. + + + -1 + + Like -S but after one session the server + exits. This mode is for debugging only. + + + -T + + Operate the server in threaded mode. The server creates a thread + for each connection rather than a fork a process. Only available + on UNIX systems that offers POSIX threads. + + + -s + + Use the SR protocol (obsolete). + + + -z + + Use the Z39.50 protocol (default). This option and -s + complement each other. + You can use both multiple times on the same command + line, between listener-specifications (see below). This way, you + can set up the server to listen for connections in both protocols + concurrently, on different local ports. + + + -l + file + The logfile. + + + -c + config + A user option that serves as a specifier for some + sort of configuration, usually a filename. + The argument to this option is transferred to member + confignameof the + statserv_options_block. + + + -f + vconfig + This specifies an XML file that describes + one or more YAZ frontend virtual servers. + + + -C + fname + Sets SSL certificate file name for server (PEM). + + + -v + level + + The log level. Use a comma-separated list of members of the set + {fatal,debug,warn,log,malloc,all,none}. + + + -u + uid + + Set user ID. Sets the real UID of the server process to that of the + given user. It's useful if you aren't comfortable with having the + server run as root, but you need to start it as such to bind a + privileged port. + + + -w + dir + + The server changes to this directory during before listening + on incoming connections. This option is useful + when the server is operating from the inetd + daemon (see -i). + + + -p + pidfile + + Specifies that the server should write its Process ID to + file given by pidfile. + A typical location would be /var/run/yaz-ztest.pid. + + + -i + + Use this to make the the server run from the + inetd server (UNIX only). + + + -D + + Use this to make the server put itself in the background and + run as a daemon. If neither -i nor + -D is given, the server starts in the foreground. + + + -install + + Use this to install the server as an NT service + (Windows NT/2000/XP only). + Control the server by going to the Services in the Control Panel. + + + -installa + + Use this to install and activate the server as an NT service + (Windows NT/2000/XP only). + Control the server by going to the Services in the Control Panel. + + + -remove + + Use this to remove the server from the NT services + (Windows NT/2000/XP only). + + + -t + minutes + + Idle session timeout, in minutes. + + + -k + size + + Maximum record size/message size, in kilobytes. + + + + -d + daemon + + Set name of daemon to be used in hosts access file. + See + + hosts_access + 5 + + and + + tcpd + 8 + . + + + + + + diff --git a/doc/gfs-synopsis.xml b/doc/gfs-synopsis.xml new file mode 100644 index 0000000..ef76933 --- /dev/null +++ b/doc/gfs-synopsis.xml @@ -0,0 +1,41 @@ + + + + &gfs-synopsis-app; + + + + + + + + + + + + + + + + + listener-spec + + + diff --git a/doc/gfs-virtual.xml b/doc/gfs-virtual.xml new file mode 100644 index 0000000..d307f62 --- /dev/null +++ b/doc/gfs-virtual.xml @@ -0,0 +1,89 @@ + + + + The Virtual hosts mechanism allows a YAZ frontend server to + support multiple backends. A backend is selected on the basis of + the TCP/IP binding (port+listening adddress) and/or the virtual host. + + + For the HTTP protocol, the virtual host is specified in the Host header. + For the Z39.50 protocol, the virtual host is specified as in the + Initialize Request in the OtherInfo, OID 1.2.840.10003.10.1000.81.1. + + + + Not all Z39.50 clients allows the VHOST information to be set. + For those the selection of the backend must rely on the + TCP/IP information alone (port and address). + + + + The YAZ frontend server uses XML to describe the backend + configurations. Command-line option -f + specifies filename of the XML configuration. + + + The configuration uses the root element yazgfs. + This element includes a list of listen elements, + followed by one or more server elements. + + + The listen describes listener (transport end point), + such as TCP/IP, Unix file socket or SSL server. + + + The server describes a server and includes sub + elements which servers as parameters for this server. + + + The XML below configures a server with 2 listeners and 3 backend + servers. The server listens on port 9900 and 9901 identified + with references "public9900" and "public9901". + + [More to be written] + + + tcp:@:9900 + tcp:@:9901 + + host1 + /var/www/s1 + zebra1.cfg + + + host2 + /var/www/s2 + zebra2.cfg + + + /var/www/s3 + zebra3.cfg + ../etc/pqf.properties + + explain + + + +]]> + + + + diff --git a/doc/yaz-ztest-man.xml b/doc/yaz-ztest-man.xml index f0776cc..094a588 100644 --- a/doc/yaz-ztest-man.xml +++ b/doc/yaz-ztest-man.xml @@ -1,7 +1,10 @@ + + + + ]> - + @@ -15,26 +18,7 @@ - - yaz-ztest - - - - - - - - - - - - - - - - listener-spec - - + &gfs-synopsis; DESCRIPTION @@ -43,45 +27,48 @@ The server acts as a real Z39.50 server but does not use a database. It returns a random hit count and returns a subset of a few built-in records. - - - The listener-spec consists of a transport - mode followed by a colon, followed by a listener address. The - transport mode is either tcp, unix, - or ssl. - - - For TCP and SSL, an address has the form: - - hostname | IP-number [ : portnumber ] - - - - For UNIX local socket the address is the filename of the local socket. - - - - OPTIONS - &ztest-options; - - FILES - - yaz-<version>/ztest/yaz-ztest.c - - - yaz-<version>/include/yaz/backend.h - - - SEE ALSO - - - yaz - 7 - - - Section "Generic server" in the YAZ manual. - - + + + The listener-spec consists of a transport + mode followed by a colon, followed by a listener address. The + transport mode is either tcp, unix, + or ssl. + + + For TCP and SSL, an address has the form: + + hostname | IP-number [ : portnumber ] + + + + For UNIX local socket the address is the filename of the local socket. + + + + OPTIONS + &gfs-options; + + FILES + + yaz-<version>/ztest/yaz-ztest.c + + + yaz-<version>/include/yaz/backend.h + + + VIRTUAL HOSTS + &gfs-virtual; + + SEE ALSO + + + yaz + 7 + + + Section "Generic server" in the YAZ manual. + + + YAZ User's Guide and Reference diff --git a/doc/ztest-options.xml b/doc/ztest-options.xml deleted file mode 100644 index f7c4f93..0000000 --- a/doc/ztest-options.xml +++ /dev/null @@ -1,184 +0,0 @@ - - - - - -a - file - - Specify a file for dumping PDUs (for diagnostic purposes). - The special name - (dash) sends output to - stderr. - - - -S - - Don't fork or make threads on connection requests. This is good for - debugging, but not recommended for real operation: Although the - server is asynchronous and non-blocking, it can be nice to keep - a software malfunction (okay then, a crash) from affecting all - current users. - - - -1 - - Like -S but after one session the server - exits. This mode is for debugging only. - - - -T - - Operate the server in threaded mode. The server creates a thread - for each connection rather than a fork a process. Only available - on UNIX systems that offers POSIX threads. - - - -s - - Use the SR protocol (obsolete). - - - -z - - Use the Z39.50 protocol (default). This option and -s - complement each other. - You can use both multiple times on the same command - line, between listener-specifications (see below). This way, you - can set up the server to listen for connections in both protocols - concurrently, on different local ports. - - - -l - file - The logfile. - - - -c - config - A user option that serves as a specifier for some - sort of configuration, usually a filename. - The argument to this option is transferred to member - confignameof the - statserv_options_block. - - - -C - fname - Sets SSL certificate file name for server (PEM). - - - -v - level - - The log level. Use a comma-separated list of members of the set - {fatal,debug,warn,log,malloc,all,none}. - - - -u - uid - - Set user ID. Sets the real UID of the server process to that of the - given user. It's useful if you aren't comfortable with having the - server run as root, but you need to start it as such to bind a - privileged port. - - - -w - dir - - The server changes to this directory during before listening - on incoming connections. This option is useful - when the server is operating from the inetd - daemon (see -i). - - - -p - pidfile - - Specifies that the server should write its Process ID to - file given by pidfile. - A typical location would be /var/run/yaz-ztest.pid. - - - -i - - Use this to make the the server run from the - inetd server (UNIX only). - - - -D - - Use this to make the server put itself in the background and - run as a daemon. If neither -i nor - -D is given, the server starts in the foreground. - - - -install - - Use this to install the server as an NT service - (Windows NT/2000/XP only). - Control the server by going to the Services in the Control Panel. - - - -installa - - Use this to install and activate the server as an NT service - (Windows NT/2000/XP only). - Control the server by going to the Services in the Control Panel. - - - -remove - - Use this to remove the server from the NT services - (Windows NT/2000/XP only). - - - -t - minutes - - Idle session timeout, in minutes. - - - -k - size - - Maximum record size/message size, in kilobytes. - - - - -d - daemon - - Set name of daemon to be used in hosts access file. - See - - hosts_access - 5 - - and - - tcpd - 8 - . - - - - - -