← Back to branch summary

~ubuntu-branches/ubuntu/utopic/eglibc/utopic

« back to all changes in this revision

Viewing changes to manual/syslog.texi

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2012-10-26 05:14:58 UTC
  • mfrom: (1.5.1) (4.4.22 experimental)
  • Revision ID: package-import@ubuntu.com-20121026051458-oryotr4i03ob5pab
Tags: 2.16-0ubuntu1
* Merge with unreleased 2.16 in Debian experimental, remaining changes:
  - Drop the Breaks line from libc6, which refers to a Debian transition
  - Remove the libc6 recommends on libc6-i686, which we don't build
  - Enable libc6{,-dev}-armel on armhf and libc6{-dev}-armhf on armel
  - Ship update-locale and validlocale in /usr/sbin in libc-bin
  - Don't build locales or locales-all in Ubuntu, we rely on langpacks
  - Heavily mangle the way we do service restarting on major upgrades
  - Use different MIN_KERNEL_SUPPORTED versions than Debian, due to
    buildd needs.  This should be universally bumped to 3.2.0 once all
    our buildds (including the PPA guests) are running precise kernels
  - Build i386 variants as -march=i686, build amd64 with -O3, and build
    ppc64 variants (both 64-bit and 32-bit) with -O3 -fno-tree-vectorize
  - Re-enable unsubmitted-ldconfig-cache-abi.diff and rebuild the cache
    on upgrades from previous versions that used a different constant
  - debian/patches/any/local-CVE-2012-3406.diff: switch to malloc when
    array grows too large to handle via alloca extension (CVE-2012-3406)
  - Build generic i386/i686 flavour with -mno-tls-direct-seg-refs
* Changes added/dropped with this merge while reducing our delta:
  - Stop building glibc docs from the eglibc source, and instead make
    the glibc-docs stub have a hard dependency on glibc-doc-reference
  - Remove outdated conflicts against ancient versions of ia32-libs
  - Drop the tzdata dependency from libc6, it's in required and minimal
  - Use gcc-4.7/g++-4.7 by default on all our supported architectures
  - Save our historical changelog as changelog.ubuntu in the source
  - Drop nscd's libaudit build-dep for now, as libaudit is in universe
  - Drop the unnecessary Breaks from libc6 to locales and locales-all
  - Ship xen's ld.so.conf.d snippet as /etc/ld.so.conf.d/libc6-xen.conf
* Disable hard failures on the test suite for the first upload to raring

Show diffs side-by-side

added added

removed removed

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