syslogd.tproj/syslogd.8

   1 .\" Copyright (c) 2004 Apple Computer
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of Apple Computer nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"
  29 .Dd October 18, 2004
  30 .Dt SYSLOGD 8
  31 .Os "Mac OS X"
  32 .Sh NAME
  33 .Nm syslogd
  34 .Nd Apple System Log server
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl d
  38 .Op Fl D
  39 .Op Fl m Ar mark_interval
  40 .Op Fl p Ar prune_days
  41 .Op Fl c Ar log_cutoff
  42 .Op Fl l Ar lib_path
  43 .Op Fl u
  44 .Op Fl module_name Li {0|1}
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 server receives and processes log messages.
  49 Several modules receive input messages through various channels,
  50 including UNIX domain sockets associated with the
  51 .Xr syslog 3 ,
  52 .Xr asl 3 ,
  53 and kernel printf APIs,
  54 and optionally from a UDP socket if the
  55 .Dq udp_in
  56 module is enabled.
  57 .Pp
  58 The Apple System Log facility comprises the
  59 .Xr asl 3
  60 API, a new
  61 .Nm
  62 server, and the
  63 .Xr syslog 1
  64 command-line utility.
  65 The system supports structured and extensible messages,
  66 permitting advanced message browsing and management through search APIs and
  67 other components of the Apple system log facility.
  68 .Pp
  69 Log messages are retained in a data store,
  70 subject to pruning and input filtering as described below,
  71 to simplify the task of locating log messages and to facilitate browsing and searching.
  72 The data store is intended to become a replacement for the numerous log files that are currently
  73 found in various locations on the system.
  74 Those files will be phased out in future versions of Mac OS.
  75 .Pp
  76 The following options are recognized:
  77 .Bl -tag -width indent
  78 .It Fl d
  79 Run
  80 .Nm
  81 in debugging mode.
  82 The server stays attached to the controlling terminal and prints debugging messages.
  83 .It Fl D
  84 Start as a daemon.
  85 This option forces
  86 .Nm
  87 to fork and have the child process become a daemon.
  88 Since
  89 .Nm
  90 is started by
  91 .Nm launchd ,
  92 this is not normally required.
  93 .It Fl m
  94 Set the number of minutes between
  95 .Dq mark
  96 messages.
  97 The default is 20 minutes.
  98 The
  99 .Dq mark
 100 facility is disabled if the setting is zero minutes.
 101 .It Fl p
 102 .Nm
 103 saves log messages in a data store that may be searched using the
 104 .Xr syslog 1
 105 utility or with the
 106 .Xr asl 3
 107 API.
 108 The data store is pruned daily by the /etc/daily cron job to keep it from growing without bound.
 109 Since many systems are shut down overnight (when the daily cron job runs),
 110 the data store is also pruned shortly after
 111 .Nm
 112 starts up as the system boots.
 113 By default, log messages in the data store that are more than 7 days old are removed.
 114 The setting of the
 115 .Fl p Ar prune_days
 116 overrides the default.
 117 A setting of zero days disables pruning of the data store when
 118 .Nm
 119 starts up.
 120 .It Fl c
 121 Sets a cutoff filter for log priorities for messages to be retained in the log message data store.
 122 The value of
 123 .Ar log_cutoff
 124 must be between 0 and 7, corresponding to log priorities LOG_EMERG or ASL_LEVEL_EMERG
 125 and LOG_DEBUG or ASL_LEVEL_DEBUG as defined in the
 126 .Xr syslog 3
 127 and
 128 .Xr asl 3
 129 header files.
 130 Received messages with a priority or level value greater than the cutoff will not be saved in the data store.
 131 The default filter will retain messages in the range 0 (Emergency) to 5 (Notice) inclusive.
 132 .Pp
 133 Note that a this filter value may be adjusted while
 134 .Nm
 135 is running using the
 136 .Nm syslog
 137 command-line utility.
 138 See the
 139 .Xr syslog 1
 140 manual.
 141 The filter may be adjusted using the
 142 .Dq -c
 143 option, e.g.
 144 .Pp
 145 .Li             sudo syslog -c syslogd -d
 146 .Pp
 147 will set the filter to retain messages in the range 0 (Emergency) to 7 (Debug).
 148 .It Fl l
 149 Specifies an alternate path for loading plug-in modules.
 150 By default,
 151 .Nm
 152 checks for plug-in modules in the directory /usr/lib/asl.
 153 .It Fl u
 154 Enables the
 155 .Dq udp_in
 156 module, configuring
 157 .Nm
 158 to act as a network log message receiver.
 159 The server will receive messages on the standard
 160 .Dq syslog
 161 UDP port.
 162 Note that this opens the server to potential denial-of-service attacks,
 163 as a malicious remote sender can flood the server with messages.
 164 The
 165 .Fl u
 166 option is equivalent to using the
 167 .Fl udp_in Li 1
 168 option.
 169 .El
 170 .Pp
 171 The remaining options of the form
 172 .Fl module_name Li {0|1}
 173 may be used to disable (0) or enable (1) the action of several of
 174 .Mn 's
 175 internal modules.
 176 .Bl -tag -width "-asl_action"
 177 .It Fl asl_in
 178 The
 179 .Dq asl_in
 180 module receives log messages on the UNIX domain socket associated with the
 181 .Xr asl 3
 182 API.
 183 The module may be disabled using
 184 .Fl asl_in Li 0 .
 185 The module is normally enabled.
 186 .It Fl asl_action
 187 The
 188 .Dq asl_action
 189 module examines the stream of received log messages and acts upon them according to the rules specified
 190 in the file /etc/asl.conf.
 191 See
 192 .Xr asl.conf 5
 193 for details.
 194 .It Fl klog_in
 195 The
 196 .Dq klog_in
 197 module receives log messages on the UNIX domain socket associated with the kernel logging API.
 198 The module may be disabled using
 199 .Fl klog_in Li 0 .
 200 The module is normally enabled.
 201 .It Fl bsd_in
 202 The
 203 .Dq bsd_in
 204 module receives log messages on the UNIX domain socket associated with the
 205 .Xr syslog 3
 206 API.
 207 The module may be disabled using
 208 .Fl bsd_in Li 0 .
 209 The module is normally enabled.
 210 .It Fl bsd_out
 211 The
 212 .Dq bsd_out
 213 module examines the stream of received log messages and acts upon them according to the rules specified
 214 in the file /etc/syslog.conf.
 215 See
 216 .Xr syslog.conf 5
 217 for details.
 218 This module exists for backward compatibility with previous
 219 .Nm
 220 implementations.
 221 Apple encourages use of the
 222 .Xr syslog 1
 223 and
 224 .Xr asl 3
 225 search APIs over the use of the log files that are specified in the /etc/syslog.conf file.
 226 Future versions of Mac OS will move functions that are currently handled by the
 227 .Dq bsd_out
 228 module to the
 229 .Dq asl_action
 230 module.
 231 .It Fl udp_in
 232 The
 233 .Dq udp_in
 234 module receives log messages on the UDP socket associated with the Internet syslog message protocol.
 235 The module may be enabled using
 236 .Fl udp_in Li 1 .
 237 The module is normally disabled.
 238 This module may also be enabled using the
 239 .Fl u
 240 option.
 241 .El
 242 .Pp
 243 .Nm
 244 initializes its built-in modules and loads plug-ins during its start-up.
 245 The data store is pruned approximately 5 minutes after startup.
 246 .Pp
 247 .Nm
 248 reinitializes in response to a HUP signal.
 249 .Sh FILES
 250 .Bl -tag -width /var/run/syslog.pid -compact
 251 .It Pa /etc/syslog.conf
 252 bsd_out module configuration file
 253 .It Pa /etc/asl.conf
 254 asl_action module configuration file
 255 .It Pa /var/run/syslog.pid
 256 process ID file
 257 .It Pa /var/run/log
 258 name of the
 259 .Ux
 260 domain datagram log socket
 261 .It Pa /dev/klog
 262 kernel log device
 263 .El
 264 .Sh SEE ALSO
 265 .Xr syslog 1 ,
 266 .Xr logger 1 ,
 267 .Xr asl 3 ,
 268 .Xr syslog 3 ,
 269 .Xr asl.conf 5
 270 .Xr syslog.conf 5
 271 .Sh HISTORY
 272 The
 273 .Nm
 274 utility appeared in
 275 .Bx 4.3 .
 276 .Pp
 277 The Apple System Log facility was introduced in Mac OS X 10.4.