-.\"Copyright (c) 2004-2008 Apple Inc. All rights reserved.
+.\"Copyright (c) 2004-2012 Apple Inc. All rights reserved.
.\"
.\"@APPLE_LICENSE_HEADER_START@
.\"
.Nm
.Op Fl f Ar file ...
.Op Fl d Ar dir ...
+.Op Fl B
.Op Fl w Op Ar n
.Op Fl F Ar format
.Op Fl T Ar format
.D1 ""
.Nm
.Fl c Ar process Op filter
+.D1 ""
+.Nm
+.Fl config Op options
+.D1 ""
+.Nm
+.Fl module
+.Op name Op action
.Sh DESCRIPTION
.Nm
is a command-line utility for a variety of tasks relating to the Apple System Log (ASL) facility.
.Pp
If invoked with no arguments,
.Nm
-fetchs all messages from the active data store.
+fetches all messages from the active data store.
Messages are then printed to standard output,
subject to formatting options and character encoding as described below.
Some log messages are read-access controlled,
options.
.Pp
The
+.Fl B
+option causes
+.Nm
+to start processing messages beginning at the time of the last system startup.
+If used in conjunction with
+.Fl w ,
+all messages since the last system startup are displayed, or matched against an expression, before
+.Nm
+waits for new messages.
+.Pp
+The
.Fl w
option causes
.Nm
.Pp
.Dl syslog -w 20
.Pp
-This usage is similar to watching a log file using, e.g.
+Use the value
+.Dq all
+to view all messages in the data store before watching for new messages.
+The value
+.Dq boot
+will display messages since the last system startup before watching for new messages.
+Specifying
+.Dq -w boot
+is equivalent to using
+.Fl w
+and
+.Fl B
+together.
+.Pp
+Using
+.Nm
+with the
+.Fl w
+option is similar to watching a log file using, e.g.
.Pp
.Dl tail -f /var/log/system.log
.Pp
Dictionary values are strings.
.El
.Pp
+Each of the format styles above may optionally be followed by a dot character and an integer value, for example:
+.Pp
+.Dl syslog -F std.4
+.Pp
+This causes sub-second time values to be printed.
+In the example above, 4 decimal digits would be printed.
+The sub-second time values come from the value of the TimeNanoSec key in the ASL message.
+If the TimeNanoSec key is missing, a value of zero is used.
+.Pp
The value of the
.Ar format
argument may also be a custom print format string.
special characters and breaking at white space.
.Pp
Custom format strings may include variables of the form
-.Dq $Name
-(or
-.Dq $(Name)
-if the variable is not delimited by whitespace)
-which will be expanded to the associated with the named key.
+.Dq $Name ,
+.Dq $(Name) ,
+or
+.Dq $((Name)(format)) .
+which will be expanded to the value associated with the named key.
For example, the command:
.Pp
-.Dl syslog -F '$Time $Host $(Sender)[$(PID)]: $Message'
+.Dl syslog -F '$Time $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message'
.Pp
produces output similar to the
-.Dq bsd
+.Dq std
format.
+The simple
+.Dq $Name
+form is sufficient in most cases.
+However, the second form:
+.Dq $(Name)
+must be used if the name is not delimited by white space.
+The third form allows different formats of the value to be printed.
+For example, a message priority level may appear as an integer value (e.g.
+.Dq 3 )
+or as a string (``Error'').
+The following print formats are known.
+.Pp
+.Bl -tag -width "$((Time)([+|-]HH[:MM]))"
+.It $((Level)(str))
+Formats a Level value as a string, for example
+.Dq Error ,
+.Dq Alert ,
+.Dq Warning ,
+and so on.
+Note that $(Level) or $Level formats the value as an integer 0 through 7.
+.It $((Time)(sec))
+Formats a Time value as the number of seconds since the Epoch.
+.It $((Time)(raw))
+Alias for $((Time)(sec)).
+.It $((Time)(local))
+Formats a Time value as a string of the form
+.Dq "Mmm dd hh:mm:ss" ,
+where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
+The local timezone is used.
+.It $((Time)(lcl))
+Alias for $((Time)(local)).
+.It $((Time)(utc))
+Formats a Time value as a string of the form
+.Dq "yyyy-mm-dd hh:mm:ssZ" ,
+using Coordinated Universal Time, or the
+.Dq Zulu
+time zone.
+.It $((Time)(zulu))
+Alias for $((Time)(utc)).
+.It $((Time)(X))
+Where X may be any letter in the range A - Z or a - z.
+Formats the Time using the format
+.Dq "yyyy-mm-dd hh:mm:ssX" ,
+using the specified nautical timezone.
+Z is the same as UTC/Zulu time. Timezones A - M (except J) decrease by one hour to the east of the
+Zulu time zone.
+Timezones N - Y increase by one hour to the west of Z.
+M and Y have the same clock time, but differ by one day.
+J is used to indicate the local timezone.
+When printing using $((Time)(J)), the output format is
+.Dq "yyyy-mm-dd hh:mm:ss" ,
+without a trailing timezone letter.
+.It $((Time)(JZ))
+Specifies the local timezone.
+The timezone offset from UTC follows the date and time.
+The time is formatted as
+.Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
+.It $((Time)(ISO8601))
+Specifies the local timezone and ISO 8601 extended format.
+The timezone offset from UTC follows the date and time.
+The time is formatted as
+.Dq "yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
+Note that this differs from
+.Dq JZ
+format only in that a
+.Dq T
+character separates the date and time.
+.It $((Time)(ISO8601B))
+Specifies the local timezone and ISO 8601 basic format, in the form:
+.Dq "yyyymmddThhmmss[+|-]HH[:MM]" .
+.It $((Time)(ISO8601Z))
+Specifies UTC/Zulu time and ISO 8601 extended format, in the form:
+.Dq "yyyy-mm-ddThh:mm:ssZ" .
+.It $((Time)(ISO8601BZ))
+Specifies UTC/Zulu time and ISO 8601 basic format, in the form:
+.Dq "yyyymmddThhmmssZ" .
+.It $((Time)([+|-]HH[:MM]))
+Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
+The value is formatted as a string of the form
+.Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
+.El
.Pp
-Timestamps may be printed in three formats.
-Times are generally converted to local time, except when the
-.Fl F Ar sec
+Each of the print formats listed above for Time values may optionally be followed by a dot character and an integer value.
+In that case, sub-second time values will be printed.
+For example, the following line prints messages with a UTC time format, and includes 6 digits of sub-second time:
+.Pp
+.Dl syslog -F '$((Time)(utc.6)) $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message
+.Pp
+If a custom format is not being used to specify the format for Time values, then Time values
+are generally converted to local time, except when the
+.Fl F Ar raw
option is used, in which case times are printed as the number of seconds since the epoch.
The
.Fl T Ar format
-option may be used to explicity control the format used for timestamps.
+option may be used to control the format used for timestamps.
The value of
.Ar format
may be one of the following:
.Pp
-.Bl -tag -width "local"
-.It sec
+.Bl -tag -width "local or lcl"
+.It sec or raw
Times are printed as the number of seconds since the epoch.
-.It local
+.It local or lcl
Times are converted to the local time zone, and printed with the format
-.Dl MMM DD HH:MM:SS
-.It utc
+.Dl mmm dd hh:mm:ss
+where mmm is the month name abbreviated as three characters.
+.It utc or zulu
Times are converted to UTC, and printed with the format
-.Dl YYYY.MM.DD HH:MM:SS UTC
+.Dl yyyy-mm-dd hh:mm:ssZ
+.It A-Z
+Times are converted to the indicated nautical time zone,
+printed in the same format as UTC.
+.Dq J
+is interpreted as the local timezone and printed in the same format,
+but without a trailing timezone letter.
+.It JZ
+is interpreted as the local timezone and printed with the format
+.Dl yyyy-mm-dd hh:mm:ss[+|-]HH[:MM] .
+The trailing
+.Dq [+|-]HH[:MM]
+string represents the local timezone offset from UTC in hours,
+or in hours and minutes if minutes are non-zero.
+.It ISO8601
+Times are printed with the format specified by ISO 8601:
+.Dl yyyy-mm-ddThh:mm:ss[+|-]HH[:MM] .
+This is the same as the
+.Dq JZ
+format, except a
+.Dq T character separates the date and time components.
+.It [+|-]hh[:mm]
+The specified offset is used to adjust time.
.El
.Pp
+Each of the time formats above may optionally be followed by a dot character and an integer value.
+In that case, sub-second time values will be printed.
+For example:
+.Pp
+.Dl syslog -T bsd.3
+.Pp
The
.Fl u
option is a short form for
By default, control characters and non-printable characters are encoded in the output stream.
In some cases this may make messages less natural in appearance.
The encoding is designed to preserve all the information in the log message,
-and to prevent malicious users from spoofing or obsucring information in log messages.
+and to prevent malicious users from spoofing or obscuring information in log messages.
.Pp
Text in the
.Dq std ,
Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
Embedded control characters are encoded as
.Dq &#xNN;
-where NN is the character's hexidecimal value.
+where NN is the character's hexadecimal value.
.Pp
Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.
.Pp
The
.Fl E Ar format
-option may be used to explicity control the text encoding.
+option may be used to explicitly control the text encoding.
The value of
.Ar format
may be one of the following:
.Pp
.Bl -tag -width "safe"
-.It vis
-The default encoding described above.
.It safe
+This is the default encoding for
+.Nm syslog
+output.
Encodes backspace characters as ^H.
Carriage returns are mapped to newlines.
A tab character is appended after newlines so that message text is indented.
+.It vis
+The C-style backslash encoding similar to that produced by the
+.Dq vis -c
+command, as described above.
.It none
No encoding is used.
.El
.Dq none
options may be garbled or subject to manipulation through the use of control characters and control sequences
embedded in user-supplied message text.
-The default
+The
.Dq vis
encoding should be used to view messages if there is any suspicion
that message text may have been used to manipulate the printed representation.
as described above for the master filter mask.
Root access is required to set the per-process filter mask for system (UID 0) processes.
.Pp
-The filtering described above takes place in the client library to determine which messages are sent to the
+The
.Nm syslogd
-daemon.
-The daemon also contains filters which determines which messages are saved in the data store.
-This determines which messages are seen when reading messages using the
-.Nm
-utility, or when viewing data store messages in the Console utility application.
+server follows filtering rules specified in the /etc/asl.conf file.
+When the remote-control mechanism is used to change the filter of a process,
+.Nm syslogd
+will save any messages received from that process until the remote-control filter is turned off.
+.Ss SERVER CONFIGURATION
+When
+.Nm syslogd
+starts up, and when it receives a HUP signal, it re-reads its configuration settings from /etc/asl.conf.
+It is sometimes useful to change configuration parameters temporarily, without needing to make changes
+to the configuration file.
+Any of the configuration options that may be set in the file (following an ``='' character) may also
+be sent to syslogd using the
+.Fl config
+flag (without an ``='' character).
+For example, to temporarily disable the kernel message-per-second limit:
.Pp
-The default data store filter mask permits all messages with priority levels from Emergency to Debug (level 0 to 7).
-The level may be inspected using:
+.Dl syslog -config mps_limit 0
.Pp
-.Dl syslog -c syslogd
+Note that only the superuser (root) may change configuration parameters.
.Pp
-To set the data store filter mask, an second argument may be supplied following
-.Fl c Li syslog
-as described above.
-For example, to save messages with priority level Error or less in the data store:
+In addition to the parameter setting options that are described in the
+.Xr asl.conf 5
+manual page, an additional option:
.Pp
-.Dl syslog -c syslog -e
+.Dl syslog -config reset
.Pp
-The
+will cause
.Nm syslogd
-server also follows filtering rules specified in the /etc/asl.conf file.
-When the remote-control mechanism is used to change the filter of a process,
-.Nm syslogd
-will save any messages received from that process until the remote-control filter is turned off.
-It is no longer necessary to adjust the filtering for both a process and for
+to reset its configuration.
+.Ss ASL OUTPUT MODULES
+ASL Output Modules are named configuration bundles used by the ASL server
+.Nm syslogd ,
+and by the ASL filesystem manager
+.Nm aslmanager .
+The /etc/asl.conf file represents the system's primary output module,
+and is given the name
+.Dq com.apple.asl .
+Other modules are read from files in the /etc/asl directory.
+File names serve as module names.
+ASL Output Modules are described in detail in
+.Xr asl.conf 5 .
+.Pp
+When invoked with
+.Fl module ,
+.Nm syslog
+prints a summary of all loaded ASL Output Modules.
+The summary includes the output files and ASL store directories used by each module,
+a list of the module's configuration rules, and the module's current enabled or disabled status.
+.Fl module Ar name
+prints a summary for the module with the given name.
+.Pp
+ASL Output Modules may be enabled or disabled using the command:
+.Pp
+ syslog -module
+.Ar name
+enable
+.Op 0
+.Pp
+Note that only the superuser (root) may enable or disable a module.
+.Pp
+The name '*'
+(including the single-quote characters)
+may be used to change the status of all ASL Output Modules,
+excluding the primary com.apple.asl module.
+com.apple.asl may be enabled or disabled, but only specifically by name.
+.Pp
+If a module includes rotated files, the command:
+.Pp
+ syslog -module
+.Ar name
+checkpoint
+.Op file
+.Pp
+Will force the module to checkpoint all of its rotated files,
+or just the single optionally named file.
+The name '*'
+(including the single-quote characters)
+may be used to force checkpointing of all rotated files for all ASL Output Modules,
+including the primary com.apple.asl module.
+.Pp
+Note that only the superuser (root) may force files to be checkpointed.
+.Pp
+The checkpoint action sends a command to
.Nm syslogd
-to have messages saved in the ASL data store.
+and waits for a reply to be returned.
+This means that any files currently in use will be checkpointed when the
+.Nm syslog
+command completes.
.Sh SEE ALSO
.Xr syslogd 8 ,
.Xr logger 1 ,
.Xr asl 3 ,
.Xr syslog 3 ,
+.Xr asl.conf 5 .
.Sh HISTORY
The
.Nm
projects / apple / syslog.git / blobdiff