2 $Id: zebrasrv-options.xml,v 1.3 2005-08-12 13:50:51 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
11 <varlistentry><term><literal>-a </literal>
12 <replaceable>file</replaceable></term>
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>
19 <varlistentry><term><literal>-S</literal></term>
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 -->
35 <varlistentry><term><literal>-1</literal></term>
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>
41 <varlistentry><term><literal>-T</literal></term>
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>
48 <varlistentry><term><literal>-s</literal></term>
50 Use the SR protocol (obsolete).
51 </para></listitem></varlistentry>
53 <varlistentry><term><literal>-z</literal></term>
55 Use the Z39.50 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>
63 <varlistentry><term><literal>-l </literal>
64 <replaceable>file</replaceable></term>
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>
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>
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
83 </para></listitem></varlistentry>
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>
90 <varlistentry><term><literal>-v </literal>
91 <replaceable>level</replaceable></term>
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
109 <varlistentry><term><literal>-u </literal>
110 <replaceable>uid</replaceable></term>
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
116 </para></listitem></varlistentry>
118 <varlistentry><term><literal>-w </literal>
119 <replaceable>working-directory</replaceable></term>
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>
127 <varlistentry><term><literal>-p </literal>
128 <replaceable>pidfile</replaceable></term>
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>
135 <varlistentry><term><literal>-i</literal></term>
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>
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.
150 <varlistentry><term><literal>-D</literal></term>
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>
157 <varlistentry><term><literal>-install</literal></term>
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>
164 <varlistentry><term><literal>-installa</literal></term>
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>
171 <varlistentry><term><literal>-remove</literal></term>
173 Use this to remove the server from the NT services
174 (Windows NT/2000/XP only).
175 </para></listitem></varlistentry>
177 <varlistentry><term><literal>-t </literal>
178 <replaceable>minutes</replaceable></term>
180 Idle session timeout, in minutes. Default is 60 minutes.
181 </para></listitem></varlistentry>
183 <varlistentry><term><literal>-k </literal>
184 <replaceable>size</replaceable></term>
186 Maximum record size/message size, in kilobytes. Default is 1024 KB (1 MB).
190 <varlistentry><term><literal>-d </literal>
191 <replaceable>daemon</replaceable></term>
193 Set name of daemon to be used in hosts access file.
196 <refentrytitle>hosts_access</refentrytitle>
197 <manvolnum>5</manvolnum>
201 <refentrytitle>tcpd</refentrytitle>
202 <manvolnum>8</manvolnum>
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).
220 For TCP, an address has the form
222 hostname | IP-number [: portnumber]
224 The port number defaults to 210 (standard Z39.50 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
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 Z39.50 protocol, on port 9999.
236 zebrasrv tcp:some.server.name.org:1234
242 To start the server listening on the registered port for
243 Z39.50, 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:
248 zebrasrv -u daemon tcp:@:210
249 zebrasrv -u daemon unix:/some/file/system/socket
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.
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
263 <!-- Keep this comment at the end of the file
268 sgml-minimize-attributes:nil
269 sgml-always-quote-attributes:t
272 sgml-parent-document: "yaz.xml"
273 sgml-local-catalogs: nil
274 sgml-namecase-general:t