Mac Developer Library Developer


This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.

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 SET-TINGS SETTINGS
     TINGS 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 module 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 form:

           = parameter_name value ...

     Most parameter settings require a single value, although some may take several values.  See the PARAME-TER PARAMETER
     TER 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 message matches the given query.
     Actions may be followed by optional arguments.  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 convenience, these configuration options may be specified on a separate line.  Output configura-tion configuration
     tion settings in the file begin with a greater-than sign ``>'' followed by a file or ASL directory name
     and the configuration options for that file or directory.  These lines generally have the form:

           > 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 /var/log/syslogd.log.

           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'' mes-sage message
                             sage 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 subsys-tems. subsystems.
                             tems.  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 command.

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

     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 pro-cessing. processing.
     cessing.  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 ``com.example.log_message''.

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

   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 equivalently 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 messages
                      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 rela-
                      tive 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 con-trols, controls,
                      trols, printed log message format, and controls for file rotation, compression, time-to-live, timeto-live,
                      to-live, and other aspects of output file life-cycle management.  See the OUTPUT CON-FIGURATION CONFIGURATION
                      FIGURATION 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 follow 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 CONFIGURA-TION CONFIGURATION
                      TION SETTINGS section for a list of options that may be set for store directories.

           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 subsequent 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 processed
                      cessed 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.

                      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 follow the ``access'' keyword as parame-ters. 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 con-figuration configuration
                      figuration file /etc/asl.conf.

           ignore     Causes a matching message to be ignored in all subsequent matching rules in the file.
                      This action is equivalent to the ``skip'' action in all module configuration files
                      except the main ASL configuration file /etc/asl.conf.  When used in the main configu-ration configuration
                      ration 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 exam-ple, example,
     ple, 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 ``>'' character:

           > 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 pattern for multiple rules that specify the same output file or
     directory is:

           > 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 directory outputs.  Exceptions are

           format=FMT    Controls the format of log messages saved in a file.  Note that this option is spe-cific specific
                         cific 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/sys-tem.log. /var/log/system.log.

                         std   Standard (default) format.  Similar to ``bsd'', but includes the message pri-ority priority
                               ority 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 property list.  Each message is
                               represented as a dictionary in a array.  Dictionary keys represent message
                               keys.  Dictionary values are strings.

                         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 MESSAGES 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 decimal 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 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
                               --- last message repeated N times ---will --will
                         will be added to the file.  The default is ``coalesce=1''.  The default may be
                         overridden by specifying ``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 management.  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 sup-ported: 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
                                           ``example.log.2012-06-24T07:00:00Z''.  The file names includes
                                           its creation time as a UTC date and time.

                              utc-basic    Rotated file names are in ISO 8601 basic format, for example
                                           ``example.log.20120624T070000Z''.  The file names includes its
                                           creation time as a UTC date and time.

                              local        Rotated file names are in ISO 8601 extended format, for example
                                           ``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.

                              local-basic  Rotated file names are in ISO 8601 basic format, for example
                                           ``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.

                              seq          Rotated file names are of the form ``example.log.N'' where N is
                                           an integer sequence number.  Files are re-numbered on each rota-tion rotation
                                           tion so that the ``0'' file is the most recent.

                              If the option ``rotate'' appears without a value, the naming style defaults to

                              Note that using the local timezone for timestamped files may cause odd behav-ior behavior
                              ior 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 considered 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

           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 dif-ferent different
                              ferent 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 checkpointed 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 specified in the same format as the file_max option.

     syslogd and aslmanager work together to automatically provide all the features of file rotation.  How-ever, However,
     ever, 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.

     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 check-pointed checkpointed
     pointed if they exceed a size limit specified by a file_max option, and they may be checkpointed manu-ally manually
     ally 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 timezone.  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 usage.

     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 speci-fied specified
     fied 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 compressed 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 automatically, 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 excep-tions. exceptions.
     tions.  Mdules may not have parameter setting lines for the system parameters listed in the PARAMETER
     SETTINGS or ASLMANAGER PARAMETER SETTINGS sections, nor may they include ``broadcast'' query-action

     Module configuration files are read by syslogd when it starts, and whenever it gets a HUP signal.  Mes-sages Messages
     sages received by syslogd are first processed 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 /etc/asl.conf.

     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 messages to files or directories,
     and will not post BSD notifications.

     Several mechanisms allow modules to be enabled or disabled dynamically.  One mechanism allows the set-ting setting
     ting 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 section may also be used in test-ing testing
     ing 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 speci-fied specified
     fied 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 files.

           = 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 messages.  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 speci-fied. specified.
     fied.  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

           archive           Enables or disables archiving of the ASL database.  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 direc-tory. directory.
                             tory.  The default archive directory path is /var/log/asl.archive.

           store_path        The ASL database path used by aslmanager.  The default is /var/log/asl.  Note
                             that this parameter 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 root.

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

Mac OS X                         Sept 19, 2008                        Mac OS X

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.