yaz-ztest - Man Page

application [-install] [-installa] [-remove] [-a file] [-v level] [-l file] [-u uid] [-c config] [-f vconfig] [-C fname] [-t minutes] [-k kilobytes] [-K] [-d daemon] [-w dir] [-p pidfile] [-r kilobytes] [-ziDSTV1] [listener-spec...]

yaz-ztest is a Z39​.50/SRU test server that uses the YAZ generic front-end 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​.

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​.

-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 fork a process​. Only available on UNIX systems that offer 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

Specifies the PEM-encoded certificate chain and private key presented by the server for SSL connections​. If the certificate chain and private key are stored in the same file, specify certificate-file​. If they are stored in separate files, specify certificate-file,key-file​. If this option is not specified, a server operating in SSL mode uses yaz​.pem as the default certificate and private key file​.

-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 before listening to 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 the 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 the server as an NT service and mark it as "auto-start​. 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​.

-K

Forces no-keepalive for HTTP sessions​. By default GFS will keep sessions alive for HTTP 1​.1 sessions (as defined by the standard)​. Using this option will force GFS to close the connection for each operation​.

-r size

Maximum size of log file before rotation occurs, in kilobytes​. Default size is 1048576 k (=1 GB)​.

-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()​.

-V

Display YAZ version and exit​.

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, then 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 from 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 will 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​.

The Virtual hosts mechanism allows a YAZ front-end server to support multiple back-ends​. A back-end is selected on the basis of the TCP/IP binding (port+listening address) and/or the virtual host​.

A back-end can be configured to execute in a particular working directory​. Or the YAZ front-end may perform CQL to RPN conversion, thus allowing traditional Z39​.50 back-ends to be offered as a SRW/SRU service​. SRW/SRU Explain information for a particular back-end 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​.

The YAZ front-end server uses XML to describe the back-end 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​.

Note

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 one or more listeners for this server​. Each server ID is separated by a comma​. If this attribute is not given, the server is accessible from all listeners​. In order for the server to be used for real, however, 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 specified, the YAZ frontend 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 ???​. If given, the backend server will only "see" a Type-1/RPN query​.

element ccl2rpn (optional)

Specifies a filename that includes CCL to RPN conversion for this backend server​. See ???​. 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 none is given, then if the client does not specify one, then no stylesheet reference is part of the SRU HTTP response​.

element client_query_charset (optional)

If specified, a conversion from the character set given to UTF-8 is performed by the generic frontend server​. It is only executed for Z39​.50 search requests (SRU/Solr are assumed to be UTF-8 encoded already)​.

element docpath (optional)

Specifies a path for local file access using HTTP​. All URLs with a leading prefix (/ excluded) 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/xsl 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 seem redundant because host information, etc​. is also stored elsewhere​.

element maximumrecordsize (optional)

Specifies maximum record size/message size, in bytes​. This value also serves as the maximum size of incoming packages (for Record Updates etc)​. It's the same value as that given by the -k option​.

element retrievalinfo (optional)

Enables the retrieval facility to support conversions and specifications of record formats/types​. See ??? for more information​.

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​.

  
 <yazgfs>
  <listen id="public">tcp:@:9900</listen>
  <listen id="internal">unix:/var/tmp/socket</listen>
  <server id="server1">
    <host>server1​.mydomain</host>
    <directory>/var/www/s1</directory>
    <config>config​.cfg</config>
  </server>
  <server id="server2" listenref="public,internal">
    <host>server2​.mydomain</host>
    <directory>/var/www/s2</directory>
    <config>config​.cfg</config>
    <cql2rpn>​.​./etc/pqf​.properties</cql2rpn>
    <explain xmlns="http://explain​.z3950​.org/dtd/2​.0/">
      <serverInfo>
        <host>server2​.mydomain</host>
        <port>9900</port>
        <database>a</database>
      </serverInfo>
    </explain>
  </server>
  <server id="server3" listenref="internal">
    <directory>/var/www/s3</directory>
    <config>config​.cfg</config>
  </server>
 </yazgfs>

There are three configured backend servers​. The first two servers, "server1" and "server2", can be reached by both listener addresses​. "server1" is reached by all (two) since no listenref attribute is specified​. "server2" is reached by the two listeners specified​. In order to distinguish between the two, a virtual host has been specified for each 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"​.

yaz-<version>/ztest/yaz-ztest​.c

yaz-<version>/include/yaz/backend​.h

yaz(7) yaz-log(7)

Index Data

yaz(7), yaz-log(7), zoomsh(1).