25.3.2. Actions
Actions specify what is to be done with the messages filtered out by an already-defined selector. The following are some of the actions you can define in your rule:
- Saving syslog messages to log files
- The majority of actions specify to which log file a syslog message is saved. This is done by specifying a file path after your already-defined selector:
FILTER PATH
where FILTER stands for user-specified selector and PATH is a path of a target file.For instance, the following rule is comprised of a selector that selects all cron syslog messages and an action that saves them into the/var/log/cron.loglog file:cron.* /var/log/cron.log
By default, the log file is synchronized every time a syslog message is generated. Use a dash mark (-) as a prefix of the file path you specified to omit syncing:FILTER -PATH
Note that you might lose information if the system terminates right after a write attempt. However, this setting can improve performance, especially if you run programs that produce very verbose log messages.Your specified file path can be either static or dynamic. Static files are represented by a fixed file path as shown in the example above. Dynamic file paths can differ according to the received message. Dynamic file paths are represented by a template and a question mark (?) prefix:FILTER ?DynamicFile
where DynamicFile is a name of a predefined template that modifies output paths. You can use the dash prefix (-) to disable syncing, also you can use multiple templates separated by a colon (;). For more information on templates, see the section called “Generating Dynamic File Names”.If the file you specified is an existing terminal or/dev/consoledevice, syslog messages are sent to standard output (using special terminal-handling) or your console (using special/dev/console-handling) when using the X Window System, respectively. - Sending syslog messages over the network
- rsyslog allows you to send and receive syslog messages over the network. This feature allows you to administer syslog messages of multiple hosts on one machine. To forward syslog messages to a remote machine, use the following syntax:
@[(
zNUMBER)]HOST:[PORT]where:- The at sign (
@) indicates that the syslog messages are forwarded to a host using theUDPprotocol. To use theTCPprotocol, use two at signs with no space between them (@@). - The optional
zNUMBERsetting enables zlib compression for syslog messages. The NUMBER attribute specifies the level of compression (from 1 – lowest to 9 – maximum). Compression gain is automatically checked byrsyslogd, messages are compressed only if there is any compression gain and messages below 60 bytes are never compressed. - The HOST attribute specifies the host which receives the selected syslog messages.
- The PORT attribute specifies the host machine's port.
When specifying anIPv6address as the host, enclose the address in square brackets ([,]).Example 25.4. Sending syslog Messages over the Network
The following are some examples of actions that forward syslog messages over the network (note that all actions are preceded with a selector that selects all messages with any priority). To forward messages to192.168.0.1via theUDPprotocol, type:*.* @192.168.0.1
To forward messages to "example.com" using port 6514 and theTCPprotocol, use:*.* @@example.com:6514
The following compresses messages with zlib (level 9 compression) and forwards them to2001:db8::1using theUDPprotocol*.* @(z9)[2001:db8::1]
- Output channels
- Output channels are primarily used to specify the maximum size a log file can grow to. This is very useful for log file rotation (for more information see Section 25.3.5, “Log Rotation”). An output channel is basically a collection of information about the output action. Output channels are defined by the
$outchanneldirective. To define an output channel in/etc/rsyslog.conf, use the following syntax:$outchannel NAME, FILE_NAME, MAX_SIZE, ACTION
where:- The NAME attribute specifies the name of the output channel.
- The FILE_NAME attribute specifies the name of the output file. Output channels can write only into files, not pipes, terminal, or other kind of output.
- The MAX_SIZE attribute represents the maximum size the specified file (in FILE_NAME) can grow to. This value is specified in bytes.
- The ACTION attribute specifies the action that is taken when the maximum size, defined in MAX_SIZE, is hit.
To use the defined output channel as an action inside a rule, type:FILTER :omfile:$NAME
Example 25.5. Output channel log rotation
The following output shows a simple log rotation through the use of an output channel. First, the output channel is defined via the$outchanneldirective:$outchannel log_rotation, /var/log/test_log.log, 104857600, /home/joe/log_rotation_script
and then it is used in a rule that selects every syslog message with any priority and executes the previously-defined output channel on the acquired syslog messages:*.* :omfile:$log_rotation
Once the limit (in the example100 MB) is hit, the/home/joe/log_rotation_scriptis executed. This script can contain anything from moving the file into a different folder, editing specific content out of it, or simply removing it. - Sending syslog messages to specific users
- rsyslog can send syslog messages to specific users by specifying a user name of the user you want to send the messages to (as in Example 25.7, “Specifying Multiple Actions”). To specify more than one user, separate each user name with a comma (
,). To send messages to every user that is currently logged on, use an asterisk (*). - Executing a program
- rsyslog lets you execute a program for selected syslog messages and uses the
system()call to execute the program in shell. To specify a program to be executed, prefix it with a caret character (^). Consequently, specify a template that formats the received message and passes it to the specified executable as a one line parameter (for more information on templates, see Section 25.3.3, “Templates”).FILTER ^EXECUTABLE; TEMPLATE
Here an output of the FILTER condition is processed by a program represented by EXECUTABLE. This program can be any valid executable. Replace TEMPLATE with the name of the formatting template.Example 25.6. Executing a Program
In the following example, any syslog message with any priority is selected, formatted with thetemplatetemplate and passed as a parameter to the test-program program, which is then executed with the provided parameter:*.* ^test-program;template
Warning
When accepting messages from any host, and using the shell execute action, you may be vulnerable to command injection. An attacker may try to inject and execute commands in the program you specified to be executed in your action. To avoid any possible security threats, thoroughly consider the use of the shell execute action. - Storing syslog messages in a database
- Selected syslog messages can be directly written into a database table using the database writer action. The database writer uses the following syntax:
:PLUGIN:DB_HOST,DB_NAME,DB_USER,DB_PASSWORD;[TEMPLATE]where:- The PLUGIN calls the specified plug-in that handles the database writing (for example, the
ommysqlplug-in). - The DB_HOST attribute specifies the database host name.
- The DB_NAME attribute specifies the name of the database.
- The DB_USER attribute specifies the database user.
- The DB_PASSWORD attribute specifies the password used with the aforementioned database user.
- The TEMPLATE attribute specifies an optional use of a template that modifies the syslog message. For more information on templates, see Section 25.3.3, “Templates”.
Important
Currently, rsyslog provides support forMySQLandPostgreSQLdatabases only. In order to use theMySQLandPostgreSQLdatabase writer functionality, install the rsyslog-mysql and rsyslog-pgsql packages, respectively. Also, make sure you load the appropriate modules in your/etc/rsyslog.confconfiguration file:$ModLoad ommysql # Output module for MySQL support $ModLoad ompgsql # Output module for PostgreSQL support
For more information on rsyslog modules, see Section 25.7, “Using Rsyslog Modules”.Alternatively, you may use a generic database interface provided by theomlibdbmodule (supports: Firebird/Interbase, MS SQL, Sybase, SQLLite, Ingres, Oracle, mSQL). - Discarding syslog messages
- To discard your selected messages, use the tilde character (
~).FILTER ~
The discard action is mostly used to filter out messages before carrying on any further processing. It can be effective if you want to omit some repeating messages that would otherwise fill the log files. The results of discard action depend on where in the configuration file it is specified, for the best results place these actions on top of the actions list. Please note that once a message has been discarded there is no way to retrieve it in later configuration file lines.For instance, the following rule discards any cron syslog messages:cron.* ~
Specifying Multiple Actions
For each selector, you are allowed to specify multiple actions. To specify multiple actions for one selector, write each action on a separate line and precede it with an ampersand (&) character:
FILTER ACTION & ACTION & ACTION
Specifying multiple actions improves the overall performance of the desired outcome since the specified selector has to be evaluated only once.
Example 25.7. Specifying Multiple Actions
In the following example, all kernel syslog messages with the critical priority (
crit) are sent to user user1, processed by the template temp and passed on to the test-program executable, and forwarded to 192.168.0.1 via the UDP protocol.
kern.=crit user1 & ^test-program;temp & @192.168.0.1
Any action can be followed by a template that formats the message. To specify a template, suffix an action with a semicolon (
;) and specify the name of the template. For more information on templates, see Section 25.3.3, “Templates”.
Warning
A template must be defined before it is used in an action, otherwise it is ignored. In other words, template definitions should always precede rule definitions in
/etc/rsyslog.conf.
