From ee2c14934a587ba105e50fec4bbf532e9941828f Mon Sep 17 00:00:00 2001 From: Ben Gras Date: Mon, 3 Apr 2006 14:59:52 +0000 Subject: [PATCH] syslog related manpages --- man/man1/logger.1 | 101 +++++++++++++++++ man/man3/syslog.3 | 198 +++++++++++++++++++++++++++++++++ man/man5/syslog.conf.5 | 246 +++++++++++++++++++++++++++++++++++++++++ man/man8/syslogd.8 | 211 +++++++++++++++++++++++++++++++++++ 4 files changed, 756 insertions(+) create mode 100644 man/man1/logger.1 create mode 100644 man/man3/syslog.3 create mode 100644 man/man5/syslog.conf.5 create mode 100644 man/man8/syslogd.8 diff --git a/man/man1/logger.1 b/man/man1/logger.1 new file mode 100644 index 000000000..ea80aa190 --- /dev/null +++ b/man/man1/logger.1 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)logger.1 8.1 (Berkeley) 6/6/93 +.\" Modified for Minix porting by G. Falzoni +.\" $Id$ +.\" +.\" Local macros +.de Xr +.BR \\$1 (\\$2)\\$3 +.. +.de LB +.TP \\$1 +\\fB\\$2\\fR +\\$3 +.. +.de LI +.TP \\$1 +\\fI\\$2\\fR +\\$3 +.. +.de LR +.TP \\$1 +\\fR\\$2\\fR +\\$3 +.. +.\" end local macros +.DD June 6, 1993 +.TH LOGGER 1 "Jan. 18, 2000" +.\" Os BSD 4.3 +.SH NAME +logger \- make entries in the system log +.SH SYNOPSIS +logger +.RB [ \-i ] +.RB [ \-f " " file ] +.RB [ \-p " " pri ] +.RB [ \-t " " tag ] +.B message ... +.SH DESCRIPTION +Logger provides a shell command interface to the +.Xr syslog 3 +system log module. +.PP +The following options are available to control message formatting: +.PP +.LB 9 -i "Log the process id of the logger process with each line." +.\" LB 9 -s "Log the message to standard error, as well as the system log." +.LB 9 "-f file" "Log the specified file." +.LB 9 "-p pri" "Enter the message with the specified priority. +The priority may be specified numerically or as a `facility.level' +pair. For example, `\-p local3.info' logs the message(s) as +.BR info rmational +level in the +.B local3 +facility. The default is `user.notice'. +.LB 9 "-t tag" "Mark every line in the log with the specified +.BR tag . +.LB 9 message "Write the message to log. If not specified, and the" +.B \-f +flag is not provided, standard input is logged. +.PP +The logger utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +.PP +logger System rebooted +.PP +logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc +.SH SEE ALSO +.Xr syslog 3 , +.Xr syslogd 8 . +.SH STANDARDS +The logger command is expected to be IEEE Std1003.2 (`POSIX') compatible. diff --git a/man/man3/syslog.3 b/man/man3/syslog.3 new file mode 100644 index 000000000..9441df618 --- /dev/null +++ b/man/man3/syslog.3 @@ -0,0 +1,198 @@ +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" from SYSLOG 3 "15 Feb 1994" "Linux" "Linux Programmer's Manual" +.\" Modified for Minix porting by G. Falzoni +.\" $Id$ +.\" +.\" Local macros +.de Xr +.BR \\$1 (\\$2)\\$3 +.. +.de LB +.TP \\$1 +\\fB\\$2\\fR +\\$3 +.. +.de LI +.TP \\$1 +\\fI\\$2\\fR +\\$3 +.. +.de LR +.TP \\$1 +\\fR\\$2\\fR +\\$3 +.. +.\" end local macros +.TH SYSLOG 3 "Jan. 18, 2000" +.SH NAME +openlog, syslog, closelog \- send messages to the system logger +.SH SYNOPSIS +.B #include +.sp +.BI "void openlog(char " *ident ", int " option ", int " facility) +.sp +.BI "void syslog(int " priority ", char " *format ", ...)" +.sp +.BI "void closelog(void)" +.sp +.SH DESCRIPTION +.B openlog() +opens a connection to the system logger for a program. The string pointed to by +.I ident +is added to each message, and is typically set to the program name. Values for +.I option +and +.I facility +are given in the next section. Its use is optional. It will automatically be called by +.B syslog() +if necessary, in which case +.I ident +will default to "syslog". +.sp +.B syslog() +generates a log message, which will be distributed by +.Xr syslogd 8 . +.I priority +is a combination of the +.I facility +and the +.IR level , +values for which are given in the next section. The remaining arguments +are a +.IR format , +as in +.Xr printf 3 +and any arguments required by the +.IR format . +.\" except that the two character %m will be replaced by the error message string +.\" RI ( strerror ) +.\" corresponding to the present value of +.\" IR errno . +.sp +.B closelog() +closes the descriptor being used to write to the system logger. Its use is optional. +.SH "PARAMETERS" +This section lists the parameters used to set the values of +.IR option , " facility" ", and " priority . +.SS option +The +.I option +argument to +.B openlog() +is an OR of any of these: +.TP +.B LOG_CONS +write directly to system console if there is an error while sending to +system logger +.TP +.B LOG_NDELAY +open the connection immediately (normally, the connection is opened when +the first message is logged) +.TP +.B LOG_PERROR +print to stderr as well +.TP +.B LOG_PID +include PID with each message +.SS facility +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP +.B LOG_AUTH +security/authorization messages (DEPRECATED Use +.B LOG_AUTHPRIV +instead) +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +other system daemons +.TP +.B LOG_KERN +kernel messages +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.B syslogd +.TP +.BR LOG_USER (default) +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem +.SS level +This determines the importance of the message. The levels are, in order +of decreasing importance: +.TP +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.SH HISTORY +A +.B syslog +function call appeared in BSD 4.2. +.SH SEE ALSO +.Xr logger 1 , +.Xr syslog.conf 5 , +.Xr syslogd 8 . diff --git a/man/man5/syslog.conf.5 b/man/man5/syslog.conf.5 new file mode 100644 index 000000000..3d2f91bb1 --- /dev/null +++ b/man/man5/syslog.conf.5 @@ -0,0 +1,246 @@ +.\" syslog.conf - syslogd(8) configuration file +.\" Copyright (c) 1995 Martin Schulze +.\" Modified for Minix porting by G. Falzoni +.\" $Id$ +.\" +.\" This file is part of the sysklogd package, a kernel and system log daemon. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. +.\" +.\" Local macros +.de Xr +.BR \\$1 (\\$2)\\$3 +.. +.de LB +.TP \\$1 +\\fB\\$2\\fR +\\$3 +.. +.de LI +.TP \\$1 +\\fI\\$2\\fR +\\$3 +.. +.de LR +.TP \\$1 +\\fR\\$2\\fR +\\$3 +.. +.\" end local macros +.TH SYSLOG.CONF 5 "1 January 1998" +.SH NAME +syslog.conf \- syslogd(8) configuration file +.SH DESCRIPTION +The +.I syslog.conf +file is the main configuration file for the +.Xr syslogd 8 +which logs system messages on *nix systems. This file specifies rules +for logging. For special features see the +.Xr syslogd 8 +manpage. +Every rule consists of two fields, a +.I selector +field and an +.I action +field. These two fields are separated by one or more tabs. +The selector field specifies a pattern of facilities and +priorities belonging to the specified action. +Lines starting with a hash mark (``#'') and empty lines are ignored. +.SH SELECTORS +The selector field itself again consists of two parts, a +.I facility +and a +.IR 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 +.BR syslog (3). +The names mentioned below correspond to the similar +.BR LOG_ -values +in +.IR /usr/include/syslog.h . +The +.I facility +is one of the following keywords: +.BR auth ", " authpriv ", " cron ", " daemon ", " kern ", " lpr ", " +.BR mail ", " mark ", " news ", " security " (same as " auth "), " +.BR syslog ", " user ", " uucp " and " local0 " through " local7 . +The keyword +.B security +should not be used anymore and +.B 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 +.I facility +specifies the subsystem that produced the message, i.e. all mail +programs log with the mail facility +.BR "" ( LOG_MAIL ) +if they log using syslog. + +The +.I priority +is one of the following keywords, in ascending order: +.BR debug ", " info ", " notice ", " warning ", " warn " (same as " +.BR warning "), " err ", " error " (same as " err "), " crit ", " +.BR alert ", " emerg ", " panic " (same as " emerg ). +The keywords +.BR error ", " warn " and " panic +are deprecated and should not be used anymore. The +.I priority +defines the severity of the message +.PP +The behavior of the original BSD syslogd is that all messages of the +specified priority and higher are logged according to the given +action. This +.BR syslogd (8) +behaves the same, but has some extensions. +.PP +In addition to the above mentioned names the +.BR syslogd (8) +understands the following extensions: +.LB 5 "*" "An asterisk (``*'') before the period stands for all facilities. +.LB 5 "none" "The keyword none stands for no priority of the given facility. +.PP +Multiple selectors may be specified for a single +.I action +using the semicolon (``;'') separator. Remember that each selector in +the +.I selector +field is capable to overwrite the preceding ones. Using this +behavior you can exclude some priorities from the pattern. +.SH ACTIONS +The action field of a rule describes the abstract term +``logfile''. A ``logfile'' need not to be a real file, btw. The +.Xr syslogd 8 +provides the following actions. +.SS Regular File +Typically messages are logged to real files. The file has to be +specified with full pathname, beginning with a slash ``/''. +.SS Terminal and Console +If the file you specified is a tty, special tty-handling is done, same +with +.IR /dev/console . +.SS Remote Machine +This release does not implement +remote logging, i.e. the ability to send messages to a remote host running +.Xr syslogd 8 . +To forward messages to another host, prepend the hostname +with the at sign (``@''). +.SS List of Users +Usually critical messages are also directed to ``root'' on that +machine. You can specify a list of users that shall get the message by +simply writing the login. You may specify more than one user by +separating them with commas (``,''). If they're logged in they +get the message. Don't think a mail would be sent, that might be too +late. +.SS Everyone logged on +Emergency messages often go to all users currently online to notify +them that something strange is happening with the system. To specify +this +.IR wall (1)-feature +use an asterisk (``*''). +.SH EXAMPLES +Here are some example, partially taken from a real existing site and +configuration. Hopefully they rub out all questions to the +configuration, if not, drop me (Joey) a line. +.IP +.nf +# Store critical stuff in critical +# +*.crit /var/adm/critical +.fi +.LP +This will store all messages with the priority +.B crit +in the file +.IR /var/adm/critical . +.IP +.nf +# The tcp wrapper loggs with mail.info, we display +# all the connections on tty12 +# +mail.info /dev/tty12 +.fi +.LP +This directs all messages that uses +.BR mail.info " (in source " LOG_MAIL " | " LOG_INFO ) +to +.IR /dev/tty12 , +the 12th console. +.IP +.nf +# Log all mail.info and news.info messages to info +# +mail,news.info /var/adm/info +.fi +.LP +This will extract all messages that come either with +.BR mail.info " or with " news.info +and store them in the file +.IR /var/adm/info . +.IP +.nf +# Emergency messages will be displayed using wall +# +*.emerg * +.fi +.LP +This rule tells the +.B syslogd +to write all emergency messages to all currently logged in users. This +is the wall action. +.IP +.nf +# Messages of the priority alert will be directed +# to the operator +# +*.alert root,joey +.fi +.LP +This rule directs all messages with a priority of +.B alert +or higher to the terminals of the operator, i.e. of the users ``root'' +and ``joey'' if they're logged in. +.IP +.nf +*.* @finlandia +.fi +.LP +This rule would redirect all messages to a remote host called +finlandia. This is useful especially in a cluster of machines where +all syslog messages will be stored on only one machine. +.SH FILES +.I /etc/syslog.conf +Configuration file for +.B syslogd +.SH BUGS +The effects of multiple selectors are sometimes not intuitive. For +example ``mail.crit,*.err'' will select ``mail'' facility messages at +the level of ``err'' or higher, not at the level of ``crit'' or +higher. + +.SH SEE ALSO +.BR syslogd (8), +.BR logger (1), +.BR syslog (3) +.SH AUTHORS +The +.B syslogd +is taken from BSD sources, Greg Wettstein (greg@wind.rmcc.com) +performed the port to Linux, Martin Schulze (joey@linux.de) +made some bugfixes and added some new features. diff --git a/man/man8/syslogd.8 b/man/man8/syslogd.8 new file mode 100644 index 000000000..02e591360 --- /dev/null +++ b/man/man8/syslogd.8 @@ -0,0 +1,211 @@ +.\" Copyright 1994 Dr. Greg Wettstein, Enjellic Systems Development. +.\" May be distributed under the GNU General Public License +.\" Sun Aug 30 11:35:55 MET: Martin Schulze: Updates +.\" +.\" from SYSKLOGD 8 "13 December 1995" "Version 1.3" "Linux System Administration" +.\" Modified for Minix porting by G. Falzoni +.\" $Id$ +.\" +.\" Local macros +.de Xr +.BR \\$1 (\\$2)\\$3 +.. +.de LB +.TP \\$1 +\\fB\\$2\\fR +\\$3 +.. +.de LI +.TP \\$1 +\\fI\\$2\\fR +\\$3 +.. +.de LR +.TP \\$1 +\\fR\\$2\\fR +\\$3 +.. +.\" end local macros +.TH SYSLOGD 8 "Jan. 23, 2000" +.SH NAME +.PP +syslogd \- system logging daemon. +.SH SYNOPSIS +.PP +.B syslogd +.RB [ " \-d " ] +.RB [ " \-f " +.I config file +] +.RB [ " \-m " +.I interval +] +.RB [ " \-p" +.IB port +] +.RB [ " \-v " ] +.LP +.SH DESCRIPTION +.PP +System logging is provided by a version of +.BR syslogd (8) +derived from the +stock BSD sources. +.B Syslogd +provides the kind of logging that many modern programs use. Every logged +message contains at least a time, a hostname field and a +program name field, but that depends on how trusty the logging +program is. +.PP +While the syslogd sources have been heavily modified a couple of notes +are necessary. First of all there has been a systematic attempt to +insure that syslogd follows the default, standard BSD behavior. +The second important concept to note is that this version of syslogd +interacts transparently with the version of syslog found in the +standard libraries, so you must insure that the correct versions are installed. +.PP +The main configuration file +.I /etc/syslog.conf +or an alternative file, given with the +.B "\-f" +option, is read at startup. Any line that begins with the hash mark +(``#'') and empty lines are ignored. If an error occurs during parsing +the whole line is ignored. +.SH OPTIONS +.PP +.LB 9 "-d" "Turns on debug mode. +When using debug mode, the daemon will not proceed to +.BR fork (2) +to set itself in the background, but will stay in the +foreground and write much debug information on the current tty. See the +DEBUGGING section for more information. +.LB 9 "\-f config file" "Specify an alternative configuration file instead of +.IR /etc/syslog.conf "," +which is the default. +.LB 9 "\-m interval" "The syslogd logs a mark timestamp regularly. The default +.I interval +between two +.I \-\- MARK \-\- +lines is 20 minutes. This can be changed with this option. +.LB 9 "\-p port" "You can specify an alternative port instead of +.I syslog/udp +default service. +.LB 9 "\-v" "Print version and exit. +.SH SIGNALS +.PP +.B Syslogd +reacts to a set of signals. You may easily send a signal to it +using the following: +.IP +kill -SIGNAL `cat /usr/run/syslogd.pid` +.LB 9 SIGHUP "This lets syslogd perform a re-initialization. +All open files are closed, the configuration file (default +is '/etc/syslog.conf') will be reread. +.LB 9 SIGTERM "The syslogd will die. +.LB 9 "SIGINT SIGQUIT" "If debugging is enabled these are ignored, otherwise +syslogd will die. +.LB 9 SIGALRM "Every time syslogd receives this signal it will log +the mark line. Normally this is done by +.Xr alarm 2 . +.SH CONFIGURATION FILE SYNTAX DIFFERENCES +.PP +.B Syslogd +uses a slightly different syntax for its configuration file than +the original BSD sources. Originally all messages of a specific priority +and above were forwarded to the log file. +.PP +For example see the following sample file +.IP +## Sample syslog.conf + +## Emergency messages (system may be unusable) +.br +*.emerg * +.br +*.alert /dev/log + +## High severity errors +.br +*.alert;*.crit /usr/adm/syslog + +## every other message (errors/warning and informational) +.br +*.info;*.notice;*.warning;*.err /usr/adm/messages +.br +*.debug /usr/adm/debug + +.SH SUPPORT FOR REMOTE LOGGING +.PP +Not implemented. +.SH OUTPUT TO NAMED PIPES (FIFOs) +.PP +Not implemented. +.SH INSTALLATION CONCERNS +.PP +There is probably one important consideration when installing this +version of syslogd. This version of syslogd is dependent on proper +formatting of messages by the syslog function. +.PP +.B Syslogd +should be started by the rc sequence. +.SH DEBUGGING +.PP +When debugging is turned on using +.B "\-d" +option and syslogd is compiled with debug=1 then syslogd +will be very verbose by writing much of what it does on stdout. +Whenever +the configuration file is reread and re-parsed you'll see a tabular, +corresponding to the internal data structure. This tabular consists of +four fields: +.TP +.I number +This field contains a serial number starting by zero. This number +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 +.IR /etc/syslog.conf . +.TP +.I pattern +This field is tricky and represents the internal structure +exactly. Every column stands for a facility (refer to +.BR syslog (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 +.BR syslog (3)). +.TP +.I action +This field describes the particular action that takes place whenever a +message is received that matches the pattern. Refer to the +.BR syslog.conf (5) +manpage for all possible actions. +.TP +.I 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-logging this is the +used console; for tty-logging this is the specified tty; wall has no +additional arguments. +.PP +Note that if syslogd is compiled with debug=0 only a subset is printed. +.SH FILES +.PP +.LR 28 /etc/syslog.conf "Configuration file for syslogd. See +.Xr syslog.conf 5 +for exact information. +.LR 28 /dev/log "The log device (console) for Minix. +.LR 28 /usr/run/syslogd.pid "The file containing the process id of syslogd. +.SH BUGS +.PP +If an error occurs in one line the whole rule is ignored. +.B Syslogd +doesn't change the filemode of opened logfiles at any stage of +process. If a file is created it is world readable. If you want to +avoid this, you have to create it and change permissions on your own. +.SH SEE ALSO +.BR syslog.conf (5), +.BR logger (1), +.BR syslog (3). +.\" .BR services (5), -- 2.44.0