-## $Id: Makefile.am,v 1.26 2004-12-15 09:10:47 adam Exp $
+## $Id: Makefile.am,v 1.27 2005-08-05 14:39:12 marc Exp $
docdir=$(datadir)/doc/@PACKAGE@
SUPPORTFILES = \
license.xml \
indexdata.xml \
zebraidx-options.xml \
- zebraidx-commands.xml
+ zebraidx-commands.xml \
+ zebrasrv-options.xml \
+ zebrasrv-synopsis.xml \
+ zebrasrv-virtual.xml
+
+# zebrasrv-commands.xml \
+
HTMLFILES = \
administration.html apps.html configuration-file.html data-model.html \
if test ! -f zebraidx-commands.xml ; then ln -s $(srcdir)/zebraidx-commands.xml .; fi
docbook2man $(srcdir)/zebraidx-man.sgml
-zebrasrv.8: zebrasrv-man.sgml
+# zebrasrv-commands.xml
+zebrasrv.8: zebrasrv-man.sgml zebrasrv-options.xml \
+ zebrasrv-synopsis.xml zebrasrv-virtual.xml
docbook2man $(srcdir)/zebrasrv-man.sgml
idzebra-config.1: idzebra-config-man.sgml
<!ENTITY zebraidx-options SYSTEM "zebraidx-options.xml">
<!ENTITY zebraidx-commands SYSTEM "zebraidx-commands.xml">
+ <!ENTITY zebrasrv-options SYSTEM "zebrasrv-options.xml">
+ <!-- <!ENTITY zebrasrv-commands SYSTEM
+ "zebrasrv-commands.xml"> -->
<!ENTITY ref-local-representation '
<xref linkend="local-representation"/>'>
<!ENTITY ref-record-types '
<!ENTITY ref-shadow-registers '
<xref linkend="shadow-registers"/>'>
]>
-<!-- $Id: zebra.xml.in,v 1.18 2005-01-15 19:42:07 adam Exp $ -->
+<!-- $Id: zebra.xml.in,v 1.19 2005-08-05 14:39:12 marc Exp $ -->
<book id="zebra">
<bookinfo>
<title>Zebra - User's Guide and Reference</title>
<author>
<firstname>Mike</firstname><surname>Taylor</surname>
</author>
+ <author>
+ <firstname>Marc</firstname><surname>Cromme</surname>
+ </author>
<copyright>
<year>1995-2005</year>
<holder>Index Data</holder>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
-<!-- $Id: zebrasrv-man.sgml,v 1.2 2002-10-08 09:10:49 adam Exp $ -->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+ <!ENTITY zebrasrv-synopsis SYSTEM "zebrasrv-synopsis.xml">
+ <!ENTITY zebrasrv-options SYSTEM "zebrasrv-options.xml">
+ <!ENTITY zebrasrv-virtual SYSTEM "zebrasrv-virtual.xml">
+ <!ENTITY gfs-synopsis-app "zebrasrv">
+ <!ENTITY reference-tools-cql-map 'section "Specifiction of CQL to RPN mappings"'>
+]>
+
+ <!-- <!ENTITY zebrasrv-commands SYSTEM "zebrasrv-commands.xml"> -->
+
+
+<!-- $Id: zebrasrv-man.sgml,v 1.3 2005-08-05 14:39:12 marc Exp $ -->
<refentry id="zebrasrv">
<refmeta>
</refnamediv>
<refsynopsisdiv>
+ <!--
<cmdsynopsis>
<command>zebrasrv</command>
<arg choice="opt"><option>-a <replaceable>file</replaceable></option></arg>
<arg choice="opt"><option>-ziST1</option></arg>
<arg choice="opt" rep="repeat">listener-spec</arg>
</cmdsynopsis>
-
+ -->
+ &zebrasrv-synopsis;
</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para>
- <command>zebrasrv</command> is a Z39.50 server for Zebra.
+ <command>zebrasrv</command> is a Z39.50 and SRW/U server for Zebra.
On Unix you can run the server from the command line - and put it
in the background. It may also operate under the inet daemon.
On WIN32 you can run the server as a console application or
as a WIN32 Service.
</para>
</refsect1>
+ <!--
+ <refsect1>
+ <title>COMMANDS</title>
+ &zebrasrv-commands;
+ </refsect1>
+ -->
<refsect1>
<title>OPTIONS</title>
+
<para>
The options for <command>zebrasrv</command> are the same
as those for YAZ' <command>yaz-ztest</command>.
Option <literal>-c</literal> specifies a Zebra configuration
file - if omitted <filename>zebra.cfg</filename> is read.
</para>
+
+ &zebrasrv-options;
+ </refsect1>
+ <refsect1><title>VIRTUAL HOSTS</title>
+ <para>
+ <command>zebrasrv</command>uses the YAZ server
+ </para>
+ &zebrasrv-virtual;
</refsect1>
<refsect1><title>FILES</title>
<para>
</para>
<para>
Section "The Z39.50 Server" in the Zebra manual.
+ <filename>http://www.indexdata.dk/zebra/doc/server.tkl</filename>
+ </para>
+ <para>
+ Section "Virtual Hosts" in the YAZ manual.
+ <filename>http://www.indexdata.dk/yaz/doc/server.vhosts.tkl</filename>
+ </para>
+ <para>
+ Section "Specification of CQL to RPN mappings" in the YAZ manual.
+ <filename>http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map</filename>
</para>
</refsect1>
</refentry>
--- /dev/null
+<!--
+ $Id: zebrasrv-options.xml,v 1.1 2005-08-05 14:39:12 marc Exp $
+ Options for generic frontend server and yaz-ztest.
+ Included in both manual and man page for yaz-ztest
+-->
+
+<variablelist>
+
+ <varlistentry><term><literal>-a </literal>
+ <replaceable>file</replaceable></term>
+ <listitem><para>
+ Specify a file for dumping PDUs (for diagnostic purposes).
+ The special name <literal>-</literal> (dash) sends output to
+ <literal>stderr</literal>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-S</literal></term>
+ <listitem><para>
+ Don't fork or make threads on connection requests. This is good for
+ debugging, but not recommended for real operation: Although the
+ server is asynchronous and non-blocking, it can be nice to keep
+ a software malfunction (okay then, a crash) from affecting all
+ current users.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-1</literal></term>
+ <listitem><para>
+ Like <literal>-S</literal> but after one session the server
+ exits. This mode is for debugging <emphasis>only</emphasis>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-T</literal></term>
+ <listitem><para>
+ Operate the server in threaded mode. The server creates a thread
+ for each connection rather than a fork a process. Only available
+ on UNIX systems that offers POSIX threads.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-s</literal></term>
+ <listitem><para>
+ Use the SR protocol (obsolete).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-z</literal></term>
+ <listitem><para>
+ Use the Z39.50 protocol (default). This option and <literal>-s</literal>
+ complement each other.
+ You can use both multiple times on the same command
+ line, between listener-specifications (see below). This way, you
+ can set up the server to listen for connections in both protocols
+ concurrently, on different local ports.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-l </literal>
+ <replaceable>file</replaceable></term>
+ <listitem><para>The logfile.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-c </literal>
+ <replaceable>config</replaceable></term>
+ <listitem><para>A user option that serves as a specifier for some
+ sort of configuration, usually a filename.
+ The argument to this option is transferred to member
+ <literal>configname</literal> of the
+ <literal>statserv_options_block</literal>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-f </literal>
+ <replaceable>vconfig</replaceable></term>
+ <listitem><para>This specifies an XML file that describes
+ one or more YAZ frontend virtual servers.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-C </literal>
+ <replaceable>fname</replaceable></term>
+ <listitem><para>Sets SSL certificate file name for server (PEM).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-v </literal>
+ <replaceable>level</replaceable></term>
+ <listitem><para>
+ The log level. Use a comma-separated list of members of the set
+ {fatal,debug,warn,log,malloc,all,none}.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-u </literal>
+ <replaceable>uid</replaceable></term>
+ <listitem><para>
+ Set user ID. Sets the real UID of the server process to that of the
+ given user. It's useful if you aren't comfortable with having the
+ server run as root, but you need to start it as such to bind a
+ privileged port.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-w </literal>
+ <replaceable>dir</replaceable></term>
+ <listitem><para>
+ The server changes to this directory during before listening
+ on incoming connections. This option is useful
+ when the server is operating from the <application>inetd</application>
+ daemon (see <literal>-i</literal>).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-p </literal>
+ <replaceable>pidfile</replaceable></term>
+ <listitem><para>
+ Specifies that the server should write its Process ID to
+ file given by <replaceable>pidfile</replaceable>.
+ A typical location would be <filename>/var/run/yaz-ztest.pid</filename>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-i</literal></term>
+ <listitem><para>
+ Use this to make the the server run from the
+ <application>inetd</application> server (UNIX only).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-D</literal></term>
+ <listitem><para>
+ Use this to make the server put itself in the background and
+ run as a daemon. If neither <literal>-i</literal> nor
+ <literal>-D</literal> is given, the server starts in the foreground.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-install</literal></term>
+ <listitem><para>
+ Use this to install the server as an NT service
+ (Windows NT/2000/XP only).
+ Control the server by going to the Services in the Control Panel.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-installa</literal></term>
+ <listitem><para>
+ Use this to install and activate the server as an NT service
+ (Windows NT/2000/XP only).
+ Control the server by going to the Services in the Control Panel.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-remove</literal></term>
+ <listitem><para>
+ Use this to remove the server from the NT services
+ (Windows NT/2000/XP only).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-t </literal>
+ <replaceable>minutes</replaceable></term>
+ <listitem><para>
+ Idle session timeout, in minutes.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><literal>-k </literal>
+ <replaceable>size</replaceable></term>
+ <listitem><para>
+ Maximum record size/message size, in kilobytes.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term><literal>-d </literal>
+ <replaceable>daemon</replaceable></term>
+ <listitem><para>
+ Set name of daemon to be used in hosts access file.
+ See
+ <citerefentry>
+ <refentrytitle>hosts_access</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>tcpd</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+</variablelist>
+
+<!-- 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:
+-->
--- /dev/null
+<!--
+ $Id: zebrasrv-synopsis.xml,v 1.1 2005-08-05 14:39:12 marc Exp $
+ cmd description of YAZ GFS application.
+ Included in both manual and man page for yaz-ztest
+-->
+
+<cmdsynopsis>
+ <command>&gfs-synopsis-app;</command>
+ <arg choice="opt"><option>-install</option></arg>
+ <arg choice="opt"><option>-installa</option></arg>
+ <arg choice="opt"><option>-remove</option></arg>
+ <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>-f <replaceable>vconfig</replaceable></option></arg>
+ <arg choice="opt"><option>-C <replaceable>fname</replaceable></option></arg>
+ <arg choice="opt"><option>-t <replaceable>minutes</replaceable></option></arg>
+ <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>-p <replaceable>pidfile</replaceable></option></arg>
+ <arg choice="opt"><option>-ziDST1</option></arg>
+ <arg choice="opt" rep="repeat">listener-spec</arg>
+</cmdsynopsis>
+
+<!-- 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:
+-->
--- /dev/null
+<!--
+ $Id: zebrasrv-virtual.xml,v 1.1 2005-08-05 14:39:12 marc Exp $
+ Description of the virtual host 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>
+ A backend can be configured to execute in a particular working
+ directory. Or the YAZ frontend may perform CQL to RPN conversion, thus
+ allowing traditional Z39.50 backends to be offered as a SRW/SRU
+ service. SRW/SRU Explain information for a particular backend may also
+ be specified.
+</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. 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>,
+ <literal>tcp:server1:2100</literal>,
+ etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>attribute <literal>id</literal> (optional)</term>
+ <listitem>
+ <para>
+ identifier for this listener. This may be referred to from
+ server sections.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <note>
+ <para>
+ We expect more information to be added for the listen section in
+ a future version, such as CERT file for SSL servers.
+ </para>
+ </note>
+</para>
+<para>
+ The <literal>server</literal> describes a server and the parameters
+ for this server type. Content for a server:
+ <variablelist>
+ <varlistentry><term>attribute <literal>id</literal> (optional)</term>
+ <listitem>
+ <para>
+ Identifier for this server. Currently not used for anything,
+ but it might be for logging purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>element <literal>config</literal> (optional)</term>
+ <listitem>
+ <para>
+ Specifies the server configuration. This is equivalent
+ to the config specified using command line option
+ <literal>-c</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>element <literal>directory</literal> (optional)</term>
+ <listitem>
+ <para>
+ Specifies a working directory for this backend server. If
+ specifid, the YAZ fronend changes current working directory
+ to this directory whenever a backend of this type is
+ started (backend handler bend_start), stopped (backend handler hand_stop)
+ and initialized (bend_init).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>element <literal>host</literal> (optional)</term>
+ <listitem>
+ <para>
+ Specifies the virtual host for this server. If this is specified
+ a client <emphasis>must</emphasis> specify this host string in
+ order to use this backend.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>element <literal>cql2rpn</literal> (optional)</term>
+ <listitem>
+ <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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>element <literal>explain</literal> (optional)</term>
+ <listitem>
+ <para>
+ Specifies SRW/SRU ZeeRex content for this server. Copied verbatim
+ to the client. As things are now, some of the Explain content
+ seeem redundant because host information, etc. is also stored
+ elsewhere.
+ </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.
+ We name the TCP/IP server <literal>public</literal> and the
+ other server <literal>internal</literal>.
+ </para>
+ <screen>
+ <![CDATA[
+ <yazgfs>
+ <listen id="public">tcp:@:9900</listen>
+ <listen id="internal">unix:/var/tmp/socket</listen>
+ <server id="server1">
+ <host>server1.mydomain</host>
+ <directory>/var/www/s1</directory>
+ <config>config.cfg</config>
+ </server>
+ <server id="server2">
+ <host>server2.mydomain</host>
+ <directory>/var/www/s2</directory>
+ <config>config.cfg</config>
+ <cql2rpn>../etc/pqf.properties</cql2rpn>
+ <explain xmlns="http://explain.z3950.org/dtd/2.0/">
+ <serverInfo>
+ <host>server2.mydomain</host>
+ <port>9900</port>
+ <database>a</database>
+ </serverInfo>
+ </explain>
+ </server>
+ <server id="server3" listenref="internal">
+ <directory>/var/www/s3</directory>
+ <config>config.cfg</config>
+ </server>
+ </yazgfs>
+]]>
+ </screen>
+<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
+ been specified for each of server in the <literal>host</literal>
+ elements.
+</para>
+<para>
+ For <literal>"server2"</literal> elements for CQL to RPN conversion
+ is supported and explain information has been added (a short one here
+ to keep the example small).
+</para>
+<para>
+ The third server, <literal>"server3"</literal> can only be reached
+ via listener <literal>"internal"</literal>.
+</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:
+-->
projects / idzebra-moved-to-github.git / commitdiff