doc/zebrasrv-options.xml

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