|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
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) facil-ity. facility.
ity. 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 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.
Note that the text of the log message should be supplied as a value following 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 specification. A single character suf-fices suffices
fices 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 mes-sages messages
sages 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 messages. 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.ar-chive. /var/log/asl.archive.
chive. 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.
Specifying ``-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 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.
The output format may by changed by specifying the -F format option. Non-printable and control charac-ters characters
ters are encoded by default. Text encoding 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 message is represented as a dic-tionary dictionary
tionary 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 character 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 exam-ple, example,
ple, 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 message 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 abbreviation 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 Universal 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 offset from UTC follows the date
and time. The time is formatted as ``yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]''. Min-utes Minutes
utes 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 off-set offset
set from UTC follows the date and time. The time is formatted 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'' character 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 format, in the form:
``yyyymmddThhmmssZ''.
$((Time)([+|-]HH[:MM])) Specifies an offset (+ or -) of the indicated number of hours (HH) and option-ally optionally
ally 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-second time values will be printed. For example, the follow-ing following
ing 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 values, then Time values are gener-ally generally
ally 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 characters.
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 character 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 message text is indented.
none No encoding is used.
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 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 mes-sages messages
sages 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 follow-ing following
ing 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
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 pro-cesses processes
cesses 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 _. 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 Emer-gency Emergency
gency 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 over-rides overrides
rides 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 syslogd server follows filtering rules specified in the /etc/asl.conf file. When the remote-con-trol remote-control
trol 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 example, 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 Output Modules. The summary
includes the output files and ASL store directories used by each module, a list of the module's config-uration configuration
uration 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 checkpointed 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
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.