Renamed ztest-options.xml to gfs-options.xml. Added GFS common synopsis

[yaz-moved-to-github.git] / doc / frontend.xml

diff --git a/doc/frontend.xml b/doc/frontend.xml
index cbb533a..7ab9e83 100644 (file)
--- a/doc/frontend.xml
+++ b/doc/frontend.xml
@@ -1,4 +1,4 @@
-<!-- $Id: frontend.xml,v 1.17 2003-04-28 21:02:16 adam Exp $ -->
+<!-- $Id: frontend.xml,v 1.24 2005-03-13 21:43:00 adam Exp $ -->
  <chapter id="server"><title>Generic server</title>
   <sect1><title>Introduction</title>
    
@@ -13,7 +13,7 @@
 
    <para>
     If you have a database system that you would like to make available by
-    means of Z39.50 or SRW, &yaz; basically offers your two options. You
+    means of Z39.50, SRW o SRU, &yaz; basically offers your two options. You
     can use the APIs provided by the &asn;, &odr;, and &comstack;
     modules to
     create and decode PDUs, and exchange them with a client.
@@ -232,7 +232,7 @@ statserv_options_block *statserv_getcontrol(void);
      <varlistentry><term>
        <literal>int idle_timeout;</literal></term>
       <listitem><para>Maximum session idle-time, in minutes. Zero indicates
-       no (infinite) timeout. Default is 120 minutes.
+       no (infinite) timeout. Default is 15 minutes.
        </para></listitem></varlistentry>
      
      <varlistentry><term>
@@ -546,10 +546,10 @@ typedef struct bend_fetch_rr {
      that holds the reference to the desired record.
      The <literal>number</literal> is the offset into the set (with 1
      being the first record in the set). The <literal>format</literal> field
-     is the record format requested by the client (See section
-     <link linkend="oid">Object Identifiers</link>). The value
-     <literal>VAL_NONE</literal> indicates that the client did not
-     request a specific format. The <literal>stream</literal> argument
+     is the record format requested by the client (See
+     <xref linkend="asn.oid"/>).
+     The value <literal>VAL_NONE</literal> indicates that the client did
+     not request a specific format. The <literal>stream</literal> argument
      is an &odr; stream which should be used for
      allocating space for structured data records.
      The stream will be reset when all records have been assembled, and
@@ -726,27 +726,13 @@ typedef struct bend_scan_rr {
     The finished application has the following
     invocation syntax (by way of <function>statserv_main()</function>):
    </para>
-   
-   <cmdsynopsis>
-    <command>appname</command>
-    <arg choice="opt"><option>-a <replaceable>file</replaceable></option></arg>
-    <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
-    <arg choice="opt"><option>-l <replaceable>file</replaceable></option></arg>
-    <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
-    <arg choice="opt"><option>-c <replaceable>config</replaceable></option></arg>
-    <arg choice="opt"><option>-t <replaceable>minutes</replaceable></option></arg>
-    <sbr/>
-    <arg choice="opt"><option>-k <replaceable>kilobytes</replaceable></option></arg>
-    <arg choice="opt"><option>-d <replaceable>daemon</replaceable></option></arg>
-    <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
-    <arg choice="opt"><option>-ziST1</option></arg>
-    <arg choice="opt" rep="repeat">listener-spec</arg>
-   </cmdsynopsis>
+
+   &gfs-synopsis;
    
    <para>
     The options are:
 
-    &ztest-options;
+    &gfs-options;
 
    </para>
    
@@ -764,7 +750,7 @@ typedef struct bend_scan_rr {
    <synopsis>
     hostname | IP-number &lsqb;: portnumber&rsqb;
    </synopsis>
-
+   
    <para>
     The port number defaults to 210 (standard Z39.50 port).
    </para>
@@ -774,22 +760,62 @@ typedef struct bend_scan_rr {
    </para>
 
    <para>
-    For TCP/IP and SSL, the special hostname &quot;@&quot; is mapped to
-    the address <literal>INADDR_ANY</literal>, which causes the
-    server to listen on any local interface. 
-   </para>
-   
-   <para>
-    Examples:
-   <screen>
-    tcp:@:210
-
-    ssl:@:3000
-
-    unix:/tmp/yaz
-   </screen>
+    For TCP/IP and SSL, the special hostname <literal>@</literal> 
+    (at sign) is mapped to the address <literal>INADDR_ANY</literal>,
+    which causes the server to listen on any local interface. 
    </para>
 
+   <example><title>Running the GFS on Unix</title>
+    <para>
+     Assuming the server application <replaceable>appname</replaceable> is
+     started as root, the following will make it listen on port 210.
+     The server will change identity to <literal>nobody</literal>
+     and write its log to <filename>/var/log/app.log</filename>.
+     <screen>
+      <replaceable>appname</replaceable> -l /var/log/app.log -u nobody tcp:@:210
+     </screen>
+    </para>
+    <para>
+     The server will accept Z39.50 requests and offer SRW/SRU service
+     on port 210.
+    </para>
+   </example>
+   <example><title>Setting up Apache as SRW/SRU Frontend</title>
+    <para>
+     If you use <ulink url="http://httpd.apache.org/">Apache</ulink>
+     as your public web server and want to offer HTTP port 80
+     access to the YAZ server on 210, you can use the
+     <ulink url="http://httpd.apache.org/docs/mod/mod_proxy.html#proxypass">
+      <literal>ProxyPass</literal></ulink> 
+     directive.
+     If you have virtual host
+     <literal>srw.mydomain</literal> you can use the following directives
+     in Apache's httpd.conf:
+     <screen>
+      &lt;VirtualHost *>
+       ErrorLog /home/srw/logs/error_log
+       TransferLog /home/srw/logs/access_log
+       ProxyPass / http://srw.mydomain:210/
+      &lt;/VirualHost>
+     </screen>
+    </para>
+    <para>
+     The above for the Apache 1.3 series.
+    </para>
+   </example>
+   <example><title>Running a server with local access only</title>
+    <para>
+     Servers that is only being accessed from the local host should listen
+     on UNIX file socket rather than a Internet socket. To listen on
+     <filename>/tmp/mysocket</filename> start the server as follows:
+     <screen>
+      <replaceable>appname</replaceable> tcp:/tmp/mysocket
+     </screen>
+    </para>
+   </example>
+  </sect1>
+  <sect1 id="server.vhosts"><title>Virtual hosts</title>
+     &gfs-virtual;
   </sect1>
  </chapter>