manpagez: man pages & more
man syslog(1)
Home | html | info | man
syslog(1)                 BSD General Commands Manual                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 -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 [filter]

     syslog -config [options]

     syslog -module [name [action]]


DESCRIPTION

     syslog 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, copying log messages to ASL format data store
     files, and for controlling the flow of log messages from client pro-
     cesses.

     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.

     Note that the text of the log message should be supplied as a value fol-
     lowing the ``Message'' key.

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

     If the -l option is omitted, the log level defaults to 7 (Debug).

     syslog only requires one or two leading characters for a level specifica-
     tion.  A single character suffices in most cases.  Use ``P'' or ``Em''
     for Panic / Emergency, and ``Er'' or ``X'' for Error).

   READING MESSAGES
     The syslogd daemon filters and saves log messages to different output
     streams.  One module saves messages to files specified in the
     syslog.conf(5) file.  Those log files may be examined with any file
     printing or editing utility, e.g.

           cat /var/log/system.log

     Another module saves messages in a data store (/var/log/asl).

     If invoked with no arguments, syslog 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, so only messages that are readable
     by the user running syslog will be fetched and printed.

     If invoked with the -C option, syslog fetches and prints console mes-
     sages.  The -C option is actually an alias for the expression:

           -k Facility com.apple.console

     See the EXPRESSIONS section below for more details.

     Individual ASL data store files may be read by providing one or more file
     names as arguments to the -f option.  This may be useful when searching
     archived files, files on alternate disk volumes, or files created as
     export files with the -x option.

     The -d option may be followed by a list of directory paths.  syslog will
     read or search all ASL data store files in those directories.  Any files
     that are not readable will be skipped.  Specifying -d with the name
     ``archive'' will open all readable files in the default ASL archive
     directory /var/log/asl.archive.  Specifying -d with the name ``store''
     will open all readable files in the ASL store directory /var/log/asl.

     Legacy ASL database files that were written by syslogd on Mac OS X 10.5
     (Leopard) may also be read using the -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 -f and -x options.

     The -B option causes syslog to start processing messages beginning at the
     time of the last system startup.  If used in conjunction with -w, all
     messages since the last system startup are displayed, or matched against
     an expression, before syslog waits for new messages.

     The -w option causes syslog to wait for new messages.  By default, syslog
     prints the last 10 messages, then waits for new messages to be added to
     the data store.  A number following the -w option specifies the number of
     messages to print and overrides the default value of 10.  For example:

           syslog -w 20

     Use the value ``all'' to view all messages in the data store before
     watching for new messages.  The value ``boot'' will display messages
     since the last system startup before watching for new messages.  Specify-
     ing ``-w boot'' is equivalent to using -w and -B together.

     Using syslog with the -w option is similar to watching a log file using,
     e.g.

           tail -f /var/log/system.log

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

     If the -x 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.

     When called without the -x option, messages are printed to standard out-
     put.  Messages are printed in a format similar to that used in the sys-
     tem.log file, except that the message priority level is printed between
     angle-brackets.

     The output format may by changed by specifying the -F format option.
     Non-printable and control characters are encoded by default.  Text encod-
     ing may be controlled using the -E option (see below).  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 as seconds since the
           epoch by default, but may also be printed in local time or UTC if
           the -T option is specified (see below).

     xml   The list of messages is printed as an XML property list.  Each mes-
           sage is represented as a dictionary in a array.  Dictionary keys
           represent message keys.  Dictionary values are strings.

     Each of the format styles above may optionally be followed by a dot char-
     acter and an integer value, for example:

           syslog -F std.4

     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.

     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'',
     ``$(Name)'', or ``$((Name)(format))''.  which will be expanded to the
     value associated with the named key.  For example, the command:

           syslog -F '$Time $Host $(Sender)[$(PID)] <$((Level)(str))>:
           $Message'

     produces output similar to the ``std'' format.  The simple ``$Name'' form
     is sufficient in most cases.  However, the second form: ``$(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 mes-
     sage priority level may appear as an integer value (e.g.  ``3'') or as a
     string (``Error'').  The following print formats are known.

     $((Level)(str))          Formats a Level value as a string, for example
                              ``Error'', ``Alert'', ``Warning'', and so on.
                              Note that $(Level) or $Level formats the value
                              as an integer 0 through 7.

     $((Time)(sec))           Formats a Time value as the number of seconds
                              since the Epoch.

     $((Time)(raw))           Alias for $((Time)(sec)).

     $((Time)(local))         Formats a Time value as a string of the form
                              ``Mmm dd hh:mm:ss'', where Mmm is the abbrevia-
                              tion for the month, dd is the date (1 - 31) and
                              hh:mm:ss is the time.  The local timezone is
                              used.

     $((Time)(lcl))           Alias for $((Time)(local)).

     $((Time)(utc))           Formats a Time value as a string of the form
                              ``yyyy-mm-dd hh:mm:ssZ'', using Coordinated Uni-
                              versal Time, or the ``Zulu'' time zone.

     $((Time)(zulu))          Alias for $((Time)(utc)).

     $((Time)(X))             Where X may be any letter in the range A - Z or
                              a - z.  Formats the Time using the format
                              ``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 ``yyyy-mm-dd
                              hh:mm:ss'', without a trailing timezone letter.

     $((Time)(JZ))            Specifies the local timezone.  The timezone off-
                              set from UTC follows the date and time.  The
                              time is formatted as ``yyyy-mm-dd
                              hh:mm:ss[+|-]HH[:MM]''.  Minutes in the timezone
                              offset are only printed if they are non-zero.

     $((Time)(ISO8601))       Specifies the local timezone and ISO 8601
                              extended format.  The timezone offset from UTC
                              follows the date and time.  The time is format-
                              ted as ``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 ``JZ'' format only in that a ``T'' charac-
                              ter separates the date and time.

     $((Time)(ISO8601B))      Specifies the local timezone and ISO 8601 basic
                              format, in the form:
                              ``yyyymmddThhmmss[+|-]HH[:MM]''.

     $((Time)(ISO8601Z))      Specifies UTC/Zulu time and ISO 8601 extended
                              format, in the form: ``yyyy-mm-ddThh:mm:ssZ''.

     $((Time)(ISO8601BZ))     Specifies UTC/Zulu time and ISO 8601 basic for-
                              mat, in the form: ``yyyymmddThhmmssZ''.

     $((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 ``yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]''.
                              Minutes in the timezone offset are only printed
                              if they are non-zero.

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

           syslog -F '$((Time)(utc.6)) $Host $(Sender)[$(PID)]
           <$((Level)(str))>: $Message

     If a custom format is not being used to specify the format for Time val-
     ues, then Time values are generally converted to local time, except when
     the -F raw option is used, in which case times are printed as the number
     of seconds since the epoch.  The -T format option may be used to control
     the format used for timestamps.  The value of format may be one of the
     following:

     sec or raw    Times are printed as the number of seconds since the epoch.

     local or lcl  Times are converted to the local time zone, and printed
                   with the format
                         mmm dd hh:mm:ss
                   where mmm is the month name abbreviated as three charac-
                   ters.

     utc or zulu   Times are converted to UTC, and printed with the format
                         yyyy-mm-dd hh:mm:ssZ

     A-Z           Times are converted to the indicated nautical time zone,
                   printed in the same format as UTC.  ``J'' is interpreted as
                   the local timezone and printed in the same format, but
                   without a trailing timezone letter.

     JZ            is interpreted as the local timezone and printed with the
                   format
                         yyyy-mm-dd hh:mm:ss[+|-]HH[:MM].
                   The trailing ``[+|-]HH[:MM]'' string represents the local
                   timezone offset from UTC in hours, or in hours and minutes
                   if minutes are non-zero.

     ISO8601       Times are printed with the format specified by ISO 8601:
                         yyyy-mm-ddThh:mm:ss[+|-]HH[:MM].
                   This is the same as the ``JZ'' format, except a ``T
                   character separates the date and time components.''

     [+|-]hh[:mm]  The specified offset is used to adjust time.

     Each of the time formats above may optionally be followed by a dot char-
     acter and an integer value.  In that case, sub-second time values will be
     printed.  For example:

           syslog -T bsd.3

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

     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
     obscuring information in log messages.

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

     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.

     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
     ``&#xNN;'' where NN is the character's hexadecimal value.

     Values that do not contain legal UTF8 are encoded in base-64 and printed
     as data objects.

     The -E format option may be used to explicitly control the text encoding.
     The value of format may be one of the following:

     vis   The default encoding described above.

     safe  Encodes backspace characters as ^H.  Carriage returns are mapped to
           newlines.  A tab character is appended after newlines so that mes-
           sage text is indented.

     none  No encoding is used.

     The intent of the ``safe'' encoding is to prevent obvious message spoof-
     ing or damage.  The appearance of messages printed will depend on termi-
     nal 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 default ``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.

   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 follow-
     ing 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 provid-
     ing 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 MES-
     SAGES section for details.  The example query above could also be speci-
     fied with the command:

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

     A special convention exists for matching time stamps.  An unsigned inte-
     ger value is regarded as the given number of seconds since 0 hours, 0
     minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.  An neg-
     ative 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
     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 sys-
     tem 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 argu-
     ment 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 exam-
     ple 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 fil-
     ter mask for system (UID 0) processes.

     The syslogd 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, syslogd will save any messages received from that process
     until the remote-control filter is turned off.

   SERVER CONFIGURATION
     When 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 -config flag (without an ``='' character).  For exam-
     ple, to temporarily disable the kernel message-per-second limit:

           syslog -config mps_limit 0

     Note that only the superuser (root) may change configuration parameters.

     In addition to the parameter setting options that are described in the
     asl.conf(5) manual page, an additional option:

           syslog -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 filesystem manager aslmanager.  The /etc/asl.conf
     file represents the system's primary output module, and is given the name
     ``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 asl.conf(5).

     When invoked with -module, syslog prints a summary of all loaded ASL Out-
     put Modules.  The summary includes the output files and ASL store direc-
     tories used by each module, a list of the module's configuration rules,
     and the module's current enabled or disabled status.  -module name prints
     a summary for the module with the given name.

     ASL Output Modules may be enabled or disabled using the command:

         syslog -module name enable [0]

     Note that only the superuser (root) may enable or disable a module.

     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.

     If a module includes rotated files, the command:

          syslog -module name checkpoint [file]

     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.

     Note that only the superuser (root) may force files to be checkpointed.

     The checkpoint action sends a command to syslogd and waits for a reply to
     be returned.  This means that any files currently in use will be check-
     pointed when the syslog command completes.


SEE ALSO

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


HISTORY

     The syslog utility appeared in Mac OS X 10.4.

Mac OS X                       October 18, 2004                       Mac OS X

Mac OS X 10.9 - Generated Sun Oct 13 13:08:28 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.