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