From 7dcaf748021e168c37a2e3eb263db03248b2d170 Mon Sep 17 00:00:00 2001 From: Marc Cromme Date: Fri, 5 Aug 2005 14:39:12 +0000 Subject: [PATCH] updated the zebrasrv man page by copying relevant files over from yaz documentation. Still miss to write a nice description, and also updating of the same info in the zebra manual is needed --- doc/Makefile.am | 14 ++- doc/zebra.xml.in | 8 +- doc/zebrasrv-man.sgml | 44 ++++++++- doc/zebrasrv-options.xml | 190 +++++++++++++++++++++++++++++++++++++++ doc/zebrasrv-synopsis.xml | 41 +++++++++ doc/zebrasrv-virtual.xml | 219 +++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 508 insertions(+), 8 deletions(-) create mode 100644 doc/zebrasrv-options.xml create mode 100644 doc/zebrasrv-synopsis.xml create mode 100644 doc/zebrasrv-virtual.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 72993cd..f6e6ecf 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.26 2004-12-15 09:10:47 adam Exp $ +## $Id: Makefile.am,v 1.27 2005-08-05 14:39:12 marc Exp $ docdir=$(datadir)/doc/@PACKAGE@ SUPPORTFILES = \ @@ -20,7 +20,13 @@ XMLFILES = \ license.xml \ indexdata.xml \ zebraidx-options.xml \ - zebraidx-commands.xml + zebraidx-commands.xml \ + zebrasrv-options.xml \ + zebrasrv-synopsis.xml \ + zebrasrv-virtual.xml + +# zebrasrv-commands.xml \ + HTMLFILES = \ administration.html apps.html configuration-file.html data-model.html \ @@ -50,7 +56,9 @@ zebraidx.1: zebraidx-man.sgml zebraidx-options.xml zebraidx-commands.xml if test ! -f zebraidx-commands.xml ; then ln -s $(srcdir)/zebraidx-commands.xml .; fi docbook2man $(srcdir)/zebraidx-man.sgml -zebrasrv.8: zebrasrv-man.sgml +# zebrasrv-commands.xml +zebrasrv.8: zebrasrv-man.sgml zebrasrv-options.xml \ + zebrasrv-synopsis.xml zebrasrv-virtual.xml docbook2man $(srcdir)/zebrasrv-man.sgml idzebra-config.1: idzebra-config-man.sgml diff --git a/doc/zebra.xml.in b/doc/zebra.xml.in index 228d15c..19d1057 100644 --- a/doc/zebra.xml.in +++ b/doc/zebra.xml.in @@ -15,6 +15,9 @@ + + '> '> ]> - + Zebra - User's Guide and Reference @@ -40,6 +43,9 @@ MikeTaylor + + MarcCromme + 1995-2005 Index Data diff --git a/doc/zebrasrv-man.sgml b/doc/zebrasrv-man.sgml index df75b76..be6c446 100644 --- a/doc/zebrasrv-man.sgml +++ b/doc/zebrasrv-man.sgml @@ -1,5 +1,15 @@ - - + + + + + +]> + + + + + @@ -13,6 +23,7 @@ + + &zebrasrv-synopsis; DESCRIPTION - zebrasrv is a Z39.50 server for Zebra. + zebrasrv is a Z39.50 and SRW/U server for Zebra. On Unix you can run the server from the command line - and put it in the background. It may also operate under the inet daemon. On WIN32 you can run the server as a console application or as a WIN32 Service. + OPTIONS + The options for zebrasrv are the same as those for YAZ' yaz-ztest. Option -c specifies a Zebra configuration file - if omitted zebra.cfg is read. + + &zebrasrv-options; + + VIRTUAL HOSTS + + zebrasrvuses the YAZ server + + &zebrasrv-virtual; FILES @@ -65,6 +92,15 @@ Section "The Z39.50 Server" in the Zebra manual. + http://www.indexdata.dk/zebra/doc/server.tkl + + + Section "Virtual Hosts" in the YAZ manual. + http://www.indexdata.dk/yaz/doc/server.vhosts.tkl + + + Section "Specification of CQL to RPN mappings" in the YAZ manual. + http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map diff --git a/doc/zebrasrv-options.xml b/doc/zebrasrv-options.xml new file mode 100644 index 0000000..6915e0d --- /dev/null +++ b/doc/zebrasrv-options.xml @@ -0,0 +1,190 @@ + + + + + -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 + configname of 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/zebrasrv-synopsis.xml b/doc/zebrasrv-synopsis.xml new file mode 100644 index 0000000..b218d91 --- /dev/null +++ b/doc/zebrasrv-synopsis.xml @@ -0,0 +1,41 @@ + + + + &gfs-synopsis-app; + + + + + + + + + + + + + + + + + listener-spec + + + diff --git a/doc/zebrasrv-virtual.xml b/doc/zebrasrv-virtual.xml new file mode 100644 index 0000000..b7b66d5 --- /dev/null +++ b/doc/zebrasrv-virtual.xml @@ -0,0 +1,219 @@ + + + + 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. + + + A backend can be configured to execute in a particular working + directory. Or the YAZ frontend may perform CQL to RPN conversion, thus + allowing traditional Z39.50 backends to be offered as a SRW/SRU + service. SRW/SRU Explain information for a particular backend may also + be specified. + + + 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. Content for + a listener: + + CDATA (required) + + + The CDATA for the listen element holds the + listener string, such as tcp:@:210, + tcp:server1:2100, + etc. + + + + attribute id (optional) + + + identifier for this listener. This may be referred to from + server sections. + + + + + + + We expect more information to be added for the listen section in + a future version, such as CERT file for SSL servers. + + + + + The server describes a server and the parameters + for this server type. Content for a server: + + attribute id (optional) + + + Identifier for this server. Currently not used for anything, + but it might be for logging purposes. + + + + + attribute listenref (optional) + + + Specifies listener for this server. If this attribute is not + given, the server is accessible from all listener. In order + for the server to be used for real, howeever, the virtual host + must match (if specified in the configuration). + + + + + element config (optional) + + + Specifies the server configuration. This is equivalent + to the config specified using command line option + -c. + + + + + element directory (optional) + + + Specifies a working directory for this backend server. If + specifid, the YAZ fronend changes current working directory + to this directory whenever a backend of this type is + started (backend handler bend_start), stopped (backend handler hand_stop) + and initialized (bend_init). + + + + + element host (optional) + + + Specifies the virtual host for this server. If this is specified + a client must specify this host string in + order to use this backend. + + + + + element cql2rpn (optional) + + + Specifies a filename that includes CQL to RPN conversion for this + backend server. See &reference-tools-cql-map; + If given, the backend server will only "see" a Type-1/RPN query. + + + + + element explain (optional) + + + Specifies SRW/SRU ZeeRex content for this server. Copied verbatim + to the client. As things are now, some of the Explain content + seeem redundant because host information, etc. is also stored + elsewhere. + + + + + + + + The XML below configures a server that accepts connections from + two ports, TCP/IP port 9900 and a local UNIX file socket. + We name the TCP/IP server public and the + other server internal. + + + + tcp:@:9900 + unix:/var/tmp/socket + + server1.mydomain + /var/www/s1 + config.cfg + + + server2.mydomain + /var/www/s2 + config.cfg + ../etc/pqf.properties + + + server2.mydomain + 9900 + a + + + + + /var/www/s3 + config.cfg + + +]]> + + + There are three configured backend servers. The first two + servers, "server1" and "server2", + can be reached by both listener addresses - since + no listenref attribute is specified. + In order to distinguish between the two a virtual host has + been specified for each of server in the host + elements. + + + For "server2" elements for CQL to RPN conversion + is supported and explain information has been added (a short one here + to keep the example small). + + + The third server, "server3" can only be reached + via listener "internal". + + + -- 1.7.10.4