Provided by: yaz_2.1.8-4_i386 bug

NAME

       yaz-ztest - Z39.50 Test Server

SYNOPSIS

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

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

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

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.

              Note: 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.

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

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

FILES

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

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

SEE ALSO

       yaz(7)

       Section "Generic server" in the YAZ manual.

                                 08 July 2005                     YAZ-ZTEST(8)