1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. Application Invocation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="server.html" title="Chapter 4. Generic server"><link rel="prev" href="server.backendfunctions.html" title="5. The Backend Functions"><link rel="next" href="server.vhosts.html" title="7. GFS Configuration and Virtual Hosts"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Application Invocation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="server.backendfunctions.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Generic server</th><td width="20%" align="right"> <a accesskey="n" href="server.vhosts.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="server.invocation"></a>6. Application Invocation</h2></div></div></div><p>
2 The finished application has the following
3 invocation syntax (by way of <code class="function">statserv_main()</code>):
4 </p><div class="cmdsynopsis"><p><code class="command">application</code> [<code class="option">-install</code>] [<code class="option">-installa</code>] [<code class="option">-remove</code>] [<code class="option">-a <em class="replaceable"><code>file</code></em></code>] [<code class="option">-v <em class="replaceable"><code>level</code></em></code>] [<code class="option">-l <em class="replaceable"><code>file</code></em></code>] [<code class="option">-u <em class="replaceable"><code>uid</code></em></code>] [<code class="option">-c <em class="replaceable"><code>config</code></em></code>] [<code class="option">-f <em class="replaceable"><code>vconfig</code></em></code>] [<code class="option">-C <em class="replaceable"><code>fname</code></em></code>] [<code class="option">-t <em class="replaceable"><code>minutes</code></em></code>] [<code class="option">-k <em class="replaceable"><code>kilobytes</code></em></code>] [<code class="option">-d <em class="replaceable"><code>daemon</code></em></code>] [<code class="option">-w <em class="replaceable"><code>dir</code></em></code>] [<code class="option">-p <em class="replaceable"><code>pidfile</code></em></code>] [<code class="option">-r <em class="replaceable"><code>kilobytes</code></em></code>] [<code class="option">-ziDST1</code>] [listener-spec...]</p></div><p>
9 </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">-a </code>
10 <em class="replaceable"><code>file</code></em></span></dt><dd><p>
11 Specify a file for dumping PDUs (for diagnostic purposes).
12 The special name <code class="literal">-</code> (dash) sends output to
13 <code class="literal">stderr</code>.
14 </p></dd><dt><span class="term"><code class="literal">-S</code></span></dt><dd><p>
15 Don't fork or make threads on connection requests. This is good for
16 debugging, but not recommended for real operation: Although the
17 server is asynchronous and non-blocking, it can be nice to keep
18 a software malfunction (okay then, a crash) from affecting all
20 </p></dd><dt><span class="term"><code class="literal">-1</code></span></dt><dd><p>
21 Like <code class="literal">-S</code> but after one session the server
22 exits. This mode is for debugging <span class="emphasis"><em>only</em></span>.
23 </p></dd><dt><span class="term"><code class="literal">-T</code></span></dt><dd><p>
24 Operate the server in threaded mode. The server creates a thread
25 for each connection rather than a fork a process. Only available
26 on UNIX systems that offers POSIX threads.
27 </p></dd><dt><span class="term"><code class="literal">-s</code></span></dt><dd><p>
28 Use the SR protocol (obsolete).
29 </p></dd><dt><span class="term"><code class="literal">-z</code></span></dt><dd><p>
30 Use the Z39.50 protocol (default). This option and <code class="literal">-s</code>
31 complement each other.
32 You can use both multiple times on the same command
33 line, between listener-specifications (see below). This way, you
34 can set up the server to listen for connections in both protocols
35 concurrently, on different local ports.
36 </p></dd><dt><span class="term"><code class="literal">-l </code>
37 <em class="replaceable"><code>file</code></em></span></dt><dd><p>The logfile.
38 </p></dd><dt><span class="term"><code class="literal">-c </code>
39 <em class="replaceable"><code>config</code></em></span></dt><dd><p>A user option that serves as a specifier for some
40 sort of configuration, usually a filename.
41 The argument to this option is transferred to member
42 <code class="literal">configname</code> of the
43 <code class="literal">statserv_options_block</code>.
44 </p></dd><dt><span class="term"><code class="literal">-f </code>
45 <em class="replaceable"><code>vconfig</code></em></span></dt><dd><p>This specifies an XML file that describes
46 one or more YAZ frontend virtual servers.
47 </p></dd><dt><span class="term"><code class="literal">-C </code>
48 <em class="replaceable"><code>fname</code></em></span></dt><dd><p>Sets SSL certificate file name for server (PEM).
49 </p></dd><dt><span class="term"><code class="literal">-v </code>
50 <em class="replaceable"><code>level</code></em></span></dt><dd><p>
51 The log level. Use a comma-separated list of members of the set
52 {fatal,debug,warn,log,malloc,all,none}.
53 </p></dd><dt><span class="term"><code class="literal">-u </code>
54 <em class="replaceable"><code>uid</code></em></span></dt><dd><p>
55 Set user ID. Sets the real UID of the server process to that of the
56 given user. It's useful if you aren't comfortable with having the
57 server run as root, but you need to start it as such to bind a
59 </p></dd><dt><span class="term"><code class="literal">-w </code>
60 <em class="replaceable"><code>dir</code></em></span></dt><dd><p>
61 The server changes to this directory during before listening
62 on incoming connections. This option is useful
63 when the server is operating from the <span class="application">inetd</span>
64 daemon (see <code class="literal">-i</code>).
65 </p></dd><dt><span class="term"><code class="literal">-p </code>
66 <em class="replaceable"><code>pidfile</code></em></span></dt><dd><p>
67 Specifies that the server should write its Process ID to
68 file given by <em class="replaceable"><code>pidfile</code></em>.
69 A typical location would be <code class="filename">/var/run/yaz-ztest.pid</code>.
70 </p></dd><dt><span class="term"><code class="literal">-i</code></span></dt><dd><p>
71 Use this to make the the server run from the
72 <span class="application">inetd</span> server (UNIX only).
73 </p></dd><dt><span class="term"><code class="literal">-D</code></span></dt><dd><p>
74 Use this to make the server put itself in the background and
75 run as a daemon. If neither <code class="literal">-i</code> nor
76 <code class="literal">-D</code> is given, the server starts in the foreground.
77 </p></dd><dt><span class="term"><code class="literal">-install</code></span></dt><dd><p>
78 Use this to install the server as an NT service
79 (Windows NT/2000/XP only).
80 Control the server by going to the Services in the Control Panel.
81 </p></dd><dt><span class="term"><code class="literal">-installa</code></span></dt><dd><p>
82 Use this to install and activate the server as an NT service
83 (Windows NT/2000/XP only).
84 Control the server by going to the Services in the Control Panel.
85 </p></dd><dt><span class="term"><code class="literal">-remove</code></span></dt><dd><p>
86 Use this to remove the server from the NT services
87 (Windows NT/2000/XP only).
88 </p></dd><dt><span class="term"><code class="literal">-t </code>
89 <em class="replaceable"><code>minutes</code></em></span></dt><dd><p>
90 Idle session timeout, in minutes.
91 </p></dd><dt><span class="term"><code class="literal">-k </code>
92 <em class="replaceable"><code>size</code></em></span></dt><dd><p>
93 Maximum record size/message size, in kilobytes.
94 </p></dd><dt><span class="term"><code class="literal">-r </code>
95 <em class="replaceable"><code>size</code></em></span></dt><dd><p>
96 Maximum size of log file before rotation occurs, in kilobytes.
97 Default size is 1048576 k (=1 GB).
98 </p></dd><dt><span class="term"><code class="literal">-d </code>
99 <em class="replaceable"><code>daemon</code></em></span></dt><dd><p>
100 Set name of daemon to be used in hosts access file.
102 <span class="citerefentry"><span class="refentrytitle">hosts_access</span>(5)</span>
104 <span class="citerefentry"><span class="refentrytitle">tcpd</span>(8)</span>.
105 </p></dd><dt><span class="term"><code class="literal">-m </code>
106 <em class="replaceable"><code>time-format</code></em></span></dt><dd><p>
107 Sets the format of time-stamps in the log-file. Specify a string in
108 the input format to <code class="literal">strftime()</code>.
109 </p></dd></dl></div><p>
115 A listener specification consists of a transport mode followed by a
116 colon (:) followed by a listener address. The transport mode is
117 either <code class="literal">tcp</code>, <code class="literal">unix:</code> or
118 <code class="literal">ssl</code>.
120 For TCP and SSL, an address has the form
121 </p><pre class="synopsis">
122 hostname | IP-number [: portnumber]
124 The port number defaults to 210 (standard Z39.50 port).
126 For UNIX, the address is the filename of socket.
128 For TCP/IP and SSL, the special hostname <code class="literal">@</code>
129 (at sign) is mapped to the address <code class="literal">INADDR_ANY</code>,
130 which causes the server to listen on any local interface.
131 </p><div class="example"><a name="server.example.running.unix"></a><p class="title"><b>Example 4.1. Running the GFS on Unix</b></p><div class="example-contents"><p>
132 Assuming the server application <em class="replaceable"><code>appname</code></em> is
133 started as root, the following will make it listen on port 210.
134 The server will change identity to <code class="literal">nobody</code>
135 and write its log to <code class="filename">/var/log/app.log</code>.
136 </p><pre class="screen">
137 <em class="replaceable"><code>appname</code></em> -l /var/log/app.log -u nobody tcp:@:210
140 The server will accept Z39.50 requests and offer SRU service on port 210.
141 </p></div></div><br class="example-break"><div class="example"><a name="server.example.apache.sru"></a><p class="title"><b>Example 4.2. Setting up Apache as SRU Frontend</b></p><div class="example-contents"><p>
142 If you use <a class="ulink" href="http://httpd.apache.org/" target="_top">Apache</a>
143 as your public web server and want to offer HTTP port 80
144 access to the YAZ server on 210, you can use the
145 <a class="ulink" href="http://httpd.apache.org/docs/mod/mod_proxy.html#proxypass" target="_top">
146 <code class="literal">ProxyPass</code></a>
148 If you have virtual host
149 <code class="literal">srw.mydomain</code> you can use the following directives
150 in Apache's httpd.conf:
151 </p><pre class="screen">
152 <VirtualHost *>
153 ErrorLog /home/srw/logs/error_log
154 TransferLog /home/srw/logs/access_log
155 ProxyPass / http://srw.mydomain:210/
159 The above for the Apache 1.3 series.
160 </p></div></div><br class="example-break"><div class="example"><a name="server.example.local.access"></a><p class="title"><b>Example 4.3. Running a server with local access only</b></p><div class="example-contents"><p>
161 Servers that is only being accessed from the local host should listen
162 on UNIX file socket rather than a Internet socket. To listen on
163 <code class="filename">/tmp/mysocket</code> start the server as follows:
164 </p><pre class="screen">
165 <em class="replaceable"><code>appname</code></em> tcp:/tmp/mysocket
167 </p></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server.backendfunctions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="server.vhosts.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. The Backend Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7. GFS Configuration and Virtual Hosts</td></tr></table></div></body></html>