[syslog-ng]Documentation update: template() options added and some other stuff
Achim Gsell
syslog-ng@lists.balabit.hu
Tue, 25 Feb 2003 22:42:25 +0100
--Boundary-00=_BN+W+FoaEDzVxfu
Content-Type: text/plain;
charset="us-ascii"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Hi,
in the attachment you find a patch to update the syslog-ng documentation.
The patch includes:
o documentation of the template() and template_escape() options
o some missing close tags the docbook parser complains about
o examples for all destination driver (where missing)
o some fixes
Achim
--Boundary-00=_BN+W+FoaEDzVxfu
Content-Type: text/x-diff;
charset="us-ascii";
name="syslog-ng-documentation.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="syslog-ng-documentation.diff"
--- syslog-ng-1.6.0rc1/doc/sgml/syslog-ng.sgml 2003-01-31 11:04:55.000000000 +0100
+++ syslog-ng-1.6.0rc1+20030224/doc/sgml/syslog-ng.sgml 2003-02-25 22:26:56.000000000 +0100
@@ -167,6 +167,7 @@
called door. By default the door used by syslogd is
/etc/.syslog_door
</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -207,35 +208,35 @@
</thead>
<tbody>
<row>
- <entry>internal</entry>
+ <entry>internal()</entry>
<entry>Messages generated internally in syslog-ng</entry>
</row>
<row>
- <entry>unix-stream</entry>
+ <entry>unix-stream()</entry>
<entry>Opens the specified unix socket in SOCK_STREAM mode, and listens for messages.</entry>
</row>
<row>
- <entry>unix-dgram</entry>
+ <entry>unix-dgram()</entry>
<entry>Opens the specified unix socket in SOCK_DGRAM mode, and listens for messages.</entry>
</row>
<row>
- <entry>file</entry>
+ <entry>file()</entry>
<entry>Opens the specified file, and reads messages.</entry>
</row>
<row>
- <entry>pipe, fifo</entry>
+ <entry>pipe(), fifo</entry>
<entry>Opens the specified named pipe and reads messages</entry>
</row>
<row>
- <entry>udp</entry>
+ <entry>udp()</entry>
<entry>Listens on the specified UDP port for messages.</entry>
</row>
<row>
- <entry>tcp</entry>
+ <entry>tcp()</entry>
<entry>Listens on the specified TCP port for messages.</entry>
</row>
<row>
- <entry>sun-stream, sun-streams</entry>
+ <entry>sun-stream(), sun-streams()</entry>
<entry>Opens the specified STREAMS device on Solaris systems, and reads messages.</entry>
</row>
</tbody>
@@ -306,41 +307,41 @@
<tgroup cols=2>
<thead>
<row>
- <entry/Name/
- <entry/Description>
+ <entry>Name</entry>
+ <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
- <entry>file</entry>
+ <entry>file()</entry>
<entry>Writes messages to the given file</entry>
</row>
<row>
- <entry>fifo, pipe</entry>
+ <entry>fifo(), pipe()</entry>
<entry>Writes messages to the given named pipe</entry>
</row>
<row>
- <entry>unix-stream</entry>
+ <entry>unix-stream()</entry>
<entry>Sends messages to the given unix socket in SOCK_STREAM style (Linux)</entry>
</row>
<row>
- <entry>unix-dgram</entry>
+ <entry>unix-dgram()</entry>
<entry>Sends messages to the given unix socket in SOCK_DGRAM style (BSD)</entry>
</row>
<row>
- <entry>udp</entry>
+ <entry>udp()</entry>
<entry>Sends messages to specified host and UDP port</entry>
</row>
<row>
- <entry>tcp</entry>
+ <entry>tcp()</entry>
<entry>Sends messages to specified host and TCP port</entry>
</row>
<row>
- <entry>usertty</entry>
+ <entry>usertty()</entry>
<entry>Sends messages to specified user if logged in</entry>
</row>
<row>
- <entry>program</entry>
+ <entry>program()</entry>
<entry>Forks and launches given program, and sends messages to its standard input.</entry>
</row>
@@ -576,6 +577,7 @@
"best effort service" to transfer messages between
hosts. It may lose messages, and no attempt is made to
retransmit such lost messages at the protocol level.
+ </para>
<para>
TCP provides connection-oriented service, which basically
means a flow-controlled message pipeline. In this pipeline,
@@ -619,7 +621,7 @@
</thead>
<tbody>
<row>
- <entry>ip or localip</entry>
+ <entry>ip() or localip()</entry>
<entry>string</entry>
<entry>
The IP address to bind to. Note that this is not the
@@ -628,13 +630,13 @@
<entry>0.0.0.0</entry>
</row>
<row>
- <entry>port or localport</entry>
+ <entry>port() or localport()</entry>
<entry>number</entry>
<entry>The port number to bind to.</entry>
<entry>514</entry>
</row>
<row>
- <entry>keep-alive</entry>
+ <entry>keep-alive()</entry>
<entry>yes or no</entry>
<entry>
@@ -646,10 +648,11 @@
<entry>yes</entry>
</row>
<row>
- <entry>max-connections</entry>
+ <entry>max-connections()</entry>
<entry>number</entry>
<entry>Specifies the maximum number of simoultaneous connections.</entry>
<entry>10</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -696,7 +699,7 @@
</thead>
<tbody>
<row>
- <entry>log_prefix</entry>
+ <entry>log_prefix()</entry>
<entry>string</entry>
<entry>
The string to prepend log messages. Useful for logging
@@ -704,6 +707,7 @@
default
</entry>
<entry>empty string</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -751,7 +755,7 @@
</thead>
<tbody>
<row>
- <entry>pad_size</entry>
+ <entry>pad_size()</entry>
<entry>number</entry>
<entry>
Specifies input padding. Some operating systems (such as
@@ -759,6 +763,7 @@
be used to specify the block size. (HP-UX uses 2048 bytes)
</entry>
<entry>0</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -813,7 +818,7 @@
</thead>
<tbody>
<row>
- <entry>door</entry>
+ <entry>door()</entry>
<entry>string</entry>
<entry>
Specifies the filename of a door to open, needed on Solaris above 2.5.1.
@@ -960,7 +965,7 @@
<entry>TZOFFSET</entry>
<entry>
The time-zone as hour offset from GMT. e.g. '-0700'
- <entry>
+ </entry>
</row>
<row>
<entry>TZ</entry>
@@ -1023,7 +1028,10 @@
<row>
<entry>fsync()</entry>
<entry>yes or no</entry>
- <entry>Forces an fsync() call on the destination fd after each write. Note: this may degrade performance seriously</entry>
+ <entry>
+ Forces an fsync() call on the destination fd after
+ each write. Note: this may degrade performance
+ seriously</entry>
</row>
<row>
@@ -1097,6 +1105,17 @@
0600
</entry>
</row>
+
+ <row>
+ <entry>create_dirs()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Enable creating non-existing directories.
+ </entry>
+ <entry>
+ no
+ </entry>
+ </row>
<row>
<entry>dir_perm()</entry>
<entry>number</entry>
@@ -1111,13 +1130,23 @@
</entry>
</row>
<row>
- <entry>create_dirs()</entry>
- <entry>yes or no</entry>
+ <entry>dir_owner()</entry>
+ <entry>string</entry>
<entry>
- Enable creating non-existing directories.
+ The owner of directories created by syslog-ng.
</entry>
<entry>
- no
+ root
+ </entry>
+ </row>
+ <row>
+ <entry>dir_group()</entry>
+ <entry>string</entry>
+ <entry>
+ The group of directories created by syslog-ng.
+ </entry>
+ <entry>
+ root
</entry>
</row>
<row>
@@ -1166,7 +1195,27 @@
</tbody>
</tgroup>
</table>
+ <example>
+ <title>Using the file() driver</title>
+ <synopsis>
+ destination d_file { file("/var/log/messages" ); };
+ </synopsis>
+ </example>
+
+ <example>
+ <title>Using the file() driver with macros in the file name
+ and a template for the message</title>
+ <synopsis>
+ destination d_file {
+ file("/var/log/$YEAR.$MONTH.$DAY/messages"
+ template("$HOUR:$MIN:$SEC $TZ $HOST [$LEVEL] $MSG $MSG\n")
+ template_escape(no)
+ );
+ };
+ </synopsis>
+ </example>
</sect2>
+
<sect2>
<title>pipe()</title>
<para>
@@ -1174,7 +1223,7 @@
</para>
<para>
The pipe driver has a single required parameter, specifying the
- filename of the pipe to open, and no options.
+ filename of the pipe to open.
</para>
<synopsis>
Declaration:
@@ -1183,6 +1232,84 @@
<para>
NOTE: you'll need to create this pipe using mkfifo(1).
</para>
+
+ <table>
+ <title>Available options for pipe()</title>
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry/Name/
+ <entry/Type/
+ <entry/Description/
+ <entry/Default/
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>owner()</entry>
+ <entry>string</entry>
+ <entry>
+ Set the owner of the pipe to the one
+ specified.
+ </entry>
+ <entry>
+ root
+ </entry>
+ </row>
+
+ <row>
+ <entry>group()</entry>
+ <entry>string</entry>
+ <entry>
+ Set the group of the pipe to the one
+ specified.
+ </entry>
+ <entry>
+ root
+ </entry>
+ </row>
+
+ <row>
+ <entry>perm()</entry>
+ <entry>number</entry>
+ <entry>
+ The permission mask of the pipe.
+ </entry>
+ <entry>
+ 0600
+ </entry>
+ </row>
+
+ <row>
+ <entry>template()</entry>
+ <entry>string</entry>
+ <entry>
+ Specifies a template which specifies the logformat to
+ be used. The possible macros are the same
+ as in destination filenames.
+ </entry>
+ <entry>
+ a format conforming to default logfile format.
+ </entry>
+ </row>
+ <row>
+ <entry>template_escape()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Turns on escaping ' and " in templated output files. It is useful
+ for generating SQL statements and quoting string contents
+ so that parts of your log message don't get interpreted
+ as commands to the SQL server.
+ </entry>
+ <entry>
+ yes
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
<example>
<title>Using the pipe() driver</title>
<synopsis>
@@ -1190,6 +1317,7 @@
</synopsis>
</example>
</sect2>
+
<sect2>
<title>unix-stream() & unix-dgram()</title>
<para>
@@ -1198,7 +1326,7 @@
</para>
<para>
Both drivers have a single required argument specifying the
- name of the socket to connect to, and no optional arguments.
+ name of the socket to connect to.
</para>
<synopsis>
Declaration:
@@ -1206,7 +1334,55 @@
unix-dgram(filename [options]);
</synopsis>
+ <table>
+ <title>Available options for unix-stream() & unix-dgram()</title>
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry/Name/
+ <entry/Type/
+ <entry/Description/
+ <entry/Default/
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>template()</entry>
+ <entry>string</entry>
+ <entry>
+ Specifies a template which specifies the logformat to
+ be used. The possible macros are the same
+ as in destination filenames.
+ </entry>
+ <entry>
+ a format conforming to default logfile format.
+ </entry>
+ </row>
+ <row>
+ <entry>template_escape()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Turns on escaping ' and " in templated output files. It is useful
+ for generating SQL statements and quoting string contents
+ so that parts of your log message don't get interpreted
+ as commands to the SQL server.
+ </entry>
+ <entry>
+ yes
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example>
+ <title>Using the unix-stream() driver</title>
+ <synopsis>
+ destination d_unix_stream { unix-stream("/var/run/logs"); };
+ </synopsis>
+ </example>
</sect2>
+
<sect2>
<title>udp() & tcp()</title>
<para>
@@ -1226,7 +1402,7 @@
udp(host [options]);
</synopsis>
<table>
- <title>Available options for udp and tcp</title>
+ <title>Available options for udp() & tcp()</title>
<tgroup cols=4>
<thead>
<row>
@@ -1238,7 +1414,7 @@
</thead>
<tbody>
<row>
- <entry>localip</entry>
+ <entry>localip()</entry>
<entry>string</entry>
<entry>
The IP address to bind to before connecting to target.
@@ -1246,20 +1422,73 @@
<entry>0.0.0.0</entry>
</row>
<row>
- <entry>localport</entry>
+ <entry>localport()</entry>
<entry>number</entry>
<entry>The port number to bind to.</entry>
<entry>0</entry>
</row>
<row>
- <entry>port or destport</entry>
+ <entry>port() or destport()</entry>
<entry>number</entry>
<entry>The port number to connect to.</entry>
<entry>514</entry>
</row>
+ <row>
+ <entry>template()</entry>
+ <entry>string</entry>
+ <entry>
+ Specifies a template which specifies the logformat to
+ be used. The possible macros are the same
+ as in destination filenames.
+ </entry>
+ <entry>
+ a format conforming to default logfile format.
+ </entry>
+ </row>
+ <row>
+ <entry>template_escape()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Turns on escaping ' and " in templated output. It is useful
+ for generating SQL statements and quoting string contents
+ so that parts of your log message don't get interpreted
+ as commands to the SQL server.
+ </entry>
+ <entry>
+ yes
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
+
+ <table>
+ <title>Additional options for tcp()</title>
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry/Name/
+ <entry/Type/
+ <entry/Description/
+ <entry/Default/
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>sync()</entry>
+ <entry>number</entry>
+ <entry>
+ The messages are send to the remote host when this
+ number of messages has been collected.
+ </entry>
+ <entry>
+ 0
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
<example>
<title>Using the tcp() driver</title>
<synopsis>
@@ -1267,6 +1496,7 @@
</synopsis>
</example>
</sect2>
+
<sect2>
<title>usertty()</title>
<para>
@@ -1282,7 +1512,54 @@
Declaration:
usertty(username);
</synopsis>
+ <table>
+ <title>Available options for usertty()</title>
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry/Name/
+ <entry/Type/
+ <entry/Description/
+ <entry/Default/
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>template()</entry>
+ <entry>string</entry>
+ <entry>
+ Specifies a template which specifies the logformat to
+ be used. The possible macros are the same
+ as in destination filenames.
+ </entry>
+ <entry>
+ a format conforming to default logfile format.
+ </entry>
+ </row>
+ <row>
+ <entry>template_escape()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Turns on escaping ' and " in templated output. It is useful
+ for generating SQL statements and quoting string contents
+ so that parts of your log message don't get interpreted
+ as commands to the SQL server.
+ </entry>
+ <entry>
+ yes
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <example>
+ <title>Using the usertty() driver</title>
+ <synopsis>
+ destination d_usertty { usertty("root"); };
+ </synopsis>
+ </example>
</sect2>
+
<sect2>
<title>program()</title>
<para>
@@ -1308,6 +1585,47 @@
would imply an easy DoS.
</para>
</note>
+ <table>
+ <title>Available options for program()</title>
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry/Name/
+ <entry/Type/
+ <entry/Description/
+ <entry/Default/
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>template()</entry>
+ <entry>string</entry>
+ <entry>
+ Specifies a template which specifies the logformat to
+ be used. The possible macros are the same
+ as in destination filenames.
+ </entry>
+ <entry>
+ a format conforming to default logfile format.
+ </entry>
+ </row>
+ <row>
+ <entry>template_escape()</entry>
+ <entry>yes or no</entry>
+ <entry>
+ Turns on escaping ' and " in templated output. It is useful
+ for generating SQL statements and quoting string contents
+ so that parts of your log message don't get interpreted
+ as commands to the SQL server.
+ </entry>
+ <entry>
+ yes
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
<example>
<title>Using the program() destination driver</title>
<synopsis>
@@ -1316,6 +1634,7 @@
</example>
</sect2>
</sect1>
+
<sect1>
<title/Filter functions/
<para>
--Boundary-00=_BN+W+FoaEDzVxfu--