1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" [
3 <!ENTITY gfs-options SYSTEM "gfs-options.xml">
4 <!ENTITY gfs-virtual SYSTEM "gfs-virtual.xml">
5 <!ENTITY gfs-synopsis SYSTEM "gfs-synopsis.xml">
6 <!ENTITY gfs-synopsis-app "yaz-ztest">
7 <!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
9 <!-- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $ -->
10 <refentry id="yaz-ztest">
13 <refentrytitle>yaz-ztest</refentrytitle>
14 <manvolnum>8</manvolnum>
18 <refname>yaz-ztest</refname>
19 <refpurpose>Z39.50 Test Server</refpurpose>
24 $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
25 cmd description of YAZ GFS application.
26 Included in both manual and man page for yaz-ztest
30 <command>yaz-ztest</command>
31 <arg choice="opt"><option>-install</option></arg>
32 <arg choice="opt"><option>-installa</option></arg>
33 <arg choice="opt"><option>-remove</option></arg>
34 <arg choice="opt"><option>-a <replaceable>file</replaceable></option></arg>
35 <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
36 <arg choice="opt"><option>-l <replaceable>file</replaceable></option></arg>
37 <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
38 <arg choice="opt"><option>-c <replaceable>config</replaceable></option></arg>
39 <arg choice="opt"><option>-f <replaceable>vconfig</replaceable></option></arg>
40 <arg choice="opt"><option>-C <replaceable>fname</replaceable></option></arg>
41 <arg choice="opt"><option>-t <replaceable>minutes</replaceable></option></arg>
42 <arg choice="opt"><option>-k <replaceable>kilobytes</replaceable></option></arg>
43 <arg choice="opt"><option>-d <replaceable>daemon</replaceable></option></arg>
44 <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
45 <arg choice="opt"><option>-p <replaceable>pidfile</replaceable></option></arg>
46 <arg choice="opt"><option>-ziDST1</option></arg>
47 <arg choice="opt" rep="repeat">listener-spec</arg>
50 <!-- Keep this Emacs mode comment at the end of the file
58 <refsect1><title>DESCRIPTION</title>
60 <command>yaz-ztest</command> is a Z39.50 test server that uses
61 the YAZ generic frontend server API.
62 The server acts as a real Z39.50 server but does not use a database.
63 It returns a random hit count and returns a subset of a few built-in
67 The <replaceable>listener-spec</replaceable> consists of a transport
68 mode followed by a colon, followed by a listener address. The
69 transport mode is either <literal>tcp</literal>, <literal>unix</literal>,
70 or <literal>ssl</literal>.
73 For TCP and SSL, an address has the form:
75 hostname | IP-number [ : portnumber ]
79 For UNIX local socket the address is the filename of the local socket.
83 <title>OPTIONS</title>
86 $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
87 Options for generic frontend server and yaz-ztest.
88 Included in both manual and man page for yaz-ztest
92 <varlistentry><term><literal>-a </literal>
93 <replaceable>file</replaceable></term>
95 Specify a file for dumping PDUs (for diagnostic purposes).
96 The special name <literal>-</literal> (dash) sends output to
97 <literal>stderr</literal>.
98 </para></listitem></varlistentry>
100 <varlistentry><term><literal>-S</literal></term>
102 Don't fork or make threads on connection requests. This is good for
103 debugging, but not recommended for real operation: Although the
104 server is asynchronous and non-blocking, it can be nice to keep
105 a software malfunction (okay then, a crash) from affecting all
107 </para></listitem></varlistentry>
109 <varlistentry><term><literal>-1</literal></term>
111 Like <literal>-S</literal> but after one session the server
112 exits. This mode is for debugging <emphasis>only</emphasis>.
113 </para></listitem></varlistentry>
115 <varlistentry><term><literal>-T</literal></term>
117 Operate the server in threaded mode. The server creates a thread
118 for each connection rather than a fork a process. Only available
119 on UNIX systems that offers POSIX threads.
120 </para></listitem></varlistentry>
122 <varlistentry><term><literal>-s</literal></term>
124 Use the SR protocol (obsolete).
125 </para></listitem></varlistentry>
127 <varlistentry><term><literal>-z</literal></term>
129 Use the Z39.50 protocol (default). This option and <literal>-s</literal>
130 complement each other.
131 You can use both multiple times on the same command
132 line, between listener-specifications (see below). This way, you
133 can set up the server to listen for connections in both protocols
134 concurrently, on different local ports.
135 </para></listitem></varlistentry>
137 <varlistentry><term><literal>-l </literal>
138 <replaceable>file</replaceable></term>
139 <listitem><para>The logfile.
140 </para></listitem></varlistentry>
142 <varlistentry><term><literal>-c </literal>
143 <replaceable>config</replaceable></term>
144 <listitem><para>A user option that serves as a specifier for some
145 sort of configuration, usually a filename.
146 The argument to this option is transferred to member
147 <literal>configname</literal> of the
148 <literal>statserv_options_block</literal>.
149 </para></listitem></varlistentry>
151 <varlistentry><term><literal>-f </literal>
152 <replaceable>vconfig</replaceable></term>
153 <listitem><para>This specifies an XML file that describes
154 one or more YAZ frontend virtual servers.
155 </para></listitem></varlistentry>
157 <varlistentry><term><literal>-C </literal>
158 <replaceable>fname</replaceable></term>
159 <listitem><para>Sets SSL certificate file name for server (PEM).
160 </para></listitem></varlistentry>
162 <varlistentry><term><literal>-v </literal>
163 <replaceable>level</replaceable></term>
165 The log level. Use a comma-separated list of members of the set
166 {fatal,debug,warn,log,malloc,all,none}.
167 </para></listitem></varlistentry>
169 <varlistentry><term><literal>-u </literal>
170 <replaceable>uid</replaceable></term>
172 Set user ID. Sets the real UID of the server process to that of the
173 given user. It's useful if you aren't comfortable with having the
174 server run as root, but you need to start it as such to bind a
176 </para></listitem></varlistentry>
178 <varlistentry><term><literal>-w </literal>
179 <replaceable>dir</replaceable></term>
181 The server changes to this directory during before listening
182 on incoming connections. This option is useful
183 when the server is operating from the <application>inetd</application>
184 daemon (see <literal>-i</literal>).
185 </para></listitem></varlistentry>
187 <varlistentry><term><literal>-p </literal>
188 <replaceable>pidfile</replaceable></term>
190 Specifies that the server should write its Process ID to
191 file given by <replaceable>pidfile</replaceable>.
192 A typical location would be <filename>/var/run/yaz-ztest.pid</filename>.
193 </para></listitem></varlistentry>
195 <varlistentry><term><literal>-i</literal></term>
197 Use this to make the the server run from the
198 <application>inetd</application> server (UNIX only).
199 </para></listitem></varlistentry>
201 <varlistentry><term><literal>-D</literal></term>
203 Use this to make the server put itself in the background and
204 run as a daemon. If neither <literal>-i</literal> nor
205 <literal>-D</literal> is given, the server starts in the foreground.
206 </para></listitem></varlistentry>
208 <varlistentry><term><literal>-install</literal></term>
210 Use this to install the server as an NT service
211 (Windows NT/2000/XP only).
212 Control the server by going to the Services in the Control Panel.
213 </para></listitem></varlistentry>
215 <varlistentry><term><literal>-installa</literal></term>
217 Use this to install and activate the server as an NT service
218 (Windows NT/2000/XP only).
219 Control the server by going to the Services in the Control Panel.
220 </para></listitem></varlistentry>
222 <varlistentry><term><literal>-remove</literal></term>
224 Use this to remove the server from the NT services
225 (Windows NT/2000/XP only).
226 </para></listitem></varlistentry>
228 <varlistentry><term><literal>-t </literal>
229 <replaceable>minutes</replaceable></term>
231 Idle session timeout, in minutes.
232 </para></listitem></varlistentry>
234 <varlistentry><term><literal>-k </literal>
235 <replaceable>size</replaceable></term>
237 Maximum record size/message size, in kilobytes.
241 <varlistentry><term><literal>-d </literal>
242 <replaceable>daemon</replaceable></term>
244 Set name of daemon to be used in hosts access file.
247 <refentrytitle>hosts_access</refentrytitle>
248 <manvolnum>5</manvolnum>
252 <refentrytitle>tcpd</refentrytitle>
253 <manvolnum>8</manvolnum>
258 <varlistentry><term><literal>-m </literal>
259 <replaceable>time-format</replaceable></term>
261 Sets the format of time-stamps in the log-file. Specify a string in
262 the input format to <literal>strftime()</literal>.
267 <!-- Keep this Emacs mode comment at the end of the file
275 <refsect1><title>VIRTUAL HOSTS</title>
277 $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $
278 Description of the virtual host mechanism in YAZ GFS
279 Included in both manual and man page for yaz-ztest
283 The Virtual hosts mechanism allows a YAZ frontend server to
284 support multiple backends. A backend is selected on the basis of
285 the TCP/IP binding (port+listening adddress) and/or the virtual host.
288 A backend can be configured to execute in a particular working
289 directory. Or the YAZ frontend may perform CQL to RPN conversion, thus
290 allowing traditional Z39.50 backends to be offered as a SRW/SRU
291 service. SRW/SRU Explain information for a particular backend may also
295 For the HTTP protocol, the virtual host is specified in the Host header.
296 For the Z39.50 protocol, the virtual host is specified as in the
297 Initialize Request in the OtherInfo, OID 1.2.840.10003.10.1000.81.1.
301 Not all Z39.50 clients allows the VHOST information to be set.
302 For those the selection of the backend must rely on the
303 TCP/IP information alone (port and address).
307 The YAZ frontend server uses XML to describe the backend
308 configurations. Command-line option <literal>-f</literal>
309 specifies filename of the XML configuration.
312 The configuration uses the root element <literal>yazgfs</literal>.
313 This element includes a list of <literal>listen</literal> elements,
314 followed by one or more <literal>server</literal> elements.
317 The <literal>listen</literal> describes listener (transport end point),
318 such as TCP/IP, Unix file socket or SSL server. Content for
321 <varlistentry><term>CDATA (required)</term>
324 The CDATA for the <literal>listen</literal> element holds the
325 listener string, such as <literal>tcp:@:210</literal>,
326 <literal>tcp:server1:2100</literal>,
331 <varlistentry><term>attribute <literal>id</literal> (optional)</term>
334 identifier for this listener. This may be referred to from
342 We expect more information to be added for the listen section in
343 a future version, such as CERT file for SSL servers.
348 The <literal>server</literal> describes a server and the parameters
349 for this server type. Content for a server:
351 <varlistentry><term>attribute <literal>id</literal> (optional)</term>
354 Identifier for this server. Currently not used for anything,
355 but it might be for logging purposes.
360 <varlistentry><term>attribute <literal>listenref</literal> (optional)</term>
363 Specifies listener for this server. If this attribute is not
364 given, the server is accessible from all listener. In order
365 for the server to be used for real, howeever, the virtual host
366 must match (if specified in the configuration).
371 <varlistentry><term>element <literal>config</literal> (optional)</term>
374 Specifies the server configuration. This is equivalent
375 to the config specified using command line option
376 <literal>-c</literal>.
381 <varlistentry><term>element <literal>directory</literal> (optional)</term>
384 Specifies a working directory for this backend server. If
385 specifid, the YAZ fronend changes current working directory
386 to this directory whenever a backend of this type is
387 started (backend handler bend_start), stopped (backend handler hand_stop)
388 and initialized (bend_init).
393 <varlistentry><term>element <literal>host</literal> (optional)</term>
396 Specifies the virtual host for this server. If this is specified
397 a client <emphasis>must</emphasis> specify this host string in
398 order to use this backend.
403 <varlistentry><term>element <literal>cql2rpn</literal> (optional)</term>
406 Specifies a filename that includes CQL to RPN conversion for this
407 backend server. See section "Specifiction of CQL to RPN mappings"
408 If given, the backend server will only "see" a Type-1/RPN query.
413 <varlistentry><term>element <literal>stylesheet</literal> (optional)</term>
416 Specifies the stylesheet reference to be part of SRU HTTP responses
417 when the client does not specify one. If neither this is given, nor
418 the client specifies one, no stylesheet reference is part of the
424 <varlistentry><term>element <literal>docpath</literal> (optional)</term>
427 Specifies a path for local file access using HTTP. All URLs with
428 a leading prefix (/ exluded) that matches the value of docpath
429 are used for file access. For example, if the server is to offer
430 access in directory <literal>xsl</literal>, the docpath would be
431 <literal>xsl</literal> and all URLs of the form
432 <literal>http://host/exl</literal> will result in a local file access.
437 <varlistentry><term>element <literal>explain</literal> (optional)</term>
440 Specifies SRW/SRU ZeeRex content for this server. Copied verbatim
441 to the client. As things are now, some of the Explain content
442 seeem redundant because host information, etc. is also stored
451 The XML below configures a server that accepts connections from
452 two ports, TCP/IP port 9900 and a local UNIX file socket.
453 We name the TCP/IP server <literal>public</literal> and the
454 other server <literal>internal</literal>.
459 <listen id="public">tcp:@:9900</listen>
460 <listen id="internal">unix:/var/tmp/socket</listen>
461 <server id="server1">
462 <host>server1.mydomain</host>
463 <directory>/var/www/s1</directory>
464 <config>config.cfg</config>
466 <server id="server2">
467 <host>server2.mydomain</host>
468 <directory>/var/www/s2</directory>
469 <config>config.cfg</config>
470 <cql2rpn>../etc/pqf.properties</cql2rpn>
471 <explain xmlns="http://explain.z3950.org/dtd/2.0/">
473 <host>server2.mydomain</host>
475 <database>a</database>
479 <server id="server3" listenref="internal">
480 <directory>/var/www/s3</directory>
481 <config>config.cfg</config>
487 There are three configured backend servers. The first two
488 servers, <literal>"server1"</literal> and <literal>"server2"</literal>,
489 can be reached by both listener addresses - since
490 no <literal>listenref</literal> attribute is specified.
491 In order to distinguish between the two a virtual host has
492 been specified for each of server in the <literal>host</literal>
496 For <literal>"server2"</literal> elements for CQL to RPN conversion
497 is supported and explain information has been added (a short one here
498 to keep the example small).
501 The third server, <literal>"server3"</literal> can only be reached
502 via listener <literal>"internal"</literal>.
505 <!-- Keep this Emacs mode comment at the end of the file
513 <refsect1><title>FILES</title>
515 <filename>yaz-<version>/ztest/yaz-ztest.c</filename>
518 <filename>yaz-<version>/include/yaz/backend.h</filename>
521 <refsect1 id="tools.cql.map"><title>SEE ALSO</title>
524 <refentrytitle>yaz</refentrytitle>
525 <manvolnum>7</manvolnum></citerefentry>
528 Section "Generic server" in the YAZ manual.
532 <!-- Keep this Emacs mode comment at the end of the file