SYSLOG(1)

NAME
syslog - Apple System Log utility

SYNOPSIS
syslog -help

syslog -s [-r host] [-l level] message...

syslog -s [-r host] -k key val [key val] ...

syslog [-w] [-F format] expression

syslog -p expression

syslog -c process [filter]

DESCRIPTION
syslog is a command-line utility for a variety of tasks relating to the Apple System Log facility. It provides mechanisms for sending and viewing log messages, pruning the contents of the system's log message data store, and for controlling the flow of log messages from client processes.

When invoked with the -help option, syslog prints a usage message.

  SENDING MESSAGES
The -s option is used send log messages to the syslogd(8) log message daemon, either locally or to a remote server if the -r host option in used.

There are two main forms of the command. If the -k option is used, then it must be followed by a list of keys and values. 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.

If the -k option is not specified, then the rest of the command line is treated as the message text. The text may be preceded by -l level to set the log level (priority) of the message. Levels may be an integer value corresponding the the log levels specified in syslog(3) or asl(3), or they may be a string. String values are case insensitive, and should be one of:

Emergency
    (level 0)
Alert
    (level 1)
Critical
    (level 2)
Error
    (level 3)
Warning
    (level 4)
Notice
    (level 5)
Info
    (level 6)
Debug
    (level 7)

The string “Panic” is an alias for “Emergency”. syslog only requires one or two leading characters for a level specification. A single character suffices in most cases. Use “P” or “” for Panic / Emergency, and “” or “X” for Error).

  READING MESSAGES
The 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.

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 syslog.conf(5) file. The output files specified in that configuration may be examined by any file printing or editing utility, e.g.

    cat /var/log/system.log

Another module saves messages in a data store, which may be searched using the syslog command.

If invoked with no arguments, syslog simply prints all of the messages saved in the data store. If the -w option is used, syslog waits for new messages to be added to the data store. Messages already in the store are ignored. This usage is similar to watching a log file using, e.g.

    tail -f /var/log/system.log

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.

The -u option forces all time stamps to be printed using UTC. This overrides printing of time stamps using the local time zone.

The output format may by changed by specifying the -F format option. The value of format may be one of the following:

bsd Format used by the syslogd daemon for system log files, e.g. /var/log/system.log.

std Standard (default) format. Similar to “bsd”, but includes the message priority level.

raw 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.

The value of the format argument may also be a custom print format string. A custom format should in most cases be enclosed in single quotes to prevent the shell from substituting special characters and breaking at white space.

Custom format strings may include variables of the form “$Name” (or “$(Name)” if the variable is not delimited by whitespace) which will be expanded to the associated with the named key. For example, the command:

    syslog -F '$Time $Host $(Sender)[$(PID)]: $Message'

produces output similar to the “bsd” format.

If no further command line options are specified, syslog displays all messages, either all those saved in the data store, or all new messages if -w is used. However, an expression may be specified using the -k and -o options.

  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 -p option.

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:

    syslog -k Sender portmap

The -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 three arguments are given, they are of the form -k key operation value. syslog supports the following matching operators:

eq  equal
ne  not equal
gt  greater than
ge  greater than or equal to
lt  less than
le  less than or equal to

Additionally, the operator may be preceded by one or more of the following modifiers:

C   case-fold
R   regular expression (see regex(3))
S   substring
A   prefix
Z   suffix
N   numeric comparison

An simple expression matches a message if all of the key-value operations match. Logically, the result is an AND of all of key-value operations. The -o option separates simple expressions and provides an OR operation. If two or more simple expressions are given, separated by -o options, then a match occurs is a message matches any of the simple expressions. For example, to find all messages which have either a “Sender” value of “portmap” or that have a numeric priority level of 4 or less:

    syslog -k Sender portmap -o -k Level Nle 4

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:

    syslog -k Level Nle 3 -k Time ge -30

a relative time value may be optionally followed by one of the characters “s”, “m”, “h”, “d”, or “w” 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).

  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.

The syslogd daemon itself will prune the data store shortly after it starts up. See the syslogd(8) manual for more details on startup pruning. During extended operation of syslogd, pruning is accomplished by using the -p option of syslog. The -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.

A daily pruning operation is performed by the cron utility. The command is specified in the /etc/periodic/daily/500.daily file.

  FILTERING CONTROLS
Clients of the Apple System Log facility using either the asl(3) or syslog(3) interfaces may specify a log filter mask. The mask specifies which messages should be sent to the syslogd daemon by specifying a yes/no setting for each priority level. Many clients set a filter mask to avoid sending relatively unimportant messages. Debug or Info priority level messages are generally only useful for debugging operations. By setting a filter mask, a process can improve performance by avoiding spending time sending messages that are in most cases unnecessary.

The -c option may be used to control filtering. In addition to the internal filter value that processes may set as described above, the system maintains a global “master” filter. This filter is normally “off”, meaning that it has no effect. If a value is set for the master filter, it overrides the local filter for all processes. Root user access is required to set the master filter value.

The current setting of the master filter mask may be inspected using:

    syslog -c 0

The value of the master filter mask my be set by providing a second argument following -c 0. The value may a set of characters from the set “pacewnid”. These correspond to the priority levels Emergency (Panic), Alert, Critical, Error, Warning, Notice, Info, and Debug. The character “x” may be used for Error, as it is used for sending messages. The master filter may be unset with:

    syslog -c 0 off

Since it is common to use the filter as a “cutoff” mechanism, for example to cut off messages with Debug and Info priority, a single character from the list above may be specified, preceded by a minus sign. In this case, syslog uses a filter mask starting at level 0 (Emergency) “up to” the given level. For example, to set the master filter level to cause all processes to log messages from Emergency up to Debug:

    syslog -c 0 -d

While the master filter level may be set to control the messages produced by all processes, another filter mask may be specified for an individual process. If a per-process filter mask is set, it overrides both the local filter mask and the master filter mask. The current setting for a per-process filter mask may be inspected using -c process, where process is either a PID or the name of a process. If a name is used, it must uniquely identify a process. To set a per-process filter mask, an second argument may be supplied following -c process as described above for the master filter mask. Root access is required to set the per-process filter mask for system (UID 0) processes.

The filtering described above takes place in the client library to determine which messages are sent to the 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 syslog utility.

The default data store filter mask saves messages with priority levels from Emergency to Notice (level 0 to 5). The level may be inspected using:

    syslog -c syslogd

To set the data store filter mask, an second argument may be supplied following -c syslog as described above. For example, to save messages with priority level Error or less in the data store:

    syslog -c syslog -e

SEE ALSO
syslogd(8), logger(1), asl(3), syslog(3),

HISTORY
The syslog utility appeared in Mac OS X 10.4.