syslogd.tproj/syslogd.8

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