dependencies/yaz_3.0.14/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.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>
   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">-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.
 101     See
 102     <span class="citerefentry"><span class="refentrytitle">hosts_access</span>(5)</span>
 103     and
 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>
 110
 111
 112
 113
 114    </p><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>.
 119    </p><p>
 120     For TCP and SSL, an address has the form
 121    </p><pre class="synopsis">
 122     hostname | IP-number [: portnumber]
 123    </pre><p>
 124     The port number defaults to 210 (standard Z39.50 port).
 125    </p><p>
 126     For UNIX, the address is the filename of socket.
 127    </p><p>
 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
 138      </pre><p>
 139     </p><p>
 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>
 147      directive.
 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       &lt;VirtualHost *&gt;
 153        ErrorLog /home/srw/logs/error_log
 154        TransferLog /home/srw/logs/access_log
 155        ProxyPass / http://srw.mydomain:210/
 156       &lt;/VirtualHost&gt;
 157      </pre><p>
 158     </p><p>
 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
 166      </pre><p>
 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>