syslog-356.200.4.tar.gz

[apple/syslog.git] / syslogd.tproj / syslogd.8

diff --git a/syslogd.tproj/syslogd.8 b/syslogd.tproj/syslogd.8
index 2dd6da1fa28b14f18357192ac6b2e88416c29b6c..0d72d0d0b8a4829cc98b7783ea108050664043b6 100644 (file)
--- a/syslogd.tproj/syslogd.8
+++ b/syslogd.tproj/syslogd.8
@@ -1,30 +1,23 @@
-.\" Copyright (c) 2004 Apple Computer
-.\" All rights reserved.
+.\"Copyright (c) 2004-2011 Apple Inc. All rights reserved.

 .\"
 .\"

-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 4. Neither the name of Apple Computer nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
+.\"@APPLE_LICENSE_HEADER_START@

 .\"
 .\"

-.\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
+.\"This file contains Original Code and/or Modifications of Original Code
+.\"as defined in and that are subject to the Apple Public Source License
+.\"Version 2.0 (the 'License'). You may not use this file except in
+.\"compliance with the License. Please obtain a copy of the License at
+.\"http://www.opensource.apple.com/apsl/ and read it before using this
+.\"file.

 .\"
 .\"

+.\"The Original Code and all software distributed under the License are
+.\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\"Please see the License for the specific language governing rights and
+.\"limitations under the License.
+.\"
+.\"@APPLE_LICENSE_HEADER_END@

 .\"
 .Dd October 18, 2004
 .Dt SYSLOGD 8
 .\"
 .Dd October 18, 2004
 .Dt SYSLOGD 8


@@ -37,10 +30,11 @@
 .Op Fl d
 .Op Fl D
 .Op Fl m Ar mark_interval
 .Op Fl d
 .Op Fl D
 .Op Fl m Ar mark_interval

-.Op Fl p Ar prune_days
-.Op Fl c Ar log_cutoff

 .Op Fl l Ar lib_path
 .Op Fl l Ar lib_path

-.Op Fl u
+.Op Fl db_max Ar size
+.Op Fl utmp_ttl Ar time
+.Op Fl mps_limit Ar quota
+.Op Fl dup_delay Ar time

 .Op Fl module_name Li {0|1}
 .Sh DESCRIPTION
 The
 .Op Fl module_name Li {0|1}
 .Sh DESCRIPTION
 The


@@ -51,30 +45,29 @@ including UNIX domain sockets associated with the
 .Xr syslog 3 ,
 .Xr asl 3 ,
 and kernel printf APIs, 
 .Xr syslog 3 ,
 .Xr asl 3 ,
 and kernel printf APIs, 

-and optionally from a UDP socket if the
-.Dq udp_in
-module is enabled.
+and optionally on a UDP socket from network clients.

 .Pp
 The Apple System Log facility comprises the 
 .Xr asl 3
 API, a new 
 .Nm
 .Pp
 The Apple System Log facility comprises the 
 .Xr asl 3
 API, a new 
 .Nm

-server, and the
+server, the

 .Xr syslog 1
 .Xr syslog 1

-command-line utility.
+command-line utility, and a data store file manager,
+.Xr aslmanager 8 .

 The system supports structured and extensible messages, 
 permitting advanced message browsing and management through search APIs and
 other components of the Apple system log facility.
 .Pp
 Log messages are retained in a data store,
 The system supports structured and extensible messages, 
 permitting advanced message browsing and management through search APIs and
 other components of the Apple system log facility.
 .Pp
 Log messages are retained in a data store,

-subject to pruning and input filtering as described below,
+subject to automatic archival, and input filtering as described below,

 to simplify the task of locating log messages and to facilitate browsing and searching.
 The data store is intended to become a replacement for the numerous log files that are currently
 found in various locations on the system.
 Those files will be phased out in future versions of Mac OS.
 .Pp
 The following options are recognized:
 to simplify the task of locating log messages and to facilitate browsing and searching.
 The data store is intended to become a replacement for the numerous log files that are currently
 found in various locations on the system.
 Those files will be phased out in future versions of Mac OS.
 .Pp
 The following options are recognized:

-.Bl -tag -width indent
+.Bl -tag -width "-dup_delay"

 .It Fl d
 Run
 .Nm
 .It Fl d
 Run
 .Nm


@@ -94,78 +87,58 @@ this is not normally required.
 Set the number of minutes between
 .Dq mark
 messages.
 Set the number of minutes between
 .Dq mark
 messages.

-The default is 20 minutes.
+Mark messages are normally disabled.
+If
+.Fl m
+is specified with no arguments, mark messages will be written every 20 minutes.

 The 
 .Dq mark
 facility is disabled if the setting is zero minutes.
 The 
 .Dq mark
 facility is disabled if the setting is zero minutes.

-.It Fl p
-.Nm
-saves log messages in a data store that may be searched using the
-.Xr syslog 1
-utility or with the
-.Xr asl 3
-API.
-The data store is pruned daily by the /etc/daily cron job to keep it from growing without bound.
-Since many systems are shut down overnight (when the daily cron job runs),
-the data store is also pruned shortly after
-.Nm
-starts up as the system boots.
-By default, log messages in the data store that are more than 7 days old are removed.
-The setting of the
-.Fl p Ar prune_days
-overrides the default.
-A setting of zero days disables pruning of the data store when
-.Nm
-starts up.
-.It Fl c
-Sets a cutoff filter for log priorities for messages to be retained in the log message data store.
-The value of 
-.Ar log_cutoff
-must be between 0 and 7, corresponding to log priorities LOG_EMERG or ASL_LEVEL_EMERG
-and LOG_DEBUG or ASL_LEVEL_DEBUG as defined in the 
-.Xr syslog 3
+.It Fl db_max
+Sets the size limit in bytes for individual files in the data store.
+The default value for
+.Fl db_max
+is 25600000 bytes.
+Files are closed upon reaching the maximum size, and a new file is opened for subsequent messages.
+.It Fl utmp_ttl
+Sets the time-to-live in seconds for messages used by the
+.Xr utmp ,
+.Xr wtmp ,

 and
 and

-.Xr asl 3
-header files.
-Received messages with a priority or level value greater than the cutoff will not be saved in the data store.
-The default filter will retain messages in the range 0 (Emergency) to 5 (Notice) inclusive.
+.Xr lastlog
+subsystems.
+The default is 31622400 seconds (approximately 1 year).
+Note that if archival is enabled (see the
+.Xr aslmanager 8
+manual), these messages will be copied to an archive
+after the regular time-to-live interval, but will persist in the data store until their own expiry time.
+.It Fl mps_limit
+Sets the kernel quota for messages per second allowed by
+.Nm .
+Any messages in excess of the quota limit from any process are ignored.
+An error message is logged stating that the kernel message quota has
+been exceeded, and that remaining messages for the current second will be discarded.
+The default limit is 500 messages per second per process.
+A value of 0 turns off the quota mechanism.

 .Pp
 .Pp

-Note that a this filter value may be adjusted while
+Note that this setting only limits the number of kernel messages that will be saved by
+.Nm .
+User processes are limited to 36000 messages per hour.
+The limit for a user process is not enforced if a remote-control ASL filter is in
+place for the process.
+.It Fl dup_delay
+Sets the time to delay for coalescing duplicate message in log files.
+If a process logs multiple messages with the same text,

 .Nm
 .Nm

-is running using the
-.Nm syslog
-command-line utility.
-See the
-.Xr syslog 1
-manual.
-The filter may be adjusted using the
-.Dq -c
-option, e.g.
+will wait for the specified period of time to coalesce duplicates.
+If identical messages arrive during this interval,
+.Nm
+will print a message of the form:

 .Pp
 .Pp

-.Li            sudo syslog -c syslogd -d
+.Li            May  7 12:34:56: --- last message repeated 17 times ---

 .Pp
 .Pp

-will set the filter to retain messages in the range 0 (Emergency) to 7 (Debug).
-.It Fl l
-Specifies an alternate path for loading plug-in modules.
-By default,
-.Nm
-checks for plug-in modules in the directory /usr/lib/asl.
-.It Fl u
-Enables the
-.Dq udp_in
-module, configuring
-.Nm
-to act as a network log message receiver.
-The server will receive messages on the standard 
-.Dq syslog
-UDP port.
-Note that this opens the server to potential denial-of-service attacks,
-as a malicious remote sender can flood the server with messages.
-The 
-.Fl u
-option is equivalent to using the
-.Fl udp_in Li 1
-option.
+The default delay time is 30 seconds.
+Setting the value to 0 disables the coalescing mechanism.

 .El
 .Pp
 The remaining options of the form
 .El
 .Pp
 The remaining options of the form


@@ -232,34 +205,90 @@ module.
 The 
 .Dq udp_in
 module receives log messages on the UDP socket associated with the Internet syslog message protocol.
 The 
 .Dq udp_in
 module receives log messages on the UDP socket associated with the Internet syslog message protocol.

-The module may be enabled using
-.Fl udp_in Li 1 .
-The module is normally disabled.
-This module may also be enabled using the
-.Fl u
+.Pp
+This module is normally enabled, but is inactive.
+The actual UDP sockets are managed by
+.Nm launchd ,
+and configured in the
+.Nm syslogd
+configuration file /System/Library/LaunchDaemons/com.apple.syslogd.plist.
+In the default configuration, 
+.Nm launchd
+does not open any sockets for the
+.Dq syslog
+UDP service, so no sockets are provided to the
+.Dq udp_in 
+module.
+If no sockets are provided, the module remains inactive.
+A socket may be specified by adding the following entry to the
+.Dq Sockets
+dictionary in the com.apple.syslogd.plist file.
+.Pp
+.Dl            <key>NetworkListener</key>
+.Dl            <dict>
+.Dl                    <key>SockServiceName</key>
+.Dl                    <string>syslog</string>
+.Dl                    <key>SockType</key>
+.Dl                    <string>dgram</string>
+.Dl            </dict>
+.Pp
+The module may be specifically disabled using the
+.Fl udp_in Li 0 

 option.
 .El
 .Pp
 .Nm
 option.
 .El
 .Pp
 .Nm

-initializes its built-in modules and loads plug-ins during its start-up.
-The data store is pruned approximately 5 minutes after startup.
-.Pp
-.Nm

 reinitializes in response to a HUP signal.
 reinitializes in response to a HUP signal.

+.Sh MESSAGE EXPIRY AND ARCHIVAL
+.Nm
+periodically invokes the
+.Nm aslmanager
+utility, which manages files in the ASL data store.
+Files are removed or optionally copied to an archival directory after a (default) 2 day time-to-live.
+See the
+.Xr aslmanager 8
+manual for details.
+.Nm
+invokes
+.Nm aslmanager
+shortly after it starts up, at midnight local time if it is running,
+and any time that a data store file reaches the
+.Fl db_max
+size limit.
+.Sh DATA STORE SECURITY
+Messages saved in the ASL message store are written to files in /var/log/asl.
+The message files are given read access controls corresponding to the read UID and GID specified in the messages themselves.
+Read access UID and GID settings may be attached to messages using the
+.Xr asl 3
+library by setting a value for the "ReadUID" and/or "ReadGID" message keys.
+The file permissions prevent access-controlled messages from being read by unauthorized users.
+.Pp
+Although clients are generally free to use any value for the "Facility" message key,
+only processes running with UID 0 may log messages with a facility value of "com.apple.system",
+or with a value that has "com.apple.system" as a prefix.
+Messages logged by non UID 0 processes that use "com.apple.system" as a facility value or prefix
+will be saved with the facility value "user".

 .Sh FILES
 .Sh FILES

-.Bl -tag -width /var/run/syslog.pid -compact
+.Bl -tag -width /var/log/asl.archive -compact

 .It Pa /etc/syslog.conf
 bsd_out module configuration file
 .It Pa /etc/asl.conf
 asl_action module configuration file
 .It Pa /var/run/syslog.pid
 process ID file
 .It Pa /etc/syslog.conf
 bsd_out module configuration file
 .It Pa /etc/asl.conf
 asl_action module configuration file
 .It Pa /var/run/syslog.pid
 process ID file

-.It Pa /var/run/log
+.It Pa /var/run/syslog

 name of the
 .Ux
 domain datagram log socket
 .It Pa /dev/klog
 kernel log device
 name of the
 .Ux
 domain datagram log socket
 .It Pa /dev/klog
 kernel log device

+.It Pa /var/log/asl
+data store directory
+.It Pa /var/log/asl.archive
+default archive directory
+.It Pa /System/Library/LaunchDaemons/com.apple.syslogd.plist
+launchd configuration file for
+.Nm syslogd

 .El
 .Sh SEE ALSO
 .Xr syslog 1 ,
 .El
 .Sh SEE ALSO
 .Xr syslog 1 ,