GFS: Allow multiple listenrefs YAZ-554
[yaz-moved-to-github.git] / doc / gfs-virtual.xml
index d04e9e2..1250331 100644 (file)
@@ -1,5 +1,4 @@
-<!-- 
-   $Id: gfs-virtual.xml,v 1.9 2007-08-13 16:58:46 mike Exp $
+<!--
    Description of the virtual host mechanism in YAZ GFS
    Included in both manual and man page for yaz-ztest
 -->
@@ -30,7 +29,7 @@
 </note>
 <para>
  The YAZ frontend server uses XML to describe the backend
- configurations. Command-line option <literal>-f</literal> 
+ configurations. Command-line option <literal>-f</literal>
  specifies filename of the XML configuration.
 </para>
 <para>
 </para>
 <para>
  The <literal>listen</literal> describes listener (transport end point),
- such as TCP/IP, Unix file socket or SSL server. Content for 
+ such as TCP/IP, Unix file socket or SSL server. Content for
  a listener:
  <variablelist>
   <varlistentry><term>CDATA (required)</term>
    <listitem>
     <para>
      The CDATA for the <literal>listen</literal> element holds the
-     listener string, such as <literal>tcp:@:210</literal>, 
+     listener string, such as <literal>tcp:@:210</literal>,
      <literal>tcp:server1:2100</literal>,
      etc.
     </para>
   <varlistentry><term>attribute <literal>listenref</literal> (optional)</term>
    <listitem>
     <para>
-     Specifies listener for this server. If this attribute is not
-     given, the server is accessible from all listener. In order
-     for the server to be used for real, howeever, the virtual host
-     must match (if specified in the configuration).
+     Specifies one or more listeners for this server. Each server ID is
+     separated by a comma.
+     If this attribute is not given, the server is accessible from all
+     listeners. In order for the server to be used for real, however, the
+     virtual host must match if specified in the configuration.
     </para>
    </listitem>
   </varlistentry>
     <para>
      Specifies a filename that includes CQL to RPN conversion for this
      backend server. See &reference-tools-cql-map;
-     If given, the backend server will only "see" a Type-1/RPN query. 
+     If given, the backend server will only "see" a Type-1/RPN query.
     </para>
    </listitem>
   </varlistentry>
     <para>
      Specifies a filename that includes CCL to RPN conversion for this
      backend server. See &reference-tools-ccl-qualifiers;
-     If given, the backend server will only "see" a Type-1/RPN query. 
+     If given, the backend server will only "see" a Type-1/RPN query.
     </para>
    </listitem>
   </varlistentry>
     </para>
    </listitem>
   </varlistentry>
-   
+
   <varlistentry><term>element <literal>docpath</literal> (optional)</term>
    <listitem>
     <para>
     </para>
    </listitem>
   </varlistentry>
-   
+
   <varlistentry><term>element <literal>explain</literal> (optional)</term>
    <listitem>
     <para>
     </para>
    </listitem>
   </varlistentry>
-   
+
  </variablelist>
 </para>
+
 <para>
  The XML below configures a server that accepts connections from
  two ports, TCP/IP port 9900 and a local UNIX file socket.
     <directory>/var/www/s1</directory>
     <config>config.cfg</config>
   </server>
-  <server id="server2">
+  <server id="server2" listenref="public,internal">
     <host>server2.mydomain</host>
     <directory>/var/www/s2</directory>
     <config>config.cfg</config>
 <para>
  There are three configured backend servers. The first two
  servers, <literal>"server1"</literal> and <literal>"server2"</literal>,
- can be reached by both listener addresses - since
- no <literal>listenref</literal> attribute is specified.
- In order to distinguish between the two a virtual host has
+ can be reached by both listener addresses.
+ <literal>"server1"</literal> is reached by all (two) since no
+  <literal>listenref</literal> attribute is specified.
+ <literal>"server2"</literal> is reached by the two listeners specified.
+ In order to distinguish between the two, a virtual host has
  been specified for each of server in the <literal>host</literal>
  elements.
 </para>