dependencies/yaz-2.1.28/doc/server.invocation.html

   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.70.1"><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. 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">-ziDST1</code>] [listener-spec...]</p></div><p>
   5     The options are:
   6
   7
   8
   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
  19     current users.
  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
  58     privileged port.
  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">-d </code>
  95    <em class="replaceable"><code>daemon</code></em></span></dt><dd><p>
  96     Set name of daemon to be used in hosts access file.
  97     See
  98     <span class="citerefentry"><span class="refentrytitle">hosts_access</span>(5)</span>
  99     and
 100     <span class="citerefentry"><span class="refentrytitle">tcpd</span>(8)</span>.
 101    </p></dd><dt><span class="term"><code class="literal">-m </code>
 102    <em class="replaceable"><code>time-format</code></em></span></dt><dd><p>
 103    Sets the format of time-stamps in the log-file. Specify a string in
 104    the input format to <code class="literal">strftime()</code>.
 105    </p></dd></dl></div><p>
 106
 107
 108
 109
 110    </p><p>
 111     A listener specification consists of a transport mode followed by a
 112     colon (:) followed by a listener address. The transport mode is
 113     either <code class="literal">tcp</code>, <code class="literal">unix:</code> or
 114     <code class="literal">ssl</code>.
 115    </p><p>
 116     For TCP and SSL, an address has the form
 117    </p><pre class="synopsis">
 118     hostname | IP-number [: portnumber]
 119    </pre><p>
 120     The port number defaults to 210 (standard Z39.50 port).
 121    </p><p>
 122     For UNIX, the address is the filename of socket.
 123    </p><p>
 124     For TCP/IP and SSL, the special hostname <code class="literal">@</code>
 125     (at sign) is mapped to the address <code class="literal">INADDR_ANY</code>,
 126     which causes the server to listen on any local interface.
 127    </p><div class="example"><a name="id2572708"></a><p class="title"><b>Example 4.1. Running the GFS on Unix</b></p><div class="example-contents"><p>
 128      Assuming the server application <em class="replaceable"><code>appname</code></em> is
 129      started as root, the following will make it listen on port 210.
 130      The server will change identity to <code class="literal">nobody</code>
 131      and write its log to <code class="filename">/var/log/app.log</code>.
 132      </p><pre class="screen">
 133       <em class="replaceable"><code>appname</code></em> -l /var/log/app.log -u nobody tcp:@:210
 134      </pre><p>
 135     </p><p>
 136      The server will accept Z39.50 requests and offer SRU service on port 210.
 137     </p></div></div><br class="example-break"><div class="example"><a name="id2573158"></a><p class="title"><b>Example 4.2. Setting up Apache as SRU Frontend</b></p><div class="example-contents"><p>
 138      If you use <a href="http://httpd.apache.org/" target="_top">Apache</a>
 139      as your public web server and want to offer HTTP port 80
 140      access to the YAZ server on 210, you can use the
 141      <a href="http://httpd.apache.org/docs/mod/mod_proxy.html#proxypass" target="_top">
 142       <code class="literal">ProxyPass</code></a>
 143      directive.
 144      If you have virtual host
 145      <code class="literal">srw.mydomain</code> you can use the following directives
 146      in Apache's httpd.conf:
 147      </p><pre class="screen">
 148       &lt;VirtualHost *&gt;
 149        ErrorLog /home/srw/logs/error_log
 150        TransferLog /home/srw/logs/access_log
 151        ProxyPass / http://srw.mydomain:210/
 152       &lt;/VirtualHost&gt;
 153      </pre><p>
 154     </p><p>
 155      The above for the Apache 1.3 series.
 156     </p></div></div><br class="example-break"><div class="example"><a name="id2573210"></a><p class="title"><b>Example 4.3. Running a server with local access only</b></p><div class="example-contents"><p>
 157      Servers that is only being accessed from the local host should listen
 158      on UNIX file socket rather than a Internet socket. To listen on
 159      <code class="filename">/tmp/mysocket</code> start the server as follows:
 160      </p><pre class="screen">
 161       <em class="replaceable"><code>appname</code></em> tcp:/tmp/mysocket
 162      </pre><p>
 163     </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. Virtual Hosts</td></tr></table></div></body></html>