| ASL.CONF(5) | File Formats Manual | ASL.CONF(5) |
asl.conf —
configuration file for syslogd(8) and
aslmanager(8)
The syslogd(8) server reads the /etc/asl.conf file at startup, and re-reads the file when it receives a HUP signal. The aslmanager(8) daemon reads the file when it starts. See the ASLMANAGER PARAMETER SETTINGS section for details on aslmanager-specific parameters.
If the /etc/asl directory exists, then
syslogd and aslmanager will
read each file it contains. These files must have the same format as
asl.conf. Each file configures an independent
module, identified by the file name. Modules may be enabled or disabled
independently. Each module may specify its own set of rules for acting on
received messages. See the ASL MODULES section for details.
The files contain several types of lines, described below. Each type is identified by the first non-whitespace character in the line.
Parameter setting lines in the configuration file are generally of the form:
= parameter_name value
...Most parameter settings require a single value, although some may take several values. See the PARAMETER SETTINGS section for details.
Query-action rules in the file generally have the form:
? query action ...This directs syslogd to perform the
specified action when a received message matches the given query. Actions
may be followed by optional arguments. See the QUERY-ACTION RULES section
for details.
Most query-action rules specify output files or ASL-format data stores where matching messages should be saved. The optional parameters for those rules can specify a number of options for these outputs. As a convenience, these configuration options may be specified on a separate line. Output configuration settings in the file begin with a greater-than sign “>” followed by a file or ASL directory name and the configuration options for that file or directory. These lines generally have the form:
> filename option ...See the OUTPUT CONFIGURATION SETTINGS section for details.
Comment lines are ignored.
The following parameter-settings are recognized by
syslogd.
syslogd. User processes are limited to 36000
messages per hour. The limit for a user process is not enforced if a
remote-control ASL filter is in place for the process. See the
syslog(1) manual for enabling a remote-control filter
using the -c option with the
syslog command.
Query-action rules are used to cause
syslogd to perform specific actions when received
messages match a specified query pattern. For example, to save certain
messages in a file. The rules are processed in the order in which they
appear in the file. This matters because some actions can affect further
processing. For example, an “ignore” action causes
syslogd to stop processing the rules in a file for
messages that match a given query pattern.
Query-action rules contain three components: a query, an action,
and optional parameters specific to that action. For example, the following
rule matches log messages sent by the “example” process which
have log priority levels in the range emergency to error. If a received
message matches, syslogd posts a BSD notification
for the key “com.example.log_message”.
? [= Sender example] [<= Level
error] notify com.example.log_messageQueries comprise one or more message matching components, each of which has the form:
[OP KEY VAL]OP is a comparison operator. It can have the following values:
It can also be preceded by one or more modifiers:
KEY and VAL are message keys and values. For example
[= Sender example]matches any message with value “example” for the “Sender” key. The query
[CA= Color gr]matches any message with a value beginning with the letters GR, Gr, gr, or gR ( “C” meaning casefold, “A” meaning prefix) for the “Color” key. The example query above,
[= Sender example] [N< Level
3]matches any message from “example” with a level numerically less than 3 (string values are converted to integers, and the comparison is done on the integer values). Note that the string values may be used equivalently for the Level key, so the example above may also be written as:
[= Sender example] [< Level
Error]String values for levels may be any of the set “emergency”, “alert”, “critical”, “error”, “warning”, “notice”, “info”, or “debug”. These strings may be upper, lower, or mixed case.
The “T” operator is useful to test for the presence of a particular key.
[T Flavor]Will match any message that has a “Flavor” key, regardless of its value.
Note that space characters and closing square bracket characters (']') are specially processed. The first space character following the beginning of a key delimits the key. The first closing square bracket following the beginning of a value delimits the value. So '[= foo bar ]' will match messages which have a key 'foo' with the value 'bar ', including a trailing space character.
As a special case, the query
*matches all messages.
The following actions are available.
syslogd to save matching messages in the
ASL database. Note that if /etc/asl.conf contains no “store”
action rules, then syslogd will save all messages
it receives in the ASL database.
syslogd will treat the given path as
relative to /var/log (for /etc/asl.conf), or for other output modules
relative to /var/log/module/NAME where NAME is the module name.
By default, the file's owner will be root, and the file will be readable by the admin group. Various options may follow the file name to specify ownership and access controls, printed log message format, and controls for file rotation, compression, time-to-live, and other aspects of output file life-cycle management. See the OUTPUT CONFIGURATION SETTINGS section for more details.
Messages saved to an ASL directory are saved in files that are named “yyyy.mm.dd.asl”, where “yyyy”, “mm”, and “dd” are the year, month (01 to 12) and day of the month (01 to 31) associated with matching messages. This has the effect of saving messages in a separate file for each day.
By default, files in the directory will be owned by root, and readable by the admin group. Various options may follow the directory name to control ownership, access controls, and the management of the store and its contents. See the OUTPUT CONFIGURATION SETTINGS section for a list of options that may be set for store directories.
syslogd to post a notification with
notify_post().
The notification key must appear as a single parameter following the
“notify” action.
The “claim” action may be followed by the keyword “only”. In this case, only those messages that match the “claim only” query will be processed by subsequent rules in the module.
syslogd will restrict read access to
matching messages to a specific user and group. The user ID number and
group ID number must follow the “access” keyword as
parameters.
Various options may follow the path name in a “file” or “directory” query-action rule. For example, the following rule specifies that all messages from the “example” facility will be saved in the file “example.log”, and that messages are printed in a “raw” format that shows all the keys and values in the message:
? [= Facility example] file
example.log format=rawMultiple options may be specified separated by whitespace characters. For example:
? [= Facility example] file
example.log format=raw rotate=local compress ttl=3 mode=0640 uid=0 gid=5
gid=20As a convenience, a file or directory name and any associated options can be specified on a separate output configuration line following a “>” character:
> example.log format=raw
rotate=local compress ttl=3 mode=0640 uid=0 gid=5 gid=20Options for a file or directory are taken from the first query-action rule or output configuration line for the given path. A good usage pattern for multiple rules that specify the same output file or directory is:
> example.log options
...? query1 file
example.log? query2 file
example.log? query3 file
example.logMost of the options listed below may be used with either file or directory outputs. Exceptions are noted.
The format is specified by the value given for FMT. Several pre-defined formats are available:
syslogd daemon for system
log files, e.g. /var/log/system.log.syslog command line utility with the use of
the -f path option.Custom format strings may also be specified. Since custom formats often contain white-space characters, the entire string may be enclosed in single or double quote characters, or each white-space character may be preceded by a backslash escape character. Escaped characters are not interpreted. Custom format strings are described in detail in the READING MESSAGES section of the syslog(1) manual.
syslogd starts and may create the log file before
network directory services are available. Unknown UIDs and GIDs will be
ignored when setting access controls.
--- last message repeated N times
---The following options all deal with file rotation and life-cycle management. The FILE ROTATION section describes this in detail.
If the option “rotate” appears without a value, the naming style defaults to “sec”.
aslmanager will move files to the
directory given by PATH.
syslogd ignore write errors when saving
messages. Normally, syslogd will stop saving to a
file or ASL directory after 5 consecutive write errors.
syslog -d or using
the asl(3) API. Messages in compressed data files will
not be available until the files are un-compressed.
syslogd and a new file
is opened. Note that “file_max” specifies a size limit
before file compression is performed if the “compress”
option is also present.
aslmanager will delete rotated files, oldest
first, to reduce the total below the limit. SIZE may be specified in the
same format as the file_max option.
syslogd to add a timestamp to the file name
when it is created. For example,
will result in syslogd writing to, e.g. “example.log.20120625T070000Z” rather than to “example.log”. Note that this option does nothing with sequenced (``seq'') files.
syslogd to create a symlink with the unstamped
file name to the currently active log file. For example,
will result in syslogd writing to, e.g. “example.log.T1340607600”, and creating a sybolic link from “example.log” to the active file.
syslogd and
aslmanager work together to provide the features of
file rotation. This section describes the file rotation options that may be
used in /etc/asl.conf or an ASL Output Module configuration file, together
with a description of how the system works to support those features.
File rotation or file rolling is enabled by the “rotate” output configuration option. It is typically specificed with a value which specifies the naming sytle for rotated files. Name styles may simply be a timestamp format, which is appended to the filename.
Note that using the local timezone for timestamped files may cause
odd behavior on highly mobile systems. aslmanager
will delete files after a specified time-to-live (see below). The age of the
file is determined by the file name. If files are created in different
timezones but saved with a non-absolute timestamp, the age calculation may
result in some files being considered older or newer than they are in
reality.
Also note that sequenced files (using the “seq”
style) will initially be checkpointed using a file name containing a
timestamp in seconds. aslmanager will re-sequence
the files when it scans for checkpoint files.
Alternatively, the name style may be have two or three components. The first component is the “base” name of the file, with no filename extension. The base name may be followed by a timestamp format and optionally by a filename extension, or the base name may be followed by an extension (the extension is optional) and a timestamp format. These components must be separated by a dot character.
For example, this output configuration line specifies that the output file “example.log” should be rotated to create the files “example.0.log”, “example.1.log”, and so on.
> example.log
rotate=example.seq.logIf a file is marked for rotation, syslogd
will close the file at the start of a new day or when the file exceeds its
“file_max” size limit. At that point,
syslogd renames the file with the file's creation
time included in its name (unless the basestamp option is present, in which
case the file's creation time is already included in the filename) and
starts a new file to continue logging. This operation is called
checkpointing the file.
For example, syslogd might close
“example.log” and rename it
“example.log.T1340521200”, 1340521200 being the time that the
file was created. It would then start a new “example.log” file
and use it until midnight, when the cycle would be repeated.
Files are normally checkpointed at midnight. If the system is sleeping or powered off, then files are checkpointed when the the first message of a new day (local time) is received. Files are also checkpointed if they exceed a size limit specified by a file_max option, and they may be checkpointed manually through options provided by the syslog(1) and aslmanager(8) utilities. The checkpointed file name always contains the file's creation time. If the options for the file include “rotate=utc” then the timestamp will be a UTC date and time string. “rotate=local” causes the timestamp to be the date and time in the current local timezone. Otherwise, the timestamp will be in seconds since the epoch.
syslogd only performs the checkpointing
operation. It closes old files, moves them out of the way, and starts
writing new files. Most of the work of file rotation is done by the
aslmanager(8) utility. That includes moving files to a
destination directory, compressing files, re-naming files according to one
of the naming style options, deleting old files after they exceed their
time-to-live, and checking file space usage.
aslmanager normally runs once during
system start-up, and once a day just after midnight. It may also be
triggered occasionally by syslogd, and it may be run
manually.
aslmanager scans for any checkpointed
files created by syslogd and will rename the files
(if required) to match the naming style specified by the
“rotate=NAME_STYLE” option. If “rotate=seq” is
specified for a file, checkpointed files created by
syslogd contain a timestamp in seconds. These files
are renamed so that the file names contain a sequence number. The most
recent version has the number “0”, and older versions have
higher numbers. For example:
example.log.0example.log.1example.log.2...As well as renaming files, aslmanager may
perform other actions. If the file has been given a
“dest=PATH” option, the rotated versions of the file will be
moved to the specified directory. Files will be gzip compressed using the
zlib(3) library if the “compress” option has
been given. If the total size of all the rotated versions of the file
exceeds a value given in an “all_max” option, older versions
of the rotated file will be deleted to keep the total below the specified
limit.
Although checkpoint and file rotation operations are normally done
automatically, aslmanager supports an option that
will trigger syslogd to checkpoint files before
aslmanager starts its scan.
syslog also supports an option to force files to be
checkpointed without running aslmanager. See the
aslmanager(8) and syslog(1) manuals for
details.
Programmatically, an asl(3) message may be sent to syslogd to force it to checkpoint either a single file, or to checkpoint all files for a particular ASL module. To checkpoint all files:
const char *module_name;
//TODO: set module_name
asl_object_t ctl = asl_new(ASL_TYPE_MSG);
asl_set(ctl, ASL_KEY_OPTION, "control");
asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s checkpoint",
module_name);
asl_release(ctl);
To checkpoint just one file:
const char *module_name;
const char *file_name;
//TODO: set module_name
//TODO: set file_name
asl_object_t ctl = asl_new(ASL_TYPE_MSG);
asl_set(ctl, ASL_KEY_OPTION, "control");
asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s checkpoint %s",
module_name, file_name);
asl_release(ctl);
An ASL output module is created by a configuration file in the
directory /etc/asl. The file name is used as the module's name. The format
of the file is generally the same as asl.conf with a
few exceptions. Modules may not have parameter setting lines for the system
parameters listed in the PARAMETER SETTINGS or ASLMANAGER PARAMETER SETTINGS
sections, nor may they include “broadcast” query-action
rules.
Module configuration files are read by
syslogd when it starts, and whenever it gets a HUP
signal. Messages received by syslogd are first
processed according the the rules found in /etc/asl.conf (also known as the
“com.apple.asl” module), then the message is processed by the
rules from each module found in /etc/asl.
An exception to this is that messages that match the query in a “claim” action rule in any module are not processed by the rules in /etc/asl.conf.
ASL output modules are enabled by default, but a module may include a parameter setting:
= enable 0The module is still loaded by syslogd, but
the module will not save messages to files or directories, and will not post
BSD notifications.
Several mechanisms allow modules to be enabled or disabled dynamically. One mechanism allows the setting of the “enable” parameter to be based on the existence of a path in the filesystem, or on the value associated with a dictionary key in a property list file. On iOS only, the value of a key in an installed configuration profile may be tested.
To enable a module based on the existence of a file, the module may use:
= enable [File /a/b/c]where “/a/b/c” may be any filesystem path.
To enable a module based on the value of a dictionary key in a property list file,
= enable [Plist /path/config.plist]
[= SomeKey SomeValue]Any of the test operations described above in the QUERY-ACTION RULES section may also be used in testing key / value pairs. Multiple operations are also allowed, for example:
= enable [Plist /path/config.plist]
[N>= DebugLevel 7] [S= Othervalue xyz]If the property list file does not exist, the test will evaluate to zero. The file may be in binary or xml format. It may only contain a single dictionary object at its top level. Only keys and values at the top level of the dictionary may be tested. Values must be strings, integer values, doubles, UUIDs, dates, or booleans. Boolean <true/> and <false/> values are converted to 1 and 0 respectively. Values are converted into strings, and string comparisons are used unless unless an “N” modifier is specified with the test operator.
On iOS, a module may test key / value pairs in a configuration profile using the same key / value tests that may be used for property list files.
= enable [Profile name] [= Verbose
1]The profile name is the value of its DefaultsDomainName key. The test will evaluate to zero if the profile is not installed.
A module may be also enabled or disabled using
syslog or by sending syslogd
a special asl(3) control message. Only the user
“root” may enable or disable modules.
A module may be enabled or disabled by sending an asl(3) message as shown in this example:
int enable;
const char *module_name;
//TODO: set module_name
//TODO: set enable to 0 or 1
asl_object_t ctl = asl_new(ASL_TYPE_MSG);
asl_set(ctl, ASL_KEY_OPTION, "control");
asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s enable %d", module_name,
enable);
asl_release(ctl);
A control message may also be sent using
syslog as the following example shows to disable a
module named “com.apple.example”:
sudo syslog -module com.apple.example
enable 0A module may also enable or disable itself. Although a module that is not enabled will not write or post notifications, it still will scan messages. The module may contain conditional parameter-setting rules like:
= [= Color Green] enable
1= [= Color Red] enable 0This is similar to a query-action rule. If a message received by syslogd matches the specified query, in this case having a Color key with the value Green or Red, then the enable parameter is set as specified. So in this example, the module would be enabled and disabled whenever syslogd received a message containing the appropriate value for the “Color” key.
The following parameter-settings are recognized by
aslmanager.
aslmanager. The
default is /var/log/asl. Note that this parameter is ignored by
syslogd.
| September 19, 2008 | macOS |