syslog-ng 系列连载-43 ：参考- source drivers

8.1. Source drivers

The following drivers may be used in source statements, as described in . The option is available in each source: it specifies the maximum length of incoming log messages in bytes. If not specified, the value of the global option is used (see ).

# 注释 ：本节介绍所有的 source drivers  ，首先介绍每个 source 都可以使用 flags

8.1.1. Options common for every source

Some parameters affecting message parsing are common for all sources:

Name	Type	Default	Description
flags()	set of [no-parse,kernel]	empty set	Specifies log parsing flags. no-parse completely disables syslog message parsing and processes the complete line as the message part of a syslog message. Other information (timestamp, host, etc.) is added automatically. This flag is useful for parsing files not complying to the syslog format. kernel makes the source default to the LOG_KERN | LOG_CRIT priority if not specified otherwise.
log_msg_size()	number	The value specified by the global log_msg_size() option, which defaults to 8192.	Specifies the maximum length of incoming log messages. Uses the value of the if not specified.   # 注释 ：log_msg_size（）用于指定进入的消息的最大长度，默认是 8192 字节，你可以在单个 source 指定它，这会覆盖全局的设置
log_iw_size()	number	100	The size of the initial window, this value is used during flow control.
log_fetch_limit()	number	The value specified by the global option, which defaults to 10.	The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log_fetch_limit() is too high.
log_prefix()	string		A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux.   # 注释：log_prefix （) 用于在进入该 source 的每个消息的前面加上任何字符串
pad_size()	number	0	Specifies input padding. Some operating systems (such as HP-UX) pad all 0 messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). Syslog-ng will pad reads from the associated device to the number of bytes set in pad_size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes.
follow_freq()	number	-1	Indicates that the source should be checked periodically instead of being polled. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow_freq() interval (in seconds) has elapsed.   # 注释 ：默认 syslog-ng 是采取 pull （轮询）的方式来检查每个 source 是否有新消息，该选项可以改为定期检查的方式
time_zone()	timezone in the form +/-HH:MM		The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.   # 注释 ：time_zone（）设置该 source 来的消息的时区，默认是从消息中获取
optional()	yes or no		Instruct syslog-ng to ignore the error if a specific source cannot be initialized. No other attempts to initialize the source will be made until the configuration is reloaded. This option currently applies to the pipe(), unix-dgram, and unix-stream drivers.
keep_timestamp()	yes or no	yes	Specifies whether syslog-ng should accept the timestamp received from the peer. If disabled, the time of reception will be used instead.

Table 8.1. Common options for source drivers

8.1.2. internal()

All internally generated messages "come" from this special source. To collect warnings, errors and notices from syslog-ng itself, include this source in one of your source statements.

# 注释 ：首先第1种 source driver 就是 internal （） 。它用于指定所有来自 syslog-ng 内部的消息。

internal()
				

The syslog-ng application will issue a warning upon startup if this driver is not referenced.

	Example 8.1. Using the internal() driver
	source s_local { internal(); };

8.1.3. unix-stream() and unix-dgram()

These two drivers behave similarly: they open the given AF_UNIX socket and start listening on it for messages. unix-stream() is primarily used on Linux and uses SOCK_STREAM semantics (connection oriented, no messages are lost); while unix-dgram() is used on BSDs and uses SOCK_DGRAM semantics: this may result in lost local messages if the system is overloaded.

# 注释 ：第2种就是 unix-steam（）和 unix-dgram（），它们和类似，linux 上主要是使用 UNIX_STREAM 类型的，BSD 主要是使用 UNIX_DGRAM 类型的。

# 后者可能在系统过载时出现消息的丢失。

To avoid denial of service attacks when using 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 it on a busy system.

# 注释 ：对于前者来说，由于是面向连接的，所以有可能被用来做 DoS 攻击。可以通过设置 max-connections（）来设置同一时刻最大的连接数。

Both unix-stream and unix-dgram have a single required positional argument, specifying the filename of the socket to create, and several optional parameters.

# 注释 ：这两者都需要至少指定一个 socket 文件的名称，还可以带一些选项。

	Note
	syslogd on Linux originally used SOCK_STREAM sockets, but some distributions switched to SOCK_DGRAM around 1999 to fix a possible DoS problem. On Linux you can choose to use whichever driver you like as syslog clients automatically detect the socket type being used.

The difference between the unix-stream and unix-dgram drivers is similar to the difference between the TCP and UDP network protocols. Use the following guidelines to select which driver to use in a particular situation:

Choose unix-stream if you would choose TCP (stream) instead of UDP (datagram). The unix-stream driver offers the following features:

• Increased reliability

• Ordered delivery of messages

• Client-side notification of failures

Choose unix-dgram if you would choose TCP (stream) over UDP (datagram). The unix-dgram driver offers the following features:

• Decreased possibility of Dos by opening too many connections (a local vulnerability)

• Less overhead

However, the client does not notice if a message is lost when using the unix-dgram driver.

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

The following options can be specified for these divers:

# 注释 ：对于这两种 drivers ，可用的选项有如下几个 ：

#     -）1、owner （）：默认是 root 。用于指定该 socket 是属于那个用户的。

#     -）2、group（）：默认是 root ，用于指定该 socket 是属于那个用户组的。

#     -）3、perm（）：默认是 0666 （rw-rw-rw）

#     -）4、keep-alive（） ：默认是 yes 。控制当 syslog-ng 重启时是否保持该 socket 为 Open 的状态，这样即使 syslog-ng 重启期间也不会丢失消息

#     -）5、max-connections（） ：控制该 source 允许的最大并发连接数，只能用于 unix-stream（）。默认是 256 个。

#     -）6、so_broadcast ：

#     -）7、so_rcvbuf ：指定该 socket 的接收缓冲区大小，单位是字节

#     -）8、so_sndbuf ：指定该 socket 的发送缓冲区大小，单位字节

#     -）9、so_keepalive ：允许发送 keep-alive 消息，保持该 socket 为 open 状态。 

Name	Type	Default	Description
owner()	string	root	Set the uid of the socket.
group()	string	root	Set the gid of the socket.
perm()	number