X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fyaz-ztest-man.xml;h=dfa1b3a96082da1ff39593ba7a27e53dfd1f356f;hp=d8f5fadab7fae9061db991f287acbd4c9e12be18;hb=cca8a96be6d6ce6de52009e53e23876ce2fc195c;hpb=f0fff840ae259cab0b1c17297c4367172a7cd229;ds=sidebyside diff --git a/doc/yaz-ztest-man.xml b/doc/yaz-ztest-man.xml index d8f5fad..dfa1b3a 100644 --- a/doc/yaz-ztest-man.xml +++ b/doc/yaz-ztest-man.xml @@ -1,65 +1,42 @@ - - - - - + + %local; + + %entities; + + %idcommon; + + + ]> - - + + YAZ + &version; + Index Data + + yaz-ztest 8 + System management commands - + yaz-ztest - Z39.50 Test Server + Z39.50/SRU Test Server - - - - - - yaz-ztest - - - - - - - - - - - - - - - - - listener-spec - - - - + + &gfs-synopsis; DESCRIPTION - yaz-ztest is a Z39.50 test server that uses - the YAZ generic frontend server API. - The server acts as a real Z39.50 server but does not use a database. + yaz-ztest is a Z39.50/SRU test server that uses + the YAZ generic frontend server (GFS) API. + The server acts as a real Z39.50/SRU server but does not use a database. It returns a random hit count and returns a subset of a few built-in records. @@ -81,434 +58,72 @@ End: 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(). - - - - - - - + &gfs-options; - VIRTUAL HOSTS - - - - 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. + + TESTING + + yaz-ztest normally returns a random hit count between + 0 and 24. However, if a query term includes leading digits, then the + integer value of that term is used as hit count. This allows testers + to return any number of hits. yaz-ztest includes + 24 MARC records for testing. Hit counts exceeding 24 will make + yaz-ztest return the same record batch over and over.. + So record at position 1, 25, 49, etc .. are equivalent. + + + For XML if no element set is given or element has value "marcxml", + MARCXML is returned (each of the 24 dummy records converted from + ISO2709 to XML). For element set OP, OPAC XML is returned. + + + yaz-ztest may also return predefined XML records (for testing). + This is enabled if YAZ_ZTEST_XML_FETCH environment + variable is defined. A record is fetched form a file (one record per file). + The path for the filename is + FE.d.xml + where F is the YAZ_ZTEST_XML_FETCH value + (possibly + empty), E is element-set, + d is record position (starting from 1). + + + The following databases are honored by yaz-ztest: + Default, slow + and db.* (all databases with prefix "db"). Any + other database will make yaz-ztest return diagnostic + 109: "Database unavailable". + + + Options for search may be included in the form or URL get arguments + included as part of the Z39.50 database name. The following + database options are present: search-delay, + present-delay, fetch-delay + and seed. + + + The former, delay type options, specify + a fake delay (sleep) that yaz-ztest will perform + when searching, presenting, fetching records respectively. + The value of the delay may either be a fixed floating point + value which specifies the delay in seconds. + Alternatively the value may be given as two floating point numbers + separated by colon, which wil make yaz-ztest perform + a random sleep between the first and second number. + + + The database parameter seed takes an integer + as value. This will call srand with this integer to + ensure that the random behavior can be re-played. + + + Suppose we want searches to take between 0.1 and 0.5 seconds and + a fetch to take 0.2 second. To access test database Default we'd use: + Default?search-delay=0.1:0.5&fetch-delay=0.2. - - - - 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". - - - - - + + GFS CONFIGURATION AND VIRTUAL HOSTS + &gfs-virtual; FILES @@ -518,19 +133,31 @@ End: yaz-<version>/include/yaz/backend.h - SEE ALSO + SEE ALSO yaz - 7 - - - Section "Generic server" in the YAZ manual. + 7 + + + yaz-log + 7 + -