.\"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 .