<orderedlist>
<listitem>
<para> If the <literal>InitializeRequest</literal> PDU from the
- client includes an <literal>otherInfo</literal> element with OID
+ client includes an
+ <link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
+ element with OID
<literal>1.2.840.10003.10.1000.81.1</literal>, then the
contents of that element specify the target to be used, in the
usual YAZ address format (typically
guarantee that the Z39.50 connection to the backend
target is kept forever: the proxy will shut it down after certain
idle time.
- <!-- ### How long? Wot no command-line option? -->
So in effect, the connection from the client's
point of view should be considered stateless, and the keep-alive
facility should be treated only as a performance booster.
</para>
<para>
- Cookies may be passed in an <literal>otherInfo</literal> element
- with OID <literal>1.2.840.10003.10.1000.81.2</literal>.
+ Cookies may be passed in an
+ <link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
+ element with OID <literal>1.2.840.10003.10.1000.81.2</literal>.
</para>
</section>
backend target, so that if an identical query is received next, it
is turned into Present Requests rather than new Search Requests.
</para>
- <!-- ### should be generalised to an arbitrary-sized cache -->
+ <note>
+ <para>
+ In a future we release will will probably allows for
+ an arbitrary-sized cache for targets supporting named result sets.
+ </para>
+ </note>
<para>
- This optimization should work for any Z39.50 client and/or
- target. The target does not have to support named result sets.
+ You can enable/disable query caching using option -o.
</para>
- <!-- ### There should be an option to turn this off, as it will
- affect semantics for some searches on some databases:
- e.g. "ten most recent stories" in a newswire database.
- -->
</section>
<section id="proxy-optimizations">
<para>
</para>
<refentry id="yaz-proxy">
- <refmeta>
- <refentrytitle>yaz-proxy</refentrytitle>
- <manvolnum>8</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>yaz-proxy</refname>
- <refpurpose>The YAZ toolkit's transparent Z39.50 proxy</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>yaz-proxy</command>
- <arg choice="opt">-a <replaceable>filename</replaceable></arg>
- <arg choice="opt">-c <replaceable>num</replaceable></arg>
- <arg choice="opt">-v <replaceable>level</replaceable></arg>
- <arg choice="opt">-t <replaceable>target</replaceable></arg>
- <arg choice="opt">-u <replaceable>auth</replaceable></arg>
- <arg choice="opt">-o <replaceable>level</replaceable></arg>
- <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1><title>DESCRIPTION</title>
- <para>
- The proxy runs stand-alone (not from
- <literal>inetd</literal>). The
- <replaceable>host</replaceable>:<replaceable>port</replaceable>
- argument specifies host address to listen to, and the port to
- listen on. Use the host <literal>@</literal>
- to listen for connections coming from any address.
- </para>
- </refsect1>
- <refsect1><title>OPTIONS</title>
- <variablelist>
- <varlistentry><term>-a <replaceable>filename</replaceable></term>
- <listitem><para>
- Specifies the name of a file to which to write a log of the
- APDUs (protocol packets) that pass through the proxy. The
- special filename <literal>-</literal> may be used to indicate
- standard output.
- </para></listitem>
- </varlistentry>
- <varlistentry><term>-c <replaceable>num</replaceable></term>
- <listitem><para>
- Specifies the maximum number of connections to be cached
- [default 50].
- </para></listitem>
- </varlistentry>
- <varlistentry><term>-v <replaceable>level</replaceable></term>
- <listitem><para>
- Sets the logging level. <replaceable>level</replaceable> is
- a comma-separated list of members of the set
- {<literal>fatal</literal>,<literal>debug</literal>,<literal>warn</literal>,<literal>log</literal>,<literal>malloc</literal>,<literal>all</literal>,<literal>none</literal>}.
- </para></listitem>
- </varlistentry>
- <varlistentry><term>-t <replaceable>target</replaceable></term>
- <listitem><para>
- Specifies the default backend target to use when a client
- connects that does not explicitly specify a target in its
- <literal>initRequest</literal>.
- </para></listitem>
- </varlistentry>
- <varlistentry><term>-u <replaceable>auth</replaceable></term>
- <listitem><para>
- Specifies authentication info to be sent to the backend target.
- This is useful if you happen to have an internal target that
- requires authentication, or if the client software does not allow
- you to set it.
- </para></listitem>
- </varlistentry>
- <varlistentry><term>-o <replaceable>level</replaceable></term>
- <listitem><para>
- Sets level for optimization. Use zero to disable; non-zero
- to enable. Handling for this is not fully implemented;
- we will probably use a bit mask to enable/disable specific
- features.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>EXAMPLES</title>
- <para>
- The following command starts the proxy, listening on port
- 9000, with its default backend target set to the Library of
- Congress bibliographic server:
- </para>
- <screen>
- $ yaz-proxy -t z3950.loc.gov:7090 @:9000
- </screen>
- <para>
- The LOC target is sometimes very slow. You can connect to
- it using yaz-client as follows:
- </para>
- <screen>
- $ yaz-client localhost:9000/voyager
- Connecting...Ok.
- Sent initrequest.
- Connection accepted by target.
- ID : 34
- Name : Voyager LMS - Z39.50 Server
- Version: 1.13
- Options: search present
- Elapsed: 7.131197
- Z> f computer
- Sent searchRequest.
- Received SearchResponse.
- Search was a success.
- Number of hits: 10000
- records returned: 0
- Elapsed: 6.695174
- Z> f computer
- Sent searchRequest.
- Received SearchResponse.
- Search was a success.
- Number of hits: 10000
- records returned: 0
- Elapsed: 0.001417
- </screen>
- <para>
- In this test, the second search was more than 4000 times faster
- than the first, because the proxy cached the result of the first
- search and noticed that the second was the same.
- </para>
- <para>
- The YAZ command-line client,
- <literal>yaz-client</literal>,
- allows you to set the backend target in
- the <literal>initRequest</literal> using the
- <literal>-p</literal> option. For example, to connect to
- Index Data's target you could use:
- </para>
- <screen>
- yaz-client -p indexdata.dk localhost:9000/gils
- </screen>
- </refsect1>
+ &yaz-proxy-ref;
</refentry>
</section>
+ <section id="otherinfo-encoding"><title>Otherinformation Encoding</title>
+ <para>
+ The proxy uses the OtherInformation definition to carry
+ information about the target address and cookie.
+ </para>
+ <literallayout>
+ OtherInformation ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{
+ category [1] IMPLICIT InfoCategory OPTIONAL,
+ information CHOICE{
+ characterInfo [2] IMPLICIT InternationalString,
+ binaryInfo [3] IMPLICIT OCTET STRING,
+ externallyDefinedInfo [4] IMPLICIT EXTERNAL,
+ oid [5] IMPLICIT OBJECT IDENTIFIER}}
+--
+ InfoCategory ::= SEQUENCE{
+ categoryTypeId [1] IMPLICIT OBJECT IDENTIFIER OPTIONAL,
+ categoryValue [2] IMPLICIT INTEGER}
+ </literallayout>
+ <para>
+ The <literal>categoryTypeId</literal> is either
+ OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2
+ for proxy target and proxy cookie respectively. The
+ integer element <literal>category</literal> is set to 0.
+ The value proxy and cookie is stored in element
+ <literal>characterInfo</literal> of the <literal>information</literal>
+ choice.
+ </para>
+ </section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
--- /dev/null
+<refmeta>
+ <refentrytitle>yaz-proxy</refentrytitle>
+ <manvolnum>8</manvolnum>
+</refmeta>
+<refnamediv>
+ <refname>yaz-proxy</refname>
+ <refpurpose>The YAZ toolkit's transparent Z39.50 proxy</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>yaz-proxy</command>
+ <arg choice="opt">-a <replaceable>filename</replaceable></arg>
+ <arg choice="opt">-c <replaceable>num</replaceable></arg>
+ <arg choice="opt">-v <replaceable>level</replaceable></arg>
+ <arg choice="opt">-t <replaceable>target</replaceable></arg>
+ <arg choice="opt">-u <replaceable>auth</replaceable></arg>
+ <arg choice="opt">-o <replaceable>level</replaceable></arg>
+ <arg choice="opt">-i <replaceable>seconds</replaceable></arg>
+ <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
+ </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>DESCRIPTION</title>
+ <para>
+ The proxy runs stand-alone (not from
+ <literal>inetd</literal>). The
+ <replaceable>host</replaceable>:<replaceable>port</replaceable>
+ argument specifies host address to listen to, and the port to
+ listen on. Use the host <literal>@</literal>
+ to listen for connections coming from any address.
+ </para>
+</refsect1>
+<refsect1><title>OPTIONS</title>
+ <variablelist>
+ <varlistentry><term>-a <replaceable>filename</replaceable></term>
+ <listitem><para>
+ Specifies the name of a file to which to write a log of the
+ APDUs (protocol packets) that pass through the proxy. The
+ special filename <literal>-</literal> may be used to indicate
+ standard output.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-c <replaceable>num</replaceable></term>
+ <listitem><para>
+ Specifies the maximum number of connections to be cached
+ [default 50].
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-v <replaceable>level</replaceable></term>
+ <listitem><para>
+ Sets the logging level. <replaceable>level</replaceable> is
+ a comma-separated list of members of the set
+ {<literal>fatal</literal>,<literal>debug</literal>,<literal>warn</literal>,<literal>log</literal>,<literal>malloc</literal>,<literal>all</literal>,<literal>none</literal>}.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-t <replaceable>target</replaceable></term>
+ <listitem><para>
+ Specifies the default backend target to use when a client
+ connects that does not explicitly specify a target in its
+ <literal>initRequest</literal>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-u <replaceable>auth</replaceable></term>
+ <listitem><para>
+ Specifies authentication info to be sent to the backend target.
+ This is useful if you happen to have an internal target that
+ requires authentication, or if the client software does not allow
+ you to set it.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-o <replaceable>level</replaceable></term>
+ <listitem><para>
+ Sets level for optimization. Use zero to disable; non-zero
+ to enable. Handling for this is not fully implemented;
+ we will probably use a bit mask to enable/disable specific
+ features. By default optimization is enabled (value 1).
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-i <replaceable>seconds</replaceable></term>
+ <listitem><para>
+ Specifies in seconds the idle time for communication
+ for proxy. If a connection is inactive for this long
+ it willl be closed. Default: 600 seconds (10 minutes).
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+ <para>
+ The following command starts the proxy, listening on port
+ 9000, with its default backend target set to the Library of
+ Congress bibliographic server:
+ </para>
+ <screen>
+ $ yaz-proxy -t z3950.loc.gov:7090 @:9000
+ </screen>
+ <para>
+ The LOC target is sometimes very slow. You can connect to
+ it using yaz-client as follows:
+ </para>
+ <screen>
+ $ yaz-client localhost:9000/voyager
+ Connecting...Ok.
+ Sent initrequest.
+ Connection accepted by target.
+ ID : 34
+ Name : Voyager LMS - Z39.50 Server
+ Version: 1.13
+ Options: search present
+ Elapsed: 7.131197
+ Z> f computer
+ Sent searchRequest.
+ Received SearchResponse.
+ Search was a success.
+ Number of hits: 10000
+ records returned: 0
+ Elapsed: 6.695174
+ Z> f computer
+ Sent searchRequest.
+ Received SearchResponse.
+ Search was a success.
+ Number of hits: 10000
+ records returned: 0
+ Elapsed: 0.001417
+ </screen>
+ <para>
+ In this test, the second search was more than 4000 times faster
+ than the first, because the proxy cached the result of the first
+ search and noticed that the second was the same.
+ </para>
+ <para>
+ The YAZ command-line client,
+ <literal>yaz-client</literal>,
+ allows you to set the proxy target as part of the Initialize
+ Request using option <literal>-p</literal>.
+ For example, to connect to Index Data's target you could use:
+ </para>
+ <screen>
+ yaz-client -p indexdata.dk localhost:9000/gils
+ </screen>
+</refsect1>
+ <!-- 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: "proxy.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->
projects / yazpp-moved-to-github.git / commitdiff