From 2357d1442991dbe0e154870437b11e17be72e427 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Tue, 16 Oct 2007 08:27:09 +0000 Subject: added new rsyslogd man page in html format (thanks to man2html) --- doc/man_rsyslogd.html | 438 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 438 insertions(+) create mode 100644 doc/man_rsyslogd.html diff --git a/doc/man_rsyslogd.html b/doc/man_rsyslogd.html new file mode 100644 index 00000000..fab309db --- /dev/null +++ b/doc/man_rsyslogd.html @@ -0,0 +1,438 @@ +
+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)
+
-- cgit