doc/zebrasrv-options.xml

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