syslog-267.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 8d305ac224e16bb80f83f3a691fe23b69f52b199..5d6e115e87d03200201663fbe8e9cf584cd47ac3 100644 (file)
--- a/syslogd.tproj/asl.conf.5
+++ b/syslogd.tproj/asl.conf.5
@@ -1,4 +1,4 @@
-.\"Copyright (c) 2004-2011 Apple Inc. All rights reserved.
+.\"Copyright (c) 2004-2013 Apple Inc. All rights reserved.

 .\"
 .\"@APPLE_LICENSE_HEADER_START@
 .\"
 .\"
 .\"@APPLE_LICENSE_HEADER_START@
 .\"


@@ -31,37 +31,69 @@ and
 .Sh DESCRIPTION
 The
 .Xr syslogd 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.
+server reads the /etc/asl.conf file at startup, and re-reads the file when it receives a HUP signal.

 The
 .Xr aslmanager 8
 daemon reads the file when it starts.
 The
 .Xr aslmanager 8
 daemon reads the file when it starts.

-See the ASLMANAGER PARAMETER SETTINGS section below for details on those parameter settings.
+See the ASLMANAGER PARAMETER SETTINGS section for details on aslmanager-specific parameters.

 .Pp
 .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
+If the /etc/asl directory exists, then

 .Nm syslogd
 .Nm syslogd

-receives messages that match the query pattern.
+and
+.Nm aslmanager
+will read each file it contains.
+These files must have the same format as
+.Nm asl.conf .
+Each file configures an independent module, identified by the file name.
+Modules may be enabled or disabled independently.
+Each module may specify its own set of rules for acting on received messages.
+See the ASL MODULES section for details.
+.Pp
+The files contain several types of lines, described below.
+Each type is identified by the first non-whitespace character in the line.
+.Pp
+.Bl -tag -width "=" -compact
+.It =
+Parameter settings
+.It ?
+Query-action rules
+.It >
+Output file or directory configuration options
+.It #
+Comments
+.El

 .Pp
 .Pp

-Parameter setting lines in the configuration file begin with an equal sign
-.Dq = , 
-and are generally of the form:
+Parameter setting lines in the configuration file are generally of the form:

 .Pp
 .Dl = parameter_name value ...
 .Pp
 Most parameter settings require a single value, although some may take several values.
 .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.
+See the PARAMETER SETTINGS section for details.

 .Pp
 .Pp

-Query-action rules in the file begin with a question-mark ``?'' or a
-.Dq Q ,
-and generally have the form:
+Query-action rules in the file generally have the form:

 .Pp
 .Dl ? query action ...
 .Pp
 .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
+This directs
+.Nm syslogd
+to perform the specified action when a received message matches the given query.
+Actions may be followed by optional arguments.
+See the QUERY-ACTION RULES section for details.
+.Pp
+Most query-action rules specify output files or ASL-format data stores where matching messages should be saved.
+The optional parameters for those rules can specify a number of options for these outputs.
+As a convenience, these configuration options may be specified on a separate line.
+Output configuration settings in the file begin with a greater-than sign 
+.Dq >
+followed by a file or ASL directory name and the configuration options for that file or directory.
+These lines generally have the form:
+.Pp
+.Dl > filename option ...
+.Pp
+See the OUTPUT CONFIGURATION SETTINGS section for details.
+.Pp
+Comment lines are ignored.
+.Ss PARAMETER SETTINGS

 The following parameter-settings are recognized by
 .Nm syslogd .
 .Pp
 The following parameter-settings are recognized by
 .Nm syslogd .
 .Pp


@@ -74,12 +106,7 @@ The debug parameter requires a value of
 to enable debug output, or a value of
 .Dq 0
 to disable it.
 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.
+Debugging messages are written to /var/log/syslogd.log.

 .Pp
 .It mark_time
 Sets the time interval for the mark facility.
 .Pp
 .It mark_time
 Sets the time interval for the mark facility.


@@ -96,21 +123,49 @@ Sets the time-to-live for messages used by the utmp, wtmp, and lastlog subsystem
 The default is 31622400 seconds (approximately 1 year).
 .Pp
 .It mps_limit
 The default is 31622400 seconds (approximately 1 year).
 .Pp
 .It mps_limit

-Sets the per-process message per second quota.
+Sets the kernel message per second quota.

 The default is value is 500.
 A value of 0 disables the quota mechanism.
 The default is value is 500.
 A value of 0 disables the quota mechanism.

+Note that this setting only limits the number of kernel messages that will be saved by
+.Nm syslogd .
+User processes are limited to 36000 messages per hour.
+The limit for a user process is not enforced if a remote-control ASL filter is in
+place for the process.
+See the
+.Xr syslog 1
+manual for enabling a remote-control filter using the 
+.Fl c
+option with the
+.Nm syslog
+command.

 .Pp
 .It max_file_size
 .Pp
 .It max_file_size

-Sets the maximum file size for individual files in the ASL data store.
+Sets the maximum file size for individual files in the ASL database.

 The default is 25600000 bytes.
 .El
 The default is 25600000 bytes.
 .El

+.Ss QUERY-ACTION RULES
+Query-action rules are used to cause
+.Nm syslogd
+to perform specific actions when received messages match a specified query pattern.
+For example, to save certain messages in a file.
+The rules are processed in the order in which they appear in the file.
+This matters because some actions can affect further processing.
+For example, an 
+.Dq ignore 
+action causes
+.Nm syslogd
+to stop processing the rules in a file for messages that match a given query pattern.

 .Pp
 .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
+Query-action rules contain three components: a query, an action, and optional parameters specific to that action.
+For example, the following rule matches log messages sent by the 
+.Dq example
+process which have log priority levels in the range emergency to error.
+If a received message matches, 
+.Nm syslogd
+posts a BSD notification for the key 
+.Dq com.example.log_message .

 .Pp
 .Pp

+.Dl ? [= Sender example] [<= Level error] notify com.example.log_message

 .Ss Query Format
 Queries comprise one or more message matching components, each of which has the form:
 .Pp
 .Ss Query Format
 Queries comprise one or more message matching components, each of which has the form:
 .Pp


@@ -154,10 +209,10 @@ suffix
 KEY and VAL are message keys and values.
 For example
 .Pp
 KEY and VAL are message keys and values.
 For example
 .Pp

-.Dl [= Sender foobar]
+.Dl [= Sender example]

 .Pp
 matches any message with value 
 .Pp
 matches any message with value 

-.Dq foobar
+.Dq example

 for the 
 .Dq Sender
 key.
 for the 
 .Dq Sender
 key.


@@ -166,21 +221,25 @@ The query
 .Dl [CA= Color gr]
 .Pp
 matches any message with a value beginning with the letters GR, Gr, gr, or gR
 .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 C
+meaning casefold,
+.Dq A
+meaning prefix) for the

 .Dq Color
 key.
 The example query above,
 .Pp
 .Dq Color
 key.
 The example query above,
 .Pp

-.Dl [= Sender foobar] [N< Level 3]
+.Dl [= Sender example] [N< Level 3]

 .Pp
 matches any message from 
 .Pp
 matches any message from 

-.Dq foobar
+.Dq example

 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
 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]
+.Dl [= Sender example] [< Level Error]

 .Pp
 String values for levels may be any of the set
 .Dq emergency ,
 .Pp
 String values for levels may be any of the set
 .Dq emergency ,


@@ -189,7 +248,8 @@ String values for levels may be any of the set
 .Dq error ,
 .Dq warning ,
 .Dq notice ,
 .Dq error ,
 .Dq warning ,
 .Dq notice ,

-.Dq info , or
+.Dq info ,
+or

 .Dq debug .
 These strings may be upper, lower, or mixed case.
 .Pp
 .Dq debug .
 These strings may be upper, lower, or mixed case.
 .Pp


@@ -203,10 +263,68 @@ Will match any message that has a
 .Dq Flavor
 key, regardless of its value.
 .Pp
 .Dq Flavor
 key, regardless of its value.
 .Pp

+Note that space characters and closing square bracket characters (']') are specially processed.
+The first space character following the beginning of a key delimits the key.
+The first closing square bracket following the beginning of a value delimits the value.
+So '[= foo bar\ ]'
+will match messages which have a key 'foo' with the value 'bar ', including a trailing space character.
+.Pp
+As a special case, the query
+.Pp
+.Dl *
+.Pp
+matches all messages.

 .Ss Actions
 The following actions are available.
 .Pp
 .Ss Actions
 The following actions are available.
 .Pp

-.Bl -tag -width "store_directory" -compact -offset indent
+.Bl -tag -width "directory" -compact -offset indent
+.It store
+Causes
+.Nm syslogd
+to save matching messages in the ASL database.
+Note that if /etc/asl.conf contains no 
+.Dq store 
+action rules, then
+.Nm syslogd
+will save all messages it receives in the ASL database.
+.Pp
+.It file
+Causes matching messages to be stored in a log file.
+The file's path name must follow as the first parameter.
+If the path already exists, it must be a plain file.
+If the file does not exist, it will be created when the first message is written.
+If the pathname specified is not an absolute path,
+.Nm syslogd
+will treat the given path as relative to /var/log (for /etc/asl.conf), 
+or for other output modules relative to /var/log/module/NAME where NAME is the module name.
+.Pp
+By default, the file's owner will be root, and the file will be readable by the admin group.
+Various options may follow the file name to specify ownership and access controls,
+printed log message format, and controls for file rotation, compression, time-to-live,
+and other aspects of output file life-cycle management.
+See the OUTPUT CONFIGURATION SETTINGS section for more details.
+.Pp
+.It directory
+Causes matching messages to be stored in an ASL-format log message data store.
+A directory path name must follow as the first parameter.
+If the path exists, it must be a directory.
+.Pp
+Messages saved to an ASL 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
+By default, files in the directory will be owned by root, and readable by the admin group.
+Various options may follow the directory name to control ownership, access controls,
+and the management of the store and its contents.
+See the OUTPUT CONFIGURATION SETTINGS section for a list of options that may be set for store directories.
+.Pp

 .It notify
 Causes
 .Nm syslogd
 .It notify
 Causes
 .Nm syslogd


@@ -216,173 +334,578 @@ The notification key must appear as a single parameter following the
 .Dq notify
 action.
 .Pp
 .Dq notify
 action.
 .Pp

+.It skip
+Causes a matching message to be ignored in all subsequent matching rules in the file.
+Its scope is local to a single module configuration file.
+.Pp
+.It claim
+Messages that match the query associated with a
+.Dq claim
+action are not processed by the main ASL configuration file /etc/asl.conf.
+While claimed messages are not processed by /etc/asl.conf,
+they are not completely private.
+Other modules may also claim messages,
+and in some cases two or more modules may have claim actions
+that match the same messages.
+This action only blocks processing by /etc/asl.conf.
+.Pp
+The
+.Dq claim
+action may be followed by the keyword
+.Dq only .
+In this case, only those messages that match the 
+.Dq claim only
+query will be processed by subsequent rules in the module.
+.Pp

 .It access
 .It access

-Sets read access controls for messages that match the associated query pattern. 
+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
 .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.
+.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.
+Note that this action is restricted to the main ASL configuration file /etc/asl.conf.

 .Pp
 .Pp

-Two other optional parameters may also follow the pathname.
+.It ignore
+Causes a matching message to be ignored in all subsequent matching rules in the file.
+This action is equivalent to the
+.Dq skip
+action in all module configuration files except the main ASL configuration file /etc/asl.conf.
+When used in the main configuration file, the scope of the action is global,
+and matching messages will be ignored by all ASL modules.
+.El
+.Ss OUTPUT CONFIGURATION SETTINGS
+Various options may follow the path name in a
+.Dq file
+or
+.Dq directory
+query-action rule.
+For example, the following rule specifies that all messages from the
+.Dq example
+facility will be saved in the file
+.Dq example.log ,
+and that messages are printed in a
+.Dq raw
+format that shows all the keys and values in the message:

 .Pp
 .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.
+.Dl ? [= Facility example] file example.log format=raw

 .Pp
 .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.
+Multiple options may be specified separated by whitespace characters.
+For example:

 .Pp
 .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.
+.Dl ? [= Facility example] file example.log format=raw rotate=local compress ttl=3 mode=0640 uid=0 gid=5 gid=20

 .Pp
 .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.
+As a convenience, a file or directory name and any associated options can be specified on a separate
+output configuration line following a 
+.Dq >
+character:

 .Pp
 .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.
+.Dl > example.log format=raw rotate=local compress ttl=3 mode=0640 uid=0 gid=5 gid=20
+.Pp
+Options for a file or directory are taken from the first query-action rule
+or output configuration line for the given path.
+A good usage pattern for multiple rules that specify the same output file or directory is:
+.Pp
+.Dl > example.log options ...
+.Dl ? query1 file example.log
+.Dl ? query2 file example.log
+.Dl ? query3 file example.log
+.Pp
+Most of the options listed below may be used with either file or directory outputs.
+Exceptions are noted.

 .Pp
 .Pp

-By default, log files will be written using the same format used for printing by 
+.Bl -tag -width "coalesce=VAL" -compact -offset indent
+.It format=FMT
+Controls the format of log messages saved in a file.
+Note that this option is specific to file outputs.
+It is ignored for ASL directories.
+.Pp
+The format is specified by the value given for FMT.
+Several pre-defined formats are available:
+.Bl -tag -width "abcd"
+.It bsd
+Format used by the
+.Nm syslogd
+daemon for system log files, e.g. /var/log/system.log.
+.It std
+Standard (default) format.
+Similar to 
+.Dq bsd ,
+but includes the message priority level.
+.It raw
+Prints the complete message structure.
+Each key/value pair is enclosed in square brackets.
+Embedded closing brackets and white space are escaped.
+Time stamps are printed as seconds since the epoch.
+.It xml
+The list of messages is printed as an XML property list.
+Each message is represented as a dictionary in a array.
+Dictionary keys represent message keys.
+Dictionary values are strings.
+.It asl
+The output file is written as an ASL-format data store file.
+Files in this format may be read and searched using the

 .Nm syslog
 .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
+command line utility with the use of the
+.Fl f Ar path

 option.
 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:
+.El

 .Pp
 .Pp

-.Dl format=$((Time)(Z))\ $Host\ $(Sender)[$(PID)]\ <$((Level)(str))>:\ $Message
+Custom format strings may also be specified.
+Since custom formats often contain white-space characters, 
+the entire string may be enclosed in single or double quote characters,
+or each white-space character may be preceded by a backslash escape character.
+Escaped characters are not interpreted.
+Custom format strings are described in detail in the READING MESSAGES section of the
+.Xr syslog 1
+manual.
+.Pp
+.It mode=MMM
+Sets the mode of the file or files within an ASL directory.
+The value MMM may be specified as a decimal value,
+a hexadecimal value (if preceded by ``0x''),
+or octal value (if preceded by ``0'').
+.Pp
+.It uid=UUU
+Specifies the file's owner.
+If more than one 
+.Dq uid=UUU
+option is given, the first will be used to set ownership,
+and subsequent user IDs will be given read access to in the files POSIX.1e ACLs.
+Note that UIDs 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
 .Pp

-produces output similar to the 
-.Dq std
-format, but using the UTC (Zulu) timezone.
+.It gid=GGG
+Specifies the file's group.
+If more than one 
+.Dq gid=GGG
+option is given, the first will be used to set the file's group,
+and subsequent group IDs will be given read access to in the files POSIX.1e ACLs.
+As with UID=UUU options, groups should be defined in the local Open Directory database.

 .Pp
 .Pp

+.It coalesce=VAL

 By default, files printed using the
 .Dq bsd
 and
 .Dq std
 By default, files printed using the
 .Dq bsd
 and
 .Dq std

-formats will suppress printing duplicates.
+formats will coalesce 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.
 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
+The default is
+.Dq coalesce=1 .
+The default may be overridden by specifying
+.Dq coalesce=0 .
+The values 
+.Dq off
+and 
+.Dq false
+may be used in place of 
+.Dq 0 .
+.El
+.Pp
+The following options all deal with file rotation and life-cycle management.
+The FILE ROTATION section describes this in detail.
+.Pp
+.Bl -tag -width "rotate=NAME_STYLE" -compact -offset indent
+.Pp
+.It rotate=NAME_STYLE
+Enables log file rotation and specifies the file naming scheme for rotated files.
+This option does not apply to ASL directories.
+Four styles are supported:
+.Pp
+.Bl -tag -width "local-basic" -compact -indent
+.It sec
+Rotated file names are of the form
+.Dq example.log.T1340607600 .
+The file names include the creation time of the file in seconds since the epoch.
+.Pp
+.It utc
+Rotated file names are in ISO 8601 extended format, for example
+.Dq example.log.2012-06-24T07:00:00Z .
+The file names includes its creation time as a UTC date and time.
+.Pp
+.It utc-basic
+Rotated file names are in ISO 8601 basic format, for example
+.Dq example.log.20120624T070000Z .
+The file names includes its creation time as a UTC date and time.
+.Pp
+.It local
+Rotated file names are in ISO 8601 extended format, for example
+.Dq example.log.2012-06-24T07:00:00-7 .
+The file names includes its creation time as date and time in the local time zone.
+The local timezone offset is included as a trailing part of the name.
+.Pp
+.It local-basic
+Rotated file names are in ISO 8601 basic format, for example
+.Dq example.log.20120624T070000-07 .
+The file names includes its creation time as date and time in the local time zone.
+The local timezone offset is included as a trailing part of the name.
+.Pp
+.It seq
+Rotated file names are of the form
+.Dq example.log.N
+where N is an integer sequence number.
+Files are re-numbered on each rotation so that the 
+.Dq 0
+file is the most recent.
+.El
+.Pp
+If the option 
+.Dq rotate
+appears without a value, the naming style defaults to
+.Dq "sec" .
+.Pp
+Note that using the local timezone for timestamped files may cause odd behavior on highly-mobile systems.
+.Nm aslmanager
+will delete files after a specified time-to-live (see below).
+The age of the file is determined by the file name.
+If files are created in different timezones but saved with a non-absolute timestamp,
+the age calculation may result in some files being considered older or newer than they are in reality.
+.Pp
+Also note that sequenced files (using the
+.Dq seq
+style) will initially be checkpointed using a file name containing a timestamp in seconds.
+.Nm aslmanager
+will re-sequence the files when it scans for checkpoint files.
+.Pp
+.It ttl=DAYS
+Specifies the number of days that older versions of rotated files should be allowed to remain in the filesystem.
+Rotated files older than this limit are deleted.
+.Pp
+.It dest=PATH
+By default, rotated files are left in the same directory as the original file.
+However, in some cases it may be useful to move the rotated versions to a different
+directory for archival or other reasons.
+If this option is specified,
+.Nm aslmanager
+will move files to the directory given by PATH.
+.Pp
+.It soft
+Makes
+.Nm syslogd
+ignore write errors when saving messages.
+Normally,
+.Nm syslogd
+will stop saving to a file or ASL directory after 5 consecutive write errors.
+.Pp
+.It compress
+Enables gzip file compression for rotated log files.
+When compressed, the extension 
+.Dq .gz
+is appended to the file name.
+.Pp
+.It file_max=SIZE
+Limits the size of an active log file.
+SIZE may be an integer number of bytes, or the value may be followed by a single character 
+.Dq k , 
+.Dq m ,
+or 
+.Dq g
+(upper or lower case),
+to indicate a size limit in multiples of 1024 (kibibyte), 1048576 (mebibyte), or 1073741824 (gibibyte).
+If a file exceeds this limit, it is immediately checkpointed by
+.Nm syslogd 
+and a new file is opened.
+Note that
+.Dq file_max
+specifies a size limit before file compression is performed if the
+.Dq compress
+option is also present.
+.Pp
+.It all_max=SIZE
+Specifies a size limit for the total of all rotated versions of a file.
+.Nm aslmanager
+will delete rotated files, oldest first, to reduce the total below the limit.
+SIZE may be specified in the same format as the file_max option.
+.El
+.Ss FILE ROTATION
+.Nm syslogd
+and
+.Nm aslmanager
+work together to automatically provide all the features of file rotation.
+However, it is useful to understand how the process works.
+This section describes the file rotation options that may be used in /etc/asl.conf
+or an ASL Output Module configuration file,
+together with a description of how the system works to support those features.
+.Pp
+If a file is marked for rotation,
+.Nm syslogd
+will close the file at the start of a new day or when the file exceeds its 
+.Dq file_max
+size limit.
+At that point,
+.Nm syslogd
+renames the file and starts a new file to continue logging.
+The old file is renamed with the file's creation time included in its name.
+This operation is called checkpointing the file.
+.Pp
+For example,
+.Nm syslogd
+might close
+.Dq example.log
+and rename it
+.Dq example.log.T1340521200 ,
+1340521200 being the time that the file was created.
+It would then start a new 
+.Dq example.log
+file and use it until midnight, when the cycle would be repeated.
+.Pp
+Files are normally checkpointed at midnight.
+If the system is sleeping or powered off, then files are checkpointed when
+the the first message of a new day (local time) is received.
+Files are also checkpointed if they exceed a size limit specified by a file_max option,
+and they may be checkpointed manually through options provided by the
+.Xr syslog 1
+and
+.Xr aslmanager 8
+utilities.
+The checkpointed file name always contains the file's creation time.
+If the options for the file include
+.Dq rotate=utc
+then the timestamp will be a UTC date and time string.
+.Dq rotate=local
+causes the timestamp to be the date and time in the current local timezone.
+Otherwise, the timestamp will be in seconds since the epoch.
+.Pp
+.Nm syslogd
+only performs the checkpointing operation.
+It closes old files, moves them out of the way, and starts writing new files.
+Most of the work of file rotation is done by the
+.Xr aslmanager 8
+utility.
+That includes moving files to a destination directory, compressing files,
+re-naming files according to one of the naming style options,
+deleting old files after they exceed their time-to-live,
+and checking file space usage.
+.Pp
+.Nm aslmanager
+normally runs once during system start-up, and once a day just after midnight.
+It may also be triggered occasionally by
+.Nm syslogd ,
+and it may be run manually.
+.Pp
+.Nm aslmanager
+scans for any checkpointed files created by
+.Nm syslogd 
+and will rename the files (if required) to match the naming style specified by the
+.Dq rotate=NAME_STYLE

 option.
 option.

+If 
+.Dq rotate=seq
+is specified for a file, checkpointed files created by
+.Nm syslogd
+contain a timestamp in seconds.
+These files are renamed so that the file names
+contain a sequence number.
+The most recent version has the number 
+.Dq 0 ,
+and older versions have higher numbers.
+For example:

 .Pp
 .Pp

-.It broadcast
-Causes syslogd to write the text of matching messages to all terminal windows.
-If optional text follows the
+.Dl example.log.0
+.Dl example.log.1
+.Dl example.log.2
+.Dl ...
+.Pp
+As well as renaming files,
+.Nm aslmanager
+may perform other actions.
+If the file has been given a 
+.Dq dest=PATH
+option,
+the rotated versions of the file will be moved to the specified directory.
+Files will be gzip compressed using the
+.Xr zlib 3
+library if the 
+.Dq compress
+option has been given.
+If the total size of all the rotated versions of the file exceeds a value given in an 
+.Dq all_max
+option, older versions of the rotated file will be deleted to keep the total below the specified limit.
+.Pp
+Although checkpoint and file rotation operations are normally done automatically,
+.Nm aslmanager
+supports an option that will trigger 
+.Nm syslogd
+to checkpoint files before
+.Nm aslmanager
+starts its scan.
+.Nm syslog
+also supports an option to force files to be checkpointed without running
+.Nm aslmanager .
+See the
+.Xr aslmanager 8
+and
+.Xr syslog 1
+manuals for details.
+.Pp
+Programmatically, an
+.Xr asl 3
+message may be sent to syslogd to force it to checkpoint either a single file,
+or to checkpoint all files for a particular ASL module.
+To checkpoint all files:
+.Pp
+    const char *module_name;
+.Pp
+    //TODO: set module_name
+    asl_object_t ctl = asl_new(ASL_TYPE_MSG);
+    asl_set(ctl, ASL_KEY_OPTION, "control");
+    asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s checkpoint", module_name);
+    asl_release(ctl);
+.Pp
+To checkpoint just one file:
+.Pp
+    const char *module_name;
+    const char *file_name;
+.Pp
+    //TODO: set module_name
+    //TODO: set file_name
+    asl_object_t ctl = asl_new(ASL_TYPE_MSG);
+    asl_set(ctl, ASL_KEY_OPTION, "control");
+    asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s checkpoint %s", module_name, file_name);
+    asl_release(ctl);
+.Pp
+.Ss ASL OUTPUT MODULES
+.Pp
+An ASL output module is created by a configuration file in the directory /etc/asl.
+The file name is used as the module's name.
+The format of the file is generally the same as
+.Nm asl.conf 
+with a few exceptions.
+Modules may not have parameter setting lines for the system parameters listed in the
+PARAMETER SETTINGS or ASLMANAGER PARAMETER SETTINGS sections,
+nor may they include

 .Dq broadcast
 .Dq broadcast

-keyword, then that text is written rather that the matching message text.
+query-action rules.

 .Pp
 .Pp

-.It ignore
-Causes a matching message to be ignored in all subsequent matching rules.
-.El
-.Sh ASLMANAGER PARAMETER SETTINGS
+Module configuration files are read by
+.Nm syslogd
+when it starts, and whenever it gets a HUP signal.
+Messages received by
+.Nm syslogd
+are first processed according the the rules found in /etc/asl.conf
+(also known as the 
+.Dq com.apple.asl
+module), then the message is processed by the
+rules from each module found in /etc/asl.
+.Pp
+An exception to this is that messages that match the query in a
+.Dq claim
+action rule in any module are not processed by the rules in /etc/asl.conf.
+.Pp
+ASL output modules are enabled by default, but a module may include a parameter setting:
+.Pp
+.Dl = enable 0
+.Pp
+The module is still loaded by
+.Nm syslogd ,
+but the module will not save messages to files or directories, and will not post BSD notifications.
+.Pp
+Several mechanisms allow modules to be enabled or disabled dynamically.
+One mechanism allows the setting of the 
+.Dq enable
+parameter to be based on the existence of a path in the filesystem,
+or on the value associated with a dictionary key in a property list file.
+On iOS only, the value of a key in an installed configuration profile may be tested.
+.Pp
+To enable a module based on the existence of a file, the module may use:
+.Pp
+.Dl = enable [File /a/b/c]
+.Pp
+where
+.Dq /a/b/c
+may be any filesystem path.
+.Pp
+To enable a module based on the value of a dictionary key in a property list file,
+.Pp
+.Dl = enable [Plist /path/config.plist] [= SomeKey SomeValue]
+.Pp
+Any of the test operations described above in the QUERY-ACTION RULES section
+may also be used in testing key / value pairs.
+Multiple operations are also allowed, for example:
+.Pp
+.Dl = enable [Plist /path/config.plist] [N>= DebugLevel 7] [S= Othervalue xyz]
+.Pp
+If the property list file does not exist, the test will evaluate to zero.
+The file may be in binary or xml format.
+It may only contain a single dictionary object at its top level.
+Only keys and values at the top level of the dictionary may be tested.
+Values must be strings, integer values, doubles, UUIDs, dates, or booleans.  
+Boolean <true/> and <false/> values are converted to 1 and 0 respectively. 
+Values are converted into strings,
+and string comparisons are used unless unless an
+.Dq N
+modifier is specified with the test operator.
+.Pp
+On iOS, a module may test key / value pairs in a configuration profile using the
+same key / value tests that may be used for property list files.
+.Pp
+.Dl = enable [Profile name] [= Verbose 1]
+.Pp
+The profile name is the value of its DefaultsDomainName key.
+The test will evaluate to zero if the profile is not installed.
+.Pp
+A module may be also enabled or disabled using
+.Nm syslog
+or by sending
+.Nm syslogd
+a special
+.Xr asl 3
+control message.
+Only the user
+.Dq root
+may enable or disable modules.
+.Pp
+A module may be enabled or disabled by sending an
+.Xr asl 3
+message as shown in this example:
+.Pp
+    int enable;
+    const char *module_name;
+.Pp
+    //TODO: set module_name
+    //TODO: set enable to 0 or 1
+    asl_object_t ctl = asl_new(ASL_TYPE_MSG);
+    asl_set(ctl, ASL_KEY_OPTION, "control");
+    asl_log(NULL, ctl, ASL_LEVEL_NOTICE, "@ %s enable %d", module_name, enable);
+    asl_release(ctl);
+.Pp
+A control message may also be sent using
+.Nm syslog
+as the following example shows to disable a module named
+.Dq com.apple.example :
+.Pp
+.Dl sudo syslog -module com.apple.example enable 0
+.Pp
+A module may also enable or disable itself.
+Although a module that is not enabled will not write or post notifications,
+it still will scan messages.
+The module may contain conditional parameter-setting rules like:
+.Pp
+.Dl = [= Color Green] enable 1
+.Dl = [= Color Red] enable 0
+.Pp
+This is similar to a query-action rule.
+If a message received by syslogd matches the specified query,
+in this case having a Color key with the value Green or Red,
+then the enable parameter is set as specified.
+So in this example, the module would be enabled and disabled
+whenever syslogd received a message containing the appropriate value for the 
+.Dq Color
+key.
+.Ss ASLMANAGER PARAMETER SETTINGS

 The following parameter-settings are recognized by
 .Nm aslmanager .
 .Pp
 The following parameter-settings are recognized by
 .Nm aslmanager .
 .Pp


@@ -395,39 +918,40 @@ The debug parameter requires a value of
 to enable debug output, or a value of 
 .Dq 0
 to disable it.
 to enable debug output, or a value of 
 .Dq 0
 to disable it.

-Debug messages are sent to
-.Nm syslogd .
+Debug messages are saved in an auxiliary file attached to an ASL log message.
+The file may be inspected by opening the file attachement from the Console utility.

 .Pp
 .It store_ttl
 .Pp
 .It store_ttl

-Sets the time-to-live in days for messages in the syslog data store.
+Sets the time-to-live in days for messages in the ASL database.

 The default is 7 days.
 .Pp
 .It max_store_size
 The default is 7 days.
 .Pp
 .It max_store_size

-Sets the maximum size for for the ASL data store.
+Sets the maximum size for for the ASL database.

 The default is 150000000 bytes.
 .Pp
 .It archive
 The default is 150000000 bytes.
 .Pp
 .It archive

-Enables or disables archiving.
+Enables or disables archiving of the ASL database.

 The archive parameter requires a value of 
 .Dq 1
 to enable archiving, or a value of
 .Dq 0
 to disable it.
 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
+An optional archive directory path may follow the

 .Dq 0
 or
 .Dq 1 .
 .Dq 0
 or
 .Dq 1 .

-If enabled, files removed from the ASL data store are moved to the archive directory.
+If enabled, files removed from the ASL database are moved to the archive directory.

 The default archive directory path is /var/log/asl.archive.
 .Pp
 .It store_path
 The default archive directory path is /var/log/asl.archive.
 .Pp
 .It store_path

-The data store path used by 
+The ASL database path used by 

 .Nm aslmanager .
 The default is /var/log/asl.
 Note that this parameter is ignored by
 .Nm syslogd .
 .Nm aslmanager .
 The default is /var/log/asl.
 Note that this parameter is ignored by
 .Nm syslogd .

+.Pp

 .It archive_mode
 .It archive_mode

-Files copied to the archive will be given the specified access mode.
+Files copied to the ASL database archive will be given the specified access mode.

 The default is 0400, so archive files will only be readable by root.
 .El
 .Pp
 The default is 0400, so archive files will only be readable by root.
 .El
 .Pp