Update doc/common
[metaproxy-moved-to-github.git] / doc / metaproxy.xml
1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN" 
2     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
3  <!ENTITY copyright SYSTEM "copyright.xml">
4  <!ENTITY % local SYSTEM "local.ent">
5      %local;
6  <!ENTITY % idcommon SYSTEM "common/common.ent">
7      %idcommon;
8 ]>
9 <refentry id="ref-metaproxy">
10  <refentryinfo>
11   <productname>Metaproxy</productname>
12   <productnumber>&version;</productnumber>
13   <info><orgname>Index Data</orgname></info>
14  </refentryinfo>
15
16  <refmeta>
17   <refentrytitle>metaproxy</refentrytitle>
18   <manvolnum>1</manvolnum>
19   <refmiscinfo class="manual">Commands</refmiscinfo>
20  </refmeta>
21  
22  <refnamediv>
23   <refname>metaproxy</refname>
24   <refpurpose>Metaproxy - server</refpurpose>
25  </refnamediv>
26  
27  <refsynopsisdiv>
28   <cmdsynopsis>
29    <command>metaproxy</command>
30    <arg choice="opt"><option>--help</option></arg>
31    <arg choice="opt"><option>--version</option></arg>
32    <arg choice="opt"><option>--config <replaceable>config</replaceable></option></arg>
33    <arg choice="opt"><option>-D</option></arg>
34    <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
35    <arg choice="opt"><option>-p <replaceable>pidfile</replaceable></option></arg>
36    <arg choice="opt"><option>-t</option></arg>
37    <arg choice="opt"><option>-u <replaceable>ID</replaceable></option></arg>
38    <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
39    <arg choice="opt"><option>-X</option></arg>
40   </cmdsynopsis>
41  </refsynopsisdiv>
42  
43  <refsect1><title>DESCRIPTION</title>
44
45   <para>
46    <command>metaproxy</command> is the Metaproxy daemon
47   </para>
48
49  </refsect1>
50  
51  <refsect1><title>OPTIONS</title>
52   
53   <variablelist>
54    <varlistentry>
55     <term>--help</term>
56     <listitem><para>
57       Displays help message.
58      </para></listitem>
59    </varlistentry>
60
61    <varlistentry>
62     <term>--version</term>
63     <listitem><para>
64       Displays Metaproxy version.
65      </para></listitem>
66    </varlistentry>
67
68    <varlistentry>
69     <term>--config <replaceable>config</replaceable></term>
70     <listitem><para>
71       Specify the configuration.
72      </para></listitem>
73    </varlistentry>
74
75    <varlistentry>
76     <term>-D</term>
77     <listitem><para>
78       Puts Metaproxy in the background after startup.
79      </para></listitem>
80    </varlistentry>
81
82    <varlistentry>
83     <term>-l <replaceable>logfile</replaceable></term>
84     <listitem><para>
85       Specifies YAZ log file.
86      </para></listitem>
87    </varlistentry>
88
89    <varlistentry>
90     <term>-p <replaceable>pidfile</replaceable></term>
91     <listitem><para>
92       Specifies file which holds PID after startup.
93      </para></listitem>
94    </varlistentry>
95
96    <varlistentry>
97     <term>-t</term>
98     <listitem><para>
99       Tests configuration. Returns exit code 0 on success; non-zero on failure.
100      </para></listitem>
101    </varlistentry>
102
103    <varlistentry>
104     <term>-u <replaceable>ID</replaceable></term>
105     <listitem><para>
106       Makes Metaproxy changes its identity to ID after startup.
107      </para></listitem>
108    </varlistentry>
109
110    <varlistentry>
111     <term>-w <replaceable>dir</replaceable></term>
112     <listitem><para>
113       Changes working directory to <replaceable>dir</replaceable>.
114      </para></listitem>
115    </varlistentry>
116
117    <varlistentry>
118     <term>-X</term>
119     <listitem><para>
120       Makes Metaproxy operate in debug mode.
121      </para></listitem>
122    </varlistentry>
123
124   </variablelist>
125  </refsect1>
126
127  <refsect1><title>CONFIGURATION</title>
128    <para>Metaproxy's configuration is XML based. All elements
129      should be in namespace <literal>http://indexdata.com/metaproxy</literal>.
130    </para>
131    <para>
132      The root element must be named <literal>metaproxy</literal> and
133      must specify a version. Currently the version must be
134      <literal>1.0</literal>. The children elements of metaproxy
135      are:
136      <variablelist>
137        <varlistentry>
138          <term>dlpath</term>
139          <listitem>
140            <para>
141              Specifies the path for Loadable filter modules
142            </para>
143          </listitem>
144        </varlistentry>
145        <varlistentry>
146          <term>start</term>
147          <listitem>
148            <para>
149              Specifies the start route. Takes a <literal>route</literal>
150              attribute with the name of the route.
151            </para>
152          </listitem>
153        </varlistentry>
154        <varlistentry>
155          <term>filters</term>
156          <listitem>
157            <para>
158              Specifies all filters. Includes one ore more 
159              <literal>filter</literal> elements with filter-specific
160              configuration material.
161            </para>
162          </listitem>
163        </varlistentry>
164        <varlistentry>
165          <term>routes</term>
166          <listitem>
167            <para>
168              Specifies all routes. Includes one or more
169              <literal>route</literal> elements. Each <literal>route</literal>
170              in turn includes one or more filter specifications.
171            </para>
172          </listitem>
173        </varlistentry>
174      </variablelist>
175    </para>
176    <para>
177      The configuration is described in more detail in the
178      <ulink url="&url.metaproxy.doc;">Metaproxy manual</ulink>.
179    </para>
180  </refsect1>
181  <refsect1><title>EXAMPLES</title>
182    <para>
183      The configuration below specifies a simple Z39.50 proxy and
184      illustrates most configuration elements of Metaproxy.
185    </para>
186    <screen><![CDATA[
187 <?xml version="1.0"?>
188 <metaproxy xmlns="http://indexdata.com/metaproxy" version="1.0">
189   <dlpath>/usr/local/metaproxy/filters</dlpath>
190   <start route="start"/>
191   <filters>
192     <filter id="frontend" type="frontend_net">
193       <threads>10</threads>
194       <port>@:9000</port>
195     </filter>
196     <filter id="backend" type="z3950_client">
197      <timeout>30</timeout>
198      <default_target>z3950.indexdata.dk</default_target>
199     </filter>
200   </filters>
201   <routes>  
202     <route id="start">
203       <filter refid="frontend"/>
204       <filter type="log">
205         <message>log</message>
206       </filter>
207       <filter refid="backend"/>
208       <filter type="bounce"/>
209     </route>
210   </routes>
211 </metaproxy>
212 ]]>
213    </screen>
214    <para>
215      Start server with configuration in <filename>my.xml</filename>.
216      <screen>
217        metaproxy --config my.xml
218      </screen>
219    </para>
220  </refsect1> 
221
222  <refsect1><title>SCHEMA</title>
223    <literallayout><xi:include
224                      xi:href="../xml/schema/metaproxy.rnc"
225                      xi:parse="text"  
226                      xmlns:xi="http://www.w3.org/2001/XInclude" />
227    </literallayout>
228  </refsect1>
229  
230  <refsect1><title>FILES</title>
231   <para>
232    None important.
233   </para>
234  </refsect1>
235
236  <refsect1><title>SEE ALSO</title>
237   <para>
238    <citerefentry>
239     <refentrytitle>auth_simple</refentrytitle>
240     <manvolnum>3mp</manvolnum>
241    </citerefentry>,
242    <citerefentry>
243     <refentrytitle>backend_test</refentrytitle>
244     <manvolnum>3mp</manvolnum>
245    </citerefentry>,
246    <citerefentry>
247     <refentrytitle>bounce</refentrytitle>
248     <manvolnum>3mp</manvolnum>
249    </citerefentry>,
250    <citerefentry>
251     <refentrytitle>frontend_net</refentrytitle>
252     <manvolnum>3mp</manvolnum>
253    </citerefentry>,
254    <citerefentry>
255     <refentrytitle>http_file</refentrytitle>
256     <manvolnum>3mp</manvolnum>
257    </citerefentry>,
258    <citerefentry>
259     <refentrytitle>log</refentrytitle>
260     <manvolnum>3mp</manvolnum>
261    </citerefentry>,
262    <citerefentry>
263     <refentrytitle>multi</refentrytitle>
264     <manvolnum>3mp</manvolnum>
265    </citerefentry>,
266    <citerefentry>
267     <refentrytitle>query_rewrite</refentrytitle>
268     <manvolnum>3mp</manvolnum>
269    </citerefentry>,
270    <citerefentry>
271     <refentrytitle>record_transform</refentrytitle>
272     <manvolnum>3mp</manvolnum>
273    </citerefentry>,
274    <citerefentry>
275     <refentrytitle>session_shared</refentrytitle>
276     <manvolnum>3mp</manvolnum>
277    </citerefentry>,
278    <citerefentry>
279     <refentrytitle>sru_z3950</refentrytitle>
280     <manvolnum>3mp</manvolnum>
281    </citerefentry>,
282    <citerefentry>
283     <refentrytitle>template</refentrytitle>
284     <manvolnum>3mp</manvolnum>
285    </citerefentry>,
286    <citerefentry>
287     <refentrytitle>virt_db</refentrytitle>
288     <manvolnum>3mp</manvolnum>
289    </citerefentry>,
290    <citerefentry>
291     <refentrytitle>z3950_client</refentrytitle>
292     <manvolnum>3mp</manvolnum>
293    </citerefentry>.
294   </para>
295   <para>
296    The Metaproxy
297    <ulink url="&url.metaproxy.doc;">manual</ulink>.
298   </para>
299  </refsect1>
300
301  &copyright;
302
303 </refentry>
304
305 <!-- Keep this comment at the end of the file
306 Local variables:
307 mode: nxml
308 nxml-child-indent: 1
309 End:
310 -->