ASL.CONF(5) File Formats Manual ASL.CONF(5)
NAME
asl.conf – configuration file for syslogd(8) and aslmanager(8)
DESCRIPTION
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 settings
? Query-action rules
> Output file or directory configuration options
# Comments
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.
PARAMETER SETTINGS
The following parameter-settings are recognized by syslogd.
debug Enables or disables internal debugging output.
This is probably of little interest to most
users. The debug parameter requires a value of
“1” to enable debug output, or a value of “0” to
disable it. Debugging messages are written to
/var/log/syslogd.log.
mark_time Sets the time interval for the mark facility.
The default is 0 seconds, which indicates that
mark messages are not generated.
dup_delay Sets the maximum time before writing a “last
message repeated <N> times” message in a log file
when duplicate messages have been detected. The
default is 30 seconds.
utmp_ttl Sets the time-to-live for messages used by the
utmp, wtmp, and lastlog subsystems. The default
is 31622400 seconds (approximately 1 year).
mps_limit Sets the kernel message per second quota. The
default is value is 500. A value of 0 disables
the quota mechanism. Note that this setting only
limits the number of kernel messages that will be
saved by 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.
max_file_size Sets the maximum file size for individual files
in the ASL database. The default is 25600000
bytes.
QUERY-ACTION RULES
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_message
Query Format
Queries 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:
T true (always matches)
= equal
! not equal
> greater than
>= greater than or equal to
< less than
<= less than or equal to
It can also be preceded by one or more modifiers:
C casefold
N numeric comparison
S substring
A prefix
Z suffix
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.
Actions
The following actions are available.
store Causes 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.
file Causes matching messages to be stored in a log file.
The file's path name must follow as the first parameter.
If the path already exists, it must be a plain file. If
the file does not exist, it will be created when the
first message is written. If the pathname specified is
not an absolute path, 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.
directory Causes matching messages to be stored in an ASL-format
log message data store. A directory path name must
follow as the first parameter. If the path exists, it
must be a directory.
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.
notify Causes syslogd to post a notification with
notify_post(). The notification key must appear as a
single parameter following the “notify” action.
skip Causes a matching message to be ignored in all
subsequent matching rules in the file. Its scope is
local to a single module configuration file.
claim Messages that match the query associated with a “claim”
action are not processed by the main ASL configuration
file /etc/asl.conf. While claimed messages are not
processed by /etc/asl.conf, they are not completely
private. Other modules may also claim messages, and in
some cases two or more modules may have claim actions
that match the same messages. This action only blocks
processing by /etc/asl.conf.
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.
access Sets read access controls for messages that match the
associated query pattern. 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.
broadcast Causes syslogd to write the text of matching messages to
all terminal windows. If optional text follows the
“broadcast” keyword, then that text is written rather
that the matching message text. Note that this action
is restricted to the main ASL configuration file
/etc/asl.conf.
ignore Causes a matching message to be ignored in all
subsequent matching rules in the file. This action is
equivalent to the “skip” action in all module
configuration files except the main ASL configuration
file /etc/asl.conf. When used in the main configuration
file, the scope of the action is global, and matching
messages will be ignored by all ASL modules.
OUTPUT CONFIGURATION SETTINGS
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=raw
Multiple 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=20
As 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=20
Options 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.log
Most of the options listed below may be used with either file or
directory outputs. Exceptions are noted.
format=FMT Controls the format of log messages saved in a file.
Note that this option is specific to file outputs.
It is ignored for ASL directories.
The format is specified by the value given for FMT.
Several pre-defined formats are available:
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.
xml The list of messages is printed as an XML
property list. Each message is represented as
a dictionary in a array. Dictionary keys
represent message keys. Dictionary values are
strings.
asl The output file is written as an ASL-format
data store file. Files in this format may be
read and searched using the 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.
mode=MMM Sets the mode of the file or files within an ASL
directory. The value MMM may be specified as a
decimal value, a hexadecimal value (if preceded by
``0x''), or octal value (if preceded by ``0'').
uid=UUU Specifies the file's owner. If more than one
“uid=UUU” option is given, the first will be used to
set ownership, and subsequent user IDs will be given
read access to in the files POSIX.1e ACLs. Note that
UIDs should be defined in the local Open Directory
database, since 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.
gid=GGG Specifies the file's group. If more than one
“gid=GGG” option is given, the first will be used to
set the file's group, and subsequent group IDs will
be given read access to in the files POSIX.1e ACLs.
As with UID=UUU options, groups should be defined in
the local Open Directory database.
coalesce=VAL By default, files printed using the “bsd” and “std”
formats will coalesce duplicates. If two or more
messages are logged within 30 seconds, and which
differ only in time, then the second and subsequent
messages will not be printed. When a different
message is logged, or 30 seconds have elapsed since
the initial message was logged, a line with the text
--- last message repeated N times ---
will be added to the file. The default is
“coalesce=1”. The default may be overridden by
specifying “coalesce=0”. The values “off” and
“false” may be used in place of “0”.
The following options all deal with file rotation and life-cycle
management. The FILE ROTATION section describes this in detail.
rotate=NAME_STYLE Enables log file rotation and specifies the file
naming scheme for rotated files. This option
does not apply to ASL directories. NAME_STYLE
may either be a simple time-stamp style: “sec”,
“utc”, “utc-basic”, “local”, “local-basic”, or
“seq”; or the value may contain the file's base
name, a file name extension, and one of the
time-stame styles. For example
“example.seq.log” or “example.log.utc-basic.” A
detailed description of name styles may be found
in the FILE ROTATION section below.
If the option “rotate” appears without a value,
the naming style defaults to “sec”.
ttl=DAYS Specifies the number of days that older versions
of rotated files should be allowed to remain in
the filesystem. Rotated files older than this
limit are deleted.
dest=PATH By default, rotated files are left in the same
directory as the original file. However, in
some cases it may be useful to move the rotated
versions to a different directory for archival
or other reasons. If this option is specified,
aslmanager will move files to the directory
given by PATH.
soft Makes syslogd ignore write errors when saving
messages. Normally, syslogd will stop saving to
a file or ASL directory after 5 consecutive
write errors.
compress Enables gzip file compression for rotated log
files. When compressed, the extension “.gz” is
appended to the file name. When the output is
an ASL directory, data files are compressed
after midnight local time. This means that
messages written in the current day will be
readable using syslog -d or using the asl(3)
API. Messages in compressed data files will not
be available until the files are un-compressed.
file_max=SIZE Limits the size of an active log file. SIZE may
be an integer number of bytes, or the value may
be followed by a single character “k”, “m”, or
“g” (upper or lower case), to indicate a size
limit in multiples of 1024 (kibibyte), 1048576
(mebibyte), or 1073741824 (gibibyte). If a file
exceeds this limit, it is immediately
checkpointed by 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.
all_max=SIZE Specifies a size limit for the total of all
rotated versions of a file. 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.
basestamp Causes syslogd to add a timestamp to the file
name when it is created. For example,
> example.log rotate=utc-basic basestamp
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.
symlink This option may only be used together with the
basestamp option. It causes syslogd to create a
symlink with the unstamped file name to the
currently active log file. For example,
> example.log rotate=sec basestamp symlink
will result in syslogd writing to, e.g.
“example.log.T1340607600”, and creating a
sybolic link from “example.log” to the active
file.
FILE ROTATION
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.
sec Rotated file names are of the form
“example.log.T1340607600”. The file names include the
creation time of the file in seconds since the epoch.
utc Rotated file names are in ISO 8601 extended format,
for example “example.log.2012-06-24T07:00:00Z”. The
file names includes its creation time as a UTC date
and time.
utc-basic Rotated file names are in ISO 8601 basic format, for
example “example.log.20120624T070000Z”. The file
names includes its creation time as a UTC date and
time.
local Rotated file names are in ISO 8601 extended format,
for example “example.log.2012-06-24T07:00:00-7”. The
file names includes its creation time as date and time
in the local time zone. The local timezone offset is
included as a trailing part of the name. The value
“lcl” is an alias for “local”.
local-basic Rotated file names are in ISO 8601 basic format, for
example “example.log.20120624T070000-07”. The file
names includes its creation time as date and time in
the local time zone. The local timezone offset is
included as a trailing part of the name. The value
“lcl-basic” is an alias for “local-basic”.
seq Rotated file names are of the form “example.log.N”
where N is an integer sequence number. Files are re-
numbered on each rotation so that the “0” file is the
most recent.
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.log
If 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.0
example.log.1
example.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);
ASL OUTPUT MODULES
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 0
The 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 0
A 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 0
This 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.
ASLMANAGER PARAMETER SETTINGS
The following parameter-settings are recognized by aslmanager.
aslmanager_debug Enables or disables internal debugging output.
This is probably of little interest to most
users. The debug parameter requires a value of
“1” to enable debug output, or a value of “0” to
disable it. Debug messages are saved in an
auxiliary file attached to an ASL log message.
The file may be inspected by opening the file
attachement from the Console utility.
store_ttl Sets the time-to-live in days for messages in the
ASL database. The default is 7 days.
max_store_size Sets the maximum size for for the ASL database.
The default is 150000000 bytes.
archive Enables or disables archiving of the ASL
database. The archive parameter requires a value
of “1” to enable archiving, or a value of “0” to
disable it. An optional archive directory path
may follow the “0” or “1”. If enabled, files
removed from the ASL database are moved to the
archive directory. The default archive directory
path is /var/log/asl.archive.
store_path The ASL database path used by aslmanager. The
default is /var/log/asl. Note that this
parameter is ignored by syslogd.
archive_mode Files copied to the ASL database archive will be
given the specified access mode. The default is
0400, so archive files will only be readable by
root.
SEE ALSO
syslog(1), asl(3), notify(3), aslmanager(8), syslogd(8)
macOS September 19, 2008 macOS