asl.conf man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

asl.conf(5)		    BSD File Formats Manual		   asl.conf(5)

     asl.conf — configuration file for syslogd(8) and aslmanager(8)

     The syslogd(8) server reads the /etc/asl.conf file at startup, and re-
     reads the file when it receives a HUP signal.  The aslmanager(8) daemon
     reads the file when it starts.  See the ASLMANAGER PARAMETER SETTINGS
     section for details on aslmanager-specific parameters.

     If the /etc/asl directory exists, then syslogd and aslmanager will read
     each file it contains.  These files must have the same format as
     asl.conf.	Each file configures an independent module, identified by the
     file name.	 Modules may be enabled or disabled independently.  Each mod‐
     ule may specify its own set of rules for acting on received messages.
     See the ASL MODULES section for details.

     The files contains four types of lines.  Each type is identified by the
     first non-whitespace character.

     =	Parameter settings
     ?	Query-action rules
     >	Output file or directory configuration options
     #	Comments

     Parameter setting lines in the configuration file are generally of the

	   = parameter_name value ...

     Most parameter settings require a single value, although some may take
     several values.  See the PARAMETER SETTINGS section for details.

     Query-action rules in the file generally have the form:

	   ? query action ...

     This directs syslogd to perform the specified action when a received mes‐
     sage matches the given query.  Actions may be followed by optional argu‐
     ments.  See the QUERY-ACTION RULES section for details.

     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 con‐
     venience, these configuration options may be specified on a separate
     line.  Output configuration settings in the file begin with a greater-
     than sign “>” followed by a file or ASL directory name and the configura‐
     tion options for that file or directory.  These lines generally have the

	   > filename option ...

     See the OUTPUT CONFIGURATION SETTINGS section for details.

     Comments lines are ignored.

     The following parameter-settings are recognized by syslogd.

	   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.  Debugging messages are written to

	   mark_time	     Sets the time interval for the mark facility.
			     The default is 0 seconds, which indicates that
			     mark messages are not generated.

	   dup_delay	     Sets the maximum time before writing a “last
			     message repeated <N> times” message in a log file
			     when duplicate messages have been detected.  The
			     default is 30 seconds.

	   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).

	   mps_limit	     Sets the kernel message per second quota.	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 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
			     syslog(1) manual for enabling a remote-control
			     filter using the -c option with the syslog com‐

	   max_file_size     Sets the maximum file size for individual files
			     in the ASL database.  The default is 25600000

     Query-action rules are used to cause 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 “ignore” action causes
     syslogd to stop processing the rules in a file for messages that match a
     given query pattern.

     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 “example” process which have log
     priority levels in the range emergency to error.  If a received message
     matches, syslogd posts a BSD notification for the key

	   ? [= Sender example] [<= Level error] notify

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

	   [OP KEY VAL]

     OP is a comparison operator.  It can have the following values:

	   T	 true (always matches)
	   =	 equal
	   !	 not equal
	   >	 greater than
	   >=	 greater than or equal to
	   <	 less than
	   <=	 less than or equal to

     It can also be preceded by one or more modifiers:

	   C	 casefold
	   N	 numeric comparison
	   S	 substring
	   A	 prefix
	   Z	 suffix

     KEY and VAL are message keys and values.  For example

	   [= Sender example]

     matches any message with value “example” for the “Sender” key.  The query

	   [CA= Color gr]

     matches any message with a value beginning with the letters GR, Gr, gr,
     or gR ( “C” meaning casefold, “A” meaning prefix) for the “Color” key.
     The example query above,

	   [= Sender example] [N< Level 3]

     matches any message from “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 equiva‐
     lently for the Level key, so the example above may also be written as:

	   [= Sender example] [< Level Error]

     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.

     The “T” operator is useful to test for the presence of a particular key.

	   [T Flavor]

     Will match any message that has a “Flavor” key, regardless of its value.

     As a special case, the query


     matches all messages.

     The following actions are available.

	   store      Causes syslogd to save matching messages in the ASL
		      database.	 Note that if /etc/asl.conf contains no
		      “store” action rules, then syslogd will save all mes‐
		      sages it receives in the ASL database.

	   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, 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.

		      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.

	   directory  Causes matching messages to be stored in an ASL-format
		      log message data store.  A directory path name must fol‐
		      low as the first parameter.  If the path exists, it must
		      be a directory.

		      Messages saved to an ASL directory are saved in files
		      that are named “”, 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.

		      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 directo‐

	   notify     Causes syslogd to post a notification with
		      notify_post().  The notification key must appear as a
		      single parameter following the “notify” action.

	   skip	      Causes a matching message to be ignored in all subse‐
		      quent matching rules in the file.	 Its scope is local to
		      a single module configuration file.

	   claim      Messages that match the query associated with a “claim”
		      action are not processed by the main ASL configuration
		      file /etc/asl.conf.  While claimed messages are not pro‐
		      cessed by /etc/asl.conf, they are not completely pri‐
		      vate.  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.

		      The “claim” action may be followed by the keyword
		      “only”.  In this case, only those messages that match
		      the “claim only” query will be processed by subsequent
		      rules in the module.

	   access     Sets read access controls for messages that match the
		      associated query pattern.	 syslogd will restrict read
		      access to matching messages to a specific user and
		      group.  The user ID number and group ID number must fol‐
		      low the “access” keyword as parameters.

	   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.  Note that this action
		      is restricted to the main ASL configuration file

	   ignore     Causes a matching message to be ignored in all subse‐
		      quent matching rules in the file.	 This action is equiv‐
		      alent to the “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.

     Various options may follow the path name in a “file” or “directory”
     query-action rule.	 For example, the following rule specifies that all
     messages from the “example” facility will be saved in the file
     “example.log”, and that messages are printed in a “raw” format that shows
     all the keys and values in the message:

	   ? [= Facility example] file example.log format=raw

     Multiple options may be specified separated by whitespace characters.
     For example:

	   ? [= Facility example] file example.log format=raw rotate=local
	   compress ttl=3 mode=0640 uid=0 gid=5 gid=20

     As a convenience, a file or directory name and any associated options can
     be specified on a separate output configuration line following a “>”

	   > example.log format=raw rotate=local compress ttl=3 mode=0640
	   uid=0 gid=5 gid=20

     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 pat‐
     tern for multiple rules that specify the same output file or directory

	   > example.log options ...
	   ? query1 file example.log
	   ? query2 file example.log
	   ? query3 file example.log

     Most of the options listed below may be used with either file or direc‐
     tory outputs.  Exceptions are noted.

	   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.

			 The format is specified by the value given for FMT.
			 Several pre-defined formats are available:

			 bsd   Format used by the syslogd daemon for system
			       log files, e.g. /var/log/system.log.

			 std   Standard (default) format.  Similar to “bsd”,
			       but includes the message priority level.

			 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.

			 xml   The list of messages is printed as an XML prop‐
			       erty list.  Each message is represented as a
			       dictionary in a array.  Dictionary keys repre‐
			       sent message keys.  Dictionary values are

			 asl   The output file is written as an ASL-format
			       data store file.	 Files in this format may be
			       read and searched using the syslog command line
			       utility with the use of the -f path option.

			 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 MES‐
			 SAGES section of the syslog(1) manual.

	   mode=MMM	 Sets the mode of the file or files within an ASL
			 directory.  The value MMM may be specified as a deci‐
			 mal value, a hexadecimal value (if preceded by
			 ``0x''), or octal value (if preceded by ``0'').

	   uid=UUU	 Specifies the file's owner.  If more than one
			 “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 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.

	   gid=GGG	 Specifies the file's group.  If more than one
			 “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.

	   coalesce=VAL	 By default, files printed using the “bsd” and “std”
			 formats will coalesce duplicates.  If two or more
			 messages are logged within 30 seconds, and which dif‐
			 fer only in time, then the second and subsequent mes‐
			 sages will not be printed.  When a different message
			 is logged, or 30 seconds have elapsed since the ini‐
			 tial message was logged, a line with the text
			       --- last message repeated N times ---
			 will be added to the file.  The default is
			 “coalesce=1”.	The default may be overridden by spec‐
			 ifying “coalesce=0”.  The values “off” and “false”
			 may be used in place of “0”.

     The following options all deal with file rotation and life-cycle manage‐
     ment.  The FILE ROTATION section describes this in detail.

	   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:

			      sec	   Rotated file names are of the form
					   “example.log.T1340607600”.  The
					   file names include the creation
					   time of the file in seconds since
					   the epoch.

			      utc	   Rotated file names are in ISO 8601
					   extended format, for example
					   The file names includes its cre‐
					   ation time as a UTC date and time.

			      utc-basic	   Rotated file names are in ISO 8601
					   basic format, for example
					   The file names includes its cre‐
					   ation time as a UTC date and time.

			      local	   Rotated file names are in ISO 8601
					   extended format, for example
					   The file names includes its cre‐
					   ation time as date and time in the
					   local time zone.  The local time‐
					   zone offset is included as a trail‐
					   ing part of the name.

			      local-basic  Rotated file names are in ISO 8601
					   basic format, for example
					   The file names includes its cre‐
					   ation time as date and time in the
					   local time zone.  The local time‐
					   zone offset is included as a trail‐
					   ing part of the name.

			      seq	   Rotated file names are of the form
					   “example.log.N” where N is an inte‐
					   ger sequence number.	 Files are re-
					   numbered on each rotation so that
					   the “0” file is the most recent.

			      If the option “rotate” appears without a value,
			      the naming style defaults to “sec”.

			      Note that using the local timezone for times‐
			      tamped files may cause odd behavior on highly-
			      mobile systems.  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 con‐
			      sidered older or newer than they are in reality.

			      Also note that sequenced files (using the “sec”
			      style) will initially be checkpointed using a
			      file name containing a timestamp in seconds.
			      aslmanager will re-sequence the files when it
			      scans for checkpoint files.

	   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.

	   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,
			      aslmanager will move files to the directory
			      given by PATH.

	   soft		      Makes syslogd ignore write errors when saving
			      messages.	 Normally, syslogd will stop saving to
			      a file or ASL directory after 5 consecutive
			      write errors.

	   compress	      Enables gzip file compression for rotated log
			      files.  When compressed, the extension “.gz” is
			      appended to the file name.

	   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 “k”, “m”, or
			      “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 check‐
			      pointed by syslogd and a new file is opened.
			      Note that “file_max” specifies a size limit
			      before file compression is performed if the
			      “compress” option is also present.

	   all_max=SIZE	      Specifies a size limit for the total of all
			      rotated versions of a file.  aslmanager will
			      delete rotated files, oldest first, to reduce
			      the total below the limit.  SIZE may be speci‐
			      fied in the same format as the file_max option.

     syslogd and 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 fea‐

     If a file is marked for rotation, syslogd will close the file at the
     start of a new day or when the file exceeds its “file_max” size limit.
     At that point, 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.

     For example, syslogd might close “example.log” and rename it
     “example.log.T1340521200”, 1340521200 being the time that the file was
     created.  It would then start a new “example.log” file and use it until
     midnight, when the cycle would be repeated.

     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 syslog(1) and
     aslmanager(8) utilities.  The checkpointed file name always contains the
     file's creation time.  If the options for the file include “rotate=utc”
     then the timestamp will be a UTC date and time string.  “rotate=local”
     causes the timestamp to be the date and time in the current local time‐
     zone.  Otherwise, the timestamp will be in seconds since the epoch.

     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 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

     aslmanager normally runs once during system start-up, and once a day just
     after midnight.  It may also be triggered occasionally by syslogd, and it
     may be run manually.

     aslmanager scans for any checkpointed files created by syslogd and will
     rename the files (if required) to match the naming style specified by the
     “rotate=NAME_STYLE” option.  If “rotate=seq” is specified for a file,
     checkpointed files created by 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 “0”, and older versions have
     higher numbers.  For example:


     As well as renaming files, aslmanager may perform other actions.  If the
     file has been given a “dest=PATH” option, the rotated versions of the
     file will be moved to the specified directory.  Files will be gzip com‐
     pressed using the zlib(3) library if the “compress” option has been
     given.  If the total size of all the rotated versions of the file exceeds
     a value given in an “all_max” option, older version of the rotated file
     will be deleted to keep the total below the specified limit.

     Although checkpoint and file rotation operations are normally done auto‐
     matically, aslmanager supports an option that will trigger syslogd to
     checkpoint files before aslmanager starts its scan.  syslog also supports
     an option to force files to be checkpointed without running aslmanager.
     See the aslmanager(8) and syslog(1) manuals for details.

     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 asl.conf with a few exceptions.  Mdules may
     not have parameter setting lines for the system parameters listed in the
     they include “broadcast” query-action rules.

     Module configuration files are read by syslogd when it starts, and when‐
     ever it gets a HUP signal.	 Messages received by syslogd are first pro‐
     cessed according the the rules found in /etc/asl.conf (also known as the
     “” module), then the message is processed by the rules from
     each module found in /etc/asl.

     An exception to this is that messages that match the query in a “claim”
     action rule in any module are not processed by the rules in

     ASL output modules are enabled by default, but a module may include a
     parameter setting:

	   = enable 0

     The module is still loaded by syslogd, but the module will not save mes‐
     sages to files or directories, and will not post BSD notifications.

     Several mechanisms allow modules to be enabled or disabled dynamically.
     One mechanism allows the setting of the “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.

     To enable a module based on the existence of a file, the module may use:

	   = enable [File /a/b/c]

     where “/a/b/c” may be any filesystem path.

     To enable a module based on the value of a dictionary key in a property
     list file,

	   = enable [Plist /path/config.plist] [= SomeKey SomeValue]

     Any of the test operations described above in the QUERY-ACTION RULES sec‐
     tion may also be used in testing key / value pairs.  Multiple operations
     are also allowed, for example:

	   = enable [Plist /path/config.plist] [N>= DebugLevel 7] [S=
	   Othervalue xyz]

     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 “N” modifier is
     specified with the test operator.

     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

	   = enable [Profile name] [= Verbose 1]

     The profile name is the value of its DefaultsDomainName key.  The test
     will evaluate to zero if the profile is not installed.

     A module may be also enabled or disabled using syslog or by sending
     syslogd a special asl(3) control message.	Only the user “root” may
     enable or disable modules.

     A module may be enabled or disabled by sending an asl(3) message as shown
     in this example, which enables a module named “”:

	 #include <asl.h>
	 aslmsg ctl = asl_new(ASL_TYPE_MSG);
	 asl_set(ctl, ASL_KEY_OPTION, "control");
	 asl_set(ctl, ASL_KEY_MSG, "@ enable 1");
	 asl_send(NULL, ctl);

     A control message may also be sent using syslog as the following example
     shows to disable a module named “”:

	   sudo syslog -module enable 0

     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 mes‐
     sages.  The module may contain conditional parameter-setting rules like:

	   = [= Color Green] enable 1
	   = [= Color Red] enable 0

     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 “Color” key.

     The following parameter-settings are recognized by aslmanager.

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

	   store_ttl	     Sets the time-to-live in days for messages in the
			     ASL database.  The default is 7 days.

	   max_store_size    Sets the maximum size for for the ASL database.
			     The default is 150000000 bytes.

	   archive	     Enables or disables archiving of the ASL data‐
			     base.  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 database are moved to the archive
			     directory.	 The default archive directory path is

	   store_path	     The ASL database path used by aslmanager.	The
			     default is /var/log/asl.  Note that this parame‐
			     ter is ignored by syslogd.

	   archive_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

     asl(3), notify(3), syslog(1), aslmanager(8), syslogd(8).

Mac OS X			 Sept 19, 2008			      Mac OS X

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net