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 per-process 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 on behalf of the limited process, stating that its 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 .It Fl dup_delay
 124 Sets the time to delay for coalescing duplicate message in log files.
 125 If a process logs multiple messages with the same text,
 126 .Nm
 127 will wait for the specified period of time to coalesce duplicates.
 128 If identical messages arrive during this interval,
 129 .Nm
 130 will print a message of the form:
 131 .Pp
 132 .Li             May  7 12:34:56: --- last message repeated 17 times ---
 133 .Pp
 134 The default delay time is 30 seconds.
 135 Setting the value to 0 disables the coalescing mechanism.
 136 .El
 137 .Pp
 138 The remaining options of the form
 139 .Fl module_name Li {0|1}
 140 may be used to disable (0) or enable (1) the action of several of
 141 .Mn 's
 142 internal modules.
 143 .Bl -tag -width "-asl_action"
 144 .It Fl asl_in
 145 The
 146 .Dq asl_in
 147 module receives log messages on the UNIX domain socket associated with the
 148 .Xr asl 3
 149 API.
 150 The module may be disabled using
 151 .Fl asl_in Li 0 .
 152 The module is normally enabled.
 153 .It Fl asl_action
 154 The
 155 .Dq asl_action
 156 module examines the stream of received log messages and acts upon them according to the rules specified
 157 in the file /etc/asl.conf.
 158 See
 159 .Xr asl.conf 5
 160 for details.
 161 .It Fl klog_in
 162 The
 163 .Dq klog_in
 164 module receives log messages on the UNIX domain socket associated with the kernel logging API.
 165 The module may be disabled using
 166 .Fl klog_in Li 0 .
 167 The module is normally enabled.
 168 .It Fl bsd_in
 169 The
 170 .Dq bsd_in
 171 module receives log messages on the UNIX domain socket associated with the
 172 .Xr syslog 3
 173 API.
 174 The module may be disabled using
 175 .Fl bsd_in Li 0 .
 176 The module is normally enabled.
 177 .It Fl bsd_out
 178 The
 179 .Dq bsd_out
 180 module examines the stream of received log messages and acts upon them according to the rules specified
 181 in the file /etc/syslog.conf.
 182 See
 183 .Xr syslog.conf 5
 184 for details.
 185 This module exists for backward compatibility with previous
 186 .Nm
 187 implementations.
 188 Apple encourages use of the
 189 .Xr syslog 1
 190 and
 191 .Xr asl 3
 192 search APIs over the use of the log files that are specified in the /etc/syslog.conf file.
 193 Future versions of Mac OS will move functions that are currently handled by the
 194 .Dq bsd_out
 195 module to the
 196 .Dq asl_action
 197 module.
 198 .It Fl udp_in
 199 The
 200 .Dq udp_in
 201 module receives log messages on the UDP socket associated with the Internet syslog message protocol.
 202 .Pp
 203 This module is normally enabled, but is inactive.
 204 The actual UDP sockets are managed by
 205 .Nm launchd ,
 206 and configured in the
 207 .Nm syslogd
 208 configuration file /System/Library/LaunchDaemons/com.apple.syslogd.plist.
 209 In the default configuration,
 210 .Nm launchd
 211 does not open any sockets for the
 212 .Dq syslog
 213 UDP service, so no sockets are provided to the
 214 .Dq udp_in
 215 module.
 216 If no sockets are provided, the module remains inactive.
 217 A socket may be specified by adding the following entry to the
 218 .Dq Sockets
 219 dictionary in the com.apple.syslogd.plist file.
 220 .Pp
 221 .Dl             <key>NetworkListener</key>
 222 .Dl             <dict>
 223 .Dl                     <key>SockServiceName</key>
 224 .Dl                     <string>syslog</string>
 225 .Dl                     <key>SockType</key>
 226 .Dl                     <string>dgram</string>
 227 .Dl             </dict>
 228 .Pp
 229 The module may be specifically disabled using the
 230 .Fl udp_in Li 0
 231 option.
 232 .El
 233 .Pp
 234 .Nm
 235 reinitializes in response to a HUP signal.
 236 .Sh MESSAGE EXPIRY AND ARCHIVAL
 237 .Nm
 238 periodically invokes the
 239 .Nm aslmanager
 240 utility, which manages files in the ASL data store.
 241 Files are removed or optionally copied to an archival directory after a (default) 2 day time-to-live.
 242 See the
 243 .Xr aslmanager 8
 244 manual for details.
 245 .Nm
 246 invokes
 247 .Nm aslmanager
 248 shortly after it starts up, at midnight local time if it is running,
 249 and any time that a data store file reaches the
 250 .Fl db_max
 251 size limit.
 252 .Sh DATA STORE SECURITY
 253 Messages saved in the ASL message store are written to files in /var/log/asl.
 254 The message files are given read access controls corresponding to the read UID and GID specified in the messages themselves.
 255 Read access UID and GID settings may be attached to messages using the
 256 .Xr asl 3
 257 library by setting a value for the "ReadUID" and/or "ReadGID" message keys.
 258 The file permissions prevent access-controlled messages from being read by unauthorized users.
 259 .Pp
 260 Although clients are generally free to use any value for the "Facility" message key,
 261 only processes running with UID 0 may log messages with a facility value of "com.apple.system",
 262 or with a value that has "com.apple.system" as a prefix.
 263 Messages logged by non UID 0 processes that use "com.apple.system" as a facility value or prefix
 264 will be saved with the facility value "user".
 265 .Sh FILES
 266 .Bl -tag -width /var/log/asl.archive -compact
 267 .It Pa /etc/syslog.conf
 268 bsd_out module configuration file
 269 .It Pa /etc/asl.conf
 270 asl_action module configuration file
 271 .It Pa /var/run/syslog.pid
 272 process ID file
 273 .It Pa /var/run/log
 274 name of the
 275 .Ux
 276 domain datagram log socket
 277 .It Pa /dev/klog
 278 kernel log device
 279 .It Pa /var/log/asl
 280 data store directory
 281 .It Pa /var/log/asl.archive
 282 default archive directory
 283 .It Pa /System/Library/LaunchDaemons/com.apple.syslogd.plist
 284 launchd configuration file for
 285 .Nm syslogd
 286 .El
 287 .Sh SEE ALSO
 288 .Xr syslog 1 ,
 289 .Xr logger 1 ,
 290 .Xr asl 3 ,
 291 .Xr syslog 3 ,
 292 .Xr asl.conf 5
 293 .Xr syslog.conf 5
 294 .Sh HISTORY
 295 The
 296 .Nm
 297 utility appeared in
 298 .Bx 4.3 .
 299 .Pp
 300 The Apple System Log facility was introduced in Mac OS X 10.4.