Added to CVS.

1 files changed, 561 insertions, 0 deletions

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>