syslog

Apple System Log utility

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

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

syslog -C

syslog [-f file] [-d dir …] [-B] [-w [n]] [-F format] [-T format] [-E format] expression

syslog [-f file] [-d dir …] -x file expression

syslog -c process [mask]

syslog -config [options]

syslog -module [name [action]]

syslog -help

Command-line utility for tasks of the Apple System Log (ASL) facility: sending, viewing , copying messages to ASL format data store (/var/log/asl) and controlling the flow of messages from client processes.

Without arguments, syslog outputs all messages, formated and encoded, from the active data store to standard output.

The syslogd daemon filters and saves messages to files as specified in /etc/syslog.conf
Messages may be read-access controlled for specific users. See Expressions

Sending Messages

-s sends a message
-r host to a remote server
-k key value [] structured message.
Keys and values with embedded white space must be enclosed in quotes.

Message key is folllowed by a value with the text of the message.

The rest of the command line is treated as the message text.

-l { emergency | 0 |
alert | 1 |
critical | 2 |
error | 3 |
warning | 4 |
notice | 5 |
info | 6 |
debug | 7 default ]
level (priority).
Panic is an alias for Emergency.
P or Em may be used for Panic / Emergency, and Er or X for Error.

Displaying messages

-C console messages, alias for : -k Facility com.apple.console
-d { store | directory |archive [] reads or searchs data store readable files in store opens readable files in the ASL store directory /var/log/asl.
archive opens readable files in the default ASL archive directory /var/log/asl.archive.
directories or
-f file [] process an ASL data store file
-x file export a legacy file to a ASL data store file with -f
Useful when searching archived files, files on alternate volumes or exports.
-B Begin processing messages from the time of the last Boot.
-w [n | all |boot|-B] Output n (default 10) messages. Then wait for new messages.
similar to tail -n 10 -f
Boot or -B outputs messages since the last boot .
-T use local time or UTC
-E
safe default encoding for syslog output.
Carriage returns are mapped to newlines.
A tab character is appended after newlines so that message text is indented.
Encodes backspace characters as ^H.
vis C-style backslash encoding similar to that produced with vis -c

none  
-F fmtoutput format

Non-printable and control characters are encoded by default. Messages containg tabs and newlines become ugly.

Messages are output in a format similar to system.log with the priority between angle-brackets < >.

fmt may be:

Format styles may be followed by a dot and an integer value, Display n digits of sub-second times from TimeNanoSec key in the ASL message or 0. for example:
 syslog -F std.4
syslog -F '$((Time)(utc.6)) $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message

produces output similar to std .

Variables

"$(Name)" must be used if the name is not delimited by white space.

$((Level)(str))"Error", "Alert", "Warning", and so on.
$(Level) or
$Level
0 through 7.
$((Time)(sec)) $((Time)(raw)) ssssssss seconds since the Epoch.
$((Time)(local))
$((Time)(lcl))
"Mmm dd hh:mm:ss", where Mmm is the abbreviation for the month, dd is the date (1 - 31). The local timezone is used.
$((Time)(utc))
$((Time)(zulu))
"yyyy-mm-dd hh:mm:ssZ", using Coordinated Universal Time, or the "Zulu" time zone.
$((Time)(X)) "yyyy-mm-dd hh:mm:ssX", using the specified nautical timezone.
Where X is the time zone.
Z for UTC/Zulu time.
J indicates local timezone.
A - M (except J) decrease by one hour to the east of the Zulu time zone.
N - Y increase by one hour to the west of Z.
M and Y have the same clock time, but differ by one day.
$((Time)(J)) yyyy-mm-dd hh:mm:ss no timezone
$((Time)(JZ)) yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]". local timezone. Minutes in the timezone offset if non-zero . The timezone offset from UTC follows the date and time.
$((Time)(ISO8601)) yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]".
Minutes in the local timezone and ISO 8601 extended . The timezone offset from UTC follows the date and time. timezone offset are only output if non-zero. this differs from "JZ" only in that a "T" character separates the date and time.
$((Time)(ISO8601B)) yyyymmddThhmmss[+|-]HH[:MM]. the local timezone and ISO 8601 , :
$((Time)(ISO8601Z)) UTC/Zulu time and ISO 8601 extended , : "yyyy-mm-ddThh:mm:ssZ".
$((Time)(ISO8601BZ)) UTC/Zulu time and ISO 8601 , : "yyyymmddThhmmssZ".
$((Time)([+|-]HH[:MM])) "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]". an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC. Minutes in the timezone offset only if non-zero.

If a custom format is not used Time values are generally converted to local time,
The -T may be used to control the format used for timestamps.
The value of format may be :

sec or raw number of seconds since the epoch.
local or lcl converted to the local time zone, with mmm dd hh:mm:ss
where mmm is the month name abbreviated as three characters.
utc or zulu UTC with yyyy-mm-dd hh:mm:ssZ
A-Z nautical time zone, as UTC.
J local timezone without a trailing timezone letter.
JZ local timezone with yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]. The trailing [+|-]HH[:MM] represents the local timezone offset from UTC in hours, or in hours and minutes if minutes are non-zero.
ISO8601 yyyy-mm-ddThh:mm:ss[+|-]HH[:MM].

> the same as JZ , a with "T separating the date and time

[+|-]hh[:mm] offset to adjust time.

Each of the formats may be followed by a dot and an integer to display subsecond time values. For example:

syslog -T bsd.3

The -u is a short form for - T utc.

Text in the "std", "bsd", and "raw" formats is encoded as it is by the vis with -c . `Newlines and tabs are also encoded as "\n" and "\t" respectively.
In "raw" format, spaces in log message keys are encoded as "\s" and embedded brackets are escaped to output as "\[" and "\]".

XML requires that keys are valid UTF8 strings otherwise they are ignored, and the value is not output.
Values of UTF8 are output as strings.
Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
control characters are encoded as "&#xNN;" where NN is the hexadecimal value.
Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.

The -E explicitly controls the text encoding. The value of format may be one of the :

The intent of the "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 "safe" or "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 "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.

If no further command line options are specified, syslog displays all messages, or copies all messages to a data store file. However, an expression may be specified using the -k and -o options.

<>h3>EXPRESSIONS Expressions specify matching criteria. They may be used to search for messages of interest.

A simple expression has the form:

-k key [[op] val]

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 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:

           syslog -k Sender portmap
Note that the -C option is treated as an alias for the expression:
           -k Facility com.apple.console
This provides a quick way to search for console messages.

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 More complex search expressions may be built by combining two or more simple expressions. A complex expression that has more than one "-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:

syslog -k Sender portmap -k Time ge -2h finds all messages sent by portmap in the last 2 hours (-2h means "two hours ago").

The -o 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 -o options, then a match occurs is a message matches any of the sub-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 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:

           syslog -k Sender portmap -o -k Level Nle warning
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 Error priority level (3) or less which were logged in the last 30 seconds:

syslog -k Level Nle error -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).

Filtering Controls

which messages should be sent to syslogd by specifying a yes/no setting for each priority level.

A global "master" filter mask is normally "off", meaning that it has no effect.
Master filter mask uses PID of 0
A value set for the master filter mask overrides the local filter mask for all processes.
Root access is required to set the master filter mask value.
Process filter mask uses PID or name overrides the local and the master filter mask.

-c 0|PID|name display filter.
If a name is used, it must uniquely identify a process. Display master filter mask:
 syslog -c 0
-c 0|PID|name [-]p|a|c|e|w|n|i|d Set filter.

To cut off messages with a priority, a preceded by a minus sign filter mask starting at level 0 (Emergency) "up to" the given level.
For example, to set the master filter mask to cause all processes to log messages from Emergency up to Notice only:

 syslog -c 0 -n
Root access is required to set the per-process filter mask for system (UID 0) processes.

SERVER CONFIGURATION

When syslogd starts up, and when it receives a HUP signal, it reads its configuration settings from /etc/asl.conf. When the remote-control mechanism is used to change the filter of a process, syslogd will save any messages received from that process until the remote-control filter is turned off.

-config flag change configuration parameters temporarily, For example, to temporarily disable the kernel message-per-second limit:
 syslog -config mps_limit 0
Only the superuser may change configuration parameters.
-config reset will cause syslogd to reset its configuration.

ASL OUTPUT MODULES

ASL Output Modules are named configuration bundles used by the ASL server syslogd, and by the ASL file system manager aslmanager.

/etc/asl.conf represents the system's primary output module, and is given the name "com.apple.asl".

i# configuration file for syslogd and aslmanager
##

# aslmanager logs
> /var/log/asl/Logs/aslmanager external style=lcl-b ttl=2

# authpriv messages are root/admin readable
? [= Facility authpriv] access 0 80

# remoteauth critical, alert, and emergency messages are root/admin readable
? [= Facility remoteauth] [<= Level critical] access 0 80

# broadcast emergency messages
? [= Level emergency] broadcast

# save kernel [PID 0] and launchd [PID 1] messages
? [<= PID 1] store

# ignore "internal" facility
? [= Facility internal] ignore

# save everything from emergency to notice
? [<= Level notice] store

# Rules for /var/log/system.log
> system.log mode=0640 format=bsd rotate=seq compress file_max=5M all_max=50M
? [= Sender kernel] file system.log
? [<= Level notice] file system.log
? [= Facility auth] [<= Level info] file system.log
? [= Facility authpriv] [<= Level info] file system.log

# Facility com.apple.alf.logging gets saved in appfirewall.log
? [= Facility com.apple.alf.logging] file appfirewall.log file_max=5M all_max=50M
Other modules are read from files in /etc/asl , file names serve as module names.
ASL Output Modules are described in detail in asl.conf(5).
com.apple.iokit.power    com.apple.MessageTracer   
com.apple.authd          com.apple.login.guest
com.apple.cdscheduler    com.apple.mail
com.apple.coreduetd      com.apple.mkb.internal
com.apple.eventmonitor   com.apple.networking.boringssl
com.apple.install        com.apple.performance
com.apple.mkb            com.apple.contacts.ContactsAutocomplete     

-module

When invoked with -module[name] syslog outputs all loaded ASL Output Modules, files and ASL store directories, configuration rules, and current enabled or disabled status. Sample

enable
disable
The name '*' (including the quotes ) may be used to change the status of all Output Modules, excluding the primary com.apple.asl module which may be enabled or disabled be specificing the name.
Only the superuser (root) may enable or disable a module.
syslog -module name enable [0] 
checkpoint Forces module to checkpoint all of its rotated files, or just the single optionally named file.
The name '*' (including the apostrophes) forces checkpointing of all rotated files for all Modules, including the primary com.apple.asl .
Only the superuser (root) may force files to be checkpointed.

Waits for a reply from syslogd after files in use have been checkpointed.

 syslog -module '*' checkpoint 

SEE log(1), logger(1), asl(3), syslog(3), asl.conf(5), syslogd(8)

other versiuon </a><p>