[syslog-ng]Documentation update: template() options added and some other stuff

Achim Gsell syslog-ng@lists.balabit.hu
Tue, 25 Feb 2003 23:57:48 +0100


--Boundary-00=_sT/W+qd9jhJjNBs
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

Hi Ratz!


Thanks ... done (see attachment)!

On Tuesday 25 February 2003 23:13, Roberto Nibali wrote:

> Looks good to me, but I'm not the one to call ;). You might also fix the
> stuff below once you're at it.
>
> >  		<entry>Specifies the maximum number of simoultaneous
> > connections.</entry>
>
> s/simoultaneous/simultaneous/

ACK

> > +		  a format conforming to default logfile format.
>
> s/to default/to the default/   #multiple instances of this mistake

ACK

> > +		  Turns on escaping ' and " in templated output files. It is useful
>
> s/It/This/                     #multiple instances of this mistake

ACK

> > +		  Specifies a template which specifies the logformat to
>
> s/specifies/defines/           #multiple instances of this mistake

ACK

> > +		  be used. The possible macros are the same
>
> s/The//                        #multiple instances of this mistake

ACK

>
> > +		  as in destination filenames.
>
> s/in/with/

s/as in destination filenames/as with destination file()/

> > +		  The messages are send to the remote host when this
>
> s/send/sent/

ACK

> > +		  number of messages has been collected.
>
> s/has/have/

ACK

Cheers,

Achim

--Boundary-00=_sT/W+qd9jhJjNBs
Content-Type: text/x-diff;
  charset="iso-8859-1";
  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 23:53:10.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>
 	      
@@ -483,7 +484,7 @@
 	</para>
 	<para>
 	  To avoid denial of service attacks when using
-	  connection-oriented protocols, the number of simoultaneously
+	  connection-oriented protocols, the number of simultaneously
 	  accepted connections should be limited. This can be achieved
 	  using the max-connections() parameter. The default value of
 	  this parameter is quite strict, you might have to increase
@@ -544,7 +545,7 @@
 	      <row>
 		<entry>max-connections()</entry>
 		<entry>number</entry>
-		<entry>Limits the number of simoultaneously opened connections.
+		<entry>Limits the number of simultaneously opened connections.
 		  Can be used only with unix-stream().</entry>
 		<entry>10</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>Specifies the maximum number of simultaneous 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,32 +1130,42 @@
 		</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>
 		<entry>template()</entry> 
 		<entry>string</entry>
 		<entry>
-		  Specifies a template which specifies the logformat to
-		  be used in this file. The possible macros are the same
-		  as in destination filenames.
+		  Specifies a template which defines the logformat to
+		  be used in this file. Possible macros are the same
+		  as with destination file().
 		</entry>
 		<entry>
-		  a format conforming to default logfile format.
+		  a format conforming to the 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
+		  Turns on escaping ' and " in templated output files. This 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.
@@ -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 defines the logformat to
+		  be used. Possible macros are the same
+		  as with destination file().
+		</entry>
+		<entry>
+		  a format conforming to the default logfile format.
+		</entry>
+	      </row>
+	      <row>
+		<entry>template_escape()</entry> 
+		<entry>yes or no</entry>
+		<entry>
+		  Turns on escaping ' and " in templated output files. This 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() &amp; 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() &amp; 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 defines the logformat to
+		  be used. Possible macros are the same
+		  as with destination file().
+		</entry>
+		<entry>
+		  a format conforming to the default logfile format.
+		</entry>
+	      </row>
+	      <row>
+		<entry>template_escape()</entry> 
+		<entry>yes or no</entry>
+		<entry>
+		  Turns on escaping ' and " in templated output files. This 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() &amp; 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() &amp; 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 defines the logformat to
+		  be used. Possible macros are the same
+		  as with destination file().
+		</entry>
+		<entry>
+		  a format conforming to the default logfile format.
+		</entry>
+	      </row>
+	      <row>
+		<entry>template_escape()</entry> 
+		<entry>yes or no</entry>
+		<entry>
+		  Turns on escaping ' and " in templated output. This 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 sent to the remote host when this
+		  number of messages have 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 defines the logformat to
+		  be used. Possible macros are the same
+		  as with destination file().
+		</entry>
+		<entry>
+		  a format conforming to the default logfile format.
+		</entry>
+	      </row>
+	      <row>
+		<entry>template_escape()</entry> 
+		<entry>yes or no</entry>
+		<entry>
+		  Turns on escaping ' and " in templated output. This 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 defines the logformat to
+		  be used. Possible macros are the same
+		  as with destination file().
+		</entry>
+		<entry>
+		  a format conforming to the default logfile format.
+		</entry>
+	      </row>
+	      <row>
+		<entry>template_escape()</entry> 
+		<entry>yes or no</entry>
+		<entry>
+		  Turns on escaping ' and " in templated output. This 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=_sT/W+qd9jhJjNBs--