1 .\"Copyright (c) 2004-2012 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 mask
75 is a command-line utility for a variety of tasks relating to the Apple System Log (ASL) facility.
76 It provides mechanisms for sending and viewing log messages,
77 copying log messages to ASL format data store files,
78 and for controlling the flow of log messages from client processes.
84 prints a usage message.
86 NOTE: Most system logs have moved to a new logging system. See
92 option is used send log messages to the
95 either locally or to a remote server if the
99 There are two main forms of the command.
102 option is used, then it must be followed by a list of keys and values.
103 A structured message will be sent to the server with the keys and values given as arguments.
104 If a key or a value has embedded white space, it must be enclosed in quotes.
106 Note that the text of the log message should be supplied as a value following the
112 option is not specified, then the rest of the command line is treated as the message text.
113 The text may be preceded by
115 to set the log level (priority) of the message.
116 Levels may be an integer value corresponding the the log levels specified in
120 or they may be a string.
121 String values are case insensitive, and should be one of:
149 option is omitted, the log level defaults to 7 (Debug).
152 only requires one or two leading characters for a level specification.
153 A single character suffices in most cases.
158 for Panic / Emergency, and
166 daemon filters and saves log messages to different output streams.
167 One module saves messages to files specified in the
170 Those log files may be examined with any file printing or editing utility,
173 .Dl cat /var/log/system.log
175 Another module saves messages in a data store (/var/log/asl).
177 If invoked with no arguments,
179 fetches all messages from the active data store.
180 Messages are then printed to standard output,
181 subject to formatting options and character encoding as described below.
182 Some log messages are read-access controlled,
183 so only messages that are readable by the user running
185 will be fetched and printed.
191 fetches and prints console messages.
194 option is actually an alias for the expression:
196 .Dl -k Facility com.apple.console
198 See the EXPRESSIONS section below for more details.
200 Individual ASL data store files may be read by providing one or more file names as arguments to the
203 This may be useful when searching archived files, files on alternate disk volumes,
204 or files created as export files with the
210 option may be followed by a list of directory paths.
212 will read or search all ASL data store files in those directories.
213 Any files that are not readable will be skipped.
218 will open all readable files in the default ASL archive directory /var/log/asl.archive.
223 will open all readable files in the ASL store directory /var/log/asl.
225 Legacy ASL database files that were written by
227 on Mac OS X 10.5 (Leopard) may also be read using the
230 However only one such legacy database may be read or searched at a time.
231 Note that a legacy database may be read and copied into a new ASL data store format file using a combination of
241 to start processing messages beginning at the time of the last system startup.
242 If used in conjunction with
244 all messages since the last system startup are displayed, or matched against an expression, before
246 waits for new messages.
252 to wait for new messages.
255 prints the last 10 messages,
256 then waits for new messages to be added to the data store.
257 A number following the
259 option specifies the number of messages to print and overrides the default value of 10.
266 to view all messages in the data store before watching for new messages.
269 will display messages since the last system startup before watching for new messages.
272 is equivalent to using
282 option is similar to watching a log file using, e.g.
284 .Dl tail -f /var/log/system.log
288 option can only be used when reading the system's ASL data store or when reading a single data store file,
289 and when printing messages to standard output.
293 option is specified, messages are copied to the named file rather than being printed.
294 The file will be created if it does not exist.
296 When called without the
298 option, messages are printed to standard output.
299 Messages are printed in a format similar to that used in the system.log file,
300 except that the message priority level is printed between angle-brackets.
302 The output format may by changed by specifying the
305 Non-printable and control characters are encoded by default.
306 Text encoding may be controlled using the
311 may be one of the following:
313 .Bl -tag -width "xxxx"
317 daemon for system log files, e.g. /var/log/system.log.
319 Standard (default) format.
322 but includes the message priority level.
324 Prints the complete message structure.
325 Each key/value pair is enclosed in square brackets.
326 Embedded closing brackets and white space are escaped.
327 Time stamps are printed as seconds since the epoch by default, but may also be
328 printed in local time or UTC if the
330 option is specified (see below).
332 The list of messages is printed as an XML property list.
333 Each message is represented as a dictionary in a array.
334 Dictionary keys represent message keys.
335 Dictionary values are strings.
338 Each of the format styles above may optionally be followed by a dot character and an integer value, for example:
342 This causes sub-second time values to be printed.
343 In the example above, 4 decimal digits would be printed.
344 The sub-second time values come from the value of the TimeNanoSec key in the ASL message.
345 If the TimeNanoSec key is missing, a value of zero is used.
349 argument may also be a custom print format string.
350 A custom format should in most cases be enclosed in single quotes to prevent the shell from substituting
351 special characters and breaking at white space.
353 Custom format strings may include variables of the form
357 .Dq $((Name)(format)) .
358 which will be expanded to the value associated with the named key.
359 For example, the command:
361 .Dl syslog -F '$Time $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message'
363 produces output similar to the
368 form is sufficient in most cases.
369 However, the second form:
371 must be used if the name is not delimited by white space.
372 The third form allows different formats of the value to be printed.
373 For example, a message priority level may appear as an integer value (e.g.
375 or as a string (``Error'').
376 The following print formats are known.
378 .Bl -tag -width "$((Time)([+|-]HH[:MM]))"
380 Formats a Level value as a string, for example
385 Note that $(Level) or $Level formats the value as an integer 0 through 7.
387 Formats a Time value as the number of seconds since the Epoch.
389 Alias for $((Time)(sec)).
391 Formats a Time value as a string of the form
392 .Dq "Mmm dd hh:mm:ss" ,
393 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
394 The local timezone is used.
396 Alias for $((Time)(local)).
398 Formats a Time value as a string of the form
399 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
400 using Coordinated Universal Time, or the
404 Alias for $((Time)(utc)).
406 Where X may be any letter in the range A - Z or a - z.
407 Formats the Time using the format
408 .Dq "yyyy-mm-dd hh:mm:ssX" ,
409 using the specified nautical timezone.
410 Z is the same as UTC/Zulu time. Timezones A - M (except J) decrease by one hour to the east of the
412 Timezones N - Y increase by one hour to the west of Z.
413 M and Y have the same clock time, but differ by one day.
414 J is used to indicate the local timezone.
415 When printing using $((Time)(J)), the output format is
416 .Dq "yyyy-mm-dd hh:mm:ss" ,
417 without a trailing timezone letter.
419 Specifies the local timezone.
420 The timezone offset from UTC follows the date and time.
421 The time is formatted as
422 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
423 Minutes in the timezone offset are only printed if they are non-zero.
424 .It $((Time)(ISO8601))
425 Specifies the local timezone and ISO 8601 extended format.
426 The timezone offset from UTC follows the date and time.
427 The time is formatted as
428 .Dq "yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]" .
429 Minutes in the timezone offset are only printed if they are non-zero.
430 Note that this differs from
432 format only in that a
434 character separates the date and time.
435 .It $((Time)(ISO8601B))
436 Specifies the local timezone and ISO 8601 basic format, in the form:
437 .Dq "yyyymmddThhmmss[+|-]HH[:MM]" .
438 .It $((Time)(ISO8601Z))
439 Specifies UTC/Zulu time and ISO 8601 extended format, in the form:
440 .Dq "yyyy-mm-ddThh:mm:ssZ" .
441 .It $((Time)(ISO8601BZ))
442 Specifies UTC/Zulu time and ISO 8601 basic format, in the form:
443 .Dq "yyyymmddThhmmssZ" .
444 .It $((Time)([+|-]HH[:MM]))
445 Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
446 The value is formatted as a string of the form
447 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
448 Minutes in the timezone offset are only printed if they are non-zero.
451 Each of the print formats listed above for Time values may optionally be followed by a dot character and an integer value.
452 In that case, sub-second time values will be printed.
453 For example, the following line prints messages with a UTC time format, and includes 6 digits of sub-second time:
455 .Dl syslog -F '$((Time)(utc.6)) $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message
457 If a custom format is not being used to specify the format for Time values, then Time values
458 are generally converted to local time, except when the
460 option is used, in which case times are printed as the number of seconds since the epoch.
463 option may be used to control the format used for timestamps.
466 may be one of the following:
468 .Bl -tag -width "local or lcl"
470 Times are printed as the number of seconds since the epoch.
472 Times are converted to the local time zone, and printed with the format
474 where mmm is the month name abbreviated as three characters.
476 Times are converted to UTC, and printed with the format
477 .Dl yyyy-mm-dd hh:mm:ssZ
479 Times are converted to the indicated nautical time zone,
480 printed in the same format as UTC.
482 is interpreted as the local timezone and printed in the same format,
483 but without a trailing timezone letter.
485 is interpreted as the local timezone and printed with the format
486 .Dl yyyy-mm-dd hh:mm:ss[+|-]HH[:MM] .
489 string represents the local timezone offset from UTC in hours,
490 or in hours and minutes if minutes are non-zero.
492 Times are printed with the format specified by ISO 8601:
493 .Dl yyyy-mm-ddThh:mm:ss[+|-]HH[:MM] .
494 This is the same as the
497 .Dq T character separates the date and time components.
499 The specified offset is used to adjust time.
502 Each of the time formats above may optionally be followed by a dot character and an integer value.
503 In that case, sub-second time values will be printed.
510 option is a short form for
513 By default, control characters and non-printable characters are encoded in the output stream.
514 In some cases this may make messages less natural in appearance.
515 The encoding is designed to preserve all the information in the log message,
516 and to prevent malicious users from spoofing or obscuring information in log messages.
523 formats is encoded as it is by the
528 Newlines and tabs are also encoded as "\\n" and "\\t" respectively.
531 format, space characters embedded in log message keys are encoded as "\\s"
532 and embedded brackets are escaped to print as "\\[" and "\\]".
534 XML format output requires that keys are valid UTF8 strings.
535 Keys which are not valid UTF8 are ignored, and the associated value is not printed.
537 Values that contain legal UTF8 are printed as strings.
538 Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
539 Embedded control characters are encoded as
541 where NN is the character's hexadecimal value.
543 Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.
547 option may be used to explicitly control the text encoding.
550 may be one of the following:
552 .Bl -tag -width "safe"
554 This is the default encoding for
557 Encodes backspace characters as ^H.
558 Carriage returns are mapped to newlines.
559 A tab character is appended after newlines so that message text is indented.
561 The C-style backslash encoding similar to that produced by the
563 command, as described above.
570 encoding is to prevent obvious message spoofing or damage.
571 The appearance of messages printed will depend on terminal settings and UTF-8 string handling.
572 It is possible that messages printed using the
576 options may be garbled or subject to manipulation through the use of control characters and control sequences
577 embedded in user-supplied message text.
580 encoding should be used to view messages if there is any suspicion
581 that message text may have been used to manipulate the printed representation.
583 If no further command line options are specified,
585 displays all messages, or copies all messages to a data store file.
586 However, an expression may be specified using the
592 Expressions specify matching criteria.
593 They may be used to search for messages of interest.
598 .Dl -k key [[op] val]
602 option may be followed by one, two, or three arguments.
603 A single argument causes a match to occur if a message has the specified key, regardless of value.
604 If two arguments are specified, a match occurs when a message has exactly the specified value for a given key.
605 For example, to find all messages sent by the portmap process:
607 .Dl syslog -k Sender portmap
611 option is treated as an alias for the expression:
613 .Dl -k Facility com.apple.console
615 This provides a quick way to search for console messages.
617 If three arguments are given, they are of the form
618 .Fl k Ar key operation value .
620 supports the following matching operators:
622 .Bl -tag -width "xxx" -compact
630 greater than or equal to
634 less than or equal to
637 Additionally, the operator may be preceded by one or more of the following modifiers:
639 .Bl -tag -width "xxx" -compact
643 regular expression (see
655 More complex search expressions may be built by combining two or more simple expressions.
656 A complex expression that has more than one
657 .Dq -k key [[op] val]
658 term matches a message if all of the key-value operations match.
659 Logically, the result is an AND of all of key-value operations.
662 .Dl syslog -k Sender portmap -k Time ge -2h
664 finds all messages sent by portmap in the last 2 hours
665 (-2h means "two hours ago").
669 option may be used to build even more complex searches by providing an OR operation.
670 If two or more sub-expressions are given, separated by
672 options, then a match occurs is a message matches any of the sub-expressions.
673 For example, to find all messages which have either a
677 or that have a numeric priority level of 4 or less:
679 .Dl syslog -k Sender portmap -o -k Level Nle 4
681 Log priority levels are internally handled as an integer value between 0 and 7.
682 Level values in expressions may either be given as integers, or as string equivalents.
683 See the table string values in the SENDING MESSAGES section for details.
684 The example query above could also be specified with the command:
686 .Dl syslog -k Sender portmap -o -k Level Nle warning
689 A special convention exists for matching time stamps.
690 An unsigned integer value is regarded as the given number of seconds since
691 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.
692 An negative integer value is regarded as the given number of seconds before the current time.
693 For example, to find all messages of Error priority level (3) or less which were logged in the last 30 seconds:
695 .Dl syslog -k Level Nle error -k Time ge -30
697 a relative time value may be optionally followed by one of the characters
704 to specify seconds, minutes, hours, days, or weeks respectively.
705 Upper case may be used equivalently.
706 A week is taken to be 7 complete days (i.e. 604800 seconds).
707 .Ss FILTERING CONTROLS
708 Clients of the Apple System Log facility using either the
712 interfaces may specify a log filter mask.
713 The mask specifies which messages should be sent to the
715 daemon by specifying a yes/no setting for each priority level.
716 Many clients set a filter mask to avoid sending relatively unimportant messages.
717 Debug or Info priority level messages are generally only useful for debugging operations.
718 By setting a filter mask, a process can improve performance by avoiding spending
719 time sending messages that are in most cases unnecessary.
723 option may be used to control filtering.
724 In addition to the internal filter mask value that processes may set as described above,
725 the system maintains a global
728 This filter is normally
730 meaning that it has no effect.
731 If a value is set for the master filter mask, it overrides the local filter mask for all processes.
732 Root user access is required to set the master filter mask value.
734 The current setting of the master filter mask may be inspected using:
738 The value of the master filter mask my be set by providing a second argument following
740 The value may a set of characters from the set
742 These correspond to the priority levels Emergency (Panic), Alert, Critical, Error, Warning, Notice, Info, and Debug.
745 may be used for Error, as it is used for sending messages.
746 The master filter mask may be deactivated with:
750 Since it is common to use the filter mask as a
752 mechanism, for example to cut off messages with Debug and Info priority,
753 a single character from the list above may be specified, preceded by a minus sign.
756 uses a filter mask starting at level 0 (Emergency)
759 For example, to set the master filter mask to cause all processes to log messages from Emergency up to Debug:
763 While the master filter mask may be set to control the messages produced by all processes,
764 another filter mask may be specified for an individual process.
765 If a per-process filter mask is set, it overrides both the local filter mask and the master filter mask.
766 The current setting for a per-process filter mask may be inspected using
770 is either a PID or the name of a process.
771 If a name is used, it must uniquely identify a process.
772 To set a per-process filter mask, an second argument may be supplied following
774 as described above for the master filter mask.
775 Root access is required to set the per-process filter mask for system (UID 0) processes.
779 server follows filtering rules specified in the /etc/asl.conf file.
780 When the remote-control mechanism is used to change the filter of a process,
782 will save any messages received from that process until the remote-control filter is turned off.
783 .Ss SERVER CONFIGURATION
786 starts up, and when it receives a HUP signal, it re-reads its configuration settings from /etc/asl.conf.
787 It is sometimes useful to change configuration parameters temporarily, without needing to make changes
788 to the configuration file.
789 Any of the configuration options that may be set in the file (following an ``='' character) may also
790 be sent to syslogd using the
792 flag (without an ``='' character).
793 For example, to temporarily disable the kernel message-per-second limit:
795 .Dl syslog -config mps_limit 0
797 Note that only the superuser (root) may change configuration parameters.
799 In addition to the parameter setting options that are described in the
801 manual page, an additional option:
803 .Dl syslog -config reset
807 to reset its configuration.
808 .Ss ASL OUTPUT MODULES
809 ASL Output Modules are named configuration bundles used by the ASL server
811 and by the ASL filesystem manager
813 The /etc/asl.conf file represents the system's primary output module,
814 and is given the name
816 Other modules are read from files in the /etc/asl directory.
817 File names serve as module names.
818 ASL Output Modules are described in detail in
824 prints a summary of all loaded ASL Output Modules.
825 The summary includes the output files and ASL store directories used by each module,
826 a list of the module's configuration rules, and the module's current enabled or disabled status.
828 prints a summary for the module with the given name.
830 ASL Output Modules may be enabled or disabled using the command:
837 Note that only the superuser (root) may enable or disable a module.
840 (including the single-quote characters)
841 may be used to change the status of all ASL Output Modules,
842 excluding the primary com.apple.asl module.
843 com.apple.asl may be enabled or disabled, but only specifically by name.
845 If a module includes rotated files, the command:
852 Will force the module to checkpoint all of its rotated files,
853 or just the single optionally named file.
855 (including the single-quote characters)
856 may be used to force checkpointing of all rotated files for all ASL Output Modules,
857 including the primary com.apple.asl module.
859 Note that only the superuser (root) may force files to be checkpointed.
861 The checkpoint action sends a command to
863 and waits for a reply to be returned.
864 This means that any files currently in use will be checkpointed when the
877 utility appeared in Mac OS X 10.4.
projects / apple / syslog.git / blob