]>
Commit | Line | Data |
---|---|---|
d52b6462 UD |
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 | ||
e4cf5229 | 62 | Syslogd can also handle messages from other systems. It listens on the |
d52b6462 UD |
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 | |
b750d5e7 | 149 | @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility}) |
d52b6462 UD |
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 | ||
b750d5e7 UD |
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 | ||
d52b6462 | 199 | @code{openlog} may or may not open the @file{/dev/log} socket, depending |
e4cf5229 | 200 | on @var{option}. If it does, it tries to open it and connect it as a |
d52b6462 UD |
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 | |
e4cf5229 | 208 | @var{options}. |
d52b6462 UD |
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 | |
e4cf5229 | 285 | facility/priority from a facility and a priority, as in the following |
d52b6462 UD |
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 | ||
e4cf5229 | 297 | @vtable @code |
d52b6462 UD |
298 | @item LOG_USER |
299 | A miscellaneous user process | |
300 | @item LOG_MAIL | |
301 | ||
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 | |
e4cf5229 | 336 | @end vtable |
d52b6462 UD |
337 | |
338 | Results are undefined if the facility code is anything else. | |
339 | ||
e4cf5229 UD |
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. | |
d52b6462 UD |
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 | ||
e4cf5229 | 352 | @vtable @code |
d52b6462 UD |
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. | |
e4cf5229 | 369 | @end vtable |
d52b6462 UD |
370 | |
371 | Results are undefined if the priority code is anything else. | |
372 | ||
32c075e1 | 373 | If the process does not presently have a Syslog connection open (i.e. |
d52b6462 UD |
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> | |
e4cf5229 UD |
396 | syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), |
397 | "Unable to make network connection to %s. Error=%m", host); | |
d52b6462 UD |
398 | |
399 | @end smallexample | |
400 | ||
401 | @end deftypefun | |
402 | ||
403 | ||
404 | @comment syslog.h | |
405 | @comment BSD | |
e4cf5229 | 406 | @deftypefun void vsyslog (int @var{facility_priority}, char *@var{format}, va_list arglist) |
d52b6462 UD |
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 | |
e4cf5229 | 422 | @deftypefun void closelog (void) |
d52b6462 UD |
423 | |
424 | @code{closelog} closes the current Syslog connection, if there is one. | |
b750d5e7 UD |
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. | |
d52b6462 UD |
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 | ||
e4cf5229 | 494 | The unfortunate naming of the macro is due to the fact that internally, |
d52b6462 UD |
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 | ||
e4cf5229 | 512 | setlogmask (LOG_UPTO (LOG_NOTICE)); |
d52b6462 | 513 | |
e4cf5229 | 514 | openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1); |
d52b6462 | 515 | |
e4cf5229 UD |
516 | syslog (LOG_NOTICE, "Program started by User %d", getuid ()); |
517 | syslog (LOG_INFO, "A tree falls in a forest"); | |
d52b6462 | 518 | |
e4cf5229 | 519 | closelog (); |
d52b6462 UD |
520 | |
521 | @end smallexample |