doc/pazpar2.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   3 [
   4      <!ENTITY % local SYSTEM "local.ent">
   5      %local;
   6      <!ENTITY % entities SYSTEM "entities.ent">
   7      %entities;
   8      <!ENTITY % idcommon SYSTEM "common/common.ent">
   9      %idcommon;
  10 ]>
  11 <refentry id="pazpar2">
  12  <refentryinfo>
  13   <productname>Pazpar2</productname>
  14   <productnumber>&version;</productnumber>
  15   <info><orgname>Index Data</orgname></info>
  16  </refentryinfo>
  17
  18  <refmeta>
  19   <refentrytitle>Pazpar2</refentrytitle>
  20   <manvolnum>8</manvolnum>
  21   <refmiscinfo class="manual">System management commands</refmiscinfo>
  22  </refmeta>
  23
  24  <refnamediv>
  25   <refname>pazpar2</refname>
  26   <refpurpose>Metasearch daemon.</refpurpose>
  27  </refnamediv>
  28
  29  <refsynopsisdiv>
  30   <cmdsynopsis>
  31    <command>pazpar2</command>
  32    <arg choice="opt"><option>-d</option></arg>
  33    <arg choice="opt"><option>-D</option></arg>
  34    <arg choice="opt"><option>-f <replaceable>config</replaceable></option></arg>
  35    <arg choice="opt"><option>-h <replaceable>ip:port</replaceable></option></arg>
  36    <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
  37    <arg choice="opt"><option>-m <replaceable>timeformat</replaceable></option></arg>
  38    <arg choice="opt"><option>-p <replaceable>pidfile</replaceable></option></arg>
  39    <arg choice="opt"><option>-R <replaceable>recfile</replaceable></option></arg>
  40    <arg choice="opt"><option>-t</option></arg>
  41    <arg choice="opt"><option>-u <replaceable>uid</replaceable></option></arg>
  42    <arg choice="opt"><option>-v <replaceable>level</replaceable></option></arg>
  43    <arg choice="opt"><option>-V</option></arg>
  44    <arg choice="opt"><option>-w <replaceable>dir</replaceable></option></arg>
  45    <arg choice="opt"><option>-X</option></arg>
  46    <arg choice="opt"><option>-install</option></arg>
  47    <arg choice="opt"><option>-remove</option></arg>
  48   </cmdsynopsis>
  49  </refsynopsisdiv>
  50
  51  <refsect1>
  52   <title>DESCRIPTION</title>
  53   <para>
  54    <command>pazpar2</command> is the Pazpar2 Metasearch daemon
  55    and server.
  56    In normal operation it acts as a simple HTTP server which serves
  57    the Pazpar2 protocol.
  58    The HTTP listener address may be given on the command line using
  59    option <option>-h</option> or in the main configuration
  60    file. The main configuration must be specified using option
  61    <option>-f</option>.
  62   </para>
  63  </refsect1>
  64
  65  <refsect1>
  66   <title>OPTIONS</title>
  67
  68   <variablelist>
  69    <varlistentry>
  70     <term><option>-d</option></term>
  71     <listitem>
  72      <para>
  73       Enables dump of XML records to the current log file.
  74       It is useful if stylesheets are being debugged. Using this option
  75       twice makes Pazpar2 also dump full HTTP responses.
  76      </para>
  77      <para>
  78       This option may also be used together with option <option>-t</option>
  79       in which case the configuration, after include processing, will be
  80       dumped to stdout.
  81      </para>
  82     </listitem>
  83    </varlistentry>
  84    <varlistentry>
  85     <term><option>-D</option></term>
  86     <listitem>
  87      <para>
  88      Puts the Pazpar2 server in the background.
  89      </para>
  90     </listitem>
  91    </varlistentry>
  92    <varlistentry>
  93     <term><option>-f <replaceable>config</replaceable></option></term>
  94     <listitem>
  95      <para>
  96       Specifies main configuration. This option must be specified
  97       in order for Pazpar2 to operate normally.
  98      </para>
  99     </listitem>
 100    </varlistentry>
 101    <varlistentry>
 102     <term><option>-h <replaceable>ip:port</replaceable></option></term>
 103     <listitem>
 104      <para>
 105       Specifies the HTTP listener binding address.
 106       The <replaceable>ip</replaceable>
 107       may be a hostname or <literal>@</literal> for "any" address.
 108       The <replaceable>port</replaceable> is an integer.
 109      </para>
 110     </listitem>
 111    </varlistentry>
 112    <varlistentry>
 113     <term><option>-l <replaceable>logfile</replaceable></option></term>
 114     <listitem>
 115      <para>
 116       Specifies log file. The log file must be specified when Pazpar2
 117       is running in the background (-D).
 118      </para>
 119     </listitem>
 120    </varlistentry>
 121    <varlistentry>
 122     <term>-m <replaceable>timeformat</replaceable></term>
 123     <listitem><para>
 124      Sets the format of time-stamps for logging.
 125      Refer to the
 126        <ulink
 127            url="http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">
 128        strftime(3)</ulink>
 129        man page for the format.
 130     </para></listitem>
 131    </varlistentry>
 132    <varlistentry>
 133     <term><option>-p <replaceable>pidfile</replaceable></option></term>
 134     <listitem>
 135      <para>
 136       Specifies PID file. If Pazpar2 is started and configured properly
 137       the file given holds the process ID of the Pazpar2 process.
 138      </para>
 139     </listitem>
 140    </varlistentry>
 141    <varlistentry>
 142     <term><option>-R <replaceable>recfile</replaceable></option></term>
 143     <listitem>
 144      <para>
 145       If this option is given, HTTP requests are logged to file named
 146       <replaceable>recfile</replaceable> and predictable sessions are enabled.
 147       Using special argument, dash
 148       (<literal>-</literal>), will make Pazpar2 use predictable sessions
 149       only (no recording).
 150       This is necessary when playing HTTP communication against pazpar2
 151       with the pazpar2 program. Refer to <xref linkend="pazpar2_play"/>.
 152      </para>
 153     </listitem>
 154    </varlistentry>
 155
 156    <varlistentry>
 157     <term><option>-t</option></term>
 158     <listitem>
 159      <para>
 160       Checks parameters and configuration. No service or daemon is
 161       started. Useful for checking a new configuration before a
 162       Pazpar2 is restarted.
 163      </para>
 164      <para>
 165       The configuration, after include processing, may also be dumped
 166       to stdout by supplying option <option>-d</option> as well.
 167      </para>
 168      <note>
 169       <para>
 170        In Pazpar2 1.2 and earlier releases, option -t specified a
 171        local target settings file.
 172       </para>
 173      </note>
 174     </listitem>
 175    </varlistentry>
 176
 177    <varlistentry>
 178     <term><option>-u <replaceable>uid</replaceable></option></term>
 179     <listitem>
 180      <para>
 181       Makes the Pazpar2 server change user ID to the
 182       <replaceable>uid</replaceable> given.
 183       This, normally, requires root privilege.
 184      </para>
 185     </listitem>
 186    </varlistentry>
 187
 188    <varlistentry>
 189     <term><option>-v <replaceable>level</replaceable></option></term>
 190     <listitem>
 191      <para>
 192       Sets log level (YAZ log level system).
 193      </para>
 194     </listitem>
 195    </varlistentry>
 196
 197    <varlistentry>
 198     <term><option>-V</option></term>
 199     <listitem>
 200      <para>
 201       Shows Pazpar2 version and versions of some of the components that it
 202       is using (ICU and YAZ). Pazpar2 will exit immediately after
 203       displaying the version information (no daemon started).
 204      </para>
 205     </listitem>
 206    </varlistentry>
 207
 208    <varlistentry>
 209     <term><option>-w <replaceable>dir</replaceable></option></term>
 210     <listitem>
 211      <para>
 212       Changes working directory to <replaceable>dir</replaceable>.
 213      </para>
 214     </listitem>
 215    </varlistentry>
 216
 217    <varlistentry>
 218     <term><option>-X</option></term>
 219     <listitem>
 220      <para>
 221       Makes the Pazpar2 server operate in debugging mode.
 222       This prevents Pazpar2 from making separate threads and processes.
 223       This option should not be used in production.
 224      </para>
 225     </listitem>
 226    </varlistentry>
 227
 228    <varlistentry>
 229     <term><option>-install</option></term>
 230     <listitem>
 231      <para>
 232       This is an option which is only recognized on Windows. It installs
 233       Pazpar2 as a Windows Service.
 234      </para>
 235      <note>
 236       <para>
 237        Pazpar2 only supports Windows Service options if Pazpar2 is
 238        linked against YAZ 3.0.29 or later.
 239       </para>
 240      </note>
 241     </listitem>
 242    </varlistentry>
 243
 244    <varlistentry>
 245     <term><option>-remove</option></term>
 246     <listitem>
 247      <para>
 248       This is an option which is only recognized on Windows. It removes
 249       a Pazpar2 - Windows Service.
 250      </para>
 251     </listitem>
 252    </varlistentry>
 253
 254   </variablelist>
 255
 256  </refsect1>
 257
 258  <refsect1>
 259   <title>EXAMPLES</title>
 260   <para>The Debian package of pazpar2 starts the server with:
 261    <screen>
 262     pazpar2 -D -f /etc/pazpar2/pazpar2.cfg -l /var/log/pazpar2.log -p /var/run/pazpar2.pid -u nobody
 263    </screen>
 264    (one line).
 265   </para>
 266   <para>
 267    This will put pazpar2 in the background (-D), read config from from
 268    <filename>/etc/pazpar2/pazpar2.cfg</filename>, log messages to
 269    <filename>/var/log/pazpar2.log</filename>, create PID file
 270    <filename>/var/run/pazpar2.pid</filename>. When the daemon is properly
 271    started, the server will change effective user ID to nobody.
 272   </para>
 273   <para>
 274    The server can be terminated with:
 275    <screen>
 276     kill `cat /var/run/pazpar2.pid`
 277    </screen>
 278   </para>
 279   <para>
 280    If Pazpar2 is to be debugged using GDB, we use option -X:
 281    <screen>
 282     cd pazpar2/src
 283     gdb ./pazpar2
 284     (gdb) run -X -f ../etc/pazpar2.cfg
 285    </screen>
 286   </para>
 287  </refsect1>
 288
 289  <refsect1>
 290   <title>FILES</title>
 291   <para><filename>/usr/sbin/pazpar2</filename>: pazpar2 daemon</para>
 292
 293   <para><filename>/usr/share/pazpar2</filename>: pazpar2 shared files</para>
 294
 295   <para><filename>/etc/pazpar2</filename>: pazpar2 config area</para>
 296  </refsect1>
 297
 298  <refsect1>
 299   <title>SEE ALSO</title>
 300   <para>
 301    Pazpar2 configuration:
 302    <citerefentry>
 303     <refentrytitle>pazpar2_conf</refentrytitle>
 304     <manvolnum>5</manvolnum>
 305    </citerefentry>
 306   </para>
 307   <para>
 308    Pazpar2 protocol:
 309    <citerefentry>
 310     <refentrytitle>pazpar2_protocol</refentrytitle>
 311     <manvolnum>7</manvolnum>
 312    </citerefentry>
 313   </para>
 314   <para>
 315    Pazpar2 player:
 316    <citerefentry>
 317     <refentrytitle>pazpar2_play</refentrytitle>
 318     <manvolnum>1</manvolnum>
 319    </citerefentry>
 320   </para>
 321  </refsect1>
 322
 323 </refentry>
 324
 325 <!-- Keep this comment at the end of the file
 326 Local variables:
 327 mode: nxml
 328 nxml-child-indent: 1
 329 End:
 330 -->