diff options
Diffstat (limited to 'manual/syslog.texi')
| -rw-r--r-- | manual/syslog.texi | 477 |
1 files changed, 477 insertions, 0 deletions
diff --git a/manual/syslog.texi b/manual/syslog.texi new file mode 100644 index 0000000000..4c190d3239 --- /dev/null +++ b/manual/syslog.texi @@ -0,0 +1,477 @@ +@node Syslog, Mathematics, Low-Level Terminal Interface, Top +@c %MENU% System logging and messaging +@chapter Syslog + + +This chapter describes facilities for issuing and logging messages of +system administration interest. This chapter has nothing to do with +programs issuing messages to their own users or keeping private logs +(One would typically do that with the facilities described in +@ref{I/O on Streams}). + +Most systems have a facility called ``Syslog'' that allows programs to +submit messages of interest to system administrators and can be +configured to pass these messages on in various ways, such as printing +on the console, mailing to a particular person, or recording in a log +file for future reference. + +A program uses the facilities in this chapter to submit such messages. + +@menu +* Overview of Syslog:: Overview of a system's Syslog facility +* Submitting Syslog Messages:: Functions to submit messages to Syslog +@end menu + +@node Overview of Syslog +@section Overview of Syslog + +System administrators have to deal with lots of different kinds of +messages from a plethora of subsystems within each system, and usually +lots of systems as well. For example, an FTP server might report every +connection it gets. The kernel might report hardware failures on a disk +drive. A DNS server might report usage statistics at regular intervals. + +Some of these messages need to be brought to a system administrator's +attention immediately. And it may not be just any system administrator +-- there may be a particular system administrator who deals with a +particular kind of message. Other messages just need to be recorded for +future reference if there is a problem. Still others may need to have +information extracted from them by an automated process that generates +monthly reports. + +To deal with these messages, most Unix systems have a facility called +"Syslog." It is generally based on a daemon called ``Syslogd'' +Syslogd listens for messages on a Unix domain socket named +@file{/dev/log}. Based on classification information in the messages +and its configuration file (usually @file{/etc/syslog.conf}), Syslogd +routes them in various ways. Some of the popular routings are: + +@itemize @bullet +@item +Write to the system console +@item +Mail to a specific user +@item +Write to a log file +@item +Pass to another daemon +@item +Discard +@end itemize + +Syslogd can also handle messages from other systems. It listens on the +@code{syslog} UDP port as well as the local socket for messages. + +Syslog can handle messages from the kernel itself. But the kernel +doesn't write to @file{/dev/log}; rather, another daemon (sometimes +called ``Klogd'') extracts messages from the kernel and passes them on to +Syslog as any other process would (and it properly identifies them as +messages from the kernel). + +Syslog can even handle messages that the kernel issued before Syslogd or +Klogd was running. A Linux kernel, for example, stores startup messages +in a kernel message ring and they are normally still there when Klogd +later starts up. Assuming Syslogd is running by the time Klogd starts, +Klogd then passes everything in the message ring to it. + +In order to classify messages for disposition, Syslog requires any process +that submits a message to it to provide two pieces of classification +information with it: + +@table @asis +@item facility +This identifies who submitted the message. There are a small number of +facilities defined. The kernel, the mail subsystem, and an FTP server +are examples of recognized facilities. For the complete list, +@xref{syslog; vsyslog}. Keep in mind that these are +essentially arbitrary classifications. "Mail subsystem" doesn't have any +more meaning than the system administrator gives to it. + +@item priority +This tells how important the content of the message is. Examples of +defined priority values are: debug, informational, warning, critical. +For the complete list, @xref{syslog; vsyslog}. Except for +the fact that the priorities have a defined order, the meaning of each +of these priorities is entirely determined by the system administrator. + +@end table + +A ``facility/priority'' is a number that indicates both the facility +and the priority. + +@strong{Warning:} This terminology is not universal. Some people use +``level'' to refer to the priority and ``priority'' to refer to the +combination of facility and priority. A Linux kernel has a concept of a +message ``level,'' which corresponds both to a Syslog priority and to a +Syslog facility/priority (It can be both because the facility code for +the kernel is zero, and that makes priority and facility/priority the +same value). + +The GNU C library provides functions to submit messages to Syslog. They +do it by writing to the @file{/dev/log} socket. @xref{Submitting Syslog +Messages}. + +The GNU C library functions only work to submit messages to the Syslog +facility on the same system. To submit a message to the Syslog facility +on another system, use the socket I/O functions to write a UDP datagram +to the @code{syslog} UDP port on that system. @xref{Sockets}. + + +@node Submitting Syslog Messages +@section Submitting Syslog Messages + +The GNU C library provides functions to submit messages to the Syslog +facility: + +@menu +* openlog:: Open connection to Syslog +* syslog; vsyslog:: Submit message to Syslog +* closelog:: Close connection to Syslog +* setlogmask:: Cause certain messages to be ignored +* Syslog Example:: Example of all of the above +@end menu + +These functions only work to submit messages to the Syslog facility on +the same system. To submit a message to the Syslog facility on another +system, use the socket I/O functions to write a UDP datagram to the +@code{syslog} UDP port on that system. @xref{Sockets}. + + + +@node openlog +@subsection openlog + +The symbols referred to in this section are declared in the file +@file{syslog.h}. + +@comment syslog.h +@comment BSD +@deftypefun void openlog (char *@var{ident}, int @var{option}, + int @var{facility}) + +@code{openlog} opens or reopens a connection to Syslog in preparation +for submitting messages. + +@var{ident} is an arbitrary identification string which future +@code{syslog} invocations will prefix to each message. This is intended +to identify the source of the message, and people conventionally set it +to the name of the program that will submit the messages. + +@code{openlog} may or may not open the @file{/dev/log} socket, depending +on @var{option}. If it does, it tries to open it and connect it as a +stream socket. If that doesn't work, it tries to open it and connect it +as a datagram socket. The socket has the ``Close on Exec'' attribute, +so the kernel will close it if the process performs an exec. + +You don't have to use @code{openlog}. If you call @code{syslog} without +having called @code{openlog}, @code{syslog} just opens the connection +implicitly and uses defaults for the information in @var{ident} and +@var{options}. + +@var{options} is a bit string, with the bits as defined by the following +single bit masks: + +@table @code +@item LOG_PERROR +If on, @code{openlog} sets up the connection so that any @code{syslog} +on this connection writes its message to the calling process' Standard +Error stream in addition to submitting it to Syslog. If off, @code{syslog} +does not write the message to Standard Error. + +@item LOG_CONS +If on, @code{openlog} sets up the connection so that a @code{syslog} on +this connection that fails to submit a message to Syslog writes the +message instead to system console. If off, @code{syslog} does not write +to the system console (but of course Syslog may write messages it +receives to the console). + +@item LOG_PID +When on, @code{openlog} sets up the connection so that a @code{syslog} +on this connection inserts the calling process' Process ID (PID) into +the message. When off, @code{openlog} does not insert the PID. + +@item LOG_NDELAY +When on, @code{openlog} opens and connects the @file{/dev/log} socket. +When off, a future @code{syslog} call must open and connect the socket. + +@strong{Portability note:} In early systems, the sense of this bit was +exactly the opposite. + +@item LOG_ODELAY +This bit does nothing. It exists for backward compatibility. + +@end table + +If any other bit in @var{options} is on, the result is undefined. + +@var{facility} is the default facility code for this connection. A +@code{syslog} on this connection that specifies default facility causes +this facility to be associated with the message. See @code{syslog} for +possible values. A value of zero means the default default, which is +@code{LOG_USER}. + +If a Syslog connection is already open when you call @code{openlog}, +@code{openlog} ``reopens'' the connection. Reopening is like opening +except that if you specify zero for the default facility code, the +default facility code simply remains unchanged and if you specify +LOG_NDELAY and the socket is already open and connected, @code{openlog} +just leaves it that way. + +@c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the +@c default log facility to LOG_USER, which means the default default log +@c facility could be whatever the default log facility was for a previous +@c Syslog connection. I have documented what the function should be rather +@c than what it is because I think if anyone ever gets concerned, the code +@c will change. + +@end deftypefun + + +@node syslog; vsyslog +@subsection syslog, vsyslog + +The symbols referred to in this section are declared in the file +@file{syslog.h}. + +@c syslog() is implemented as a call to vsyslog(). +@comment syslog.h +@comment BSD +@deftypefun void syslog (int @var{facility_priority}, char *@var{format}, ...) + +@code{syslog} submits a message to the Syslog facility. It does this by +writing to the Unix domain socket @code{/dev/log}. + +@code{syslog} submits the message with the facility and priority indicated +by @var{facility_priority}. The macro @code{LOG_MAKEPRI} generates a +facility/priority from a facility and a priority, as in the following +example: + +@smallexample +LOG_MAKEPRI(LOG_USER, LOG_WARNING) +@end smallexample + +The possible values for the facility code are (macros): + +@c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means +@c if you try to use it here, just selects default. + +@table @code +@item LOG_USER +A miscellaneous user process +@item LOG_MAIL +Mail +@item LOG_DAEMON +A miscellaneous system daemon +@item LOG_AUTH +Security (authorization) +@item LOG_SYSLOG +Syslog +@item LOG_LPR +Central printer +@item LOG_NEWS +Network news (e.g. Usenet) +@item LOG_UUCP +UUCP +@item LOG_CRON +Cron and At +@item LOG_AUTHPRIV +Private security (authorization) +@item LOG_FTP +Ftp server +@item LOG_LOCAL0 +Locally defined +@item LOG_LOCAL1 +Locally defined +@item LOG_LOCAL2 +Locally defined +@item LOG_LOCAL3 +Locally defined +@item LOG_LOCAL4 +Locally defined +@item LOG_LOCAL5 +Locally defined +@item LOG_LOCAL6 +Locally defined +@item LOG_LOCAL7 +Locally defined +@end table + +Results are undefined if the facility code is anything else. + +@strong{note:} Syslog recognizes one other facility code: that of the +kernel. But you can't specify that facility code with these functions. +If you try, it looks the same to @code{syslog} as if you are requesting +the default facility. But you wouldn't want to anyway, because any +program that uses the GNU C library is not the kernel. + +You can use just a priority code as @var{facility_priority}. In that +case, @code{syslog} assumes the default facility established when the +Syslog connection was opened. @xref{Syslog Example}. + +The possible values for the priority code are (macros): + +@table @code +@item LOG_EMERG +The message says the system is unusable. +@item LOG_ALERT +Action on the message must be taken immediately. +@item LOG_CRIT +The message states a critical condition. +@item LOG_ERR +The message describes an error. +@item LOG_WARNING +The message is a warning. +@item LOG_NOTICE +The message describes a normal but important event. +@item LOG_INFO +The message is purely informational. +@item LOG_DEBUG +The message is only for debugging purposes. +@end table + +Results are undefined if the priority code is anything else. + +If the process does not presently have a Syslog connection open (i.e. +it did not call @code{openlog}), @code{syslog} implicitly opens the +connection the same as @code{openlog} would, with the following defaults +for information that would otherwise be included in an @code{openlog} +call: The default identification string is the program name. The +default default facility is @code{LOG_USER}. The default for all the +connection options in @var{options} is as if those bits were off. +@code{syslog} leaves the Syslog connection open. + +If the @file{dev/log} socket is not open and connected, @code{syslog} +opens and connects it, the same as @code{openlog} with the +@code{LOG_NDELAY} option would. + +@code{syslog} leaves @file{/dev/log} open and connected unless its attempt +to send the message failed, in which case @code{syslog} closes it (with the +hope that a future implicit open will restore the Syslog connection to a +usable state). + +Example: + +@smallexample + +#include <syslog.h> +syslog(LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), + "Unable to make network connection to %s. Error=%m", host); + +@end smallexample + +@end deftypefun + + +@comment syslog.h +@comment BSD +@deftypefun void vsyslog (int @var{facility_priority}, char *@var{format}, + __gnuc_va_list arglist) + +This is functionally identical to @code{syslog}, with the BSD style variable +length argument. + +@end deftypefun + + +@node closelog +@subsection closelog + +The symbols referred to in this section are declared in the file +@file{syslog.h}. + +@comment syslog.h +@comment BSD +@deftypefun void closelog () + +@code{closelog} closes the current Syslog connection, if there is one. +This include closing the @file{dev/log} socket, if it is open. + +There is very little reason to use this function. It does not flush any +buffers; you can reopen a Syslog connection without closing it first; +The connection gets closed automatically on exec or exit. +@code{closelog} has primarily aesthetic value. + +@end deftypefun + + +@node setlogmask +@subsection setlogmask + +The symbols referred to in this section are declared in the file +@file{syslog.h}. + +@comment syslog.h +@comment BSD +@deftypefun int setlogmask (int @var{mask}) + +@code{setlogmask} sets a mask (the ``logmask'') that determines which +future @code{syslog} calls shall be ignored. If a program has not +called @code{setlogmask}, @code{syslog} doesn't ignore any calls. You +can use @code{setlogmask} to specify that messages of particular +priorities shall be ignored in the future. + +A @code{setlogmask} call overrides any previous @code{setlogmask} call. + +Note that the logmask exists entirely independently of opening and +closing of Syslog connections. + +Setting the logmask has a similar effect to, but is not the same as, +configuring Syslog. The Syslog configuration may cause Syslog to +discard certain messages it receives, but the logmask causes certain +messages never to get submitted to Syslog in the first place. + +@var{mask} is a bit string with one bit corresponding to each of the +possible message priorities. If the bit is on, @code{syslog} handles +messages of that priority normally. If it is off, @code{syslog} +discards messages of that priority. Use the message priority macros +described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct +an appropriate @var{mask} value, as in this example: + +@smallexample +LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR) +@end smallexample + +or + +@smallexample +~(LOG_MASK(LOG_INFO)) +@end smallexample + +There is also a @code{LOG_UPTO} macro, which generates a mask with the bits +on for a certain priority and all priorities above it: + +@smallexample +LOG_UPTO(LOG_ERROR) +@end smallexample + +The unfortunate naming of the macro is due to the fact that internally, +higher numbers are used for lower message priorities. + +@end deftypefun + + +@node Syslog Example +@subsection Syslog Example + +Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}: + +This example sets the logmask so that debug and informational messages +get discarded without ever reaching Syslog. So the second @code{syslog} +in the example does nothing. + +@smallexample +#include <syslog.h> + +setlogmask(LOG_UPTO(LOG_NOTICE)); + +openlog("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1); + +syslog(LOG_NOTICE, "Program started by User %d", getuid()); +syslog(LOG_INFO, "A tree falls in a forest"); + +closelog(); + +@end smallexample + + + |