syslogd.tproj/syslogd.8

   1 .\"Copyright (c) 2004-2008 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 October 18, 2004
  23 .Dt SYSLOGD 8
  24 .Os "Mac OS X"
  25 .Sh NAME
  26 .Nm syslogd
  27 .Nd Apple System Log server
  28 .Sh SYNOPSIS
  29 .Nm
  30 .Op Fl d
  31 .Op Fl D
  32 .Op Fl m Ar mark_interval
  33 .Op Fl c Ar log_cutoff
  34 .Op Fl l Ar lib_path
  35 .Op Fl db_max Ar size
  36 .Op Fl utmp_ttl Ar time
  37 .Op Fl fs_ttl Ar time
  38 .Op Fl mps_limit Ar quota
  39 .Op Fl dup_delay Ar time
  40 .Op Fl module_name Li {0|1}
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 server receives and processes log messages.
  45 Several modules receive input messages through various channels,
  46 including UNIX domain sockets associated with the
  47 .Xr syslog 3 ,
  48 .Xr asl 3 ,
  49 and kernel printf APIs,
  50 and optionally on a UDP socket from network clients.
  51 .Pp
  52 The Apple System Log facility comprises the
  53 .Xr asl 3
  54 API, a new
  55 .Nm
  56 server, the
  57 .Xr syslog 1
  58 command-line utility, and a data store file manager,
  59 .Xr aslmanager 8 .
  60 The system supports structured and extensible messages,
  61 permitting advanced message browsing and management through search APIs and
  62 other components of the Apple system log facility.
  63 .Pp
  64 Log messages are retained in a data store,
  65 subject to automatic archival, and input filtering as described below,
  66 to simplify the task of locating log messages and to facilitate browsing and searching.
  67 The data store is intended to become a replacement for the numerous log files that are currently
  68 found in various locations on the system.
  69 Those files will be phased out in future versions of Mac OS.
  70 .Pp
  71 The following options are recognized:
  72 .Bl -tag -width "-dup_delay"
  73 .It Fl d
  74 Run
  75 .Nm
  76 in debugging mode.
  77 The server stays attached to the controlling terminal and prints debugging messages.
  78 .It Fl D
  79 Start as a daemon.
  80 This option forces
  81 .Nm
  82 to fork and have the child process become a daemon.
  83 Since
  84 .Nm
  85 is started by
  86 .Nm launchd ,
  87 this is not normally required.
  88 .It Fl m
  89 Set the number of minutes between
  90 .Dq mark
  91 messages.
  92 Mark messages are normally disabled.
  93 If
  94 .Fl m
  95 is specified with no arguments, mark messages will be written every 20 minutes.
  96 The
  97 .Dq mark
  98 facility is disabled if the setting is zero minutes.
  99 .It Fl c
 100 Sets a cutoff filter for log priorities for messages to be retained in the log message data store.
 101 The value of
 102 .Ar log_cutoff
 103 must be between 0 and 7, corresponding to log priorities LOG_EMERG or ASL_LEVEL_EMERG
 104 and LOG_DEBUG or ASL_LEVEL_DEBUG as defined in the
 105 .Xr syslog 3
 106 and
 107 .Xr asl 3
 108 header files.
 109 Received messages with a priority or level value greater than the cutoff will not be saved in the data store.
 110 The default filter value is set to allow all message priorities.
 111 Message filtering is primarily specified by the rules in the /etc/asl.conf file.
 112 However, if there are no matching rules for the ASL data store in the asl.conf file,
 113 then all messages that are allowed by the cutoff filter are saved.
 114 .Pp
 115 Note that a this filter value may be adjusted while
 116 .Nm
 117 is running using the
 118 .Nm syslog
 119 command-line utility.
 120 See the
 121 .Xr syslog 1
 122 manual.
 123 The filter may be adjusted using the
 124 .Dq -c
 125 option.
 126 .It Fl l
 127 Specifies an alternate path for loading plug-in modules.
 128 By default,
 129 .Nm
 130 checks for plug-in modules in the directory /usr/lib/asl.
 131 .It Fl db_max
 132 Sets the size limit in bytes for individual files in the data store.
 133 The default value for
 134 .Fl db_max
 135 is 25600000 bytes.
 136 Files are closed upon reaching the maximum size, and a new file is opened for subsequent messages.
 137 .It Fl utmp_ttl
 138 Sets the time-to-live in seconds for messages used by the
 139 .Xr utmp ,
 140 .Xr wtmp ,
 141 and
 142 .Xr lastlog
 143 subsystems.
 144 The default is 31622400 seconds (approximately 1 year).
 145 Note that if archival is enabled (see the
 146 .Xr aslmanager 8
 147 manual), these messages will be copied to an archive
 148 after the regular time-to-live interval, but will persist in the data store until their own expiry time.
 149 .It Fl fs_ttl
 150 Sets the time-to-live in seconds for filesystem error messages generated by the kernel.
 151 The default is 31622400 seconds (approximately 1 year).
 152 As in the case of
 153 .Fl utmp_ttl ,
 154 if archival is enabled, these messages will be copied to an archive after the regular time-to-live
 155 interval but will persist in the data store until their own expiry time.
 156 .It Fl mps_limit
 157 Sets the per-process quota for messages per second allowed by
 158 .Nm .
 159 Any messages in excess of the quota limit from any process are ignored.
 160 An error message is logged on behalf of the limited process, stating that its message quota has
 161 been exceeded, and that remaining messages for the current second will be discarded.
 162 The default limit is 500 messages per second per process.
 163 A value of 0 turns off the quota mechanism.
 164 .It Fl dup_delay
 165 Sets the time to delay for coalescing duplicate message in log files.
 166 If a process logs multiple messages with the same text,
 167 .Nm
 168 will wait for the specified period of time to coalesce duplicates.
 169 If identical messages arrive during this interval,
 170 .Nm
 171 will print a message of the form:
 172 .Pp
 173 .Li             May  7 12:34:56: --- last message repeated 17 times ---
 174 .Pp
 175 The default delay time is 30 seconds.
 176 Setting the value to 0 disables the coalescing mechanism.
 177 .El
 178 .Pp
 179 The remaining options of the form
 180 .Fl module_name Li {0|1}
 181 may be used to disable (0) or enable (1) the action of several of
 182 .Mn 's
 183 internal modules.
 184 .Bl -tag -width "-asl_action"
 185 .It Fl asl_in
 186 The
 187 .Dq asl_in
 188 module receives log messages on the UNIX domain socket associated with the
 189 .Xr asl 3
 190 API.
 191 The module may be disabled using
 192 .Fl asl_in Li 0 .
 193 The module is normally enabled.
 194 .It Fl asl_action
 195 The
 196 .Dq asl_action
 197 module examines the stream of received log messages and acts upon them according to the rules specified
 198 in the file /etc/asl.conf.
 199 See
 200 .Xr asl.conf 5
 201 for details.
 202 .It Fl klog_in
 203 The
 204 .Dq klog_in
 205 module receives log messages on the UNIX domain socket associated with the kernel logging API.
 206 The module may be disabled using
 207 .Fl klog_in Li 0 .
 208 The module is normally enabled.
 209 .It Fl bsd_in
 210 The
 211 .Dq bsd_in
 212 module receives log messages on the UNIX domain socket associated with the
 213 .Xr syslog 3
 214 API.
 215 The module may be disabled using
 216 .Fl bsd_in Li 0 .
 217 The module is normally enabled.
 218 .It Fl bsd_out
 219 The
 220 .Dq bsd_out
 221 module examines the stream of received log messages and acts upon them according to the rules specified
 222 in the file /etc/syslog.conf.
 223 See
 224 .Xr syslog.conf 5
 225 for details.
 226 This module exists for backward compatibility with previous
 227 .Nm
 228 implementations.
 229 Apple encourages use of the
 230 .Xr syslog 1
 231 and
 232 .Xr asl 3
 233 search APIs over the use of the log files that are specified in the /etc/syslog.conf file.
 234 Future versions of Mac OS will move functions that are currently handled by the
 235 .Dq bsd_out
 236 module to the
 237 .Dq asl_action
 238 module.
 239 .It Fl udp_in
 240 The
 241 .Dq udp_in
 242 module receives log messages on the UDP socket associated with the Internet syslog message protocol.
 243 .Pp
 244 This module is normally enabled, but is inactive.
 245 The actual UDP sockets are managed by
 246 .Nm launchd ,
 247 and configured in the
 248 .Nm syslogd
 249 configuration file /System/Library/LaunchDaemons/com.apple.syslogd.plist.
 250 In the default configuration,
 251 .Nm launchd
 252 does not open any sockets for the
 253 .Dq syslog
 254 UDP service, so no sockets are provided to the
 255 .Dq udp_in
 256 module.
 257 If no sockets are provided, the module remains inactive.
 258 A socket may be specified by adding the following entry to the
 259 .Dq Sockets
 260 dictionary in the com.apple.syslogd.plist file.
 261 .Pp
 262 .Dl             <key>NetworkListener</key>
 263 .Dl             <dict>
 264 .Dl                     <key>SockServiceName</key>
 265 .Dl                     <string>syslog</string>
 266 .Dl                     <key>SockType</key>
 267 .Dl                     <string>dgram</string>
 268 .Dl             </dict>
 269 .Pp
 270 The module may be specifically disabled using the
 271 .Fl udp_in Li 0
 272 option.
 273 .El
 274 .Pp
 275 .Nm
 276 reinitializes in response to a HUP signal.
 277 .Sh MESSAGE EXPIRY AND ARCHIVAL
 278 .Nm
 279 periodically invokes the
 280 .Nm aslmanager
 281 utility, which manages files in the ASL data store.
 282 Files are removed or optionally copied to an archival directory after a (default) 2 day time-to-live.
 283 See the
 284 .Xr aslmanager 8
 285 manual for details.
 286 .Nm
 287 invokes
 288 .Nm aslmanager
 289 shortly after it starts up, at midnight local time if it is running,
 290 and any time that a data store file reaches the
 291 .Fl db_max
 292 size limit.
 293 .Sh DATA STORE SECURITY
 294 Messages saved in the ASL message store are written to files in /var/log/asl.
 295 The message files are given read access controls corresponding to the read UID and GID specified in the messages themselves.
 296 Read access UID and GID settings may be attached to messages using the
 297 .Xr asl 3
 298 library by setting a value for the "ReadUID" and/or "ReadGID" message keys.
 299 The file permissions prevent access-controlled messages from being read by unauthorized users.
 300 .Pp
 301 Although clients are generally free to use any value for the "Facility" message key,
 302 only processes running with UID 0 may log messages with a facility value of "com.apple.system",
 303 or with a value that has "com.apple.system" as a prefix.
 304 Messages logged by non UID 0 processes that use "com.apple.system" as a facility value or prefix
 305 will be saved with the facility value "user".
 306 .Sh FILES
 307 .Bl -tag -width /var/log/asl.archive -compact
 308 .It Pa /etc/syslog.conf
 309 bsd_out module configuration file
 310 .It Pa /etc/asl.conf
 311 asl_action module configuration file
 312 .It Pa /var/run/syslog.pid
 313 process ID file
 314 .It Pa /var/run/log
 315 name of the
 316 .Ux
 317 domain datagram log socket
 318 .It Pa /dev/klog
 319 kernel log device
 320 .It Pa /var/log/asl
 321 data store directory
 322 .It Pa /var/log/asl.archive
 323 default archive directory
 324 .It Pa /System/Library/LaunchDaemons/com.apple.syslogd.plist
 325 launchd configuration file for
 326 .Nm syslogd
 327 .El
 328 .Sh SEE ALSO
 329 .Xr syslog 1 ,
 330 .Xr logger 1 ,
 331 .Xr asl 3 ,
 332 .Xr syslog 3 ,
 333 .Xr asl.conf 5
 334 .Xr syslog.conf 5
 335 .Sh HISTORY
 336 The
 337 .Nm
 338 utility appeared in
 339 .Bx 4.3 .
 340 .Pp
 341 The Apple System Log facility was introduced in Mac OS X 10.4.