syslog-97.1.tar.gz

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

diff --git a/syslogd.tproj/asl.conf.5 b/syslogd.tproj/asl.conf.5
index 8ac5e56c1d2f2e5b16392e78b1ea3f17d9b443b8..e9ac0225a131f8cdb5448c42759ce16fbeb6a275 100644 (file)
--- a/syslogd.tproj/asl.conf.5
+++ b/syslogd.tproj/asl.conf.5
@@ -1,4 +1,4 @@
-.\"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_START@
 .\"


@@ -19,29 +19,100 @@
 .\"
 .\"@APPLE_LICENSE_HEADER_END@
 .\"
 .\"
 .\"@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
 .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
 .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
 .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
 For example:
 .Pp

-.Dl Q [= Sender foobar] [N< Level 3] notify com.apple.foobar
+.Dl ? [= Sender foobar] [<= Level error] notify com.apple.foobar

 .Pp
 .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
 .Pp
 .Dl [OP KEY VAL]
 .Pp


@@ -83,59 +154,143 @@ suffix
 KEY and VAL are message keys and values.
 For example
 .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
 .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
 .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).
 .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
 .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
 .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
 .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
 .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.
 .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.
 .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
 .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
 .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 ,
 .Sh SEE ALSO
 .Xr asl 3 ,
 .Xr notify 3 ,
 .Xr syslog 1 ,

+.Xr aslmanager 8 ,

 .Xr syslogd 8 .
 .Xr syslogd 8 .