syslog-148.8.tar.gz

[apple/syslog.git] / syslogd.tproj / asl.conf.5

.\"Copyright (c) 2004-2011 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
.Dq = , 
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
.Dq 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
.Dq 1
to enable debug output, or a value of
.Dq 0
to disable it.
An option file name may follow the
.Dq 0
or
.Dq 1 .
If a file name is provided, debug messages are written to that file.
Otherwise, debug writes are treated as log messages.
.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 before writing a
.Dq "last message repeated <N> times"
message in a log file when duplicate messages have been detected.
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 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 value 
.Dq foobar
for the 
.Dq Sender
key.
The query
.Pp
.Dl [CA= Color gr]
.Pp
matches any message with a value beginning with the letters GR, Gr, gr, or gR
(C meaning casefold, A meaning prefix) for the
.Dq Color
key.
The example query above,
.Pp
.Dl [= Sender foobar] [N< Level 3]
.Pp
matches any message from 
.Dq 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
.Dq emergency ,
.Dq alert ,
.Dq critical ,
.Dq error ,
.Dq warning ,
.Dq notice ,
.Dq info , or
.Dq debug .
These strings may be upper, lower, or mixed case.
.Pp
The
.Dq 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
.Dq 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
.Dq 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
.Dq 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
.Dq uid=UUU ,
.Dq gid=GGG ,
and
.Dq mode=MMMM ,
where UUU and GGG are a user ID and group ID, and MMMM is a 
mode specification of the form
.Dq 0644
with a leading zero 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
.Dq 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
.Dq 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.
.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
.Dq yyyy.mm.dd.asl ,
where 
.Dq yyyy ,
.Dq mm ,
and
.Dq 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
.Dq uid=UUU ,
.Dq gid=GGG ,
.Dq mode=MMMM ,
and
.Dq continue
options available for the
.Dq 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 file
Causes matching messages to be stored in a log file.
The file's path name must follow as the first parameter.
The file's directory must exist.
If the path already exists, it must be a plain file.
Otherwise
.Nm syslogd
will create the file.
The file's owner will be root, and the file's group will be admin.
A file mode may be specified as an option of the form 
.Dq mode=MMMM
as described above.
One or more UIDs may be given as the values of options of the form 
.Dq uid=UUU .
One or more GIDs may be given as the values of options of the form 
.Dq gid=GGG .
If any UIDs or GIDs are provided, the specified users and groups will be given read access to the file.
Note that UIDs and GIDs should be defined in the local Open Directory database, since
.Nm 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.
.Pp
By default, log files will be written using the same format used for printing by 
.Nm syslog
when the
.Fl F Ar std
flag is supplied.
A print format may be specified as the value of the
.Dq format=FMT
option.
The default is
.Dq format=std .
Alternate file formats, including
.Dq bsd
and
.Dq raw
are supported.
Custom formats may be specified as well, using the syntax supported by
.Nm syslog Fl F .
Space and tab character in a custom format string must be escaped with a leading backslash character.
Custom format strings may include variables of the form
.Dq $Name
.Dq $(Name)
or
.Dq $((Name)(fmt)) .
which will be expanded to the associated with the named key.
The first form may be used in most cases.
The second form may be used if the variable is not delimited by whitespace.
The third form permits the selection of alternate output formats for certain keys,
such as Time and Level.
See
.Xr syslog 1
for details.
.Pp
For example, the option:
.Pp
.Dl format=$((Time)(Z))\ $Host\ $(Sender)[$(PID)]\ <$((Level)(str))>:\ $Message
.Pp
produces output similar to the 
.Dq std
format, but using the UTC (Zulu) timezone.
.Pp
By default, files printed using the
.Dq bsd
and
.Dq std
formats will suppress printing 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
.Dl --- last message repeated N times ---
will be added to the file.
The default may be disabled using the 
.Dq no_dup_supress
option.
.Pp
.It broadcast
Causes syslogd to write the text of matching messages to all terminal windows.
If optional text follows the
.Dq 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 
.Dq 1
to enable debug output, or a value of 
.Dq 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 
.Dq 1
to enable archiving, or a value of
.Dq 0
to disable it.
An option archive directory path may follow the
.Dq 0
or
.Dq 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 .