doc/yaz-ztest-man.xml

   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"'>
   8 ]>
   9 <!-- $Id: yaz-ztest-man.xml,v 1.8 2006-04-24 12:41:00 marc Exp $ -->
  10 <refentry id="yaz-ztest">
  11
  12  <refmeta>
  13   <refentrytitle>yaz-ztest</refentrytitle>
  14   <manvolnum>8</manvolnum>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>yaz-ztest</refname>
  19   <refpurpose>Z39.50 Test Server</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <!--
  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
  27 -->
  28
  29 <cmdsynopsis>
  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>
  48 </cmdsynopsis>
  49
  50 <!-- Keep this Emacs mode comment at the end of the file
  51 Local variables:
  52 mode: nxml
  53 End:
  54 -->
  55
  56
  57  </refsynopsisdiv>
  58  <refsect1><title>DESCRIPTION</title>
  59   <para>
  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
  64    records.
  65   </para>
  66   <para>
  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>.
  71   </para>
  72   <para>
  73    For TCP and SSL, an address has the form:
  74    <screen>
  75     hostname | IP-number [ : portnumber ]
  76    </screen>
  77   </para>
  78   <para>
  79    For UNIX local socket the address is the filename of the local socket.
  80   </para>
  81  </refsect1>
  82  <refsect1>
  83   <title>OPTIONS</title>
  84
  85 <!--
  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
  89 -->
  90 <variablelist>
  91
  92  <varlistentry><term><literal>-a </literal>
  93    <replaceable>file</replaceable></term>
  94   <listitem><para>
  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>
  99
 100  <varlistentry><term><literal>-S</literal></term>
 101   <listitem><para>
 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
 106     current users.
 107    </para></listitem></varlistentry>
 108
 109  <varlistentry><term><literal>-1</literal></term>
 110   <listitem><para>
 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>
 114
 115  <varlistentry><term><literal>-T</literal></term>
 116   <listitem><para>
 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>
 121
 122  <varlistentry><term><literal>-s</literal></term>
 123   <listitem><para>
 124     Use the SR protocol (obsolete).
 125    </para></listitem></varlistentry>
 126
 127  <varlistentry><term><literal>-z</literal></term>
 128   <listitem><para>
 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>
 136
 137  <varlistentry><term><literal>-l </literal>
 138    <replaceable>file</replaceable></term>
 139   <listitem><para>The logfile.
 140    </para></listitem></varlistentry>
 141
 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>
 150
 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>
 156
 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>
 161
 162  <varlistentry><term><literal>-v </literal>
 163    <replaceable>level</replaceable></term>
 164   <listitem><para>
 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>
 168
 169  <varlistentry><term><literal>-u </literal>
 170    <replaceable>uid</replaceable></term>
 171   <listitem><para>
 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
 175     privileged port.
 176    </para></listitem></varlistentry>
 177
 178  <varlistentry><term><literal>-w </literal>
 179    <replaceable>dir</replaceable></term>
 180   <listitem><para>
 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>
 186
 187  <varlistentry><term><literal>-p </literal>
 188    <replaceable>pidfile</replaceable></term>
 189   <listitem><para>
 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>
 194
 195  <varlistentry><term><literal>-i</literal></term>
 196   <listitem><para>
 197     Use this to make the the server run from the
 198     <application>inetd</application> server (UNIX only).
 199    </para></listitem></varlistentry>
 200
 201  <varlistentry><term><literal>-D</literal></term>
 202   <listitem><para>
 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>
 207
 208  <varlistentry><term><literal>-install</literal></term>
 209   <listitem><para>
 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>
 214
 215  <varlistentry><term><literal>-installa</literal></term>
 216   <listitem><para>
 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>
 221
 222  <varlistentry><term><literal>-remove</literal></term>
 223   <listitem><para>
 224     Use this to remove the server from the NT services
 225     (Windows NT/2000/XP only).
 226    </para></listitem></varlistentry>
 227
 228  <varlistentry><term><literal>-t </literal>
 229    <replaceable>minutes</replaceable></term>
 230   <listitem><para>
 231     Idle session timeout, in minutes.
 232    </para></listitem></varlistentry>
 233
 234  <varlistentry><term><literal>-k </literal>
 235    <replaceable>size</replaceable></term>
 236   <listitem><para>
 237     Maximum record size/message size, in kilobytes.
 238    </para></listitem>
 239  </varlistentry>
 240
 241  <varlistentry><term><literal>-d </literal>
 242    <replaceable>daemon</replaceable></term>
 243   <listitem><para>
 244     Set name of daemon to be used in hosts access file.
 245     See
 246     <citerefentry>
 247      <refentrytitle>hosts_access</refentrytitle>
 248      <manvolnum>5</manvolnum>
 249     </citerefentry>
 250     and
 251     <citerefentry>
 252      <refentrytitle>tcpd</refentrytitle>
 253      <manvolnum>8</manvolnum>
 254     </citerefentry>.
 255    </para></listitem>
 256  </varlistentry>
 257
 258  <varlistentry><term><literal>-m </literal>
 259    <replaceable>time-format</replaceable></term>
 260   <listitem><para>
 261    Sets the format of time-stamps in the log-file. Specify a string in
 262    the input format to <literal>strftime()</literal>.
 263    </para></listitem>
 264  </varlistentry>
 265
 266 </variablelist>
 267 <!-- Keep this Emacs mode comment at the end of the file
 268 Local variables:
 269 mode: nxml
 270 End:
 271 -->
 272
 273
 274  </refsect1>
 275  <refsect1><title>VIRTUAL HOSTS</title>
 276   <!--
 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
 280 -->
 281
 282 <para>
 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.
 286 </para>
 287 <para>
 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
 292  be specified.
 293 </para>
 294 <para>
 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.
 298 </para>
 299 <note>
 300  <para>
 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).
 304  </para>
 305 </note>
 306 <para>
 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.
 310 </para>
 311 <para>
 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.
 315 </para>
 316 <para>
 317  The <literal>listen</literal> describes listener (transport end point),
 318  such as TCP/IP, Unix file socket or SSL server. Content for
 319  a listener:
 320  <variablelist>
 321   <varlistentry><term>CDATA (required)</term>
 322    <listitem>
 323     <para>
 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>,
 327      etc.
 328     </para>
 329    </listitem>
 330   </varlistentry>
 331   <varlistentry><term>attribute <literal>id</literal> (optional)</term>
 332     <listitem>
 333      <para>
 334       identifier for this listener. This may be referred to from
 335       server sections.
 336      </para>
 337     </listitem>
 338    </varlistentry>
 339  </variablelist>
 340  <note>
 341   <para>
 342    We expect more information to be added for the listen section in
 343    a future version, such as CERT file for SSL servers.
 344   </para>
 345  </note>
 346 </para>
 347 <para>
 348  The <literal>server</literal> describes a server and the parameters
 349  for this server type. Content for a server:
 350  <variablelist>
 351   <varlistentry><term>attribute <literal>id</literal> (optional)</term>
 352    <listitem>
 353     <para>
 354      Identifier for this server. Currently not used for anything,
 355      but it might be for logging purposes.
 356    </para>
 357    </listitem>
 358   </varlistentry>
 359
 360   <varlistentry><term>attribute <literal>listenref</literal> (optional)</term>
 361    <listitem>
 362     <para>
 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).
 367     </para>
 368    </listitem>
 369   </varlistentry>
 370
 371   <varlistentry><term>element <literal>config</literal> (optional)</term>
 372    <listitem>
 373     <para>
 374      Specifies the server configuration. This is equivalent
 375      to the config specified using command line option
 376      <literal>-c</literal>.
 377     </para>
 378    </listitem>
 379   </varlistentry>
 380
 381   <varlistentry><term>element <literal>directory</literal> (optional)</term>
 382    <listitem>
 383     <para>
 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).
 389     </para>
 390    </listitem>
 391   </varlistentry>
 392
 393   <varlistentry><term>element <literal>host</literal> (optional)</term>
 394    <listitem>
 395     <para>
 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.
 399     </para>
 400    </listitem>
 401   </varlistentry>
 402
 403   <varlistentry><term>element <literal>cql2rpn</literal> (optional)</term>
 404    <listitem>
 405     <para>
 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.
 409     </para>
 410    </listitem>
 411   </varlistentry>
 412
 413   <varlistentry><term>element <literal>stylesheet</literal> (optional)</term>
 414    <listitem>
 415     <para>
 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
 419      SRU HTTP response.
 420     </para>
 421    </listitem>
 422   </varlistentry>
 423
 424   <varlistentry><term>element <literal>docpath</literal> (optional)</term>
 425    <listitem>
 426     <para>
 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.
 433     </para>
 434    </listitem>
 435   </varlistentry>
 436
 437   <varlistentry><term>element <literal>explain</literal> (optional)</term>
 438    <listitem>
 439     <para>
 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
 443      elsewhere.
 444     </para>
 445    </listitem>
 446   </varlistentry>
 447  </variablelist>
 448 </para>
 449
 450 <para>
 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>.
 455  </para>
 456  <screen>
 457   <![CDATA[
 458  <yazgfs>
 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>
 465   </server>
 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/">
 472       <serverInfo>
 473         <host>server2.mydomain</host>
 474         <port>9900</port>
 475         <database>a</database>
 476       </serverInfo>
 477     </explain>
 478   </server>
 479   <server id="server3" listenref="internal">
 480     <directory>/var/www/s3</directory>
 481     <config>config.cfg</config>
 482   </server>
 483  </yazgfs>
 484 ]]>
 485  </screen>
 486 <para>
 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>
 493  elements.
 494 </para>
 495 <para>
 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).
 499 </para>
 500 <para>
 501  The third server, <literal>"server3"</literal> can only be reached
 502  via listener <literal>"internal"</literal>.
 503 </para>
 504
 505 <!-- Keep this Emacs mode comment at the end of the file
 506 Local variables:
 507 mode: nxml
 508 End:
 509 -->
 510
 511
 512  </refsect1>
 513  <refsect1><title>FILES</title>
 514   <para>
 515    <filename>yaz-&lt;version&gt;/ztest/yaz-ztest.c</filename>
 516   </para>
 517   <para>
 518    <filename>yaz-&lt;version&gt;/include/yaz/backend.h</filename>
 519   </para>
 520  </refsect1>
 521  <refsect1 id="tools.cql.map"><title>SEE ALSO</title>
 522   <para>
 523    <citerefentry>
 524     <refentrytitle>yaz</refentrytitle>
 525     <manvolnum>7</manvolnum></citerefentry>
 526   </para>
 527   <para>
 528    Section "Generic server" in the YAZ manual.
 529   </para>
 530  </refsect1>
 531 </refentry>
 532 <!-- Keep this Emacs mode comment at the end of the file
 533 Local variables:
 534 mode: nxml
 535 End:
 536 -->