-.\" Copyright (c) 2004 Apple Computer
-.\" All rights reserved.
+.\"Copyright (c) 2004-2008 Apple Inc. All rights reserved.
.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 4. Neither the name of Apple Computer nor the names of its contributors
-.\" may be used to endorse or promote products derived from this software
-.\" without specific prior written permission.
+.\"@APPLE_LICENSE_HEADER_START@
.\"
-.\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
+.\"This file contains Original Code and/or Modifications of Original Code
+.\"as defined in and that are subject to the Apple Public Source License
+.\"Version 2.0 (the 'License'). You may not use this file except in
+.\"compliance with the License. Please obtain a copy of the License at
+.\"http://www.opensource.apple.com/apsl/ and read it before using this
+.\"file.
.\"
+.\"The Original Code and all software distributed under the License are
+.\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\"Please see the License for the specific language governing rights and
+.\"limitations under the License.
+.\"
+.\"@APPLE_LICENSE_HEADER_END@
.\"
.Dd October 18, 2004
.Dt SYSLOG 1
.Li ...
.D1 ""
.Nm
-.Op Fl w
+.Fl C
+.D1 ""
+.Nm
+.Op Fl f Ar file ...
+.Op Fl d Ar dir ...
+.Op Fl w Op Ar n
.Op Fl F Ar format
+.Op Fl T Ar format
+.Op Fl E Ar format
.Ar expression
.D1 ""
.Nm
-.Fl p Ar expression
+.Op Fl f Ar file ...
+.Op Fl d Ar dir ...
+.Fl x Ar file Ar expression
.D1 ""
.Nm
.Fl c Ar process Op filter
.Sh DESCRIPTION
.Nm
-is a command-line utility for a variety of tasks relating to the Apple System Log facility.
+is a command-line utility for a variety of tasks relating to the Apple System Log (ASL) facility.
It provides mechanisms for sending and viewing log messages,
-pruning the contents of the system's log message data store,
+copying log messages to ASL format data store files,
and for controlling the flow of log messages from client processes.
.Pp
When invoked with the
A structured message will be sent to the server with the keys and values given as arguments.
If a key or a value has embedded white space, it must be enclosed in quotes.
.Pp
+Note that the text of the log message should be supplied as a value following the
+.Dq Message
+key.
+.Pp
If the
.Fl k
option is not specified, then the rest of the command line is treated as the message text.
.Dq Panic
is an alias for
.Dq Emergency .
+.Pp
+If the
+.Fl l
+option is omitted, the log level defaults to 7 (Debug).
+.Pp
.Nm
only requires one or two leading characters for a level specification.
A single character suffices in most cases.
.Ss READING MESSAGES
The
.Nm syslogd
-daemon receives messages from a variety of input sources.
-Received messages are processed by a set of output modules,
-each of which may act on messages in different ways.
-.Pp
-Two of the standard modules filter messages using criteria like the sender and the priority level of the message,
-and write copies of these messages to different output streams.
-One module does this filtering and filing task using the configuration specified in the
+daemon filters and saves log messages to different output streams.
+One module saves messages to files specified in the
.Xr syslog.conf 5
file.
-The output files specified in that configuration may be examined by any file printing or editing utility,
+Those log files may be examined with any file printing or editing utility,
e.g.
.Pp
.Dl cat /var/log/system.log
.Pp
-Another module saves messages in a data store, which may be searched using the
-.Nm
-command.
+Another module saves messages in a data store (/var/log/asl).
.Pp
If invoked with no arguments,
.Nm
-simply prints all of the messages saved in the data store. If the
+fetchs 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,
+so only messages that are readable by the user running
+.Nm
+will be fetched and printed.
+.Pp
+If invoked with the
+.Fl C
+option,
+.Nm
+fetches and prints console messages.
+The
+.Fl C
+option is actually an alias for the expression:
+.Pp
+.Dl -k Facility com.apple.console
+.Pp
+See the EXPRESSIONS section below for more details.
+.Pp
+Individual ASL data store files may be read by providing one or more file names as arguments to the
+.Fl f
+option.
+This may be useful when searching archived files, files on alternate disk volumes,
+or files created as export files with the
+.Fl x
+option.
+.Pp
+The
+.Fl d
+option may be followed by a list of directory paths.
+.Nm
+will read or search all ASL data store files in those directories.
+Any files that are not readable will be skipped.
+Specifying
+.Fl d
+with the name
+.Dq archive
+will open all readable files in the default ASL archive directory /var/log/asl.archive.
+Specifying
+.Fl d
+with the name
+.Dq store
+will open all readable files in the ASL store directory /var/log/asl.
+.Pp
+Legacy ASL database files that were written by
+.Nm syslogd
+on Mac OS X 10.5 (Leopard) may also be read using the
+.Fl f
+option.
+However only one such legacy database may be read or searched at a time.
+Note that a legacy database may be read and copied into a new ASL data store format file using a combination of
+.Fl f
+and
+.Fl x
+options.
+.Pp
+The
.Fl w
-option is used,
+option causes
.Nm
-waits for new messages to be added to the data store.
-Messages already in the store are ignored.
+to wait for new messages.
+By default,
+.Nm
+prints the last 10 messages,
+then waits for new messages to be added to the data store.
+A number following the
+.Fl w
+option specifies the number of messages to print and overrides the default value of 10.
+For example:
+.Pp
+.Dl syslog -w 20
+.Pp
This usage is similar to watching a log file using, e.g.
.Pp
.Dl tail -f /var/log/system.log
.Pp
+The
+.Fl w
+option can only be used when reading the system's ASL data store or when reading a single data store file,
+and when printing messages to standard output.
+.Pp
+If the
+.Fl x Ar file
+option is specified, messages are copied to the named file rather than being printed.
+The file will be created if it does not exist.
+.Pp
+When called without the
+.Fl x
+option, messages are printed to standard output.
Messages are printed in a format similar to that used in the system.log file,
except that the message priority level is printed between angle-brackets.
.Pp
-The
-.Fl u
-option forces all time stamps to be printed using UTC.
-This overrides printing of time stamps using the local time zone.
-.Pp
The output format may by changed by specifying the
.Fl F Ar format
option.
+Non-printable and control characters are encoded by default.
+Text encoding may be controlled using the
+.Fl E
+option (see below).
The value of
.Ar format
may be one of the following:
Prints the complete message structure.
Each key/value pair is enclosed in square brackets.
Embedded closing brackets and white space are escaped.
-Time stamps are printed using UTC rather than being converted to the local time zone.
+Time stamps are printed as seconds since the epoch by default, but may also be
+printed in local time or UTC if the
+.Fl T
+option is specified (see below).
+.It xml
+The list of messages is printed as an XML property list.
+Each message is represented as a dictionary in a array.
+Dictionary keys represent message keys.
+Dictionary values are strings.
.El
.Pp
The value of the
.Dq bsd
format.
.Pp
+Timestamps may be printed in three formats.
+Times are generally converted to local time, except when the
+.Fl F Ar sec
+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.
+The value of
+.Ar format
+may be one of the following:
+.Pp
+.Bl -tag -width "local"
+.It sec
+Times are printed as the number of seconds since the epoch.
+.It local
+Times are converted to the local time zone, and printed with the format
+.Dl MMM DD HH:MM:SS
+.It utc
+Times are converted to UTC, and printed with the format
+.Dl YYYY.MM.DD HH:MM:SS UTC
+.El
+.Pp
+The
+.Fl u
+option is a short form for
+.Fl T Ar utc .
+.Pp
+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.
+.Pp
+Text in the
+.Dq std ,
+.Dq bsd ,
+and
+.Dq raw
+formats is encoded as it is by the
+.Nm vis
+utility with the
+.Fl c
+option.
+Newlines and tabs are also encoded as "\\n" and "\\t" respectively.
+In
+.Dq raw
+format, space characters embedded in log message keys are encoded as "\\s"
+and embedded brackets are escaped to print as "\\[" and "\\]".
+.Pp
+XML format output requires that keys are valid UTF8 strings.
+Keys which are not valid UTF8 are ignored, and the associated value is not printed.
+.Pp
+Values that contain legal UTF8 are printed as strings.
+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.
+.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.
+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
+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 none
+No encoding is used.
+.El
+.Pp
+The intent of the
+.Dq safe
+encoding is to prevent obvious message spoofing or damage.
+The appearance of messages printed will depend on terminal settings and UTF-8 string handling.
+It is possible that messages printed using the
+.Dq safe
+or
+.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
+.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.
+.Pp
If no further command line options are specified,
.Nm
-displays all messages,
-either all those saved in the data store,
-or all new messages if
-.Fl w
-is used.
+displays all messages, or copies all messages to a data store file.
However, an expression may be specified using the
.Fl k
and
options.
.Ss EXPRESSIONS
Expressions specify matching criteria.
-They may be used when reading messages to filter for messages of interest.
-Expressions are also required when pruning the system log file with the
-.Fl p
-option.
+They may be used to search for messages of interest.
.Pp
-A simple expression is a list of one or more key/value pairs.
-A match is made when a message has the given value for the specified key.
-For example, to find all messages send by the portmap process:
+A simple expression
+has the form:
.Pp
-.Dl syslog -k Sender portmap
+.Dl -k key [[op] val]
.Pp
The
.Fl k
option may be followed by one, two, or three arguments.
A single argument causes a match to occur if a message has the specified key, regardless of value.
-If a pair of arguments is specified, a match occurs when a message has exactly the specified value for a given key.
+If two arguments are specified, a match occurs when a message has exactly the specified value for a given key.
+For example, to find all messages sent by the portmap process:
+.Pp
+.Dl syslog -k Sender portmap
+.Pp
+Note that the
+.Fl C
+option is treated as an alias for the expression:
+.Pp
+.Dl -k Facility com.apple.console
+.Pp
+This provides a quick way to search for console messages.
+.Pp
If three arguments are given, they are of the form
.Fl k Ar key operation value .
.Nm
numeric comparison
.El
.Pp
-An simple expression matches a message if all of the key-value operations match.
+More complex search expressions may be built by combining two or more simple expressions.
+A complex expression that has more than one
+.Dq -k key [[op] val]
+term matches a message if all of the key-value operations match.
Logically, the result is an AND of all of key-value operations.
+For example:
+.Pp
+.Dl syslog -k Sender portmap -k Time ge -2h
+.Pp
+finds all messages sent by portmap in the last 2 hours
+(-2h means "two hours ago").
+.Pp
The
.Fl o
-option separates simple expressions and provides an OR operation.
-If two or more simple expressions are given, separated by
+option may be used to build even more complex searches by providing an OR operation.
+If two or more sub-expressions are given, separated by
.Fl o
-options, then a match occurs is a message matches any of the simple expressions.
+options, then a match occurs is a message matches any of the sub-expressions.
For example, to find all messages which have either a
.Dq Sender
value of
.Pp
.Dl syslog -k Sender portmap -o -k Level Nle 4
.Pp
+Log priority levels are internally handled as an integer value between 0 and 7.
+Level values in expressions may either be given as integers, or as string equivalents.
+See the table string values in the SENDING MESSAGES section for details.
+The example query above could also be specified with the command:
+.Pp
+.Dl syslog -k Sender portmap -o -k Level Nle warning
+.Pp
+.Pp
A special convention exists for matching time stamps.
An unsigned integer value is regarded as the given number of seconds since
0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.
An negative integer value is regarded as the given number of seconds before the current time.
-For example, to find all messages of priority level 3 (error) or less which were logged in the last 30 seconds:
+For example, to find all messages of Error priority level (3) or less which were logged in the last 30 seconds:
.Pp
-.Dl syslog -k Level Nle 3 -k Time ge -30
+.Dl syslog -k Level Nle error -k Time ge -30
.Pp
a relative time value may be optionally followed by one of the characters
.Dq s ,
to specify seconds, minutes, hours, days, or weeks respectively.
Upper case may be used equivalently.
A week is taken to be 7 complete days (i.e. 604800 seconds).
-.Ss PRUNING
-The Apple System Log facility saves received messages, subject to filtering criteria described in the
-FILTERING CONTROLS section below.
-Pruning is required to prevent unlimited growth of the data store.
-.Pp
-The
-.Nm syslogd
-daemon itself will prune the data store shortly after it starts up.
-See the
-.Xr syslogd 8
-manual for more details on startup pruning.
-During extended operation of
-.Nm syslogd ,
-pruning is accomplished by using the
-.Fl p
-option of
-.Nm syslog .
-The
-.Fl p
-option must be followed by an expression (see above).
-The contents of the data store are filtered using the given expression.
-Messages that match the expression are deleted.
-.Pp
-A daily pruning operation is performed by the
-.Nm cron
-utility.
-The command is specified in the /etc/periodic/daily/500.daily file.
.Ss FILTERING CONTROLS
Clients of the Apple System Log facility using either the
.Xr asl 3
The filtering described above takes place in the client library to determine which messages are sent to the
.Nm syslogd
daemon.
-The daemon also contains a filter which determines which messages are saved in the data store.
-Note that this additionally determines which messages are seen when reading messages using the
+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.
+utility, or when viewing data store messages in the Console utility application.
.Pp
-The default data store filter mask saves messages with priority levels from Emergency to Notice (level 0 to 5).
+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:
.Pp
.Dl syslog -c syslogd
For example, to save messages with priority level Error or less in the data store:
.Pp
.Dl syslog -c syslog -e
+.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,
+.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.
.Sh SEE ALSO
.Xr syslogd 8 ,
.Xr logger 1 ,
projects / apple / syslog.git / blobdiff