<!--
- $Id: zebrasrv-options.xml,v 1.1 2005-08-05 14:39:12 marc Exp $
+ $Id: zebrasrv-options.xml,v 1.7 2007-02-02 11:10:08 marc Exp $
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>
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.
+ 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>
<varlistentry><term><literal>-z</literal></term>
<listitem><para>
- Use the Z39.50 protocol (default). This option and <literal>-s</literal>
+ Use the &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
<varlistentry><term><literal>-l </literal>
<replaceable>file</replaceable></term>
- <listitem><para>The logfile.
+ <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</replaceable></term>
- <listitem><para>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
- <literal>configname</literal> of the
- <literal>statserv_options_block</literal>.
- </para></listitem></varlistentry>
+ <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 XML file that describes
- one or more YAZ frontend virtual servers.
+ <listitem><para>This specifies an &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>
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>
</para></listitem></varlistentry>
<varlistentry><term><literal>-w </literal>
- <replaceable>dir</replaceable></term>
+ <replaceable>working-directory</replaceable></term>
<listitem><para>
- The server changes to this directory during before listening
+ 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>).
<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/yaz-ztest.pid</filename>.
+ 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
<varlistentry><term><literal>-t </literal>
<replaceable>minutes</replaceable></term>
<listitem><para>
- Idle session timeout, in minutes.
+ 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.
+ Maximum record size/message size, in kilobytes. Default is 1024 KB (1 MB).
</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 &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-priviledged user - is to establish
+ a single TCP/IP listener, for the &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
+ &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-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
-sgml-parent-document: "yaz.xml"
+sgml-parent-document: "zebrasrv.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
projects / idzebra-moved-to-github.git / blobdiff