syslog-ng 系列连载-44 ：参考-destination drivers

8.2. Destination drivers

Destination drivers output log messages to somewhere outside syslog-ng e.g., to a file or a network socket.

# 注释 ：destination drivers 指定把消息输出到某个位置

8.2.1. Options common for every destination

Some of the parameters affecting message formatting and sending are common for all destinations.

# 注释 ：和 source dirver 一样，destination driver 也有一些自己的选项可用

Name	Type	Default	Description
flags()		empty set
log_fifo_size()	number	Use global setting.	The number of entries in the output buffer (output fifo).
fsync()	yes or no	no	Forces an fsync() call on the destination fd after each write. Note: this may seriously degrade performance.
sync_freq()	number	Use global setting.	This setting is an obsolete alias of the flush_lines() option.
flush_lines()	number	Use global setting.	Specifies how many lines are flushed to a destination at a time. Syslog-ng waits for this number of lines to accumulate and sends them off in a single batch. Setting this number high increases throughput as fully filled frames are sent to the network, but also increases message latency. The latency can be limited by the use of the flush_timeout option.   # 注释 ：flush_lines（）设置 syslog-ng 一次向 destinatino 发送多少行消息，提高该值可以提高吞吐量，但也会增加 syslog-ng 的反应延迟
flush_timeout()	time in milliseconds	Use global setting.	Specifies the time syslog-ng waits for lines to accumulate in its output buffer. See the flush_lines option for more information.
template()	string	A format conforming to the default logfile format.	Specifies a template defining the logformat to be used in the destination. Macros are described in . Please note that for network destinations it might not be appropriate to change the template as it changes the on-wire format of the syslog protocol which might not be tolerated by stock syslog receivers (like syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.   # 注释 ：template（）指定一个之前定义过模版，所有写入该 destination driver 的消息都会被按照模版定义的格式进行改写。
template_escape()	yes or no	yes	Turns on escaping ' and " in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.
timezone()	timezone offset in seconds	unspecified	Convert timestamps to the timezone specified by this option. If this option is not set then the original timezone information in the message is used.
ts_format()	rfc3164, bsd, rfc3339, iso	rfc3164	Override the global timestamp format (set in the global ts_format() parameter) for the specific destination.
frac_digits()	number	0	The syslog-ng application can store fractions of a second in the timestamps. The frac_digits() parameter specifies the number of digits stored. The digits storing the fractions are padded by zeros if the original timestamp of the message specifies only seconds. Fractions can always be stored for the time the message was received.
throttle()	number	0	Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.   # 注释 ：设置每秒发送的最大消息数量。默认是 0 ，没有限制，只有你启用了 disk-buffer 才需要用到这个。

Table 8.5. Common options for destination drivers

	Note
	The usertty destination does not support templates. # 注释 ：user-tty 类型的 destination 不支持模版

8.2.2. file()

The file driver is one of the most important destination drivers in syslog-ng. It allows to output messages to the specified file, or to a set of files.

# 注释 ：file（）型的 driver 是最重要的一种 driver 。

The destination filename may include macros which get expanded when the message is written, thus a simple file() driver may crete several files. For more information on available macros see .

# 注释 ：文件名可以是动态的（含有宏），而不是固定写入某个文件。

If the expanded filename refers to a directory which does not exist, it will be created depending on the create_dirs() setting (both global and a per destination option).

# 注释 ：如果一个文件名被扩展后指向一个不存在的目录，则会根据 create_dirs（）选项的值决定是否建立木屋

	Note
	When using the file() destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large. # 注释 ：一旦使用 file（）类型的 destination ，要注意使用 logrotate

Warning

Since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time_reap() global option), it is closed, and its state is freed. # 注释 ：因为每个建立的文件的状态必须被 syslog-ng 所跟踪，所以这会消耗一些内容。如果在60秒内没有消息写入，它会被关闭。 Exploiting this, a DoS attack can be mounted against the system. If the number of possible destination files and its needed memory is more than the amount available on the syslog-ng server. # 注释 ：所以这点可能被用于进行 DoS 攻击 The most suspicious macro is $PROGRAM, where the number of possible variations is rather high. Do not use the $PROGRAM macro in insecure environments. # 注释 ：最不安全的宏就是 $PROGRAM

Apart from the common destination options described in the file() destination has the following options:

# 注释 ：file（）类型的 driver 有一些自己的选项

Name	Type	Default	Description
owner()	string	root	Set the owner of the created file to the one specified.
group()	string	root	Set the group of the created file to the one specified.
perm()	number	0600	The permission mask of the file if it is created by syslog-ng. For octal numbers prefix the number with 0, e.g., use 0755 for rwxr-xr-x.
create_dirs()	yes or no	no	Enable creating non-existing directories.   # 注释 ：create_dirs （）用于设定是否自动建立目录。默认是 no
dir_perm()	number	0600	The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and directory creation is enabled (see the create_dirs() option below). For octal numbers prefix the number with 0, e.g., use 0755 for rwxr-xr-x.   # 注释 ：dir_perm（）用于设置新建目录的权限，默认是 0600（rw-------）
dir_owner()	string	root	The owner of directories created by syslog-ng.   # 注释 ：dir_owner（）和 dir_group（）用于设置目录的所有者和用户组
dir_group()	string	root	The group of directories created by syslog-ng.
overwrite_if_older()	number	0	If set to a value higher than 0, before writing to a file, syslog-ng checks whether this file is older than the specified amount of time (specified in seconds). If so, it removes the existing file and the line to be written is the first line of a new file having the same name. In combination with e.g.: the $WEEKDAY macro, this can be used for simple log rotation, in case not all history has to be kept.
remove_if_older()	number	0	Obsolete alias of the overwrite_if_older() option.

Table 8.6. Options for file()

	Example 8.8. Using the file() driver
	destination d_file { file("/var/log/messages" ); };

	Example 8.9. Using the file() driver with macros in the file name and a template for the message
	destination d_file { file("/var/log/$YEAR.$MONTH.$DAY/messages" template("$HOUR:$MIN:$SEC $TZ $HOST [$LEVEL] $MSG $MSG\n") template_escape(no)); };

8.2.3. pipe()

This driver sends messages to a named pipe like /dev/xconsole.

The pipe driver has a single required parameter, specifying the filename of the pipe to open.

Declaration:
  pipe(filename);
            

	Note
	You have to create this pipe using mkfifo(1).

Apart from the common destination options described in the pipe() destination has the following options:

Name	Type	Default	Description
owner()	string	root	Set the owner of the pipe to the one specified.
group()	string	root	Set the group of the pipe to the one specified.
perm()	number	0600	The permission mask of the pipe. For octal numbers prefix the number with '0', e.g.: use 0755 for rwxr-xr-x.
template()	string	A format conforming to the default logfile format.	Specifies a template which defines the logformat to be used. Possible macros are the same as for the file() destination.
template_escape()	yes or no	yes	Turns on escaping ' and " in templated output files. This is useful for generating SQL statements and quoting string contents so that parts of the log message are not interpreted as commands to the SQL server.

Table 8.7. Options for pipe()

	Example 8.10. Using the pipe() driver
	destination d_pipe { pipe("/dev/xconsole"); };

8.2.4. unix-stream() & unix-dgram()

This driver sends messages to a unix socket in either SOCK_STREAM or SOCK_DGRAM mode.

Both drivers have a single required argument specifying the name of the socket to connect to.

Declaration: 
  unix-stream(filename [options]);
  unix-dgram(filename [options]);
            

Apart from the common destination options described in the unix-stream() and unix-dgram() destinations has the following options:

Name	Type	Default	Description
so_broadcast	yes or no	no	This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. See the socket(7) manual page for details.
so_rcvbuf	number	0	Specifies the size of the socket receive buffer in bytes.
so_sndbuf	number	0	Specifies the size of the socket send buffer in bytes.

Table 8.8. Options for unix-stream() and unix-dgram()

	Example 8.11. Using the unix-stream() driver
	destination d_unix_stream { unix-stream("/var/run/logs"); };

8.2.5. tcp(), tcp6(), udp(), and udp6(),

This driver sends messages to another host on the local intranet or internet using the UDP or TCP protocol. The tcp6() and udp6() drivers use the IPv6 network protocol.

Both drivers have a single required argument specifying the destination host address, where messages should be sent, and several optional parameters. Note that this differs from source drivers, where local bind address is implied, and none of the parameters are required.

The udp() and udp6() drivers automatically send multicast packets if a multicast destination address is specified. The tcp() and tcp6() drivers do not support multicasting.

Declaration:
  tcp(host [options]);
  udp(host [options]);
  tcp6(host [options]);
  udp6(host [options]);					
            

Apart from the common destination options described in these destinations have the following options:

Name	Type	Default	Description
localip()	string	0.0.0.0	The IP address to bind to before connecting to target.
localport()	number	0	The port number to bind to. Messages are sent from this port.
port() or destport()	number	514	The port number to connect to.