X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzebrasrv-options.xml;h=ff025ae216899e3db00d6e5dc93112ea3bffdb10;hb=c22b27ba78b584e1f3e6ba863b854bf7f741d0a3;hp=6915e0ded7bf69460a06408bcab206f564892533;hpb=7dcaf748021e168c37a2e3eb263db03248b2d170;p=idzebra-moved-to-github.git

diff --git a/doc/zebrasrv-options.xml b/doc/zebrasrv-options.xml
index 6915e0d..ff025ae 100644
--- a/doc/zebrasrv-options.xml
+++ b/doc/zebrasrv-options.xml
@@ -1,7 +1,8 @@
 <!-- 
-   $Id: zebrasrv-options.xml,v 1.1 2005-08-05 14:39:12 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>
@@ -20,8 +21,15 @@
     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>
@@ -43,7 +51,7 @@
 
  <varlistentry><term><literal>-z</literal></term>
   <listitem><para>
-    Use the Z39.50 protocol (default). This option and <literal>-s</literal>
+    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
@@ -53,22 +61,24 @@
 
  <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 &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>
@@ -82,6 +92,18 @@
     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>
@@ -93,9 +115,9 @@
    </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>).
@@ -106,15 +128,24 @@
   <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
@@ -145,13 +176,13 @@
  <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>
 
@@ -174,6 +205,60 @@
  
 </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
@@ -183,7 +268,7 @@ sgml-minimize-attributes:nil
 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: