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

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

diff --git a/doc/gfs-virtual.xml b/doc/gfs-virtual.xml
new file mode 100644 (file)
index 0000000..d307f62
--- /dev/null
+++ b/doc/gfs-virtual.xml
@@ -0,0 +1,89 @@
+<!-- 
+   $Id: gfs-virtual.xml,v 1.1 2005-03-13 21:43:00 adam Exp $
+   Description of the virtual hosts mechanism in YAZ GFS
+   Included in both manual and man page for yaz-ztest
+-->
+
+<para>
+ The Virtual hosts mechanism allows a YAZ frontend server to
+ support multiple backends. A backend is selected on the basis of
+ the TCP/IP binding (port+listening adddress) and/or the virtual host.
+</para>
+<para>
+ For the HTTP protocol, the virtual host is specified in the Host header.
+ For the Z39.50 protocol, the virtual host is specified as in the
+ Initialize Request in the OtherInfo, OID 1.2.840.10003.10.1000.81.1.
+</para>
+<note>
+ <para>
+  Not all Z39.50 clients allows the VHOST information to be set.
+  For those the selection of the backend must rely on the
+  TCP/IP information alone (port and address).
+ </para>
+</note>
+<para>
+ The YAZ frontend server uses XML to describe the backend
+ configurations. Command-line option <literal>-f</literal> 
+ specifies filename of the XML configuration.
+</para>
+<para>
+ The configuration uses the root element <literal>yazgfs</literal>.
+ This element includes a list of <literal>listen</literal> elements,
+ followed by one or more <literal>server</literal> elements.
+</para>
+<para>
+ The <literal>listen</literal> describes listener (transport end point),
+ such as TCP/IP, Unix file socket or SSL server.
+</para>
+<para>
+ The <literal>server</literal> describes a server and includes sub
+ elements which servers as parameters for this server.
+</para>
+<para>
+ The XML below configures a server with 2 listeners and 3 backend
+ servers. The server listens on port 9900 and 9901 identified 
+ with references "public9900" and "public9901".
+
+ [More to be written]
+ <screen>
+  <![CDATA[
+<yazgfs>
+  <listen id="public9900">tcp:@:9900</listen>
+  <listen id="public9901">tcp:@:9901</listen>
+  <server>
+    <host>host1</host>
+    <directory>/var/www/s1</directory>
+    <config>zebra1.cfg</config>
+  </server>
+  <server>
+    <host>host2</host>
+    <directory>/var/www/s2</directory>
+    <config>zebra2.cfg</config>
+  </server>
+  <server listenref="public9901">
+    <directory>/var/www/s3</directory>
+    <config>zebra3.cfg</config>
+    <cql2rpn>../etc/pqf.properties</cql2rpn>
+    <explain>
+      <my>explain</my>
+    </explain>
+  </server>
+ </yazgfs>
+]]>
+ </screen>
+</para>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document: "yaz.xml"
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->