aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authoryaworsky <yaworsky>2005-10-17 19:22:16 +0000
committeryaworsky <yaworsky>2005-10-17 19:22:16 +0000
commite6d3929b119dfd10cd83a932cc3337ffb9a04b97 (patch)
tree20e1f2f1f33a9c8f73b43587d5b6a17e1064685a /doc
parentaf413c6d504ed757b081736d96c6cf87617c283b (diff)
downloadsyslog-win32-e6d3929b119dfd10cd83a932cc3337ffb9a04b97.tar.gz
syslog-win32-e6d3929b119dfd10cd83a932cc3337ffb9a04b97.tar.xz
syslog-win32-e6d3929b119dfd10cd83a932cc3337ffb9a04b97.zip
Added to CVS.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/compiling.xml93
-rw-r--r--doc/src/configuration.xml561
-rw-r--r--doc/src/intro.xml58
-rw-r--r--doc/src/logger.xml103
-rw-r--r--doc/src/syslogd.xml112
-rw-r--r--doc/src/test.xml131
6 files changed, 1058 insertions, 0 deletions
diff --git a/doc/src/compiling.xml b/doc/src/compiling.xml
new file mode 100644
index 0000000..3d78701
--- /dev/null
+++ b/doc/src/compiling.xml
@@ -0,0 +1,93 @@
+<preface>
+ <para>
+You need <ulink url="http://www.gtk.org/">Glib</ulink> to compile this stuff.
+Take <ulink url="http://www.gimp.org/win32/">the binary distribution</ulink> or compile it
+yourself (look into <filename>extras</filename> subdirectory for an example).
+ </para>
+</preface>
+
+<section>
+ <title>Compiling from CVS</title>
+ <para>
+Run <command>autogen.sh</command>. I used automake 1.8.5, autoconf 2.59
+and libtool 1.5.10.
+With earlier versions it may not work because some command line options
+aren't supported.
+Then use <command>configure</command> script as described below.
+ </para>
+</section>
+
+<section>
+ <title>Compiling from source tarball</title>
+ <para>
+Just use <command>configure &amp;&amp; make</command>.
+Option <option>--enable-relocatable</option> affects the location of
+configuration directory: if specified, <option>sysconfdir</option>
+is prepended with <quote>.</quote>.
+For example, if you run
+ <screen>
+./configure --sysconfdir=/etc --enable-relocateble</screen>
+then <command>syslogd.exe</command> and client will read their
+configuration file from <filename>etc</filename> subdirectory
+located in the same directory with executable file.
+ </para>
+</section>
+
+<section>
+ <title>Building binary distribution</title>
+ <para>
+Use <command>build.sh</command>. It does all you need.
+You should have some packages&nbsp;&mdash; look into the script
+to see which ones.
+Also, you should have <ulink url="http://www.jrsoftware.org">Inno Setup</ulink>
+with ISPP installed in your system.
+ </para>
+
+ <section>
+ <title>on UNIX</title>
+ <para>
+You should have cross compiler and <ulink url="http://winehq.org">Wine</ulink>
+installed.
+Wine is required to run Inno Setup Compiler and the directory in which
+you are going to build should be accessible via some drive letter.
+ </para>
+ <para>
+Assuming target triplet is <emphasis>i686-pc-mingw32</emphasis>,
+iscc is in its default directory <filename>c:\program files\inno setup 5</filename>
+and required packages are in <filename>./distfiles</filename>:
+ <screen>
+DISTFILES=distfiles \
+ISCC=c:\\program\ files\\inno\ setup\ 5\\iscc.exe \
+HOST=i686-pc-mingw32 \
+./build.sh</screen>
+ </para>
+ </section>
+
+ <section>
+ <title>on Windows</title>
+ <para>
+I've noticed that <ulink url="http://www.mingw.org/msys.shtml">Msys</ulink> has troubles
+running some native command-line applications.
+So you'll have to run Inno Setup by hand.
+ <screen>
+DISTFILES=&lt;path to the directory with packages&gt; \
+./build.sh</screen>
+ </para>
+ </section>
+</section>
+
+<section>
+ <title>Compiling documentation</title>
+ <para>
+You should have DocBook and DocBook Website installed in your system.
+Go to <filename>doc/website</filename> directory and issue the following commands:
+<screen>
+xsltproc --output autolayout.xml \
+ http://docbook.sourceforge.net/release/website/2.6/xsl/autolayout.xsl \
+ layout.xml
+
+xsltproc --stringparam output-root htdocs \
+ stylesheets/chunk-tabular.xsl \
+ autolayout.xml</screen>
+ </para>
+</section>
diff --git a/doc/src/configuration.xml b/doc/src/configuration.xml
new file mode 100644
index 0000000..eddd098
--- /dev/null
+++ b/doc/src/configuration.xml
@@ -0,0 +1,561 @@
+<section>
+ <title>Syslog client</title>
+ <para>
+The configuration file for client is optional.
+Its name is <filename>syslog.host</filename> and it should contain host
+name or IPv4 address optionally followed by the colon and the port number.
+By default port is 514.
+If the file is missing then localhost is assumed.
+ </para>
+ <para>
+This may look a bit ugly but if you have a better idea, send me a patch.
+But keep in mind that client should not have any dependencies like daemon.
+ </para>
+</section>
+
+<section>
+ <title>Syslog daemon</title>
+ <para>
+The concept is quite simple: there are message <emphasis>sources</emphasis>,
+message <emphasis>filters</emphasis> and <emphasis>destinations</emphasis>.
+Each item has its unique (among other items of the same kind) name.
+The <emphasis>logpath</emphasis> ties together source, filter and destination.
+ </para>
+ <para>
+Only one of the items of each kind may be specified in logpath.
+But several logpaths may refer to the same source, filter or destination.
+ </para>
+ <para>
+The configuration file for daemon has XML format.
+It is not so convinient as its counterpart for any UNIX syslog.
+Following the windows way I plan to implement GUI configuration tool.
+So its content is not intended to be convinient for human.
+ </para>
+ <para>
+The root element should be <emphasis>conf</emphasis>.
+It is not checked by the parser however.
+Top-level elements and their attributes are described below.
+ </para>
+
+ <section>
+ <title>
+&lt;source/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+name
+ </term>
+ <listitem>
+ <para>
+Required.
+The name of message source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+type
+ </term>
+ <listitem>
+ <para>
+Required.
+There are two source types: <emphasis>internal</emphasis>
+and <emphasis>udp</emphasis>.
+<emphasis>Internal</emphasis> type corresponds to syslog daemon itself
+and <emphasis>udp</emphasis> defines a listening UDP socket.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+interface
+ </term>
+ <listitem>
+ <para>
+Optional.
+If the source type is <emphasis>udp</emphasis>, it defines interface
+the socket will be bound to.
+Default is 0.0.0.0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+port
+ </term>
+ <listitem>
+ <para>
+Optional.
+If source type is <emphasis>udp</emphasis> it defines listening port number.
+Default is 514.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>
+&lt;destination/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+name
+ </term>
+ <listitem>
+ <para>
+Required.
+The name of the destination.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+file
+ </term>
+ <listitem>
+ <para>
+Required.
+The pattern for the file name.
+It may contain the following format characters:
+<segmentedlist>
+ <?dbhtml list-presentation="table"?>
+ <segtitle>Format</segtitle><segtitle>Description</segtitle>
+ <seglistitem><seg>%Y</seg><seg>four-digit year</seg></seglistitem>
+ <seglistitem><seg>%M</seg><seg>two-digit month, 01...12</seg></seglistitem>
+ <seglistitem><seg>%m</seg><seg>month, 1...12</seg></seglistitem>
+ <seglistitem><seg>%D</seg><seg>two-digit day of month, 01...31</seg></seglistitem>
+ <seglistitem><seg>%d</seg><seg>day of month, 1...31</seg></seglistitem>
+ <seglistitem><seg>%W</seg><seg>day of week, 1...7, 1 for sunday</seg></seglistitem>
+ <seglistitem><seg>%F</seg><seg>facility name</seg></seglistitem>
+ <seglistitem><seg>%f</seg><seg>facility in numeric form</seg></seglistitem>
+ <seglistitem><seg>%L</seg><seg>priority level name</seg></seglistitem>
+ <seglistitem><seg>%l</seg><seg>priority level in numeric form</seg></seglistitem>
+ <seglistitem><seg>%H</seg><seg>source host name (a <quote>device</quote>, according to <ulink url="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</ulink>)</seg></seglistitem>
+ <seglistitem><seg>%h</seg><seg>sender host name (datagram sender, which may be device or relay)</seg></seglistitem>
+ <seglistitem><seg>%P</seg><seg>program name</seg></seglistitem>
+ <seglistitem><seg>%%</seg><seg>% character</seg></seglistitem>
+</segmentedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+rotate
+ </term>
+ <listitem>
+ <para>
+Optional.
+Rotate log files periodically.
+Possible values are:
+<emphasis>daily</emphasis>,
+<emphasis>weekly</emphasis>,
+<emphasis>monthly</emphasis>.
+ </para>
+ <para>
+Note that if rotation is turned on then it is strongly recommended
+not to use format characters in the filename pattern.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+size
+ </term>
+ <listitem>
+ <para>
+Optional.
+Log files are rotated when they grow bigger then <emphasis>size</emphasis> bytes.
+If size is followed by M, the size if assumed to be in megabytes.
+If the k is used, the size is in kilobytes.
+So size 100, size 100k, and size 100M are all valid.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+backlogs
+ </term>
+ <listitem>
+ <para>
+Optional.
+If rotation is turned on this attribute specifies the number of backlog files.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ifempty
+ </term>
+ <listitem>
+ <para>
+Optional.
+Rotate the log file even if it is empty.
+Possible values are: <emphasis>yes</emphasis>, <emphasis>no</emphasis>.
+Default is <emphasis>yes</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+olddir
+ </term>
+ <listitem>
+ <para>
+Optional.
+Logs are moved to this directory for rotation.
+If value is a relative path then this directory will be located in the same
+directory with syslogd executable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+compresscmd
+ </term>
+ <listitem>
+ <para>
+Optional.
+Command to use to compress log file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+compressoptions
+ </term>
+ <listitem>
+ <para>
+Optional.
+Command line options may be passed to the compression program, if one is in use.
+Options may contain $PATHNAME and $FILENAME substrings which will be replaced
+with backlog pathname and basename respectively.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>
+&lt;filter/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+name
+ </term>
+ <listitem>
+ <para>
+Required.
+The name of the filter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+This element may contain sub-elements <emphasis>facility</emphasis>
+and <emphasis>priority</emphasis>.
+ </para>
+ <section>
+ <title>
+ &lt;facility/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+name
+ </term>
+ <listitem>
+ <para>
+Facility name. May be one of the following:
+<simplelist type="vert" columns="1">
+ <member>kern</member>
+ <member>user</member>
+ <member>mail</member>
+ <member>daemon</member>
+ <member>auth</member>
+ <member>syslog</member>
+ <member>lpr</member>
+ <member>news</member>
+ <member>uucp</member>
+ <member>cron</member>
+ <member>authpriv</member>
+ <member>ftp</member>
+ <member>local0</member>
+ <member>local1</member>
+ <member>local2</member>
+ <member>local3</member>
+ <member>local4</member>
+ <member>local5</member>
+ <member>local6</member>
+ <member>local7</member>
+</simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+value
+ </term>
+ <listitem>
+ <para>
+Alternatively, the facility may be given in the numeric form.
+Possible range is 0...23.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+ <section>
+ <title>
+ &lt;priority/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+ Attributes
+ </title>
+ <varlistentry>
+ <term>
+ name
+ </term>
+ <listitem>
+ <para>
+Priority name. May be one of the following:
+<simplelist type="vert" columns="1">
+ <member>emerg</member>
+ <member>alert</member>
+ <member>crit</member>
+ <member>error</member>
+ <member>warning</member>
+ <member>notice</member>
+ <member>info</member>
+ <member>debug</member>
+</simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+value
+ </term>
+ <listitem>
+ <para>
+Alternatively, the priority may be given in the numeric form.
+Possible range is 0...7.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>
+&lt;logpath/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+source
+ </term>
+ <listitem>
+ <para>
+Required.
+The name of the source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+filter
+ </term>
+ <listitem>
+ <para>
+Optional.
+The name of the filter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+destination
+ </term>
+ <listitem>
+ <para>
+Required.
+The name of the destination.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>
+&lt;purge/&gt;
+ </title>
+ <para>
+When destination file name contains format characters, this option is quite useful.
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+directory
+ </term>
+ <listitem>
+ <para>
+Required.
+Directory to purge.
+Must be a relative path inside <emphasis>logdir</emphasis>
+(see configuration options below).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+keep_days
+ </term>
+ <listitem>
+ <para>
+Required.
+How long to keep files.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>
+&lt;options/&gt;
+ </title>
+ <para>
+ <variablelist>
+ <title>
+Attributes
+ </title>
+ <varlistentry>
+ <term>
+logdir
+ </term>
+ <listitem>
+ <para>
+Required.
+Drectory for the log files.
+If value is a relative path then this directory will be located in the same
+directory with syslogd executable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+dns
+ </term>
+ <listitem>
+ <para>
+Optional.
+Use resolver to determine sender host name.
+Possible values are: <emphasis>yes</emphasis>, <emphasis>no</emphasis>.
+Default is <emphasis>yes</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+source_encoding
+ </term>
+ <listitem>
+ <para>
+Optional.
+Convert incoming messages from specified encoding to
+<emphasis>destination_encoding</emphasis>.
+Default is do not convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+destination_encoding
+ </term>
+ <listitem>
+ <para>
+Required, if <emphasis>source_encoding</emphasis> is given.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+mark_interval
+ </term>
+ <listitem>
+ <para>
+Optional.
+Interval in second between emissions of mark message.
+Zero means do not emit mark messages and this is the
+default value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+mark_message
+ </term>
+ <listitem>
+ <para>
+Optional.
+The content of mark message.
+Default is <quote>-- MARK --</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+hold
+ </term>
+ <listitem>
+ <para>
+Optional.
+Number of seconds to hold a single message in queue.
+During this time identical messages are coalesced.
+Minimum is 1, default is 3 seconds.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+
+</section>
diff --git a/doc/src/intro.xml b/doc/src/intro.xml
new file mode 100644
index 0000000..0afbf96
--- /dev/null
+++ b/doc/src/intro.xml
@@ -0,0 +1,58 @@
+<section>
+ <title>What's this</title>
+ <para>
+This is an implementation of syslog daemon and client for native win32 platform.
+It complies to <ulink url="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</ulink>,
+<quote>The BSD Syslog Protocol</quote>.
+ </para>
+</section>
+
+<section>
+ <title>What for</title>
+ <para>
+Maybe you are:
+ <itemizedlist>
+ <listitem>
+ <para>
+porting existing UNIX software to native win32 platform;
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+writing portable software;
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+writing pure windows software but understanding that EventLog sucks and looking for an alternative.
+ </para>
+ </listitem>
+ </itemizedlist>
+I hope that in any of these cases this stuff will be useful for you.
+ </para>
+ <para>
+Of course, you may just use the daemon as the network message collector.
+But in this case you better look at UNIX.
+ </para>
+</section>
+
+<section>
+ <title>Legal issues</title>
+ <para>
+The source code of the daemon and the client library IS NOT COPYRIGHTED
+and is offered for use in the public domain.
+You may use, modify or distribute it freely.
+ </para>
+ <para>
+However, the project includes syslog header file, logger utility and the test based on it.
+This stuff is distributed under the
+<ulink url="http://www.opensource.org/licenses/bsd-license.php">BSD license</ulink>.
+ </para>
+ <para>
+The daemon uses <ulink url="http://www.gtk.org/">Glib</ulink>,
+<ulink url="http://www.gnu.org/software/libiconv/">libiconv</ulink> and
+<ulink url="http://www.gnu.org/software/gettext/">libintl</ulink>
+libraries and the binary distribution includes them under the
+<ulink url="http://www.opensource.org/licenses/lgpl-license.php">LGPL license</ulink>.
+ </para>
+</section>
diff --git a/doc/src/logger.xml b/doc/src/logger.xml
new file mode 100644
index 0000000..af7d735
--- /dev/null
+++ b/doc/src/logger.xml
@@ -0,0 +1,103 @@
+<refentry>
+
+ <refentryinfo>
+ <title>logger</title>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>logger</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>logger</refname>
+ <refpurpose>a shell command interface to the syslog daemon</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>logger</command>
+<group choice="opt"><arg>-f</arg><replaceable>file</replaceable></group>
+<arg choice="opt">-i</arg>
+<group choice="opt"><arg>-p</arg><replaceable>pri</replaceable></group>
+<arg choice="opt">-s</arg>
+<group choice="opt"><arg>-t</arg><replaceable>tag</replaceable></group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+<command>Logger</command> makes entries in the system log.
+It provides a shell command interface to the syslog daemon.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+<option>-f</option><replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+Log the specified file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-i</option>
+ </term>
+ <listitem>
+ <para>
+Log the process id of the logger process with each line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-p</option><replaceable>pri</replaceable>
+ </term>
+ <listitem>
+ <para>
+Enter the message with the specified priority.
+The priority may be specified numerically or as a
+<quote>facility.level</quote> pair.
+For example, <option>-p local3.info</option> logs the message(s)
+as informational level in the local3 facility.
+The default is <quote>user.notice</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-t</option><replaceable>tag</replaceable>
+ </term>
+ <listitem>
+ <para>
+Mark every line in the log with the specified tag.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+The logger utility exits 0 on success, and >0 if an error occurs.
+ </para>
+ <para>
+Valid facility names are: auth, authpriv (for security information of
+a sensitive nature), cron, daemon, ftp, kern, lpr, mail, news, security
+(deprecated synonym for auth), syslog, user, uucp, and local0 to local7,
+inclusive.
+ </para>
+ <para>
+Valid level names are: alert, crit, debug, emerg, err, error (deprecated
+synonym for err), info, notice, panic (deprecated synonym for emerg),
+warning, warn (deprecated synonym for warning).
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/src/syslogd.xml b/doc/src/syslogd.xml
new file mode 100644
index 0000000..4093b51
--- /dev/null
+++ b/doc/src/syslogd.xml
@@ -0,0 +1,112 @@
+<refentry>
+
+ <refentryinfo>
+ <title>syslogd</title>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>syslogd</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>syslogd</refname>
+ <refpurpose>service process (daemon)</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>syslogd</command>
+<group choice="opt"><arg>-h</arg><arg>--help</arg></group>
+<group choice="opt"><arg>-i</arg><arg>--install</arg></group>
+<group choice="opt"><arg>-I</arg><arg>--instance</arg><replaceable>name</replaceable></group>
+<group choice="opt"><arg>-p</arg><arg>--priority</arg><replaceable>name</replaceable></group>
+<group choice="opt"><arg>-r</arg><arg>--remove</arg></group>
+<group choice="opt"><arg>-s</arg><arg>--shutdown</arg></group>
+<group choice="opt"><arg>-v</arg><arg>--verbose</arg></group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Options</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+<option>-h</option> | <option>--help</option>
+ </term>
+ <listitem>
+ <para>
+Display help message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-i</option> | <option>--install</option>
+ </term>
+ <listitem>
+ <para>
+Install and start service.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-I</option> | <option>--instance</option><replaceable>name</replaceable>
+ </term>
+ <listitem>
+ <para>
+Specify instance name for the daemon.
+This option is useful to install and run multiple daemons in the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-p</option> | <option>--priority</option><replaceable>name</replaceable>
+ </term>
+ <listitem>
+ <para>
+Set priority class for the daemon.
+Name may be <quote>normal</quote>, <quote>high</quote> or <quote>highest</quote>.
+Default is <quote>normal</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-r</option> | <option>--remove</option>
+ </term>
+ <listitem>
+ <para>
+Stop and remove service.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-s</option> | <option>--shutdown</option>
+ </term>
+ <listitem>
+ <para>
+Gracefully shutdown service.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-v</option> | <option>--verbose</option>
+ </term>
+ <listitem>
+ <para>
+Increase verbosity level.
+This option may be specified multiple times.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/src/test.xml b/doc/src/test.xml
new file mode 100644
index 0000000..2c6c6d5
--- /dev/null
+++ b/doc/src/test.xml
@@ -0,0 +1,131 @@
+<refentry>
+
+ <refentryinfo>
+ <title>test</title>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>test</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>test</refname>
+ <refpurpose>message generator</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>test</command>
+<group choice="opt"><arg>-b</arg><replaceable>seconds</replaceable></group>
+<group choice="opt"><arg>-i</arg><replaceable>number</replaceable></group>
+<group choice="opt"><arg>-n</arg><replaceable>number</replaceable></group>
+<group choice="opt"><arg>-p</arg><replaceable>pri</replaceable></group>
+<group choice="opt"><arg>-s</arg><replaceable>seconds</replaceable></group>
+<group choice="opt"><arg>-t</arg><replaceable>tag</replaceable></group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+The <command>test</command> utility generates bursts of test messages.
+Each message has the following format:
+<screen>
+test message &lt;message number&gt;</screen>
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+<option>-b</option><replaceable>seconds</replaceable>
+ </term>
+ <listitem>
+ <para>
+Duration of the burst in seconds.
+Default is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-i</option><replaceable>number</replaceable>
+ </term>
+ <listitem>
+ <para>
+The maximum number of identical messages.
+This feature is useful to test coalescer.
+The implementation is simple but explanation is a bit difficult,
+just see issued messages when this number is 3, for example:
+<screen>
+test message 1
+test message 2
+test message 2
+test message 3
+test message 3
+test message 3
+test message 4
+test message 5
+test message 5
+test message 6
+test message 6
+test message 6
+...</screen>
+Default is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-n</option><replaceable>number</replaceable>
+ </term>
+ <listitem>
+ <para>
+The number of bursts.
+Default is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-p</option><replaceable>pri</replaceable>
+ </term>
+ <listitem>
+ <para>
+The priority of messages. It may be specified numerically or as a
+<quote>facility.level</quote> pair.
+For example, <option>-p local3.info</option>.
+The default is <quote>user.notice</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-s</option><replaceable>seconds</replaceable>
+ </term>
+ <listitem>
+ <para>
+Pause between bursts in seconds.
+Default is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+<option>-t</option><replaceable>tag</replaceable>
+ </term>
+ <listitem>
+ <para>
+Mark every line in the log with the specified tag.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+</refentry>