1: @node Syslog, Mathematics, Low-Level Terminal Interface, Top
    2: @c %MENU% System logging and messaging
    3: @chapter Syslog
    4: 
    5: 
    6: This chapter describes facilities for issuing and logging messages of
    7: system administration interest.  This chapter has nothing to do with
    8: programs issuing messages to their own users or keeping private logs
    9: (One would typically do that with the facilities described in
   10: @ref{I/O on Streams}).
   11: 
   12: Most systems have a facility called ``Syslog'' that allows programs to
   13: submit messages of interest to system administrators and can be
   14: configured to pass these messages on in various ways, such as printing
   15: on the console, mailing to a particular person, or recording in a log
   16: file for future reference.
   17: 
   18: A program uses the facilities in this chapter to submit such messages.
   19: 
   20: @menu
   21: * Overview of Syslog::           Overview of a system's Syslog facility
   22: * Submitting Syslog Messages::   Functions to submit messages to Syslog
   23: @end menu
   24: 
   25: @node Overview of Syslog
   26: @section Overview of Syslog
   27: 
   28: System administrators have to deal with lots of different kinds of
   29: messages from a plethora of subsystems within each system, and usually
   30: lots of systems as well.  For example, an FTP server might report every
   31: connection it gets.  The kernel might report hardware failures on a disk
   32: drive.  A DNS server might report usage statistics at regular intervals.
   33: 
   34: Some of these messages need to be brought to a system administrator's
   35: attention immediately.  And it may not be just any system administrator
   36: -- there may be a particular system administrator who deals with a
   37: particular kind of message.  Other messages just need to be recorded for
   38: future reference if there is a problem.  Still others may need to have
   39: information extracted from them by an automated process that generates
   40: monthly reports.
   41: 
   42: To deal with these messages, most Unix systems have a facility called
   43: "Syslog."  It is generally based on a daemon called ``Syslogd''
   44: Syslogd listens for messages on a Unix domain socket named
   45: @file{/dev/log}.  Based on classification information in the messages
   46: and its configuration file (usually @file{/etc/syslog.conf}), Syslogd
   47: routes them in various ways.  Some of the popular routings are:
   48: 
   49: @itemize @bullet
   50: @item
   51: Write to the system console
   52: @item
   53: Mail to a specific user
   54: @item
   55: Write to a log file
   56: @item
   57: Pass to another daemon
   58: @item
   59: Discard
   60: @end itemize
   61: 
   62: Syslogd can also handle messages from other systems.  It listens on the
   63: @code{syslog} UDP port as well as the local socket for messages.
   64: 
   65: Syslog can handle messages from the kernel itself.  But the kernel
   66: doesn't write to @file{/dev/log}; rather, another daemon (sometimes
   67: called ``Klogd'') extracts messages from the kernel and passes them on to
   68: Syslog as any other process would (and it properly identifies them as
   69: messages from the kernel).
   70: 
   71: Syslog can even handle messages that the kernel issued before Syslogd or
   72: Klogd was running.  A Linux kernel, for example, stores startup messages
   73: in a kernel message ring and they are normally still there when Klogd
   74: later starts up.  Assuming Syslogd is running by the time Klogd starts,
   75: Klogd then passes everything in the message ring to it.
   76: 
   77: In order to classify messages for disposition, Syslog requires any process
   78: that submits a message to it to provide two pieces of classification
   79: information with it:
   80: 
   81: @table @asis
   82: @item facility
   83: This identifies who submitted the message.  There are a small number of
   84: facilities defined.  The kernel, the mail subsystem, and an FTP server
   85: are examples of recognized facilities.  For the complete list,
   86: @xref{syslog; vsyslog}.  Keep in mind that these are
   87: essentially arbitrary classifications.  "Mail subsystem" doesn't have any
   88: more meaning than the system administrator gives to it.
   89: 
   90: @item priority
   91: This tells how important the content of the message is.  Examples of
   92: defined priority values are: debug, informational, warning, critical.
   93: For the complete list, @xref{syslog; vsyslog}.  Except for
   94: the fact that the priorities have a defined order, the meaning of each
   95: of these priorities is entirely determined by the system administrator.
   96: 
   97: @end table
   98: 
   99: A ``facility/priority'' is a number that indicates both the facility
  100: and the priority.
  101: 
  102: @strong{Warning:} This terminology is not universal.  Some people use
  103: ``level'' to refer to the priority and ``priority'' to refer to the
  104: combination of facility and priority.  A Linux kernel has a concept of a
  105: message ``level,'' which corresponds both to a Syslog priority and to a
  106: Syslog facility/priority (It can be both because the facility code for
  107: the kernel is zero, and that makes priority and facility/priority the
  108: same value).
  109: 
  110: The GNU C library provides functions to submit messages to Syslog.  They
  111: do it by writing to the @file{/dev/log} socket.  @xref{Submitting Syslog
  112: Messages}.
  113: 
  114: The GNU C library functions only work to submit messages to the Syslog
  115: facility on the same system.  To submit a message to the Syslog facility
  116: on another system, use the socket I/O functions to write a UDP datagram
  117: to the @code{syslog} UDP port on that system.  @xref{Sockets}.
  118: 
  119: 
  120: @node Submitting Syslog Messages
  121: @section Submitting Syslog Messages
  122: 
  123: The GNU C library provides functions to submit messages to the Syslog
  124: facility:
  125: 
  126: @menu
  127: * openlog::                      Open connection to Syslog
  128: * syslog; vsyslog::              Submit message to Syslog
  129: * closelog::                     Close connection to Syslog
  130: * setlogmask::                   Cause certain messages to be ignored
  131: * Syslog Example::               Example of all of the above
  132: @end menu
  133: 
  134: These functions only work to submit messages to the Syslog facility on
  135: the same system.  To submit a message to the Syslog facility on another
  136: system, use the socket I/O functions to write a UDP datagram to the
  137: @code{syslog} UDP port on that system.  @xref{Sockets}.
  138: 
  139: 
  140: 
  141: @node openlog
  142: @subsection openlog
  143: 
  144: The symbols referred to in this section are declared in the file
  145: @file{syslog.h}.
  146: 
  147: @comment syslog.h
  148: @comment BSD
  149: @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility})
  150: 
  151: @code{openlog} opens or reopens a connection to Syslog in preparation
  152: for submitting messages.
  153: 
  154: @var{ident} is an arbitrary identification string which future
  155: @code{syslog} invocations will prefix to each message.  This is intended
  156: to identify the source of the message, and people conventionally set it
  157: to the name of the program that will submit the messages.
  158: 
  159: If @var{ident} is NULL, or if @code{openlog} is not called, the default
  160: identification string used in Syslog messages will be the program name,
  161: taken from argv[0].
  162: 
  163: Please note that the string pointer @var{ident} will be retained
  164: internally by the Syslog routines.  You must not free the memory that
  165: @var{ident} points to.  It is also dangerous to pass a reference to an
  166: automatic variable since leaving the scope would mean ending the
  167: lifetime of the variable.  If you want to change the @var{ident} string,
  168: you must call @code{openlog} again; overwriting the string pointed to by
  169: @var{ident} is not thread-safe.
  170: 
  171: You can cause the Syslog routines to drop the reference to @var{ident} and
  172: go back to the default string (the program name taken from argv[0]), by
  173: calling @code{closelog}: @xref{closelog}.
  174: 
  175: In particular, if you are writing code for a shared library that might get
  176: loaded and then unloaded (e.g. a PAM module), and you use @code{openlog},
  177: you must call @code{closelog} before any point where your library might
  178: get unloaded, as in this example:
  179: 
  180: @smallexample
  181: #include <syslog.h>
  182: 
  183: void
  184: shared_library_function (void)
  185: @{
  186:   openlog ("mylibrary", option, priority);
  187: 
  188:   syslog (LOG_INFO, "shared library has been invoked");
  189: 
  190:   closelog ();
  191: @}
  192: @end smallexample
  193: 
  194: Without the call to @code{closelog}, future invocations of @code{syslog}
  195: by the program using the shared library may crash, if the library gets
  196: unloaded and the memory containing the string @code{"mylibrary"} becomes
  197: unmapped.  This is a limitation of the BSD syslog interface.
  198: 
  199: @code{openlog} may or may not open the @file{/dev/log} socket, depending
  200: on @var{option}.  If it does, it tries to open it and connect it as a
  201: stream socket.  If that doesn't work, it tries to open it and connect it
  202: as a datagram socket.  The socket has the ``Close on Exec'' attribute,
  203: so the kernel will close it if the process performs an exec.
  204: 
  205: You don't have to use @code{openlog}.  If you call @code{syslog} without
  206: having called @code{openlog}, @code{syslog} just opens the connection
  207: implicitly and uses defaults for the information in @var{ident} and
  208: @var{options}.
  209: 
  210: @var{options} is a bit string, with the bits as defined by the following
  211: single bit masks:
  212: 
  213: @table @code
  214: @item LOG_PERROR
  215: If on, @code{openlog} sets up the connection so that any @code{syslog}
  216: on this connection writes its message to the calling process' Standard
  217: Error stream in addition to submitting it to Syslog.  If off, @code{syslog}
  218: does not write the message to Standard Error.
  219: 
  220: @item LOG_CONS
  221: If on, @code{openlog} sets up the connection so that a @code{syslog} on
  222: this connection that fails to submit a message to Syslog writes the
  223: message instead to system console.  If off, @code{syslog} does not write
  224: to the system console (but of course Syslog may write messages it
  225: receives to the console).
  226: 
  227: @item LOG_PID
  228: When on, @code{openlog} sets up the connection so that a @code{syslog}
  229: on this connection inserts the calling process' Process ID (PID) into
  230: the message.  When off, @code{openlog} does not insert the PID.
  231: 
  232: @item LOG_NDELAY
  233: When on, @code{openlog} opens and connects the @file{/dev/log} socket.
  234: When off, a future @code{syslog} call must open and connect the socket.
  235: 
  236: @strong{Portability note:}  In early systems, the sense of this bit was
  237: exactly the opposite.
  238: 
  239: @item LOG_ODELAY
  240: This bit does nothing.  It exists for backward compatibility.
  241: 
  242: @end table
  243: 
  244: If any other bit in @var{options} is on, the result is undefined.
  245: 
  246: @var{facility} is the default facility code for this connection.  A
  247: @code{syslog} on this connection that specifies default facility causes
  248: this facility to be associated with the message.  See @code{syslog} for
  249: possible values.  A value of zero means the default default, which is
  250: @code{LOG_USER}.
  251: 
  252: If a Syslog connection is already open when you call @code{openlog},
  253: @code{openlog} ``reopens'' the connection.  Reopening is like opening
  254: except that if you specify zero for the default facility code, the
  255: default facility code simply remains unchanged and if you specify
  256: LOG_NDELAY and the socket is already open and connected, @code{openlog}
  257: just leaves it that way.
  258: 
  259: @c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the
  260: @c default log facility to LOG_USER, which means the default default log
  261: @c facility could be whatever the default log facility was for a previous
  262: @c Syslog connection.  I have documented what the function should be rather
  263: @c than what it is because I think if anyone ever gets concerned, the code
  264: @c will change.
  265: 
  266: @end deftypefun
  267: 
  268: 
  269: @node syslog; vsyslog
  270: @subsection syslog, vsyslog
  271: 
  272: The symbols referred to in this section are declared in the file
  273: @file{syslog.h}.
  274: 
  275: @c syslog() is implemented as a call to vsyslog().
  276: @comment syslog.h
  277: @comment BSD
  278: @deftypefun void syslog (int @var{facility_priority}, char *@var{format}, ...)
  279: 
  280: @code{syslog} submits a message to the Syslog facility.  It does this by
  281: writing to the Unix domain socket @code{/dev/log}.
  282: 
  283: @code{syslog} submits the message with the facility and priority indicated
  284: by @var{facility_priority}.  The macro @code{LOG_MAKEPRI} generates a
  285: facility/priority from a facility and a priority, as in the following
  286: example:
  287: 
  288: @smallexample
  289: LOG_MAKEPRI(LOG_USER, LOG_WARNING)
  290: @end smallexample
  291: 
  292: The possible values for the facility code are (macros):
  293: 
  294: @c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means
  295: @c if you try to use it here, just selects default.
  296: 
  297: @vtable @code
  298: @item LOG_USER
  299: A miscellaneous user process
  300: @item LOG_MAIL
  301: Mail
  302: @item LOG_DAEMON
  303: A miscellaneous system daemon
  304: @item LOG_AUTH
  305: Security (authorization)
  306: @item LOG_SYSLOG
  307: Syslog
  308: @item LOG_LPR
  309: Central printer
  310: @item LOG_NEWS
  311: Network news (e.g. Usenet)
  312: @item LOG_UUCP
  313: UUCP
  314: @item LOG_CRON
  315: Cron and At
  316: @item LOG_AUTHPRIV
  317: Private security (authorization)
  318: @item LOG_FTP
  319: Ftp server
  320: @item LOG_LOCAL0
  321: Locally defined
  322: @item LOG_LOCAL1
  323: Locally defined
  324: @item LOG_LOCAL2
  325: Locally defined
  326: @item LOG_LOCAL3
  327: Locally defined
  328: @item LOG_LOCAL4
  329: Locally defined
  330: @item LOG_LOCAL5
  331: Locally defined
  332: @item LOG_LOCAL6
  333: Locally defined
  334: @item LOG_LOCAL7
  335: Locally defined
  336: @end vtable
  337: 
  338: Results are undefined if the facility code is anything else.
  339: 
  340: @strong{note:} @code{syslog} recognizes one other facility code: that of
  341: the kernel.  But you can't specify that facility code with these
  342: functions.  If you try, it looks the same to @code{syslog} as if you are
  343: requesting the default facility.  But you wouldn't want to anyway,
  344: because any program that uses the GNU C library is not the kernel.
  345: 
  346: You can use just a priority code as @var{facility_priority}.  In that
  347: case, @code{syslog} assumes the default facility established when the
  348: Syslog connection was opened.  @xref{Syslog Example}.
  349: 
  350: The possible values for the priority code are (macros):
  351: 
  352: @vtable @code
  353: @item LOG_EMERG
  354: The message says the system is unusable.
  355: @item LOG_ALERT
  356: Action on the message must be taken immediately.
  357: @item LOG_CRIT
  358: The message states a critical condition.
  359: @item LOG_ERR
  360: The message describes an error.
  361: @item LOG_WARNING
  362: The message is a warning.
  363: @item LOG_NOTICE
  364: The message describes a normal but important event.
  365: @item LOG_INFO
  366: The message is purely informational.
  367: @item LOG_DEBUG
  368: The message is only for debugging purposes.
  369: @end vtable
  370: 
  371: Results are undefined if the priority code is anything else.
  372: 
  373: If the process does not presently have a Syslog connection open (i.e.,
  374: it did not call @code{openlog}), @code{syslog} implicitly opens the
  375: connection the same as @code{openlog} would, with the following defaults
  376: for information that would otherwise be included in an @code{openlog}
  377: call: The default identification string is the program name.  The
  378: default default facility is @code{LOG_USER}.  The default for all the
  379: connection options in @var{options} is as if those bits were off.
  380: @code{syslog} leaves the Syslog connection open.
  381: 
  382: If the @file{dev/log} socket is not open and connected, @code{syslog}
  383: opens and connects it, the same as @code{openlog} with the
  384: @code{LOG_NDELAY} option would.
  385: 
  386: @code{syslog} leaves @file{/dev/log} open and connected unless its attempt
  387: to send the message failed, in which case @code{syslog} closes it (with the
  388: hope that a future implicit open will restore the Syslog connection to a
  389: usable state).
  390: 
  391: Example:
  392: 
  393: @smallexample
  394: 
  395: #include <syslog.h>
  396: syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
  397:         "Unable to make network connection to %s.  Error=%m", host);
  398: 
  399: @end smallexample
  400: 
  401: @end deftypefun
  402: 
  403: 
  404: @comment syslog.h
  405: @comment BSD
  406: @deftypefun void vsyslog (int @var{facility_priority}, char *@var{format}, va_list arglist)
  407: 
  408: This is functionally identical to @code{syslog}, with the BSD style variable
  409: length argument.
  410: 
  411: @end deftypefun
  412: 
  413: 
  414: @node closelog
  415: @subsection closelog
  416: 
  417: The symbols referred to in this section are declared in the file
  418: @file{syslog.h}.
  419: 
  420: @comment syslog.h
  421: @comment BSD
  422: @deftypefun void closelog (void)
  423: 
  424: @code{closelog} closes the current Syslog connection, if there is one.
  425: This includes closing the @file{dev/log} socket, if it is open.
  426: @code{closelog} also sets the identification string for Syslog messages
  427: back to the default, if @code{openlog} was called with a non-NULL argument
  428: to @var{ident}.  The default identification string is the program name
  429: taken from argv[0].
  430: 
  431: If you are writing shared library code that uses @code{openlog} to
  432: generate custom syslog output, you should use @code{closelog} to drop the
  433: GNU C library's internal reference to the @var{ident} pointer when you are
  434: done.  Please read the section on @code{openlog} for more information:
  435: @xref{openlog}.
  436: 
  437: @code{closelog} does not flush any buffers.  You do not have to call
  438: @code{closelog} before re-opening a Syslog connection with @code{initlog}.
  439: Syslog connections are automatically closed on exec or exit.
  440: 
  441: @end deftypefun
  442: 
  443: 
  444: @node setlogmask
  445: @subsection setlogmask
  446: 
  447: The symbols referred to in this section are declared in the file
  448: @file{syslog.h}.
  449: 
  450: @comment syslog.h
  451: @comment BSD
  452: @deftypefun int setlogmask (int @var{mask})
  453: 
  454: @code{setlogmask} sets a mask (the ``logmask'') that determines which
  455: future @code{syslog} calls shall be ignored.  If a program has not
  456: called @code{setlogmask}, @code{syslog} doesn't ignore any calls.  You
  457: can use @code{setlogmask} to specify that messages of particular
  458: priorities shall be ignored in the future.
  459: 
  460: A @code{setlogmask} call overrides any previous @code{setlogmask} call.
  461: 
  462: Note that the logmask exists entirely independently of opening and
  463: closing of Syslog connections.
  464: 
  465: Setting the logmask has a similar effect to, but is not the same as,
  466: configuring Syslog.  The Syslog configuration may cause Syslog to
  467: discard certain messages it receives, but the logmask causes certain
  468: messages never to get submitted to Syslog in the first place.
  469: 
  470: @var{mask} is a bit string with one bit corresponding to each of the
  471: possible message priorities.  If the bit is on, @code{syslog} handles
  472: messages of that priority normally.  If it is off, @code{syslog}
  473: discards messages of that priority.  Use the message priority macros
  474: described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct
  475: an appropriate @var{mask} value, as in this example:
  476: 
  477: @smallexample
  478: LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)
  479: @end smallexample
  480: 
  481: or
  482: 
  483: @smallexample
  484: ~(LOG_MASK(LOG_INFO))
  485: @end smallexample
  486: 
  487: There is also a @code{LOG_UPTO} macro, which generates a mask with the bits
  488: on for a certain priority and all priorities above it:
  489: 
  490: @smallexample
  491: LOG_UPTO(LOG_ERROR)
  492: @end smallexample
  493: 
  494: The unfortunate naming of the macro is due to the fact that internally,
  495: higher numbers are used for lower message priorities.
  496: 
  497: @end deftypefun
  498: 
  499: 
  500: @node Syslog Example
  501: @subsection Syslog Example
  502: 
  503: Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}:
  504: 
  505: This example sets the logmask so that debug and informational messages
  506: get discarded without ever reaching Syslog.  So the second @code{syslog}
  507: in the example does nothing.
  508: 
  509: @smallexample
  510: #include <syslog.h>
  511: 
  512: setlogmask (LOG_UPTO (LOG_NOTICE));
  513: 
  514: openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
  515: 
  516: syslog (LOG_NOTICE, "Program started by User %d", getuid ());
  517: syslog (LOG_INFO, "A tree falls in a forest");
  518: 
  519: closelog ();
  520: 
  521: @end smallexample