1 .\"Copyright (c) 2004-2011 Apple Inc. All rights reserved.
3 .\"@APPLE_LICENSE_HEADER_START@
5 .\"This file contains Original Code and/or Modifications of Original Code
6 .\"as defined in and that are subject to the Apple Public Source License
7 .\"Version 2.0 (the 'License'). You may not use this file except in
8 .\"compliance with the License. Please obtain a copy of the License at
9 .\"http://www.opensource.apple.com/apsl/ and read it before using this
12 .\"The Original Code and all software distributed under the License are
13 .\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 .\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 .\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 .\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
17 .\"Please see the License for the specific language governing rights and
18 .\"limitations under the License.
20 .\"@APPLE_LICENSE_HEADER_END@
27 .Nd Apple System Log utility
62 .Fl x Ar file Ar expression
65 .Fl c Ar process Op filter
71 is a command-line utility for a variety of tasks relating to the Apple System Log (ASL) facility.
72 It provides mechanisms for sending and viewing log messages,
73 copying log messages to ASL format data store files,
74 and for controlling the flow of log messages from client processes.
80 prints a usage message.
84 option is used send log messages to the
87 either locally or to a remote server if the
91 There are two main forms of the command.
94 option is used, then it must be followed by a list of keys and values.
95 A structured message will be sent to the server with the keys and values given as arguments.
96 If a key or a value has embedded white space, it must be enclosed in quotes.
98 Note that the text of the log message should be supplied as a value following the
104 option is not specified, then the rest of the command line is treated as the message text.
105 The text may be preceded by
107 to set the log level (priority) of the message.
108 Levels may be an integer value corresponding the the log levels specified in
112 or they may be a string.
113 String values are case insensitive, and should be one of:
141 option is omitted, the log level defaults to 7 (Debug).
144 only requires one or two leading characters for a level specification.
145 A single character suffices in most cases.
150 for Panic / Emergency, and
158 daemon filters and saves log messages to different output streams.
159 One module saves messages to files specified in the
162 Those log files may be examined with any file printing or editing utility,
165 .Dl cat /var/log/system.log
167 Another module saves messages in a data store (/var/log/asl).
169 If invoked with no arguments,
171 fetches all messages from the active data store.
172 Messages are then printed to standard output,
173 subject to formatting options and character encoding as described below.
174 Some log messages are read-access controlled,
175 so only messages that are readable by the user running
177 will be fetched and printed.
183 fetches and prints console messages.
186 option is actually an alias for the expression:
188 .Dl -k Facility com.apple.console
190 See the EXPRESSIONS section below for more details.
192 Individual ASL data store files may be read by providing one or more file names as arguments to the
195 This may be useful when searching archived files, files on alternate disk volumes,
196 or files created as export files with the
202 option may be followed by a list of directory paths.
204 will read or search all ASL data store files in those directories.
205 Any files that are not readable will be skipped.
210 will open all readable files in the default ASL archive directory /var/log/asl.archive.
215 will open all readable files in the ASL store directory /var/log/asl.
217 Legacy ASL database files that were written by
219 on Mac OS X 10.5 (Leopard) may also be read using the
222 However only one such legacy database may be read or searched at a time.
223 Note that a legacy database may be read and copied into a new ASL data store format file using a combination of
233 to start processing messages beginning at the time of the last system startup.
234 If used in conjunction with
236 all messages since the last system startup are displayed, or matched against an expression, before
238 waits for new messages.
244 to wait for new messages.
247 prints the last 10 messages,
248 then waits for new messages to be added to the data store.
249 A number following the
251 option specifies the number of messages to print and overrides the default value of 10.
258 to view all messages in the data store before watching for new messages.
261 will display messages since the last system startup before watching for new messages.
264 is equivalent to using
274 option is similar to watching a log file using, e.g.
276 .Dl tail -f /var/log/system.log
280 option can only be used when reading the system's ASL data store or when reading a single data store file,
281 and when printing messages to standard output.
285 option is specified, messages are copied to the named file rather than being printed.
286 The file will be created if it does not exist.
288 When called without the
290 option, messages are printed to standard output.
291 Messages are printed in a format similar to that used in the system.log file,
292 except that the message priority level is printed between angle-brackets.
294 The output format may by changed by specifying the
297 Non-printable and control characters are encoded by default.
298 Text encoding may be controlled using the
303 may be one of the following:
305 .Bl -tag -width "xxxx"
309 daemon for system log files, e.g. /var/log/system.log.
311 Standard (default) format.
314 but includes the message priority level.
316 Prints the complete message structure.
317 Each key/value pair is enclosed in square brackets.
318 Embedded closing brackets and white space are escaped.
319 Time stamps are printed as seconds since the epoch by default, but may also be
320 printed in local time or UTC if the
322 option is specified (see below).
324 The list of messages is printed as an XML property list.
325 Each message is represented as a dictionary in a array.
326 Dictionary keys represent message keys.
327 Dictionary values are strings.
332 argument may also be a custom print format string.
333 A custom format should in most cases be enclosed in single quotes to prevent the shell from substituting
334 special characters and breaking at white space.
336 Custom format strings may include variables of the form
340 .Dq $((Name)(format)) .
341 which will be expanded to the value associated with the named key.
342 For example, the command:
344 .Dl syslog -F '$Time $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message'
346 produces output similar to the
351 form is sufficient in most cases.
352 However, the second form:
354 must be used if the name is not delimited by white space.
355 The third form allows different formats of the value to be printed.
356 For example, a message priority level may appear as an integer value (e.g.
358 or as a string (``Error'').
359 The following print formats are known.
361 .Bl -tag -width "$((Time)([+|-]HH[:MM]))"
363 Formats a Level value as a string, for example
368 Note that $(Level) or $Level formats the value as an integer 0 through 7.
370 Formats a Time value as the number of seconds since the Epoch.
372 Alias for $((Time)(sec)).
374 Formats a Time value as a string of the form
375 .Dq "Mmm dd hh:mm:ss" ,
376 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
377 The local timezone is used.
379 Alias for $((Time)(local)).
381 Formats a Time value as a string of the form
382 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
383 using Coordinated Universal Time, or the
387 Alias for $((Time)(utc)).
389 Where X may be any letter in the range A - Z or a - z.
390 Formats the Time using the format
391 .Dq "yyyy-mm-dd hh:mm:ssX" ,
392 using the specified nautical timezone.
393 Z is the same as UTC/Zulu time. Timezones A - M (except J) decrease by one hour to the east of the
395 Timezones N - Y increase by one hour to the west of Z.
396 M and Y have the same clock time, but differ by one day.
397 J is used to indicate the local timezone.
398 When printing using $((Time)(J)), the output format is
399 .Dq "yyyy-mm-dd hh:mm:ss" ,
400 without a trailing timezone letter.
401 .It $((Time)([+|-]HH[:MM]))
402 Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
403 The value is formatted as a string of the form
404 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH:MM" .
407 If a custom format is not being used to specify the format for Time values, then Time values
408 are generally converted to local time, except when the
410 option is used, in which case times are printed as the number of seconds since the epoch.
413 option may be used to control the format used for timestamps.
416 may be one of the following:
418 .Bl -tag -width "local or lcl"
420 Times are printed as the number of seconds since the epoch.
422 Times are converted to the local time zone, and printed with the format
424 where mmm is the month name abbreviated as three characters.
426 Times are converted to UTC, and printed with the format
427 .Dl yyyy-mm-dd hh:mm:ssZ
429 Times are converted to the indicated nautical time zone,
430 printed in the same format as UTC.
432 is interpreted as the local timezone and printed in the same format,
433 but without a trailing timezone letter.
435 The specified offset is used to adjust time.
440 option is a short form for
443 By default, control characters and non-printable characters are encoded in the output stream.
444 In some cases this may make messages less natural in appearance.
445 The encoding is designed to preserve all the information in the log message,
446 and to prevent malicious users from spoofing or obscuring information in log messages.
453 formats is encoded as it is by the
458 Newlines and tabs are also encoded as "\\n" and "\\t" respectively.
461 format, space characters embedded in log message keys are encoded as "\\s"
462 and embedded brackets are escaped to print as "\\[" and "\\]".
464 XML format output requires that keys are valid UTF8 strings.
465 Keys which are not valid UTF8 are ignored, and the associated value is not printed.
467 Values that contain legal UTF8 are printed as strings.
468 Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
469 Embedded control characters are encoded as
471 where NN is the character's hexadecimal value.
473 Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.
477 option may be used to explicitly control the text encoding.
480 may be one of the following:
482 .Bl -tag -width "safe"
484 The default encoding described above.
486 Encodes backspace characters as ^H.
487 Carriage returns are mapped to newlines.
488 A tab character is appended after newlines so that message text is indented.
495 encoding is to prevent obvious message spoofing or damage.
496 The appearance of messages printed will depend on terminal settings and UTF-8 string handling.
497 It is possible that messages printed using the
501 options may be garbled or subject to manipulation through the use of control characters and control sequences
502 embedded in user-supplied message text.
505 encoding should be used to view messages if there is any suspicion
506 that message text may have been used to manipulate the printed representation.
508 If no further command line options are specified,
510 displays all messages, or copies all messages to a data store file.
511 However, an expression may be specified using the
517 Expressions specify matching criteria.
518 They may be used to search for messages of interest.
523 .Dl -k key [[op] val]
527 option may be followed by one, two, or three arguments.
528 A single argument causes a match to occur if a message has the specified key, regardless of value.
529 If two arguments are specified, a match occurs when a message has exactly the specified value for a given key.
530 For example, to find all messages sent by the portmap process:
532 .Dl syslog -k Sender portmap
536 option is treated as an alias for the expression:
538 .Dl -k Facility com.apple.console
540 This provides a quick way to search for console messages.
542 If three arguments are given, they are of the form
543 .Fl k Ar key operation value .
545 supports the following matching operators:
547 .Bl -tag -width "xxx" -compact
555 greater than or equal to
559 less than or equal to
562 Additionally, the operator may be preceded by one or more of the following modifiers:
564 .Bl -tag -width "xxx" -compact
568 regular expression (see
580 More complex search expressions may be built by combining two or more simple expressions.
581 A complex expression that has more than one
582 .Dq -k key [[op] val]
583 term matches a message if all of the key-value operations match.
584 Logically, the result is an AND of all of key-value operations.
587 .Dl syslog -k Sender portmap -k Time ge -2h
589 finds all messages sent by portmap in the last 2 hours
590 (-2h means "two hours ago").
594 option may be used to build even more complex searches by providing an OR operation.
595 If two or more sub-expressions are given, separated by
597 options, then a match occurs is a message matches any of the sub-expressions.
598 For example, to find all messages which have either a
602 or that have a numeric priority level of 4 or less:
604 .Dl syslog -k Sender portmap -o -k Level Nle 4
606 Log priority levels are internally handled as an integer value between 0 and 7.
607 Level values in expressions may either be given as integers, or as string equivalents.
608 See the table string values in the SENDING MESSAGES section for details.
609 The example query above could also be specified with the command:
611 .Dl syslog -k Sender portmap -o -k Level Nle warning
614 A special convention exists for matching time stamps.
615 An unsigned integer value is regarded as the given number of seconds since
616 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.
617 An negative integer value is regarded as the given number of seconds before the current time.
618 For example, to find all messages of Error priority level (3) or less which were logged in the last 30 seconds:
620 .Dl syslog -k Level Nle error -k Time ge -30
622 a relative time value may be optionally followed by one of the characters
629 to specify seconds, minutes, hours, days, or weeks respectively.
630 Upper case may be used equivalently.
631 A week is taken to be 7 complete days (i.e. 604800 seconds).
632 .Ss FILTERING CONTROLS
633 Clients of the Apple System Log facility using either the
637 interfaces may specify a log filter mask.
638 The mask specifies which messages should be sent to the
640 daemon by specifying a yes/no setting for each priority level.
641 Many clients set a filter mask to avoid sending relatively unimportant messages.
642 Debug or Info priority level messages are generally only useful for debugging operations.
643 By setting a filter mask, a process can improve performance by avoiding spending
644 time sending messages that are in most cases unnecessary.
648 option may be used to control filtering.
649 In addition to the internal filter value that processes may set as described above,
650 the system maintains a global
653 This filter is normally
655 meaning that it has no effect.
656 If a value is set for the master filter, it overrides the local filter for all processes.
657 Root user access is required to set the master filter value.
659 The current setting of the master filter mask may be inspected using:
663 The value of the master filter mask my be set by providing a second argument following
665 The value may a set of characters from the set
667 These correspond to the priority levels Emergency (Panic), Alert, Critical, Error, Warning, Notice, Info, and Debug.
670 may be used for Error, as it is used for sending messages.
671 The master filter may be unset with:
675 Since it is common to use the filter as a
677 mechanism, for example to cut off messages with Debug and Info priority,
678 a single character from the list above may be specified, preceded by a minus sign.
681 uses a filter mask starting at level 0 (Emergency)
684 For example, to set the master filter level to cause all processes to log messages from Emergency up to Debug:
688 While the master filter level may be set to control the messages produced by all processes,
689 another filter mask may be specified for an individual process.
690 If a per-process filter mask is set, it overrides both the local filter mask and the master filter mask.
691 The current setting for a per-process filter mask may be inspected using
695 is either a PID or the name of a process.
696 If a name is used, it must uniquely identify a process.
697 To set a per-process filter mask, an second argument may be supplied following
699 as described above for the master filter mask.
700 Root access is required to set the per-process filter mask for system (UID 0) processes.
704 server follows filtering rules specified in the /etc/asl.conf file.
705 When the remote-control mechanism is used to change the filter of a process,
707 will save any messages received from that process until the remote-control filter is turned off.
708 .Ss SERVER CONFIGURATION
711 starts up, and when it receives a HUP signal, it re-reads its configuration settings from /etc/asl.conf.
712 It is sometimes useful to change configuration parameters temporarily, without needing to make changes
713 to the configuration file.
714 Any of the configuration options that may be set in the file (following an ``='' character) may also
715 be sent to syslogd using the
717 flag (without an ``='' character).
718 For example, to temporarily disable the message-per-second limit:
720 .Dl syslog -config mps_limit 0
722 Note that only the superuser (root) may change configuration parameters.
724 In addition to the parameter setting options that are described in the
726 manual page, an additional option:
728 .Dl syslog -config reset
732 to reset its configuration.
742 utility appeared in Mac OS X 10.4.
projects / apple / syslog.git / blob