diff options
Diffstat (limited to 'rsyslog.conf.5')
| -rw-r--r-- | rsyslog.conf.5 | 249 |
1 files changed, 208 insertions, 41 deletions
diff --git a/rsyslog.conf.5 b/rsyslog.conf.5 index a21aca0f..0a2422c6 100644 --- a/rsyslog.conf.5 +++ b/rsyslog.conf.5 @@ -1,5 +1,5 @@ .\" rsyslog.conf - rsyslogd(8) configuration file -.\" Copyright 2003-2007 Rainer Gerhards and Adiscon GmbH. +.\" Copyright 2003-2008 Rainer Gerhards and Adiscon GmbH. .\" .\" This file is part of the rsyslog package, an enhanced system log daemon. .\" @@ -17,7 +17,7 @@ .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. .\" -.TH RSYSLOG.CONF 5 "12 February 2008" "Version 2.0.2" "Linux System Administration" +.TH RSYSLOG.CONF 5 "11 July 2008" "Version 3.18.0" "Linux System Administration" .SH NAME rsyslog.conf \- rsyslogd(8) configuration file .SH DESCRIPTION @@ -28,8 +28,104 @@ file is the main configuration file for the which logs system messages on *nix systems. This file specifies rules for logging. For special features see the .BR rsyslogd (8) -manpage. Ryslog.conf is backward-compatible with sysklogd's syslog.conf file. So if you migrate -from syklogd you can rename it and it should work. +manpage. Rsyslog.conf is backward-compatible with sysklogd's syslog.conf file. So if you migrate +from sysklogd you can rename it and it should work. + +.B Note that this version of rsyslog ships with extensive documentation in html format. +This is provided in the ./doc subdirectory and probably +in a separate package if you installed rsyslog via a packaging system. +To use rsyslog's advanced features, you +.B need +to look at the html documentation, because the man pages only cover +basic aspects of operation. + + +.SH MODULES + +Rsyslog has a modular design. Consequently, there is a growing number +of modules. See the html documentation for their full description. + +.TP +.I omsnmp +SNMP trap output module +.TP +.I omgssapi +Output module for GSS-enabled syslog +.TP +.I ommysql +Output module for MySQL +.TP +.I omrelp +Output module for the reliable RELP protocol (prevents message loss). +For details, see below at imrelp and the html documentation. +It can be used like this: +.IP +*.* :omrelp:server:port +.IP +*.* :omrelp:192.168.0.1:2514 # actual sample +.TP +.I ompgsql +Output module for PostgreSQL +.TP +.I omlibdbi +Generic database output module (Firebird/Interbase, MS SQL, Sybase, +SQLite, Ingres, Oracle, mSQL) +.TP +.I imfile +Input module for text files +.TP +.I imudp +Input plugin for UDP syslog. Replaces the deprecated -r option. Can be +used like this: +.IP +$ModLoad imudp +.IP +$InputUDPServerRun 514 +.TP +.I imtcp +Input plugin for plain TCP syslog. Replaces the deprecated -t +option. Can be used like this: +.IP +$ModLoad imtcp +.IP +$InputTCPServerRun 514 +.TP +.TP +.I imrelp +Input plugin for the RELP protocol. RELP can be used instead +of UDP or plain TCP syslog to provide reliable delivery of +syslog messages. Please note that plain TCP syslog does NOT +provide truly reliable delivery, with it messages may be lost +when there is a connection problem or the server shuts down. +RELP prevents message loss in those cases. +It can be used like this: +.IP +$ModLoad imrelp +.IP +$InputRELPServerRun 2514 +.TP +.I imgssapi +Input plugin for plain TCP and GSS-enable syslog +.TP +.I immark +Support for mark messages +.TP +.I imklog +Kernel logging. To include kernel log messages, you need to do +.IP +$ModLoad imklog + +Please note that the klogd daemon is no longer necessary and consequently +no longer provided by the rsyslog package. +.TP +.I imuxsock +Unix sockets, including the system log socket. You need to specify +.IP +$ModLoad imudp + +in order to receive log messages from local system processes. This +config directive should only left out if you know exactly what you +are doing. .SH BASIC STRUCTURE @@ -63,6 +159,54 @@ Every rule line consists of two fields, a selector field and an action field. Th two fields are separated by one or more spaces or tabs. The selector field specifies a pattern of facilities and priorities belonging to the specified action. +.SH SELECTORS + +The selector field itself again consists of two parts, a facility and a +priority, separated by a period ('.'). Both parts are case insensitive and can +also be specified as decimal numbers, but don't do that, you have been warned. +Both facilities and priorities are described in rsyslog(3). The names mentioned +below correspond to the similar LOG_-values in /usr/include/rsyslog.h. + +The facility is one of the following keywords: auth, authpriv, cron, daemon, +kern, lpr, mail, mark, news, security (same as auth), syslog, user, uucp and +local0 through local7. The keyword security should not be used anymore and mark +is only for internal use and therefore should not be used in applications. +Anyway, you may want to specify and redirect these messages here. The facility +specifies the subsystem that produced the message, i.e. all mail programs log +with the mail facility (LOG_MAIL) if they log using syslog. + +The priority is one of the following keywords, in ascending order: debug, info, +notice, warning, warn (same as warning), err, error (same as err), crit, alert, +emerg, panic (same as emerg). The keywords error, warn and panic are deprecated +and should not be used anymore. The priority defines the severity of the message. + +The behavior of the original BSD syslogd is that all messages of the specified +priority and higher are logged according to the given action. Rsyslogd behaves +the same, but has some extensions. + +In addition to the above mentioned names the rsyslogd(8) understands the +following extensions: An asterisk ('*') stands for all facilities or all +priorities, depending on where it is used (before or after the period). The +keyword none stands for no priority of the given facility. + +You can specify multiple facilities with the same priority pattern in one +statement using the comma (',') operator. You may specify as much facilities as +you want. Remember that only the facility part from such a statement is taken, a +priority part would be skipped. + +Multiple selectors may be specified for a single action using the semicolon +(';') separator. Remember that each selector in the selector field is capable +to overwrite the preceding ones. Using this behavior you can exclude some +priorities from the pattern. + +Rsyslogd has a syntax extension to the original BSD source, that makes its use +more intuitively. You may precede every priority with an equation sign ('=') to +specify only this single priority and not any of the above. You may also (both +is valid, too) precede the priority with an exclamation mark ('!') to ignore +all that priorities, either exact this one or this and any higher priority. If +you use both extensions than the exclamation mark must occur before the equation +sign, just use it intuitively. + .SH ACTIONS The action field of a rule describes what to do with the message. In general, message content is written to a kind of "logfile". But also other actions might be done, like writing to a @@ -74,7 +218,16 @@ beginning with a slash ('/'). .B Example: .RS -*.* /var/log/traditionalfile.log;TraditionalFormat # log to a file in the traditional format +*.* /var/log/traditionalfile.log;RSYSLOG_TraditionalFormat # log to a file in the traditional format +.RE + +Note: if you would like to use high-precision timestamps in your log files, +just remove the ";RSYSLOG_TraditionalFormat". That will select the default +template, which, if not changed, uses RFC 3339 timestamps. + +.B Example: +.RS +*.* /var/log/file.log # log to a file with RFC3339 timestamps .RE .SS Named pipes @@ -87,14 +240,14 @@ the mkfifo(1) command before rsyslogd(8) is started. If the file you specified is a tty, special tty-handling is done, same with /dev/console. .SS Remote machine -To forward messages to another host, prepend the hostname with the at sign ("@"). A single at -sign means that messages will be forwarded via UDP protocol (the standard for syslog). If you -prepend two at signs ("@@"), the messages will be transmitted via TCP. - -Please note that this version of rsyslogd by default does NOT forward messages it has received -from the network to another host. Specify the "-h" option to enable this. +There are three ways to forward message: the traditional UDP transport, which is extremely +lossy but standard, the plain TCP based transport which loses messages only during certain +situations but is widely available and the RELP transport which does not lose messages +but is currently available only as part of rsyslogd 3.15.0 and above. -Using the $GssMode directive TCP messages can be wrapped with GSS-API. +To forward messages to another host via UDP, prepend the hostname with the at sign ("@"). +To forward it via plain tcp, prepend two at signs ("@@"). To forward via RELP, prepend the +string ":omrelp:" in front of the hostname. .B Example: .RS @@ -102,7 +255,21 @@ Using the $GssMode directive TCP messages can be wrapped with GSS-API. .RE .sp In the example above, messages are forwarded via UDP to the machine 192.168.0.1, the destination -port defaults to 514. +port defaults to 514. Due to the nature of UDP, you will probably lose some messages in transit. +If you expect high traffic volume, you can expect to lose a quite noticeable number of messages +(the higher the traffic, the more likely and severe is message loss). + +.B If you would like to prevent message loss, use RELP: +.RS +*.* :omrelp:192.168.0.1:2514 +.RE +.sp +Note that a port number was given as there is no standard port for relp. + +Keep in mind that you need to load the correct input and output plugins (see "Modules" above). + +Please note that rsyslogd offers a variety of options in regarding to remote +forwarding. For full details, please see the html documentation. .SS List of users Usually critical messages are also directed to ``root'' on that machine. You can specify a list @@ -115,29 +282,13 @@ Emergency messages often go to all users currently online to notify them that so is happening with the system. To specify this wall(1)-feature use an asterisk ('*'). .SS Database table -This allows logging of the message to a database table. Currently, only MySQL databases are -supported. By default, a MonitorWare-compatible schema is required for this to work. You can +This allows logging of the message to a database table. +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. - -.B Example: -.RS ->dbhost,dbname,dbuser,dbpassword;dbtemplate -.RE - -.B 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 -.B $ModLoad -MySQL directive some place above the first use of the database write (we recommend doing at the -the beginning of the config file). -.B You have to install the rsyslog-mysql package to get this module. +See the html documentation for further details on database logging. .SS Discard If the discard action is carried out, the received message is immediately discarded. Discard @@ -173,11 +324,13 @@ The program-to-execute can be any valid executable. It receives the template str (argv[1]). .SH FILTER CONDITIONS -Rsyslog offers two different types "filter conditions": +Rsyslog offers three different types "filter conditions": .sp 0 * "traditional" severity and facility based selectors .sp 0 * property-based filters +.sp 0 + * expression-based filters .RE .SS Blocks @@ -231,6 +384,10 @@ Checks if the value is found exactly at the beginning of the property value Compares the property against the provided regular expression. .RE +.SS Expression-Based Filters +See the html documentation for this feature. + + .SH TEMPLATES Every output in rsyslog uses templates - this holds true for files, user @@ -263,11 +420,11 @@ To escape: .sp 0 \\ = \\\\ --> '\\' is used to escape (as in C) .sp 0 -$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n" +$template TraditionalFormat,"%timegenerated% %HOSTNAME% %syslogtag%%msg%\n" Properties can be accessed by the property replacer (see there for details). -.B Please note that as of 1.15.0, templates can also by used to generate selector lines with dynamic file names. +.B Please note that templates can also by used to generate selector lines with dynamic file names. For example, if you would like to split syslog messages from different hosts to different files (one per host), you can define the following template: @@ -325,10 +482,6 @@ it - among others, it takes some toll on the processing time. Not much, but on a really busy system you might notice it ;) The default template for the write to database action has the sql option set. -As we currently support only MySQL and the sql option matches the default MySQL -configuration, this is a good choice. However, if you have turned on -NO_BACKSLASH_ESCAPES in your MySQL config, you need to supply a template with -the stdsql option. Otherwise you will become vulnerable to SQL injection. .SS Template examples Please note that the samples are split across multiple lines. A template MUST @@ -388,7 +541,7 @@ NOTE 2: You have to have MySQL module installed to use this template. Output Channels are a new concept first introduced in rsyslog 0.9.0. As of this writing, it is most likely that they will be replaced by something different in the future. - So if you use them, be prepared to change you configuration file syntax when you upgrade +So if you use them, be prepared to change you configuration file syntax when you upgrade to a later release. Output channels are defined via an $outchannel directive. It's syntax is as follows: @@ -584,6 +737,17 @@ replace control characters by spaces drop-cc drop control characters - the resulting string will neither contain control characters, escape sequences nor any other replacement character like space. +.SH QUEUED OPERATIONS +Rsyslogd supports queued operations to handle offline outputs +(like remote syslogd's or database servers being down). When running in +queued mode, rsyslogd buffers messages to memory and optionally to disk +(on an as-needed basis). Queues survive rsyslogd restarts. + +It is highly suggested to use remote forwarding and database writing +in queued mode, only. + +To learn more about queued operations, see the html documentation. + .SH FILES .PD 0 .TP @@ -600,10 +764,13 @@ The complete documentation can be found in the doc folder of the rsyslog distrib .RS .B http://www.rsyslog.com/doc + .RE +Please note that the man page reflects only a subset of the configuration options. Be sure to read +the html documentation for all features and details. This is especially vital if you plan to set +up a more-then-extremely-simple system. .SH AUTHORS -The .B rsyslogd is taken from sysklogd sources, which have been heavily modified by Rainer Gerhards (rgerhards@adiscon.com) and others. |