diff options
Diffstat (limited to 'doc/src/configuration.xml')
| -rw-r--r-- | doc/src/configuration.xml | 561 |
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> +<source/> + </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> +<destination/> + </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> +<filter/> + </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> + <facility/> + </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> + <priority/> + </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> +<logpath/> + </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> +<purge/> + </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> +<options/> + </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> |