Merge branch 'master' into beta

1 files changed, 375 insertions, 0 deletions

diff --git a/tools/rsyslogd.8 b/tools/rsyslogd.8
new file mode 100644
index 00000000..a1395d73
--- /dev/null
+++ b/tools/rsyslogd.8
@@ -0,0 +1,375 @@
+.\" Copyright 2004-2008 Rainer Gerhards and Adiscon for the rsyslog modifications
+.\" May be distributed under the GNU General Public License
+.\"
+.TH RSYSLOGD 8 "07 April 2008" "Version 3.17.0" "Linux System Administration"
+.SH NAME
+rsyslogd \- reliable and extended syslogd 
+.SH SYNOPSIS
+.B rsyslogd
+.RB [ " \-4 " ]
+.RB [ " \-6 " ]
+.RB [ " \-A " ]
+.RB [ " \-d " ]
+.RB [ " \-f "
+.I config file
+]
+.br
+.RB [ " \-i "
+.I pid file
+]
+.RB [ " \-l "
+.I hostlist
+]
+.RB [ " \-n " ]
+.br
+.RB [ " \-q " ]
+.RB [ " \-Q " ]
+.RB [ " \-s "
+.I domainlist
+]
+.RB [ " \-v " ]
+.RB [ " \-w " ]
+.RB [ " \-x " ]
+.LP
+.SH DESCRIPTION
+.B 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.
+
+.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.
+.B For details and configuration examples, see the rsyslog.conf (5)
+.B man page and the online documentation at http://www.rsyslog.com/doc
+
+.BR Rsyslogd (8)
+is derived from the sysklogd package which in turn is derived from the
+stock BSD sources.
+
+.B 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 databases. If the database option is used, tools like phpLogCon can
+be used to view the log data.
+
+While the
+.B rsyslogd
+sources have been heavily modified a couple of notes
+are in order.  First of all there has been a systematic attempt to
+ensure that rsyslogd follows its default, standard BSD behavior. Of course,
+some configuration file changes are necessary in order to support 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 configuration 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
+standard 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
+.I /etc/rsyslog.conf
+or an alternative file, given with the 
+.B "\-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.
+
+.LP
+.SH OPTIONS
+.B Note that in version 3 of rsyslog a number of command line options
+.B have been deprecated and replaced with config file directives. The
+.B -c option controls the backward compatibility mode in use.
+.TP
+.BI "\-A"
+When sending UDP messages, there are potentially multiple pathes to
+the target destination. By default,
+.B 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.
+.TP
+.BI "\-4"
+Causes
+.B rsyslogd
+to listen to IPv4 addresses only.
+If neither -4 nor -6 is given,
+.B rsyslogd
+listens to all configured addresses of the system.
+.TP
+.BI "\-6"
+Causes
+.B rsyslogd
+to listen to IPv6 addresses only.
+If neither -4 nor -6 is given,
+.B rsyslogd
+listens to all configured addresses of the system.
+.TP
+.BI "\-c " "version"
+Selects the desired backward compatibility mode. It must always be the
+first option on the command line, as it influences processing of the
+other options. To use the rsyslog v3 native interface, specify -c3. To
+use compatibility mode , either do not use -c at all or use
+-c<version> where 
+.IR version
+is the rsyslog version that it shall be
+compatible with. Using -c0 tells rsyslog to be command-line compatible
+to sysklogd, which is the default if -c is not given.
+.B Please note that rsyslogd issues warning messages if the -c3
+.B command line option is not given.
+This is to alert you that your are running in compatibility
+mode. Compatibility mode interfers with you rsyslog.conf commands and
+may cause some undesired side-effects. It is meant to be used with a
+plain old rsyslog.conf - if you use new features, things become
+messy. So the best advice is to work through this document, convert
+your options and config file and then use rsyslog in native mode. In
+order to aid you in this process, rsyslog logs every
+compatibility-mode config file directive it has generated. So you can
+simply copy them from your logfile and paste them to the config.
+.TP
+.B "\-d"
+Turns on debug mode.  Using this the daemon will not proceed a 
+.BR 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.
+.TP
+.BI "\-f " "config file"
+Specify an alternative configuration file instead of
+.IR /etc/rsyslog.conf ","
+which is the default.
+.TP
+.BI "\-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.
+.TP
+.BI "\-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.
+.TP
+.B "\-n"
+Avoid auto-backgrounding.  This is needed especially if the
+.B rsyslogd
+is started and controlled by
+.BR init (8).
+.TP
+.BI "\-q " "add hostname if DNS fails during ACL processing"
+During ACL processing, hostnames are resolved to IP addreses for
+performance reasons. If DNS fails during that process, the hostname
+is added as wildcard text, which results in proper, but somewhat
+slower operation once DNS is up again.
+.TP
+.BI "\-Q " "do not resolve hostnames during ACL processing"
+Do not resolve hostnames to IP addresses during ACL processing.
+.TP
+.BI "\-s " "domainlist"
+Specify a domainname that should be stripped off before
+logging.  Multiple domains may be specified using the colon (``:'')
+separator.
+Please be advised that no sub-domains may be specified but only entire
+domains.  For example if
+.B "\-s north.de"
+is specified and the host logging resolves to satu.infodrom.north.de
+no domain would be cut, you will have to specify two domains like:
+.BR "\-s north.de:infodrom.north.de" .
+.TP
+.B "\-v"
+Print version and exit.
+.TP
+.B "\-w"
+Supress warnings issued when messages are received from non-authorized
+machines (those, that are in no AllowedSender list).
+.TP
+.B "\-x"
+Disable DNS for remote messages.
+.LP
+.SH SIGNALS
+.B Rsyslogd
+reacts to a set of signals.  You may easily send a signal to
+.B rsyslogd
+using the following:
+.IP
+.nf
+kill -SIGNAL $(cat /var/run/syslogd.pid)
+.fi
+.PP
+Note that -SIGNAL must be replaced with the actual signal
+you are trying to send, e.g. with HUP. So it then becomes:
+.IP
+.nf
+kill -HUP $(cat /var/run/syslogd.pid)
+.fi
+.PP
+.TP
+.B HUP
+This lets
+.B rsyslogd
+perform a re-initialization.  All open files are closed, the
+configuration file (default is 
+.IR /etc/rsyslog.conf ")"
+will be reread and the
+.BR rsyslog (3)
+facility is started again.
+.TP
+.B TERM ", " INT ", " QUIT
+.B Rsyslogd
+will die.
+.TP
+.B USR1
+Switch debugging on/off.  This option can only be used if
+.B rsyslogd
+is started with the
+.B "\-d"
+debug option.
+.TP
+.B CHLD
+Wait for childs if some were born, because of wall'ing messages.
+.LP
+.SH 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:
+.IP 1.
+Implement kernel firewalling to limit which hosts or networks have
+access to the 514/UDP socket.
+.IP 2.
+Logging can be directed to an isolated or non-root filesystem which,
+if filled, will not impair the machine.
+.IP 3.
+The ext2 filesystem can be used which can be configured to limit a
+certain percentage of a filesystem to usage by root only.  \fBNOTE\fP
+that this will require rsyslogd to be run as a non-root process.
+\fBALSO NOTE\fP that this will prevent usage of remote logging on the default port since
+rsyslogd will be unable to bind to the 514/UDP socket.
+.IP 4.
+Disabling inet domain sockets will limit risk to the local machine.
+.SS 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 replay recorded messages or spoof a sender's IP address,
+which could lead to a wrong perception of system activity. These can
+be prevented by using GSS-API authentication and encryption. Be sure
+to think about syslog network security before enabling it.
+.LP
+.SH DEBUGGING
+When debugging is turned on using
+.B "\-d"
+option then
+.B rsyslogd
+will be very verbose by writing much of what it does on stdout.
+.SH FILES
+.PD 0
+.TP
+.I /etc/rsyslog.conf
+Configuration file for
+.BR rsyslogd .
+See
+.BR rsyslog.conf (5)
+for exact information.
+.TP
+.I /dev/log
+The Unix domain socket to from where local syslog messages are read.
+.TP
+.I /var/run/rsyslogd.pid
+The file containing the process id of 
+.BR rsyslogd .
+.TP
+.I prefix/lib/rsyslog
+Default directory for
+.B rsyslogd
+modules. The
+.I prefix
+is specified during compilation (e.g. /usr/local).
+.SH ENVIRONMENT
+.TP
+.B RSYSLOG_DEBUG
+Controls runtime debug support.It contains an option string with the
+following options possible (all are case insensitive):
+
+.RS
+.IP LogFuncFlow
+Print out the logical flow of functions (entering and exiting them)
+.IP FileTrace
+Specifies which files to trace LogFuncFlow. If not set (the
+default), a LogFuncFlow trace is provided for all files. Set to
+limit it to the files specified.FileTrace may be specified multiple
+times, one file each (e.g. export RSYSLOG_DEBUG="LogFuncFlow
+FileTrace=vm.c FileTrace=expr.c"
+.IP PrintFuncDB
+Print the content of the debug function database whenever debug
+information is printed (e.g. abort case)!
+.IP PrintAllDebugInfoOnExit
+Print all debug information immediately before rsyslogd exits
+(currently not implemented!)
+.IP PrintMutexAction
+Print mutex action as it happens. Useful for finding deadlocks and
+such.
+.IP NoLogTimeStamp
+Do not prefix log lines with a timestamp (default is to do that).
+.IP NoStdOut
+Do not emit debug messages to stdout. If RSYSLOG_DEBUGLOG is not
+set, this means no messages will be displayed at all.
+.IP Help
+Display a very short list of commands - hopefully a life saver if
+you can't access the documentation...
+.RE
+
+.TP
+.B RSYSLOG_DEBUGLOG
+If set, writes (allmost) all debug message to the specified log file
+in addition to stdout.
+.TP
+.B RSYSLOG_MODDIR
+Provides the default directory in which loadable modules reside.
+.PD
+.SH BUGS
+Please review the file BUGS for up-to-date information on known
+bugs and annouyances.
+.SH Further Information
+Please visit
+.BR http://www.rsyslog.com/doc
+for additional information, tutorials and a support forum.
+.SH SEE ALSO
+.BR rsyslog.conf (5),
+.BR logger (1),
+.BR syslog (2),
+.BR syslog (3),
+.BR services (5),
+.BR savelog (8)
+.LP
+.SH COLLABORATORS
+.B rsyslogd
+is derived from sysklogd sources, which in turn was taken from
+the BSD sources. Special thanks to Greg Wettstein (greg@wind.enjellic.com)
+and Martin Schulze (joey@linux.de) for the fine sysklogd package.
+
+.PD 0
+.TP
+Rainer Gerhards
+.TP
+Adiscon GmbH
+.TP
+Grossrinderfeld, Germany
+.TP
+rgerhards@adiscon.com
+.PD