doc/zebrasrv-options.xml

   1 <!--
   2    $Id: zebrasrv-options.xml,v 1.2 2005-08-12 12:44:36 marc Exp $
   3    Options for generic frontend server and yaz-ztest.
   4    Included in both manual and man page for yaz-ztest
   5 -->
   6
   7 <variablelist>
   8
   9  <varlistentry><term><literal>-a </literal>
  10    <replaceable>file</replaceable></term>
  11   <listitem><para>
  12     Specify a file for dumping PDUs (for diagnostic purposes).
  13     The special name <literal>-</literal> (dash) sends output to
  14     <literal>stderr</literal>.
  15    </para></listitem></varlistentry>
  16
  17  <varlistentry><term><literal>-S</literal></term>
  18   <listitem><para>
  19     Don't fork or make threads on connection requests. This is good for
  20     debugging, but not recommended for real operation: Although the
  21     server is asynchronous and non-blocking, it can be nice to keep
  22     a software malfunction (okay then, a crash) from affecting all
  23     current users. The server can only accept a single
  24        connection in this mode.
  25    </para></listitem></varlistentry>
  26
  27  <varlistentry><term><literal>-1</literal></term>
  28   <listitem><para>
  29     Like <literal>-S</literal> but after one session the server
  30     exits. This mode is for debugging <emphasis>only</emphasis>.
  31    </para></listitem></varlistentry>
  32
  33  <varlistentry><term><literal>-T</literal></term>
  34   <listitem><para>
  35     Operate the server in threaded mode. The server creates a thread
  36     for each connection rather than a fork a process. Only available
  37     on UNIX systems that offers POSIX threads.
  38    </para></listitem></varlistentry>
  39
  40  <varlistentry><term><literal>-s</literal></term>
  41   <listitem><para>
  42     Use the SR protocol (obsolete).
  43    </para></listitem></varlistentry>
  44
  45  <varlistentry><term><literal>-z</literal></term>
  46   <listitem><para>
  47     Use the Z39.50 protocol (default). This option and <literal>-s</literal>
  48     complement each other.
  49     You can use both multiple times on the same command
  50     line, between listener-specifications (see below). This way, you
  51     can set up the server to listen for connections in both protocols
  52     concurrently, on different local ports.
  53    </para></listitem></varlistentry>
  54
  55  <varlistentry><term><literal>-l </literal>
  56    <replaceable>file</replaceable></term>
  57   <listitem><para>
  58     Specify an output file for the diagnostic messages.
  59        The default is to write this information to
  60    <literal>stderr</literal>
  61    </para></listitem></varlistentry>
  62
  63  <varlistentry><term><literal>-c </literal>
  64    <replaceable>config-file</replaceable></term>
  65   <listitem><para> Read configuration information from
  66        <replaceable>config-file</replaceable>.
  67        The default configuration is <literal>./zebra.cfg</literal>
  68   </para></listitem></varlistentry>
  69
  70  <varlistentry><term><literal>-f </literal>
  71    <replaceable>vconfig</replaceable></term>
  72   <listitem><para>This specifies an XML file that describes
  73     one or more YAZ frontend virtual servers.
  74    </para></listitem></varlistentry>
  75
  76  <varlistentry><term><literal>-C </literal>
  77    <replaceable>fname</replaceable></term>
  78   <listitem><para>Sets SSL certificate file name for server (PEM).
  79    </para></listitem></varlistentry>
  80
  81  <varlistentry><term><literal>-v </literal>
  82    <replaceable>level</replaceable></term>
  83   <listitem><para>
  84     The log level. Use a comma-separated list of members of the set
  85     {fatal,debug,warn,log,malloc,all,none}.
  86    </para></listitem></varlistentry>
  87
  88  <varlistentry><term><literal>-u </literal>
  89    <replaceable>uid</replaceable></term>
  90   <listitem><para>
  91     Set user ID. Sets the real UID of the server process to that of the
  92     given user. It's useful if you aren't comfortable with having the
  93     server run as root, but you need to start it as such to bind a
  94     privileged port.
  95    </para></listitem></varlistentry>
  96
  97  <varlistentry><term><literal>-w </literal>
  98    <replaceable>working-directory</replaceable></term>
  99   <listitem><para>
 100     The server changes to this working directory during before listening
 101     on incoming connections. This option is useful
 102     when the server is operating from the <application>inetd</application>
 103     daemon (see <literal>-i</literal>).
 104    </para></listitem></varlistentry>
 105
 106  <varlistentry><term><literal>-p </literal>
 107    <replaceable>pidfile</replaceable></term>
 108   <listitem><para>
 109     Specifies that the server should write its Process ID to
 110     file given by <replaceable>pidfile</replaceable>.
 111     A typical location would be <filename>/var/run/yaz-ztest.pid</filename>.
 112    </para></listitem></varlistentry>
 113
 114  <varlistentry><term><literal>-i</literal></term>
 115   <listitem><para>
 116     Use this to make the the server run from the
 117     <application>inetd</application> server (UNIX only).
 118      Make sure you use the logfile option <literal>-l</literal> in
 119        conjunction with this mode and specify the <literal>-l</literal>
 120        option before any other options.
 121    </para></listitem></varlistentry>
 122
 123  <varlistentry><term><literal>-D</literal></term>
 124   <listitem><para>
 125     Use this to make the server put itself in the background and
 126     run as a daemon. If neither <literal>-i</literal> nor
 127     <literal>-D</literal> is given, the server starts in the foreground.
 128    </para></listitem></varlistentry>
 129
 130  <varlistentry><term><literal>-install</literal></term>
 131   <listitem><para>
 132     Use this to install the server as an NT service
 133     (Windows NT/2000/XP only).
 134     Control the server by going to the Services in the Control Panel.
 135    </para></listitem></varlistentry>
 136
 137  <varlistentry><term><literal>-installa</literal></term>
 138   <listitem><para>
 139     Use this to install and activate the server as an NT service
 140     (Windows NT/2000/XP only).
 141     Control the server by going to the Services in the Control Panel.
 142    </para></listitem></varlistentry>
 143
 144  <varlistentry><term><literal>-remove</literal></term>
 145   <listitem><para>
 146     Use this to remove the server from the NT services
 147     (Windows NT/2000/XP only).
 148    </para></listitem></varlistentry>
 149
 150  <varlistentry><term><literal>-t </literal>
 151    <replaceable>minutes</replaceable></term>
 152   <listitem><para>
 153     Idle session timeout, in minutes. Default is 60 minutes.
 154    </para></listitem></varlistentry>
 155
 156  <varlistentry><term><literal>-k </literal>
 157    <replaceable>size</replaceable></term>
 158   <listitem><para>
 159     Maximum record size/message size, in kilobytes. Default is 1024 KB (1 MB).
 160    </para></listitem>
 161  </varlistentry>
 162
 163  <varlistentry><term><literal>-d </literal>
 164    <replaceable>daemon</replaceable></term>
 165   <listitem><para>
 166     Set name of daemon to be used in hosts access file.
 167     See
 168     <citerefentry>
 169      <refentrytitle>hosts_access</refentrytitle>
 170      <manvolnum>5</manvolnum>
 171     </citerefentry>
 172     and
 173     <citerefentry>
 174      <refentrytitle>tcpd</refentrytitle>
 175      <manvolnum>8</manvolnum>
 176     </citerefentry>.
 177    </para></listitem>
 178  </varlistentry>
 179
 180 </variablelist>
 181
 182
 183   <para>
 184    A <replaceable>listener-address</replaceable> consists of an optional
 185    transport mode followed by a colon (:) followed by a listener address.
 186    The transport mode is either a file system socket
 187    <literal>unix</literal>,
 188    a SSL TCP/IP socket <literal>ssl</literal>, or a plain TCP/IP socket
 189    <literal>tcp</literal> (default).
 190   </para>
 191
 192   <para>
 193    For TCP, an address has the form
 194    <screen>
 195     hostname | IP-number [: portnumber]
 196    </screen>
 197    The port number defaults to 210 (standard Z39.50 port) for
 198    privileged users (root), and 9999 for normal users.
 199    The special hostname "@" is mapped to
 200    the address INADDR_ANY, which causes the server to listen on any local
 201    interface.   </para>
 202
 203   <para>
 204    The default behavior for <literal>zebrasrv</literal> - if started
 205    as non-priviledged user - is to establish
 206    a single TCP/IP listener, for the Z39.50 protocol, on port 9999.
 207    <screen>
 208     zebrasrv @
 209     zebrasrv tcp:some.server.name.org:1234
 210     zebrasrv ssl:@:3000
 211    </screen>
 212   </para>
 213
 214   <para>
 215    To start the server listening on the registered port for
 216    Z39.50, or on a filesystem socket,
 217    and to drop root privileges once the ports are bound, execute
 218    the server like this from a root shell:
 219    <screen>
 220     zebrasrv -u daemon @
 221     zebrasrv -u daemon tcp:@:210
 222     zebrasrv -u daemon unix:/some/file/system/socket
 223    </screen>
 224    Here <literal>daemon</literal> is an existing user account, and the
 225    unix socket <literal>/some/file/system/socket</literal> is readable
 226    and writable for the <literal>daemon</literal> account.
 227   </para>
 228
 229
 230
 231 <!-- Keep this comment at the end of the file
 232 Local variables:
 233 mode: sgml
 234 sgml-omittag:t
 235 sgml-shorttag:t
 236 sgml-minimize-attributes:nil
 237 sgml-always-quote-attributes:t
 238 sgml-indent-step:1
 239 sgml-indent-data:t
 240 sgml-parent-document: "yaz.xml"
 241 sgml-local-catalogs: nil
 242 sgml-namecase-general:t
 243 End:
 244 -->