asl.conf.5   [plain text]


.\"Copyright (c) 2004-2009 Apple Inc. All rights reserved.
.\"
.\"@APPLE_LICENSE_HEADER_START@
.\"
.\"This file contains Original Code and/or Modifications of Original Code
.\"as defined in and that are subject to the Apple Public Source License
.\"Version 2.0 (the 'License'). You may not use this file except in
.\"compliance with the License. Please obtain a copy of the License at
.\"http://www.opensource.apple.com/apsl/ and read it before using this
.\"file.
.\"
.\"The Original Code and all software distributed under the License are
.\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\"Please see the License for the specific language governing rights and
.\"limitations under the License.
.\"
.\"@APPLE_LICENSE_HEADER_END@
.\"
.Dd Sept 19, 2008
.Dt asl.conf 5
.Os "Mac OS X"
.Sh NAME
.Nm asl.conf
.Nd configuration file for
.Xr syslogd 8
and
.Xr aslmanager 8
.Sh DESCRIPTION
The
.Xr syslogd 8
server reads the
.Nm
file at startup, and re-reads the file whenever it received a HUP signal.
The
.Xr aslmanager 8
daemon reads the file when it starts.
See the ASLMANAGER PARAMETER SETTINGS section below for details on those parameter settings.
.Pp
The file may contain parameter settings, used in place of (and which will override) command-line options,
and may contain query-action rules that trigger specific actions when
.Nm syslogd
receives messages that match the query pattern.
.Pp
Parameter setting lines in the configuration file begin with an equal sign ("="), 
and are generally of the form:
.Pp
.Dl = parameter_name value ...
.Pp
Most parameter settings require a single value, although some may take several values.
See the PARAMETER SETTINGS section below for details.
.Pp
Query-action rules in the file begin with a question-mark ("?") or a "Q", and generally have the form:
.Pp
.Dl ? query action ...
.Pp
Specific actions may be followed by optional arguments. 
See the QUERY-ACTION RULES section below for details.
.Sh PARAMETER SETTINGS
The following parameter-settings are recognized by
.Nm syslogd .
.Pp
.Bl -tag -width "bsd_max_dup_time" -compact -offset indent
.It 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.
An option file name may follow the "0" or "1".
If a file name is provided, debug messages are written to that file.
Otherwise, debug writes are treated as log messages.
.Pp
.It cutoff
Sets the ASL data store cutoff level, given as an integer in the range 0 to 7 as an argument.
The cutoff level is 7 by default, allowing any message that matches a "store" action
(see QUERY-ACTION RULES below) to be saved.
Setting the cutoff to a lower value will prevent messages with log priority levels numerically
greater that the specified cutoff from being saved in the ASL data store.
.Pp
.It mark_time
Sets the time interval for the mark facility.
The default is 0 seconds, which indicates that mark messages are not generated.
.Pp
.It dup_delay
Sets the maximum time that the bsd_out module will allow before writing a "last message repeated <N> times"
message in a log file specified in /etc/syslog.conf.
The default is 30 seconds.
.Pp
.It 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).
.Pp
.It fs_ttl
Sets the time-to-live for filesystem error messages generated by the kernel.
The default is 31622400 seconds (approximately 1 year).
.Pp
.It mps_limit
Sets the per-process message per second quota.
The default is value is 500.
A value of 0 disables the quota mechanism.
.Pp
.It max_file_size
Sets the maximum file size for individual files in the ASL data store.
The default is 25600000 bytes.
.El
.Pp
.Sh QUERY-ACTION RULES
Rules contain three components: a query; an action; and optionally, parameters specific to that action.
For example:
.Pp
.Dl ? [= Sender foobar] [<= Level error] notify com.apple.foobar
.Pp
.Ss Query Format
Queries comprise one or more message matching components, each of which has the form:
.Pp
.Dl [OP KEY VAL]
.Pp
OP is a comparison operator.
It can have the following values:
.Pp
.Bl -tag -width "<=  " -compact -offset indent
.It T
true (always matches)
.It =
equal
.It !
not equal
.It >
greater than
.It >=
greater than or equal to
.It <
less than
.It <=
less than or equal to
.El
.Pp
It can also be preceded by one or more modifiers:
.Bl -tag -width "C   " -compact -offset indent
.Pp
.It C
casefold
.It N
numeric comparison
.It S
substring
.It A
prefix
.It Z
suffix
.El
.Pp
KEY and VAL are message keys and values.
For example
.Pp
.Dl [= Sender foobar]
.Pp
matches any message with key="Sender" and val="foobar".
The query
.Pp
.Dl [CA= Color gr]
.Pp
matches any message with key=Color and val beginning with the letters GR, Gr, gr, or gR
(C meaning casefold, A meaning prefix).
The example query above,
.Pp
.Dl [= Sender foobar] [N< Level 3]
.Pp
matches any message from "foobar" 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:
.Pp
.Dl [= Sender foobar] [< Level Error]
.Pp
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.
.Pp
The "T" operator is useful to test for the presence of a particular key.
.Pp
.Dl [T Flavor]
.Pp
Will match any message that has a "Flavor" key, regardless of its value.
.Pp
.Ss Actions
The following actions are available.
.Pp
.Bl -tag -width "store_directory" -compact -offset indent
.It notify
Causes
.Nm syslogd
to post a notification with
.Fn notify_post .
The notification key must appear as a single parameter following the "notify" action.
.Pp
.It access
Sets read access controls for messages that match the associated query pattern. 
.Nm 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.
.Pp
.It store
Causes
.Nm syslogd
to save matching messages, either in the main ASL data store,
or in a separate log message data store file is a file name is given as a parameter.
A separate data store file may be accessed using the
.Nm syslog
command line utility.
A new file will be created if one does not exist.
If a new file is being created, the UID, GID, and mode of the file may be specified using the options
"uid=UUU", "gid=GGG", and "mode=MMMM", where UUU and GGG are a user ID and group ID, and MMMM is a 
mode specification of the form "0644" (for an octal number) or DDD for a decimal number.
.Pp
Two other optional parameters may also follow the pathname.
.Pp
If a separate log message data store file is specified as a parameter, then
.Nm syslogd
will open the database, save a matching message, and then close the database.
If a high volume of messages is expected, specifying the "stayopen" option will improve performance.
.Pp
Also, if a separate log message data store file is specified as a parameter,
matching messages will be excluded from all further processing.
Adding the "continue" option will cause syslogd to save matching messages in the specified store file
and then continue processing matching messages in accordance with the actions
specified in /etc/asl.conf and /etc/syslog.conf.
.Pp
Note that if the
.Nm asl.conf
configuration file contains no matching rules for the main ASL data store, then
.Nm syslogd
will save all messages, subject to filtering in accordance with the log cutoff level.
.Pp
.It store_directory
Causes matching messages to be stored in a log message data store file in a separate directory.
The directory path name must follow as the first parameter.
The named directory must exist.
.Nm syslogd
will not create the directory path.
.Pp
Messages saved to a store 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.
.Pp
The "uid=UUU", "gid=GGG", "mode=MMMM", and "continue" options available for the "store" action
may also be specified for a store directory.
The uid, gid, and mode specification will be used when the individual daily store files are created.
.Pp
.It 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.
.Pp
.It ignore
Causes a matching message to be ignored in all subsequent matching rules.
.El
.Sh ASLMANAGER PARAMETER SETTINGS
The following parameter-settings are recognized by
.Nm aslmanager .
.Pp
.Bl -tag -width "aslmanager_debug" -compact -offset indent
.It 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 sent to
.Nm syslogd .
.Pp
.It store_ttl
Sets the time-to-live in days for messages in the syslog data store.
The default is 7 days.
.Pp
.It max_store_size
Sets the maximum size for for the ASL data store.
The default is 150000000 bytes.
.Pp
.It archive
Enables or disables archiving.
The archive parameter requires a value of "1" to enable archiving, or a value of "0" to disable it.
An option archive directory path may follow the "0" or "1".
If enabled, files removed from the ASL data store are moved to the archive directory.
The default archive directory path is /var/log/asl.archive.
.Pp
.It store_path
The data store path used by 
.Nm aslmanager .
The default is /var/log/asl.
Note that this parameter is ignored by
.Nm syslogd .
.It archive_mode
Files copied to the archive will be given the specified access mode.
The default is 0400, so archive files will only be readable by root.
.El
.Pp
.Sh SEE ALSO
.Xr asl 3 ,
.Xr notify 3 ,
.Xr syslog 1 ,
.Xr aslmanager 8 ,
.Xr syslogd 8 .