X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fyaz-ztest-man.xml;h=d8f5fadab7fae9061db991f287acbd4c9e12be18;hp=0007b2b33862686e0781012a1163aced99dd318f;hb=f0fff840ae259cab0b1c17297c4367172a7cd229;hpb=ef696802e6afb3df60b27070a432a48f064dc777 diff --git a/doc/yaz-ztest-man.xml b/doc/yaz-ztest-man.xml index 0007b2b..d8f5fad 100644 --- a/doc/yaz-ztest-man.xml +++ b/doc/yaz-ztest-man.xml @@ -1,11 +1,12 @@ - - - - - + + + + + ]> - + @@ -19,7 +20,40 @@ - &gfs-synopsis; + + + + yaz-ztest + + + + + + + + + + + + + + + + + listener-spec + + + + + DESCRIPTION @@ -47,10 +81,434 @@ OPTIONS - &gfs-options; + + + + + -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 + . + + + + -m + time-format + + Sets the format of time-stamps in the log-file. Specify a string in + the input format to strftime(). + + + + + + + VIRTUAL HOSTS - &gfs-virtual; + + + + 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 section "Specifiction of CQL to RPN mappings" + If given, the backend server will only "see" a Type-1/RPN query. + + + + + element stylesheet (optional) + + + Specifies the stylesheet reference to be part of SRU HTTP responses + when the client does not specify one. If neither this is given, nor + the client specifies one, no stylesheet reference is part of the + SRU HTTP response. + + + + + element docpath (optional) + + + Specifies a path for local file access using HTTP. All URLs with + a leading prefix (/ exluded) that matches the value of docpath + are used for file access. For example, if the server is to offer + access in directory xsl, the docpath would be + xsl and all URLs of the form + http://host/exl will result in a local file access. + + + + + 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". + + + + + FILES @@ -71,18 +529,8 @@ - -