<!-- 
   Options for generic frontend server and yaz-ztest.
   Included in both manual and man page for yaz-ztest
   Note - these files have been altered for zebrasrv, and are not in
   sync any more!!
-->

<variablelist>
 
 <varlistentry><term><literal>-a </literal>
   <replaceable>file</replaceable></term>
  <listitem><para>
    Specify a file for dumping PDUs (for diagnostic purposes).
    The special name <literal>-</literal> (dash) sends output to
    <literal>stderr</literal>.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-S</literal></term>
  <listitem><para>
    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. The server can only accept a single
       connection in this mode.
   </para></listitem></varlistentry>
<!-- The text for -S option is (in my opinion) the wrong way around. The main
argument for not using -S is that it can handle only one connection at a
time, whereas the forking and threading interfaces can handle multiple
connections. Also, the forking (but not threading) model can survive a
crash at a single server instance. Heikki -->

 
 <varlistentry><term><literal>-1</literal></term>
  <listitem><para>
    Like <literal>-S</literal> but after one session the server
    exits. This mode is for debugging <emphasis>only</emphasis>.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-T</literal></term>
  <listitem><para>
    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.
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-s</literal></term>
  <listitem><para>
    Use the SR protocol (obsolete).
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-z</literal></term>
  <listitem><para>
    Use the &acro.z3950; protocol (default). This option and <literal>-s</literal>
    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.
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-l </literal>
   <replaceable>file</replaceable></term>
  <listitem><para>
    Specify an output file for the diagnostic messages.
       The default is to write this information to
   <literal>stderr</literal>
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-c </literal>
   <replaceable>config-file</replaceable></term>
  <listitem><para> Read configuration information from
       <replaceable>config-file</replaceable>.
       The default configuration is <literal>./zebra.cfg</literal>
  </para></listitem></varlistentry>

 <varlistentry><term><literal>-f </literal>
   <replaceable>vconfig</replaceable></term>
  <listitem><para>This specifies an &acro.xml; file that describes
    one or more &yaz; frontend virtual servers. See section VIRTUAL
   HOSTS for details.
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-C </literal>
   <replaceable>fname</replaceable></term>
  <listitem><para>Sets SSL certificate file name for server (PEM).
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-v </literal>
   <replaceable>level</replaceable></term>
  <listitem><para>
    The log level. Use a comma-separated list of members of the set
    {fatal,debug,warn,log,malloc,all,none}.
   </para></listitem></varlistentry>
<!-- The -v option (for log level) is not enough. There are many more
log switches than the simple levels you mention, and more can (and will)
be defined in (loadable?) modules. You can get them all listed in the
log file with '-v loglevel'. Most users will at least have interest in 
'server', 'session', 'request', and 'requestdetail', and possibly
'searchhits', 'searchterms', 'resultsets', 'rpn'. And maybe many more...
I ought to write a script that greps the bits from the source code -
that is the only way to get to them, there is no longer any central
repository for them. No idea how to explain this neatly in the man
page...
Heikki -->


 <varlistentry><term><literal>-u </literal>
   <replaceable>uid</replaceable></term>
  <listitem><para>
    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.
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-w </literal>
   <replaceable>working-directory</replaceable></term>
  <listitem><para>
    The server changes to this working directory during before listening 
    on incoming connections. This option is useful
    when the server is operating from the <application>inetd</application>
    daemon (see <literal>-i</literal>).
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-p </literal>
   <replaceable>pidfile</replaceable></term>
  <listitem><para>
    Specifies that the server should write its Process ID to
    file given by <replaceable>pidfile</replaceable>. 
    A typical location would be <filename>/var/run/zebrasrv.pid</filename>.
   </para></listitem></varlistentry>

 <varlistentry><term><literal>-i</literal></term>
  <listitem><para>
    Use this to make the the server run from the
    <application>inetd</application> server (UNIX only).
     Make sure you use the logfile option <literal>-l</literal> in
       conjunction with this mode and specify the <literal>-l</literal>
       option before any other options.
   </para></listitem></varlistentry>
<!--
-i: Better say "use this when the server is run from inetd", than "use
this to make the server run from inetd", as the option itself will only
tell zebra that it should assume that inetd started it.
Heikki --> 


 <varlistentry><term><literal>-D</literal></term>
  <listitem><para>
    Use this to make the server put itself in the background and
    run as a daemon. If neither <literal>-i</literal> nor 
    <literal>-D</literal> is given, the server starts in the foreground.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-install</literal></term>
  <listitem><para>
    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.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-installa</literal></term>
  <listitem><para>
    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.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-remove</literal></term>
  <listitem><para>
    Use this to remove the server from the NT services
    (Windows NT/2000/XP only). 
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-t </literal>
   <replaceable>minutes</replaceable></term>
  <listitem><para>
    Idle session timeout, in minutes. Default is 60 minutes.
   </para></listitem></varlistentry>
 
 <varlistentry><term><literal>-k </literal>
   <replaceable>size</replaceable></term>
  <listitem><para>
    Maximum record size/message size, in kilobytes. Default is 1024 KB (1 MB).
   </para></listitem>
 </varlistentry>

 <varlistentry><term><literal>-d </literal>
   <replaceable>daemon</replaceable></term>
  <listitem><para>
    Set name of daemon to be used in hosts access file.
    See
    <citerefentry>
     <refentrytitle>hosts_access</refentrytitle>
     <manvolnum>5</manvolnum>
    </citerefentry>
    and 
    <citerefentry>
     <refentrytitle>tcpd</refentrytitle>
     <manvolnum>8</manvolnum>
    </citerefentry>.
   </para></listitem>
 </varlistentry>
 
</variablelist>


  <para>
   A <replaceable>listener-address</replaceable> consists of an optional
   transport mode followed by a colon (:) followed by a listener address.
   The transport mode is either a file system socket
   <literal>unix</literal>,
   a SSL TCP/IP socket <literal>ssl</literal>, or a plain TCP/IP socket
   <literal>tcp</literal> (default).
  </para>

  <para>
   For TCP, an address has the form
   <screen>
    hostname | IP-number [: portnumber]
   </screen>
   The port number defaults to 210 (standard &acro.z3950; port) for
   privileged users (root), and 9999 for normal users.
   The special hostname "@" is mapped to
   the address INADDR_ANY, which causes the server to listen on any local
   interface.   </para>

  <para>
   The default behavior for <literal>zebrasrv</literal> - if started
   as non-privileged user - is to establish
   a single TCP/IP listener, for the &acro.z3950; protocol, on port 9999.
   <screen>
    zebrasrv @
    zebrasrv tcp:some.server.name.org:1234
    zebrasrv ssl:@:3000
   </screen>
  </para>

  <para>
   To start the server listening on the registered port for
   &acro.z3950;, or on a filesystem socket, 
   and to drop root privileges once the ports are bound, execute
   the server like this from a root shell:
   <screen>
    zebrasrv -u daemon @
    zebrasrv -u daemon tcp:@:210
    zebrasrv -u daemon unix:/some/file/system/socket
   </screen>
   Here <literal>daemon</literal> is an existing user account, and the
   unix socket <literal>/some/file/system/socket</literal> is readable
   and writable for the <literal>daemon</literal> account.
  </para>
<!--
The line before the examples "zebrasrv -u daemon @" would sound better
if it said something like "execute the server from a root shell with a
command like one of these:" - so that our users won't cut and paste all
three lines...
Heikki -->


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "zebrasrv.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->
