'\" t
.\"     Title: yaz-ztest
.\"    Author: Index Data
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/19/2023
.\"    Manual: System management commands
.\"    Source: YAZ 5.34.0
.\"  Language: English
.\"
.TH "YAZ\-ZTEST" "8" "01/19/2023" "YAZ 5.34.0" "System management commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
yaz-ztest \- Z39\&.50/SRU Test Server
.SH "SYNOPSIS"
.HP \w'\fBapplication\fR\ 'u
\fBapplication\fR [\fB\-install\fR] [\fB\-installa\fR] [\fB\-remove\fR] [\fB\-a\ \fR\fB\fIfile\fR\fR] [\fB\-v\ \fR\fB\fIlevel\fR\fR] [\fB\-l\ \fR\fB\fIfile\fR\fR] [\fB\-u\ \fR\fB\fIuid\fR\fR] [\fB\-c\ \fR\fB\fIconfig\fR\fR] [\fB\-f\ \fR\fB\fIvconfig\fR\fR] [\fB\-C\ \fR\fB\fIfname\fR\fR] [\fB\-t\ \fR\fB\fIminutes\fR\fR] [\fB\-k\ \fR\fB\fIkilobytes\fR\fR] [\fB\-K\fR] [\fB\-d\ \fR\fB\fIdaemon\fR\fR] [\fB\-w\ \fR\fB\fIdir\fR\fR] [\fB\-p\ \fR\fB\fIpidfile\fR\fR] [\fB\-r\ \fR\fB\fIkilobytes\fR\fR] [\fB\-ziDSTV1\fR] [listener\-spec...]
.SH "DESCRIPTION"
.PP
\fByaz\-ztest\fR
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\&.
.PP
The
\fIlistener\-spec\fR
consists of a transport mode followed by a colon, followed by a listener address\&. The transport mode is either
tcp,
unix, or
ssl\&.
.PP
For TCP and SSL, an address has the form:
.sp
.if n \{\
.RS 4
.\}
.nf
    hostname | IP\-number [ : portnumber ]
   
.fi
.if n \{\
.RE
.\}
.PP
For UNIX local socket, the address is the filename of the local socket\&.
.SH "OPTIONS"
.PP
\-a \fIfile\fR
.RS 4
Specify a file for dumping PDUs (for diagnostic purposes)\&. The special name
\-
(dash) sends output to
stderr\&.
.RE
.PP
\-S
.RS 4
Don\*(Aqt 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\&.
.RE
.PP
\-1
.RS 4
Like
\-S
but after one session the server exits\&. This mode is for debugging
\fIonly\fR\&.
.RE
.PP
\-T
.RS 4
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\&.
.RE
.PP
\-s
.RS 4
Use the SR protocol (obsolete)\&.
.RE
.PP
\-z
.RS 4
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\&.
.RE
.PP
\-l \fIfile\fR
.RS 4
The logfile\&.
.RE
.PP
\-c \fIconfig\fR
.RS 4
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\&.
.RE
.PP
\-f \fIvconfig\fR
.RS 4
This specifies an XML file that describes one or more YAZ frontend virtual servers\&.
.RE
.PP
\-C \fIfname\fR
.RS 4
Sets SSL certificate file name for server (PEM)\&.
.RE
.PP
\-v \fIlevel\fR
.RS 4
The log level\&. Use a comma\-separated list of members of the set {fatal,debug,warn,log,malloc,all,none}\&.
.RE
.PP
\-u \fIuid\fR
.RS 4
Set user ID\&. Sets the real UID of the server process to that of the given user\&. It\*(Aqs useful if you aren\*(Aqt comfortable with having the server run as root, but you need to start it as such to bind a privileged port\&.
.RE
.PP
\-w \fIdir\fR
.RS 4
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)\&.
.RE
.PP
\-p \fIpidfile\fR
.RS 4
Specifies that the server should write its Process ID to the file given by
\fIpidfile\fR\&. A typical location would be
/var/run/yaz\-ztest\&.pid\&.
.RE
.PP
\-i
.RS 4
Use this to make the the server run from the
inetd
server (UNIX only)\&.
.RE
.PP
\-D
.RS 4
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\&.
.RE
.PP
\-install
.RS 4
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\&.
.RE
.PP
\-installa
.RS 4
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\&.
.RE
.PP
\-remove
.RS 4
Use this to remove the server from the NT services (Windows NT/2000/XP only)\&.
.RE
.PP
\-t \fIminutes\fR
.RS 4
Idle session timeout, in minutes\&.
.RE
.PP
\-k \fIsize\fR
.RS 4
Maximum record size/message size, in kilobytes\&.
.RE
.PP
\-K
.RS 4
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\&.
.RE
.PP
\-r \fIsize\fR
.RS 4
Maximum size of log file before rotation occurs, in kilobytes\&. Default size is 1048576 k (=1 GB)\&.
.RE
.PP
\-d \fIdaemon\fR
.RS 4
Set name of daemon to be used in hosts access file\&. See
\fBhosts_access\fR(5)
and
\fBtcpd\fR(8)\&.
.RE
.PP
\-m \fItime\-format\fR
.RS 4
Sets the format of time\-stamps in the log\-file\&. Specify a string in the input format to
strftime()\&.
.RE
.PP
\-V
.RS 4
Display YAZ version and exit\&.
.RE
.SH "TESTING"
.PP
\fByaz\-ztest\fR
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\&.
\fByaz\-ztest\fR
includes 24 MARC records for testing\&. Hit counts exceeding 24 will make
\fByaz\-ztest\fR
return the same record batch over and over\&. So record at position 1, 25, 49, etc\&. are equivalent\&.
.PP
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\&.
.PP
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
\fIF\fR\fIE\fR\&.\fId\fR\&.xml
where
\fIF\fR
is the YAZ_ZTEST_XML_FETCH value (possibly empty),
\fIE\fR
is element\-set,
\fId\fR
is record position (starting from 1)\&.
.PP
The following databases are honored by
\fByaz\-ztest\fR:
Default,
slow
and
db\&.*
(all databases with prefix "db")\&. Any other database will make
\fByaz\-ztest\fR
return diagnostic 109: "Database unavailable"\&.
.PP
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\&.
.PP
The former, delay type options, specify a fake delay (sleep) that
\fByaz\-ztest\fR
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
\fByaz\-ztest\fR
perform a random sleep between the first and second number\&.
.PP
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\&.
.PP
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\*(Aqd use:
Default?search\-delay=0\&.1:0\&.5&fetch\-delay=0\&.2\&.
.SH "GFS CONFIGURATION AND VIRTUAL HOSTS"
.PP
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\&.
.PP
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\&.
.PP
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Not all Z39\&.50 clients allow the VHOST information to be set\&. For those, the selection of the back\-end must rely on the TCP/IP information alone (port and address)\&.
.sp .5v
.RE
.PP
The YAZ front\-end server uses XML to describe the back\-end configurations\&. Command\-line option
\-f
specifies filename of the XML configuration\&.
.PP
The configuration uses the root element
yazgfs\&. This element includes a list of
listen
elements, followed by one or more
server
elements\&.
.PP
The
listen
describes listener (transport end point), such as TCP/IP, Unix file socket or SSL server\&. Content for a listener:
.PP
CDATA (required)
.RS 4
The CDATA for the
listen
element holds the listener string, such as
tcp:@:210,
tcp:server1:2100, etc\&.
.RE
.PP
attribute id (optional)
.RS 4
Identifier for this listener\&. This may be referred to from server sections\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
We expect more information to be added for the listen section in a future version, such as CERT file for SSL servers\&.
.sp .5v
.RE
.PP
The
server
describes a server and the parameters for this server type\&. Content for a server:
.PP
attribute id (optional)
.RS 4
Identifier for this server\&. Currently not used for anything, but it might be for logging purposes\&.
.RE
.PP
attribute listenref (optional)
.RS 4
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\&.
.RE
.PP
element config (optional)
.RS 4
Specifies the server configuration\&. This is equivalent to the config specified using command line option
\-c\&.
.RE
.PP
element directory (optional)
.RS 4
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)\&.
.RE
.PP
element host (optional)
.RS 4
Specifies the virtual host for this server\&. If this is specified a client
\fImust\fR
specify this host string in order to use this backend\&.
.RE
.PP
element cql2rpn (optional)
.RS 4
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\&.
.RE
.PP
element ccl2rpn (optional)
.RS 4
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\&.
.RE
.PP
element stylesheet (optional)
.RS 4
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\&.
.RE
.PP
element client_query_charset (optional)
.RS 4
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)\&.
.RE
.PP
element docpath (optional)
.RS 4
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\&.
.RE
.PP
element explain (optional)
.RS 4
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\&.
.RE
.PP
element maximumrecordsize (optional)
.RS 4
Specifies maximum record size/message size, in bytes\&. This value also serves as the maximum size of
\fIincoming\fR
packages (for Record Updates etc)\&. It\*(Aqs the same value as that given by the
\-k
option\&.
.RE
.PP
element retrievalinfo (optional)
.RS 4
Enables the retrieval facility to support conversions and specifications of record formats/types\&. See
???
for more information\&.
.RE
.PP
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
  
 <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>

 
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
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)\&.
.PP
The third server,
"server3"
can only be reached via listener
"internal"\&.
.SH "FILES"
.PP
yaz\-<version>/ztest/yaz\-ztest\&.c
.PP
yaz\-<version>/include/yaz/backend\&.h
.SH "SEE ALSO"
.PP
\fByaz\fR(7)
\fByaz-log\fR(7)
.SH "AUTHORS"
.PP
\fBIndex Data\fR