-.\"Copyright (c) 2004-2008 Apple Inc. All rights reserved.
+.\"Copyright (c) 2004-2011 Apple Inc. All rights reserved.
.\"
.\"@APPLE_LICENSE_HEADER_START@
.\"
.D1 ""
.Nm
.Fl c Ar process Op filter
+.D1 ""
+.Nm
+.Fl config Op options
.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,
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)([+|-]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" .
+.El
.Pp
-Timestamps may be printed in three formats.
-Times are generally converted to local time, except when the
-.Fl F Ar sec
+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 [+|-]hh[:mm]
+The specified offset is used to adjust time.
.El
.Pp
The
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:
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 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
-.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,
+will cause
.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
-.Nm syslogd
-to have messages saved in the ASL data store.
+to reset its configuration.
.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