RSYSLOGD(8)               Linux System Administration              RSYSLOGD(8)



NAME
       rsyslogd - reliable and extended syslogd

SYNOPSIS
       rsyslogd [ -4 ] [ -6 ] [ -A ] [ -a socket ] [ -d ] [ -e ]
       [ -f config file ] [ -h ] [ -i pid file ] [ -l hostlist ]
       [ -m interval ] [ -n ] [ -o ] [ -p socket ]
       [ -r [port] ] [ -s domainlist ] [ -t port,max-nbr-of-sessions ]
       [ -v ] [ -w ] [ -x ]


DESCRIPTION
       Rsyslogd  is  a  system  utility providing support for message logging.
       Support of both internet and unix domain sockets enables  this  utility
       to support both local and remote logging (via UDP and TCP).

       Rsyslogd(8)  is  derived  from  the  sysklogd  package which in turn is
       derived from the stock BSD sources.

       Rsyslogd provides a kind of logging  that  many  modern  programs  use.
       Every  logged  message  contains  at least a time and a hostname field,
       normally a program name field, too, but that depends on how trusty  the
       logging  program  is.  The  rsyslog package supports free definition of
       output formats via templates. It also supports precise  timestamps  and
       writing  directly  to  MySQL databases. If the database option is used,
       tools like phpLogCon can be used to view the log data.

       While the rsyslogd sources have been heavily modified a couple of notes
       are  in  order.   First  of  all there has been a systematic attempt to
       insure that rsyslogd follows its default,  standard  BSD  behavior.  Of
       course,  some configuration file changes are necessary in order to sup-
       port the template system. However, rsyslogd should be  able  to  use  a
       standard  syslog.conf  and  act  like  the orginal syslogd. However, an
       original syslogd will not work correctly with a  rsyslog-enhanced  con-
       figuration  file.  At  best, it will generate funny looking file names.
       The second important concept to note is that this version  of  rsyslogd
       interacts  transparently  with the version of syslog found in the stan-
       dard libraries.  If a binary linked to the  standard  shared  libraries
       fails  to  function correctly we would like an example of the anomalous
       behavior.

       The main configuration file /etc/rsyslog.conf or an  alternative  file,
       given  with  the  -f  option, is read at startup.  Any lines that begin
       with the hash mark (‘‘#’’) and empty lines are ignored.   If  an  error
       occurs  during  parsing  the  error  element is ignored. It is tried to
       parse the rest of the line.

       For details and configuration examples, see the  rsyslog.conf  (5)  man
       page.



OPTIONS
       -A     When sending UDP messages, there are potentially multiple pathes
              to the target destination. By default, rsyslogd  only  sends  to
              the  first  target  it can successfully send to. If -A is given,
              messages are sent to all targets. This may improve  reliability,
              but  may  also  cause  message  duplicaton.  This  option should
              enabled only if it is fully understood.

       -4     Causes rsyslogd to listen to IPv4 addresses only.  If neither -4
              nor -6 is given, rsyslogd listens to all configured addresses of
              the system.

       -6     Causes rsyslogd to listen to IPv6 addresses only.  If neither -4
              nor -6 is given, rsyslogd listens to all configured addresses of
              the system.

       -a socket
              Using this argument you can specify additional sockets from that
              rsyslogd  has  to  listen to.  This is needed if you’re going to
              let some daemon run within a chroot() environment.  You can  use
              up  to  19  additional  sockets.  If your environment needs even
              more, you have to increase the symbol MAXFUNIX within  the  sys-
              logd.c  source  file.   An  example  for  a  chroot()  daemon is
              described     by     the     people     from     OpenBSD      at
              http://www.psionic.com/papers/dns.html.

       -d     Turns  on  debug mode.  Using this the daemon will not proceed a
              fork(2) to set itself in the background, but  opposite  to  that
              stay  in  the foreground and write much debug information on the
              current tty.  See the DEBUGGING section for more information.

       -e     Set the default of $RepeatedMsgReduction config option to "off".
              Hine:  "e"  like  "every  message". For further information, see
              there.

       -f config file
              Specify an alternative configuration file instead of  /etc/rsys-
              log.conf, which is the default.

       -h     By  default  rsyslogd will not forward messages it receives from
              remote hosts.  Specifying this switch on the command  line  will
              cause  the log daemon to forward any remote messages it receives
              to forwarding hosts which have been defined.

       -i pid file
              Specify an alternative pid file  instead  of  the  default  one.
              This  option  must  be  used  if  multiple instances of rsyslogd
              should run on a single machine.

       -l hostlist
              Specify a hostname that should be logged only  with  its  simple
              hostname  and  not  the  fqdn.   Multiple hosts may be specified
              using the colon (‘‘:’’) separator.

       -m interval
              The rsyslogd logs  a  mark  timestamp  regularly.   The  default
              interval  between  two -- MARK -- lines is 20 minutes.  This can
              be changed with this option.  Setting the interval to zero turns
              it off entirely.

       -n     Avoid  auto-backgrounding.   This  is  needed  especially if the
              rsyslogd is started and controlled by init(8).

       -o     Omit reading the standard local log socket. This option is  most
              useful  for  running  multiple instances of rsyslogd on a single
              machine. When specified, no local log socket is opened at all.

       -p socket
              You can specify an alternative unix  domain  socket  instead  of
              /dev/log.

       -r ["port"]
              Activates  the  syslog/udp  listener  service. The listener will
              listen to the specified port.  If no port  is  specified,  0  is
              used  as port number, which in turn will lead to a lookup of the
              system default syslog port. If there is no system  default,  514
              is  used.  Please note that the port must immediately follow the
              -r option. Thus "-r514" is valid while "-r 514" is invalid (note
              the space).

       -s domainlist
              Specify a domainname that should be stripped off before logging.
              Multiple domains may be specified using the colon (‘‘:’’)  sepa-
              rator.   Please  be advised that no sub-domains may be specified
              but only entire domains.  For example if -s north.de  is  speci-
              fied  and the host logging resolves to satu.infodrom.north.de no
              domain would be cut, you will have to specify two domains  like:
              -s north.de:infodrom.north.de.

       -t port,max-nbr-of-sessions
              Activates  the  syslog/tcp  listener  service. The listener will
              listen to the specified port. If max-nbr-of-sessions  is  speci-
              fied,  that  becomes  the  maximum number of concurrent tcp ses-
              sions. If not specified, the default is 200.  Please  note  that
              syslog/tcp  is not standardized, but the implementation in rsys-
              logd follows common practice and is compatible with  e.g.  Cisco
              PIX,  syslog-ng and MonitorWare (Windows).  Please note that the
              port must immediately follow the  -t  option.  Thus  "-t514"  is
              valid while "-t 514" is invalid (note the space).

       -v     Print version and exit.

       -w     Supress  warnings  issued  when  messages are received from non-
              authorized machines (those, that are in no AllowedSender  list).

       -x     Disable DNS for remote messages.


SIGNALS
       Rsyslogd  reacts  to a set of signals.  You may easily send a signal to
       rsyslogd using the following:

              kill -SIGNAL ‘cat /var/run/rsyslogd.pid‘


       SIGHUP This lets rsyslogd perform a re-initialization.  All open  files
              are  closed,  the  configuration  file  (default  is  /etc/rsys-
              log.conf) will be reread and the rsyslog(3) facility is  started
              again.

       SIGTERM
              Rsyslogd will die.

       SIGINT, SIGQUIT
              If  debugging  is  enabled these are ignored, otherwise rsyslogd
              will die.

       SIGUSR1
              Switch debugging on/off.  This option can only be used if  rsys-
              logd is started with the -d debug option.

       SIGCHLD
              Wait for childs if some were born, because of wall’ing messages.


SUPPORT FOR REMOTE LOGGING
       Rsyslogd provides network support to  the  syslogd  facility.   Network
       support  means  that  messages  can  be forwarded from one node running
       rsyslogd to another node  running  rsyslogd  (or  a  compatible  syslog
       implementation) where they will be actually logged to a disk file.

       To  enable  this  you have to specify either the -r or -t option on the
       command line.  The default behavior is that rsyslogd  won’t  listen  to
       the  network.  You can also combine these two options if you want rsys-
       logd to listen to both TCP and UDP messages.

       The strategy is to have rsyslogd listen on a  unix  domain  socket  for
       locally  generated  log messages.  This behavior will allow rsyslogd to
       inter-operate with the syslog found in the standard C library.  At  the
       same  time  rsyslogd  listens  on the standard syslog port for messages
       forwarded from other hosts.  To  have  this  work  correctly  the  ser-
       vices(5) files (typically found in /etc) must have the following entry:

                   syslog          514/udp

       If this entry is missing rsyslogd will use the well known port  of  514
       (so in most cases, it’s not really needed).

       To  cause  messages  to be forwarded to another host replace the normal
       file line in the rsyslog.conf file with the name of the host  to  which
       the  messages  is  to be sent prepended with an @ (for UDP delivery) or
       the sequence @@ (for TCP delivery). The host name can also be  followed
       by  a colon and a port number, in which case the message is sent to the
       specified port on the remote host.

              For example, to forward ALL messages to a remote  host  use  the
              following rsyslog.conf entry:

                   # Sample rsyslogd configuration file to
                   # messages to a remote host forward all.
                   *.*            @hostname
              More samples can be found in sample.conf.

              If  the  remote  hostname cannot be resolved at startup, because
              the name-server might not be accessible (it may be started after
              rsyslogd)  you  don’t  have  to  worry.   Rsyslogd will retry to
              resolve the name ten times and then complain.  Another possibil-
              ity to avoid this is to place the hostname in /etc/hosts.

              With  normal syslogds you would get syslog-loops if you send out
              messages that were received from a remote host to the same  host
              (or  more  complicated to a third host that sends it back to the
              first one, and so on).

              To avoid this no messages that were received from a remote  host
              are  sent out to another (or the same) remote host. You can dis-
              able this feature by the -h option.

              If the remote host is located in the same domain  as  the  host,
              rsyslogd  is running on, only the simple hostname will be logged
              instead of the whole fqdn.

              In a local network you may provide a central log server to  have
              all  the important information kept on one machine.  If the net-
              work consists of different domains you don’t  have  to  complain
              about logging fully qualified names instead of simple hostnames.
              You may want to use the strip-domain feature -s of this  server.
              You  can  tell  rsyslogd to strip off several domains other than
              the one the server is located in and only log simple  hostnames.

              Using  the -l option there’s also a possibility to define single
              hosts as local machines.  This, too,  results  in  logging  only
              their simple hostnames and not the fqdns.


OUTPUT TO DATABASES
       Rsyslogd  has  support  for  writing data to MySQL database tables. The
       exact specifics are described in the rsyslog.conf (5) man page. Be sure
       to read it if you plan to use database logging.

       While  it  is  often  handy to have the data in a database, you must be
       aware of the implications. Most importantly, database logging takes far
       longer  than  logging  to a text file. A system that can handle a large
       log volume when writing to text files can most likely not handle a sim-
       ilar large volume when writing to a database table.


OUTPUT TO NAMED PIPES (FIFOs)
       Rsyslogd has support for logging output to named pipes (fifos).  A fifo
       or named pipe can be used as a destination for log messages by prepend-
       ing  a  pipy symbol (‘‘|’’) to the name of the file.  This is handy for
       debugging.  Note that the fifo must be created with the mkfifo  command
       before rsyslogd is started.

              The  following configuration file routes debug messages from the
              kernel to a fifo:

                   # Sample configuration to route kernel debugging
                   # messages ONLY to /usr/adm/debug which is a
                   # named pipe.
                   kern.=debug              |/usr/adm/debug


INSTALLATION CONCERNS
       There is probably one important consideration when installing rsyslogd.
       It  is  dependent  on proper formatting of messages by the syslog func-
       tion.  The functioning of the syslog function in the  shared  libraries
       changed  somewhere  in  the  region of libc.so.4.[2-4].n.  The specific
       change was to null-terminate the message before transmitting it to  the
       /dev/log  socket.   Proper  functioning  of this version of rsyslogd is
       dependent on null-termination of the message.

       This problem will typically manifest itself if  old  statically  linked
       binaries  are being used on the system.  Binaries using old versions of
       the syslog function will cause empty lines to be logged followed by the
       message  with  the  first  character in the message removed.  Relinking
       these binaries to newer versions of the shared libraries  will  correct
       this problem.

       The  rsyslogd(8) can be run from init(8) or started as part of the rc.*
       sequence.  If it is started from init the option -n must be set, other-
       wise  you’ll  get  tons  of  syslog  daemons  started.  This is because
       init(8) depends on the process ID.


SECURITY THREATS
       There is the potential for the rsyslogd daemon to be used as a  conduit
       for a denial of service attack.  A rogue program(mer) could very easily
       flood the rsyslogd daemon with syslog messages  resulting  in  the  log
       files  consuming all the remaining space on the filesystem.  Activating
       logging over the inet domain sockets will of course expose a system  to
       risks outside of programs or individuals on the local machine.

       There are a number of methods of protecting a machine:

       1.     Implement  kernel  firewalling  to limit which hosts or networks
              have access to the 514/UDP socket.

       2.     Logging can be directed to an isolated  or  non-root  filesystem
              which, if filled, will not impair the machine.

       3.     The ext2 filesystem can be used which can be configured to limit
              a certain percentage of a filesystem  to  usage  by  root  only.
              NOTE  that  this  will  require rsyslogd to be run as a non-root
              process.  ALSO NOTE that this will prevent usage of remote  log-
              ging  since  rsyslogd  will  be  unable  to  bind to the 514/UDP
              socket.

       4.     Disabling inet domain sockets  will  limit  risk  to  the  local
              machine.

       5.     Use step 4 and if the problem persists and is not secondary to a
              rogue program/daemon get a 3.5 ft (approx. 1  meter)  length  of
              sucker rod* and have a chat with the user in question.

              Sucker  rod  def.  —  3/4,  7/8 or 1in. hardened steel rod, male
              threaded on each end.  Primary use in the oil industry in  West-
              ern North Dakota and other locations to pump ’suck’ oil from oil
              wells.  Secondary uses are for the construction of  cattle  feed
              lots  and  for  dealing with the occasional recalcitrant or bel-
              ligerent individual.

   Message replay and spoofing
       If remote logging is  enabled,  messages  can  easily  be  spoofed  and
       replayed.   As  the messages are transmitted in clear-text, an attacker
       might use the information  obtained  from  the  packets  for  malicious
       things.  Also,  an  attacker  might  reply recorded messages or spoof a
       sender’s IP address, which could lead to a wrong preception  of  system
       activity.  Be  sure  to  think  about  syslog  network  security before
       enabling it.


DEBUGGING
       When debugging is turned on using -d option then rsyslogd will be  very
       verbose  by  writing much of what it does on stdout.  Whenever the con-
       figuration file is reread and re-parsed you’ll see  a  tabular,  corre-
       sponding to the internal data structure.  This tabular consists of four
       fields:

       number This field contains a serial number starting by zero.  This num-
              ber represents the position in the internal data structure (i.e.
              the array).  If one number is left out then there  might  be  an
              error in the corresponding line in /etc/rsyslog.conf.

       pattern
              This  field  is  tricky  and  represents  the internal structure
              exactly.  Every column stands for  a  facility  (refer  to  sys-
              log(3)).   As  you can see, there are still some facilities left
              free for former use, only the left most are used.   Every  field
              in a column represents the priorities (refer to syslog(3)).

       action This  field  describes  the  particular  action that takes place
              whenever a message is received that matches the pattern.   Refer
              to the syslog.conf(5) manpage for all possible actions.

       arguments
              This field shows additional arguments to the actions in the last
              field.  For file-logging this is the filename for  the  logfile;
              for  user-logging  this  is  a list of users; for remote logging
              this is the hostname of the machine to log to; for  console-log-
              ging this is the used console; for tty-logging this is the spec-
              ified tty; wall has no additional arguments.


          templates
              There will also be a second internal structure which  lists  all
              defined  templates  and there contents. This also enables you to
              see the internally-defined, hardcoded templates.

FILES
       /etc/rsyslog.conf
              Configuration file for rsyslogd.  See rsyslog.conf(5) for  exact
              information.
       /dev/log
              The  Unix  domain socket to from where local syslog messages are
              read.
       /var/run/rsyslogd.pid
              The file containing the process id of rsyslogd.

BUGS
       Please review the file BUGS for up-to-date information  on  known  bugs
       and annouyances.

Further Information
       Please  visit  http://www.rsyslog.com/doc  for  additional information,
       tutorials and a support forum.

SEE ALSO
       rsyslog.conf(5),   logger(1),   syslog(2),   syslog(3),    services(5),
       savelog(8)


COLLABORATORS
       rsyslogd is derived from sysklogd sources, which in turn was taken from
       the BSD sources. Special thanks  to  Greg  Wettstein  (greg@wind.enjel-
       lic.com) and Martin Schulze (joey@linux.de) for the fine sysklogd pack-
       age.

       Rainer Gerhards
       Adiscon GmbH
       Grossrinderfeld, Germany
       rgerhards@adiscon.com

       Michael Meckelein
       Adiscon GmbH
       mmeckelein@adiscon.com



Version 1.16.1 (devel)           17 July 2007                      RSYSLOGD(8)