Actions 动作
The Action object describe what is to be done with a message. They are implemented via output modules.
The action object has different parameters:
- those that apply to all actions and are action specific. These are documented below.
- action队列的参数会应用到所有 action，参考 queue parameters.
- action-specific parameters. These are specific to a certain type of actions. They are documented by the output modules in question.
General Action Parameters
大小写不敏感
name word
This names the action. The name is used for statistics gathering and documentation. 如果没有名字，rsyslog会运达产生一个，编号从1ton
type string
强制参数， The name of the module that should be used.
action.writeAllMarkMessages on/off
默认on，每20分钟会发送mark消息给action，无论之前这个action是否被执行过，可以认为是一种心跳。一般设为on
action.execOnlyEveryNthTime integer
每隔一定的消息执行一次action，比如设为3，第1，2条消息会被丢弃，执行第3条，如是反复
action.execOnlyEveryNthTimeout integer
每隔一定的时间执行一次action。0表示不启用。在消息间隔很长时，会很有用，
action.errorfile string
New in version 8.32.0.
一条消息由于某些原因执行失败，默认就被丢弃了。
如果设置了本项，可以输出到指定文件。格式为JSON，包括失败的消息，action的名字，错误码，及错误原因。
action.execOnlyOnceEveryInterval integer
在最后一次执行后指定时间执行Execute action only if the last execute is at last seconds in the past (more info in ommail, but may be used with any action)
action.execOnlyWhenPreviousIsSuspended on/off
设置为on时，当前一个action被挂起时，才会执行。比如用来自动切换目的地址，当主服务器失败后，发送到备用服务器
action.repeatedmsgcontainsoriginalmsg on/off
如果消息重复了，会提示“last message repeated n times” messages, 比较消息的n个字符，n至少为80
action.resumeRetryCount integer
[default 0, -1 means eternal]
Sets how often an action is retried before it is considered to have failed. Failed actions discard messages.
action.resumeInterval integer
重试间隔，单位s。为防止在多消耗，每10次失败后，这个间隔扩大， (numRetries / 10 + 1) * action.resumeInterval. 比如30的间隔，在10次失败后会变成60，100次失败后变成 330
action.resumeIntervalMax integer
Default: 1800 (30 minutes)
重试间隔最大值
action.reportSuspension on/off
Configures rsyslog to report suspension and reactivation of the action. This is useful to note which actions have problems (e.g. connecting to a remote system) and when. The default for this setting is the equally-named global parameter.
action.reportSuspensionContinuation on/off
Configures rsyslog to report continuation of action suspension. This emits new messages whenever an action is to be retried, but continues to fail. If set to “on”, action.reportSuspension is also automatically set to “on”. The default for this setting is the equally-named global parameter.
action.copyMsg on/off
Configures action to copy the message if on. Defaults to off (which is how actions have worked traditionally), which causes queue to refer to the original message object, with reference-counting. (Introduced with 8.10.0).
Useful Links
- Rainer’s blog posting on the performance of main and action queue worker threads
Legacy Format
Legacy action很能写正确，有可能的话， A key problem with legacy format is that a single action is defined via multiple configurations lines, which may be spread all across rsyslog.conf. Even the definition of multiple actions may be intermixed (often not intentional!). If legacy actions format needs to be used (e.g. some modules may not yet implement the RainerScript format), it is strongly recommended to place all configuration statements pertaining to a single action closely together.
Please also note that legacy action parameters do not affect RainerScript action objects. So if you define for example:
1 | $actionResumeRetryCount 10 |
server1’s “action.resumeRetryCount” parameter is not set, instead server2’s is!
A goal of the new RainerScript action format was to avoid confusion which parameters are actually used. As such, it would be counter-productive to honor legacy action parameters inside a RainerScript definition. As result, both types of action definitions are strictly (and nicely) separated from each other. The bottom line is that if RainerScript actions are used, one does not need to care about which legacy action parameters may (still…) be in effect.
Note that not all modules necessarily support legacy action format. Especially newer modules are recommended to NOT support it.
Legacy Description
Templates can be used with many actions. If used, the specified template is used to generate the message content (instead of the default template). To specify a template, write a semicolon after the action value immediately followed by the template name. Beware: templates MUST be defined BEFORE they are used. It is OK to define some templates, then use them in selector lines, define more templates and use use them in the following selector lines. But it is NOT permitted to use a template in a selector line that is above its definition. If you do this, the action will be ignored.
可以对一个selector使用多个actions (or more precisely a single filter of such a selector line). 每一个action必须单独一行，以&打头
1 | *.=crit :omusrmsg:rger |
These three lines send critical messages to the user rger and root and also store them in /var/log/critmsgs. Using multiple actions per selector is convenient and also offers a performance benefit. As the filter needs to be evaluated only once, there is less computation required to process the directive compared to the otherwise-equal config directives below:
1 | *.=crit :omusrmsg:rger |
Regular File
消息一般会记录到文件 ，文件名使用全路径，以/起始，新版本也支持相对路径，必须以./起始。如“./file-in-current-dir.log”。但相对路径不可靠，必须要经过严格测试。可以在前面加 “-‘ 来省略文件同步，但如果系统崩溃的话可能会丢失消息，但会提高性能，尤其是记录很长的消息。所以如果有可靠的USP，并且要记录很多消息，可以开启 -
文件名可以是静态，也可以动态，有助于将消息分类保存。
可以和模板一起工作。首先定义一个文件名的模板，我们取名模板为DynFile，然后使用”?”来调用文件动态文件名
也可以使用模板来输出
支持自动创建目录
Named Pipes
This version of rsyslogd(8) has support for logging output to named pipes (fifos). A fifo or named pipe can be used as a destination for log messages by prepending a pipe symbol (“|’‘) to the name of the file. This is handy for debugging. Note that the fifo must be created with the mkfifo(1) command before rsyslogd(8) is started.
Terminal and Console
If the file you specified is a tty, special tty-handling is done, same with /dev/console.
Remote Machine
要发行其它host，在hostname前加@，默认UDP，如果需要TCP，加@@。TCP不是syslog的官方标准，但另一些app支持，比如syslog-ng或WinSyslog。
可以加一些option，不要加空格，用()包围，多个option用逗号分割
z
Enable zlib-compression for the message. The
Please note that when a TCP transport is used, compression will also turn on syslog-transport-tls framing. See the “o” option for important information on the implications.
Compressed messages 能被接受方自动识别，无需配置。
o
This option is experimental. Use at your own risk and only if you know why you need it! If in doubt, do NOT turn it on.
This option is only valid for plain TCP based transports. It selects a different framing based on IETF internet draft syslog-transport-tls-06. This framing offers some benefits over traditional LF-based framing. However, the standardization effort is not yet complete. There may be changes in upcoming versions of this standard. Rsyslog will be kept in line with the standard. There is some chance that upcoming changes will be incompatible to the current specification. In this case, all systems using -transport-tls framing must be upgraded. There will be no effort made to retain compatibility between different versions of rsyslog. The primary reason for that is that it seems technically impossible to provide compatibility between some of those changes. So you should take this note very serious. It is not something we do not like to do (and may change our mind if enough people beg…), it is something we most probably can not do for technical reasons (aka: you can beg as much as you like, it won’t change anything…).
The most important implication is that compressed syslog messages via TCP must be considered with care. Unfortunately, it is technically impossible to transfer compressed records over traditional syslog plain tcp transports, so you are left with two evil choices…
The hostname may be followed by a colon and the destination port.
The following is an example selector line with forwarding:
. @@(o,z9)192.168.0.1:1470
In this example, messages are forwarded via plain TCP with experimental framing and maximum compression to the host 192.168.0.1 at port 1470.
. @192.168.0.1
In the example above, messages are forwarded via UDP to the machine 192.168.0.1, the destination port defaults to 514. Messages will not be compressed.
Note that IPv6 addresses contain colons. So if an IPv6 address is specified in the hostname part, rsyslogd could not detect where the IP address ends and where the port starts. There is a syntax extension to support this: put square brackets around the address (e.g. “[2001::1]”). Square brackets also work with real host names and IPv4 addresses, too.
A valid sample to send messages to the IPv6 host 2001::1 at port 515 is as follows:
. @[2001::1]:515
This works with TCP, too.
Note to sysklogd users: sysklogd does not support RFC 3164 format, which is the default forwarding template in rsyslog. As such, you will experience duplicate hostnames if rsyslog is the sender and sysklogd is the receiver. The fix is simple: you need to use a different template. Use that one:
$template sysklogd,”<%PRI%>%TIMESTAMP% %syslogtag%%msg%””
. @192.168.0.1;sysklogd
List of Users
Usually critical messages are also directed to “root’’ on that machine. You can specify a list of users that shall get the message by simply writing “:omusrmsg: followed by the login name. For example, the send messages to root, use “:omusrmsg:root”. You may specify more than one user by separating them with commas (“,’‘). Do not repeat the “:omusrmsg:” prefix in this case. For example, to send data to users root and rger, use “:omusrmsg:root,rger” (do not use “:omusrmsg:root,:omusrmsg:rger”, this is invalid). If they’re logged in they get the message.
Everyone logged on
Emergency messages often go to all users currently online to notify them that something strange is happening with the system. To specify this wall(1)-feature use an asterisk as the user message destination(“:omusrmsg:*’‘).
Call Plugin
This is a generic way to call an output plugin. The plugin must support this functionality. Actual parameters depend on the module, so see the module’s doc on what to supply. The general syntax is as follows:
:modname:params;template
Currently, the ommysql database output module supports this syntax (in addition to the “>” syntax it traditionally supported). For ommysql, the module name is “ommysql” and the params are the traditional ones. The ;template part is not module specific, it is generic rsyslog functionality available to all modules.
As an example, the ommysql module may be called as follows:
:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate
For details, please see the “Database Table” section of this documentation.
Note: as of this writing, the “:modname:” part is hardcoded into the module. So the name to use is not necessarily the name the module’s plugin file is called.
Database Table
This allows logging of the message to a database table. Currently, only MySQL databases are supported. However, other database drivers will most probably be developed as plugins. By default, a MonitorWare-compatible schema is required for this to work. You can create that schema with the createDB.SQL file that came with the rsyslog package. You can also use any other schema of your liking - you just need to define a proper template and assign this template to the action. The database writer is called by specifying a greater-then sign (“>”) in front of the database connect information. Immediately after that sign the database host name must be given, a comma, the database name, another comma, the database user, a comma and then the user’s password. If a specific template is to be used, a semicolon followed by the template name can follow the connect information. This is as follows: >dbhost,dbname,dbuser,dbpassword;dbtemplate
Important: to use the database functionality, the MySQL output module must be loaded in the config file BEFORE the first database table action is used. This is done by placing the
1 |
directive some place above the first use of the database write (we recommend doing at the beginning of the config file).
Discard / Stop
If the discard action is carried out, the received message is immediately discarded. No further processing of it occurs. Discard has primarily been added to filter out messages before carrying on any further processing. For obvious reasons, the results of “discard” are depending on where in the configuration file it is being used. Please note that once a message has been discarded there is no way to retrieve it in later configuration file lines.
Discard can be highly effective if you want to filter out some annoying messages that otherwise would fill your log files. To do that, place the discard actions early in your log files. This often plays well with property-based filters, giving you great freedom in specifying what you do not want.
Discard is just the word “stop” with no further parameters:
stop
For example,
. stop
discards everything (ok, you can achieve the same by not running rsyslogd at all…).
Note that in legacy configuration the tilde character “~” can also be used instead of the word “stop”.
Output Channel
Binds an output channel definition (see there for details) to this action. Output channel actions must start with a $-sign, e.g. if you would like to bind your output channel definition “mychannel” to the action, use “$mychannel”. Output channels support template definitions like all all other actions.
Shell Execute
NOTE: This action is only supported for backwards compatibility. For new configs, use omprog instead. It provides a more solid and secure solution with higher performance.
This executes a program in a subshell. The program is passed the template-generated message as the only command line parameter. Rsyslog waits until the program terminates and only then continues to run.
^program-to-execute;template
The program-to-execute can be any valid executable. It receives the template string as a single parameter (argv[1]).
WARNING: The Shell Execute action was added to serve an urgent need. While it is considered reasonable save when used with some thinking, its implications must be considered. The current implementation uses a system() call to execute the command. This is not the best way to do it (and will hopefully changed in further releases). Also, proper escaping of special characters is done to prevent command injection. However, attackers always find smart ways to circumvent escaping, so we can not say if the escaping applied will really safe you from all hassles. Lastly, rsyslog will wait until the shell command terminates. Thus, a program error in it (e.g. an infinite loop) can actually disable rsyslog. Even without that, during the programs run-time no messages are processed by rsyslog. As the IP stacks buffers are quickly overflowed, this bears an increased risk of message loss. You must be aware of these implications. Even though they are severe, there are several cases where the “shell execute” action is very useful. This is the reason why we have included it in its current form. To mitigate its risks, always a) test your program thoroughly, b) make sure its runtime is as short as possible (if it requires a longer run-time, you might want to spawn your own sub-shell asynchronously), c) apply proper firewalling so that only known senders can send syslog messages to rsyslog. Point c) is especially important: if rsyslog is accepting message from any hosts, chances are much higher that an attacker might try to exploit the “shell execute” action.
Template Name
Every ACTION can be followed by a template name. If so, that template is used for message formatting. If no name is given, a hard-coded default template is used for the action. There can only be one template name for each given action. The default template is specific to each action. For a description of what a template is and what you can do with it, see the template documentation.