-.\"Copyright (c) 2004-2008 Apple Inc. All rights reserved.
+.\"Copyright (c) 2004-2009 Apple Inc. All rights reserved.
.\"
.\"@APPLE_LICENSE_HEADER_START@
.\"
.\"
.\"@APPLE_LICENSE_HEADER_END@
.\"
-.Dd December 22, 2005
+.Dd Sept 19, 2008
.Dt asl.conf 5
.Os "Mac OS X"
.Sh NAME
.Nm asl.conf
.Nd configuration file for
.Xr syslogd 8
-asl_action module.
+and
+.Xr aslmanager 8
.Sh DESCRIPTION
The
.Xr syslogd 8
-server in Mac OS X includes a module that compares messages with a set of query patterns,
-and which performs various actions when messages match the query patterns.
+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
+recieves 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
-Each line in the file contains three components.
-The first is a query, the second is an action, and the third contains parameters specific to that action.
+.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 Q [= Sender foobar] [N< Level 3] notify com.apple.foobar
+.Dl ? [= Sender foobar] [<= Level error] notify com.apple.foobar
.Pp
-.Ss Queries
-Queries start with the letter "Q" followed by whitespace.
-Following that are any number of message matching components, each of which has the form:
+.Ss Query Format
+Queries comprise one or more message matching components, each of which has the form:
.Pp
.Dl [OP KEY VAL]
.Pp
KEY and VAL are message keys and values.
For example
.Pp
-.Dl Q [= Sender foobar]
+.Dl [= Sender foobar]
.Pp
matches any message with key="Sender" and val="foobar".
The query
.Pp
-.Dl Q [CA= Color gr]
+.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 Q [= Sender foobar] [N< Level 3]
+.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 Q [T Flavor whatever]
+.Dl [T Flavor]
.Pp
Will match any message that has a "Flavor" key, regardless of its value.
.Pp
.Ss Actions
-The "notify" action causes
+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
-The "access" action sets read access controls for messages that match the associated query pattern.
+.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
-The "store" action saves matching messages in a separate log message database.
-The database may be accessed using the
+.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 database pathname must follow the "store" keyword.
-A new database will be created if one does not exist.
-Two optional parameters, "stayopen" and "exclude_asldb" may follow the database pathname.
+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
By default,
.Nm syslogd
will open the database, save a matching message, and then close the database.
-If a high volume of messages is expected, specifying "stayopen" will improve performance.
+If a high volume of messages is expected, specifying the "stayopen" option will improve performance.
+.Pp
+Specifying "exclude_asldb" will cause syslogd to save matching messages in the specificed file,
+but exclude them from the main ASL data store.
.Pp
-Specifying "exclude_asldb" will cause syslogd to save matching messages in the database,
-but exclude them from the main
+Note that if the configuration file contains no matching rules for the ASL data store, then
.Nm syslogd
-database (/var/log/asl.db).
+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 ceate 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 "exclude_asldb", "uid=UUU", "gid=GGG", and "mode=MMMM" 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 .
projects / apple / syslog.git / blobdiff