format=FMT Controls the format of log messages saved in a file. Note that this option is specific to file out-
puts. 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 dic-
tionary 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 charac-
ters, 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) man-
ual.
mode=MMM Sets the mode of the file or files within an ASL directory. The value MMM may be specified as a dec-
imal 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 subse-
quent 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 specify-
ing ``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 des-
tination 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 occa-
sionally 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 nam-
ing 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 check-
point 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 dictio-
nary 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 and
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 hav-
ing a Color key with the value Green or Red, then the enable parameter is set as specified. So in this example, the mod-
ule would be enabled and disabled whenever syslogd received a message containing the appropriate value for the ``Color''
key.
ASLMANAGER PARAMETER SETTINGS
aslmanager_debug 1|0| 1 Enables .
Saved in an auxiliary file attached to an ASL log message.
The file may be inspected using Console utility.
| store_ttl days | time-to-live for messages in the ASL database. default is 7 days.
| max_store_size bytes | for the ASL database. Default 150MB
| archive 1|0 [ archDir ] 1 enables default directory /var/log/asl.archive.
store_path path The ASL database path used by aslmanager. The default is /var/log/asl.
Ignored by syslogd.
archive_mode mmm | archive will be given the access mode. The default is 0400, so archive files will only be readable by root.
| | | | | | | | |
As of 6/27/23 Ventura on smac14:
authd sharing output destination /var/log/asl with ASL Module com.apple.asl.
mkb sharing output destination /private/var/log/keybagd.log with ASL Module com.apple.mkb.internal.
Output parameters from mkb.internal override any specified in ASL Module com.apple.mkb.
Output parameters from asl override any specified in ASL Module com.apple.authd.
claims selected messages:
cdscheduler install, authd, eventmonitor, mail, performance, iokit.power, contacts.ContactsAutocomplete, mkb, MessageTracer.
SEE ALSO
asl(3), notify(3), syslog(1), aslmanager(8), syslogd(8).
| | | | | | | | | | | | | | | | | | | | | | | | |