path: root/doc/src/configuration.xml

<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>
encoding
					</term>
					<listitem>
						<para>
Optional.
Expect incoming messages in this encoding.
Default is UTF-8.
						</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.
The type of destination may be either <quote>file</quote> or <quote>relay</quote>.
It is determined by the presence of attributes <quote>file</quote>
or <quote>collector</quote> respectively.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
encoding
					</term>
					<listitem>
						<para>
Optional.
Messages must be converted to this encoding.
Conversion is not performed if both source and destination encodings are identical or not specified.
Default is UTF-8.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
file
					</term>
					<listitem>
						<para>
The presence of this attribute defines destination type as <quote>file</quote>.
The value of attribute is a 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; this is taken from the MSG part of message and converted to locale encoding if source encoding is specified</seg></seglistitem>
	<seglistitem><seg>%%</seg><seg>% character</seg></seglistitem>
</segmentedlist>
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
rotate
					</term>
					<listitem>
						<para>
File-specific, 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>
File-specific, 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>
File-specific, optional.
If rotation is turned on this attribute specifies the number of backlog files.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
ifempty
					</term>
					<listitem>
						<para>
File-specific, 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>
File-specific, 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>
File-specific, optional.
Command to use to compress log file.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
compressoptions
					</term>
					<listitem>
						<para>
File-specific, 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>
				<varlistentry>
					<term>
collector
					</term>
					<listitem>
						<para>
The presence of this attribute defines destination type as <quote>relay</quote>.
The value of attribute is a name or IPv4 address of the collector optionally
followed by the colon and port number.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
omit_hostname
					</term>
					<listitem>
						<para>
Relay-specific, optional.
Do not include source hostname in the datagramm.
Some syslog daemons by default do not rely on the hostname part of datagramm
and insert actual sender hostname in the logged message.
Note that ommiting hostname violates <ulink url="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</ulink>.
Possible values are: <emphasis>yes</emphasis>, <emphasis>no</emphasis>.
Default is <emphasis>no</emphasis>
						</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>
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>