X-Git-Url: https://git.saurik.com/apple/syslog.git/blobdiff_plain/94194072b557c3881168a08e1d58367a3e3c8b4d..c4fdb7d114b21b1b97b3777dfb8a8053693e7a91:/syslogd.tproj/asl.conf.5?ds=inline diff --git a/syslogd.tproj/asl.conf.5 b/syslogd.tproj/asl.conf.5 index 8ac5e56..e9ac022 100644 --- 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@ .\" @@ -19,29 +19,100 @@ .\" .\"@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 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 @@ -83,59 +154,143 @@ suffix 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 .