syslogd.tproj/asl.conf.5

   1 .\"Copyright (c) 2004-2009 Apple Inc. All rights reserved.
   2 .\"
   3 .\"@APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\"This file contains Original Code and/or Modifications of Original Code
   6 .\"as defined in and that are subject to the Apple Public Source License
   7 .\"Version 2.0 (the 'License'). You may not use this file except in
   8 .\"compliance with the License. Please obtain a copy of the License at
   9 .\"http://www.opensource.apple.com/apsl/ and read it before using this
  10 .\"file.
  11 .\"
  12 .\"The Original Code and all software distributed under the License are
  13 .\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14 .\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15 .\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16 .\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  17 .\"Please see the License for the specific language governing rights and
  18 .\"limitations under the License.
  19 .\"
  20 .\"@APPLE_LICENSE_HEADER_END@
  21 .\"
  22 .Dd Sept 19, 2008
  23 .Dt asl.conf 5
  24 .Os "Mac OS X"
  25 .Sh NAME
  26 .Nm asl.conf
  27 .Nd configuration file for
  28 .Xr syslogd 8
  29 and
  30 .Xr aslmanager 8
  31 .Sh DESCRIPTION
  32 The
  33 .Xr syslogd 8
  34 server reads the
  35 .Nm
  36 file at startup, and re-reads the file whenever it received a HUP signal.
  37 The
  38 .Xr aslmanager 8
  39 daemon reads the file when it starts.
  40 See the ASLMANAGER PARAMETER SETTINGS section below for details on those parameter settings.
  41 .Pp
  42 The file may contain parameter settings, used in place of (and which will override) command-line options,
  43 and may contain query-action rules that trigger specific actions when
  44 .Nm syslogd
  45 recieves messages that match the query pattern.
  46 .Pp
  47 Parameter setting lines in the configuration file begin with an equal sign ("="),
  48 and are generally of the form:
  49 .Pp
  50 .Dl = parameter_name value ...
  51 .Pp
  52 Most parameter settings require a single value, although some may take several values.
  53 See the PARAMETER SETTINGS section below for details.
  54 .Pp
  55 Query-action rules in the file begin with a question-mark ("?") or a "Q", and generally have the form:
  56 .Pp
  57 .Dl ? query action ...
  58 .Pp
  59 Specific actions may be followed by optional arguments.
  60 See the QUERY-ACTION RULES section below for details.
  61 .Sh PARAMETER SETTINGS
  62 The following parameter-settings are recognized by
  63 .Nm syslogd .
  64 .Pp
  65 .Bl -tag -width "bsd_max_dup_time" -compact -offset indent
  66 .It debug
  67 Enables or disables internal debugging output.
  68 This is probably of little interest to most users.
  69 The debug parameter requires a value of "1" to enable debug output, or a value of "0" to disable it.
  70 An option file name may follow the "0" or "1".
  71 If a file name is provided, debug messages are written to that file.
  72 Otherwise, debug writes are treated as log messages.
  73 .Pp
  74 .It cutoff
  75 Sets the ASL data store cutoff level, given as an integer in the range 0 to 7 as an argument.
  76 The cutoff level is 7 by default, allowing any message that matches a "store" action
  77 (see QUERY-ACTION RULES below) to be saved.
  78 Setting the cutoff to a lower value will prevent messages with log priority levels numerically
  79 greater that the specified cutoff from being saved in the ASL data store.
  80 .Pp
  81 .It mark_time
  82 Sets the time interval for the mark facility.
  83 The default is 0 seconds, which indicates that mark messages are not generated.
  84 .Pp
  85 .It dup_delay
  86 Sets the maximum time that the bsd_out module will allow before writing a "last message repeated <N> times"
  87 message in a log file specified in /etc/syslog.conf.
  88 The default is 30 seconds.
  89 .Pp
  90 .It utmp_ttl
  91 Sets the time-to-live for messages used by the utmp, wtmp, and lastlog subsystems.
  92 The default is 31622400 seconds (approximately 1 year).
  93 .Pp
  94 .It fs_ttl
  95 Sets the time-to-live for filesystem error messages generated by the kernel.
  96 The default is 31622400 seconds (approximately 1 year).
  97 .Pp
  98 .It mps_limit
  99 Sets the per-process message per second quota.
 100 The default is value is 500.
 101 A value of 0 disables the quota mechanism.
 102 .Pp
 103 .It max_file_size
 104 Sets the maximum file size for individual files in the ASL data store.
 105 The default is 25600000 bytes.
 106 .El
 107 .Pp
 108 .Sh QUERY-ACTION RULES
 109 Rules contain three components: a query; an action; and optionally, parameters specific to that action.
 110 For example:
 111 .Pp
 112 .Dl ? [= Sender foobar] [<= Level error] notify com.apple.foobar
 113 .Pp
 114 .Ss Query Format
 115 Queries comprise one or more message matching components, each of which has the form:
 116 .Pp
 117 .Dl [OP KEY VAL]
 118 .Pp
 119 OP is a comparison operator.
 120 It can have the following values:
 121 .Pp
 122 .Bl -tag -width "<=  " -compact -offset indent
 123 .It T
 124 true (always matches)
 125 .It =
 126 equal
 127 .It !
 128 not equal
 129 .It >
 130 greater than
 131 .It >=
 132 greater than or equal to
 133 .It <
 134 less than
 135 .It <=
 136 less than or equal to
 137 .El
 138 .Pp
 139 It can also be preceded by one or more modifiers:
 140 .Bl -tag -width "C   " -compact -offset indent
 141 .Pp
 142 .It C
 143 casefold
 144 .It N
 145 numeric comparison
 146 .It S
 147 substring
 148 .It A
 149 prefix
 150 .It Z
 151 suffix
 152 .El
 153 .Pp
 154 KEY and VAL are message keys and values.
 155 For example
 156 .Pp
 157 .Dl [= Sender foobar]
 158 .Pp
 159 matches any message with key="Sender" and val="foobar".
 160 The query
 161 .Pp
 162 .Dl [CA= Color gr]
 163 .Pp
 164 matches any message with key=Color and val beginning with the letters GR, Gr, gr, or gR
 165 (C meaning casefold, A meaning prefix).
 166 The example query above,
 167 .Pp
 168 .Dl [= Sender foobar] [N< Level 3]
 169 .Pp
 170 matches any message from "foobar" with a level numerically less than 3
 171 (string values are converted to integers, and the comparison is done on the integer values).
 172 Note that the string values may be used equivalently for the Level key,
 173 so the example above may also be written as:
 174 .Pp
 175 .Dl [= Sender foobar] [< Level Error]
 176 .Pp
 177 String values for levels may be any of the set "emergency", "alert", "critical", "error",
 178 "warning", "notice", "info", or "debug".  These strings may be upper, lower, or mixed case.
 179 .Pp
 180 The "T" operator is useful to test for the presence of a particular key.
 181 .Pp
 182 .Dl [T Flavor]
 183 .Pp
 184 Will match any message that has a "Flavor" key, regardless of its value.
 185 .Pp
 186 .Ss Actions
 187 The following actions are available.
 188 .Pp
 189 .Bl -tag -width "store_directory" -compact -offset indent
 190 .It notify
 191 Causes
 192 .Nm syslogd
 193 to post a notification with
 194 .Fn notify_post .
 195 The notification key must appear as a single parameter following the "notify" action.
 196 .Pp
 197 .It access
 198 Sets read access controls for messages that match the associated query pattern.
 199 .Nm syslogd
 200 will restrict read access to matching messages to a specific user and group.
 201 The user ID number and group ID number must follow the "access" keyword as parameters.
 202 .Pp
 203 .It store
 204 Causes
 205 .Nm syslogd
 206 to save matching messages, either in the main ASL data store,
 207 or in a separate log message data store file is a file name is given as a parameter.
 208 A separate data store file may be accessed using the
 209 .Nm syslog
 210 command line utility.
 211 A new file will be created if one does not exist.
 212 If a new file is being created, the UID, GID, and mode of the file may be specified using the options
 213 "uid=UUU", "gid=GGG", and "mode=MMMM", where UUU and GGG are a user ID and group ID, and MMMM is a
 214 mode specification of the form "0644" (for an octal number) or DDD for a decimal number.
 215 .Pp
 216 Two other optional parameters may also follow the pathname.
 217 .Pp
 218 By default,
 219 .Nm syslogd
 220 will open the database, save a matching message, and then close the database.
 221 If a high volume of messages is expected, specifying the "stayopen" option will improve performance.
 222 .Pp
 223 Specifying "exclude_asldb" will cause syslogd to save matching messages in the specificed file,
 224 but exclude them from the main ASL data store.
 225 .Pp
 226 Note that if the configuration file contains no matching rules for the ASL data store, then
 227 .Nm syslogd
 228 will save all messages, subject to filtering in accordance with the log cutoff level.
 229 .Pp
 230 .It store_directory
 231 Causes matching messages to be stored in a log message data store file in a separate directory.
 232 The directory path name must follow as the first parameter.
 233 The named directory must exist.
 234 .Nm syslogd
 235 will not ceate the directory path.
 236 .Pp
 237 Messages saved to a store directory are saved in files that are named "yyyy.mm.dd.asl",
 238 where "yyyy", "mm", and "dd" are the year, month (01 to 12) and day of the month (01 to 31) associated with
 239 matching messages.
 240 This has the effect of saving messages in a separate file for each day.
 241 .Pp
 242 The "exclude_asldb", "uid=UUU", "gid=GGG", and "mode=MMMM" options available for the "store" action
 243 may also be specified for a store directory.
 244 The uid, gid, and mode specification will be used when the individual daily store files are created.
 245 .Pp
 246 .It broadcast
 247 Causes syslogd to write the text of matching messages to all terminal windows.
 248 If optional text follows the "broadcast" keyword, then  that text is written rather that the matching message text.
 249 .Pp
 250 .It ignore
 251 Causes a matching message to be ignored in all subsequent matching rules.
 252 .El
 253 .Sh ASLMANAGER PARAMETER SETTINGS
 254 The following parameter-settings are recognized by
 255 .Nm aslmanager .
 256 .Pp
 257 .Bl -tag -width "aslmanager_debug" -compact -offset indent
 258 .It aslmanager_debug
 259 Enables or disables internal debugging output.
 260 This is probably of little interest to most users.
 261 The debug parameter requires a value of "1" to enable debug output, or a value of "0" to disable it.
 262 Debug messages are sent to
 263 .Nm syslogd .
 264 .Pp
 265 .It store_ttl
 266 Sets the time-to-live in days for messages in the syslog data store.
 267 The default is 7 days.
 268 .Pp
 269 .It max_store_size
 270 Sets the maximum size for for the ASL data store.
 271 The default is 150000000 bytes.
 272 .Pp
 273 .It archive
 274 Enables or disables archiving.
 275 The archive parameter requires a value of "1" to enable archiving, or a value of "0" to disable it.
 276 An option archive directory path may follow the "0" or "1".
 277 If enabled, files removed from the ASL data store are moved to the archive directory.
 278 The default archive directory path is /var/log/asl.archive.
 279 .Pp
 280 .It store_path
 281 The data store path used by
 282 .Nm aslmanager .
 283 The default is /var/log/asl.
 284 Note that this parameter is ignored by
 285 .Nm syslogd .
 286 .It archive_mode
 287 Files copied to the archive will be given the specified access mode.
 288 The default is 0400, so archive files will only be readable by root.
 289 .El
 290 .Pp
 291 .Sh SEE ALSO
 292 .Xr asl 3 ,
 293 .Xr notify 3 ,
 294 .Xr syslog 1 ,
 295 .Xr aslmanager 8 ,
 296 .Xr syslogd 8 .