liblog/courierlogger.1

   1 '\" t
   2 .\"  <!-- Copyright 2004-2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: courierlogger
   5 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   6 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
   7 .\"      Date: 08/25/2013
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"  Language: English
  11 .\"
  12 .TH "COURIERLOGGER" "1" "08/25/2013" "Double Precision, Inc." "Double Precision, Inc."
  13 .\" -----------------------------------------------------------------
  14 .\" * Define some portability stuff
  15 .\" -----------------------------------------------------------------
  16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 .\" http://bugs.debian.org/507673
  18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 .ie \n(.g .ds Aq \(aq
  21 .el       .ds Aq '
  22 .\" -----------------------------------------------------------------
  23 .\" * set default formatting
  24 .\" -----------------------------------------------------------------
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .\" -----------------------------------------------------------------
  30 .\" * MAIN CONTENT STARTS HERE *
  31 .\" -----------------------------------------------------------------
  32 .SH "NAME"
  33 courierlogger \- Courier syslog wrapper
  34 .SH "SYNOPSIS"
  35 .HP \w'\fBcourierlogger\fR\ 'u
  36 \fBcourierlogger\fR [\-name=\fItitle\fR] [\-facility=\fIsubsystem\fR] [\-pid=\fIfilename\fR] [\-user=\fIuser\fR] [\-group=\fIgroup\fR] [\-droproot] [[[\-respawn]\ [\-start]\ \fIprogram\fR\ [argument...]] | [\-stop] | [\-restart]]
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBcourierlogger\fR
  40 is a wrapper that captures another process\*(Aqs error messages, and forwards them to the system logging facility,
  41 \(lqsyslog\(rq\&.
  42 .PP
  43 There are two ways to use courierlogger:
  44 .sp
  45 .RS 4
  46 .ie n \{\
  47 \h'-04' 1.\h'+01'\c
  48 .\}
  49 .el \{\
  50 .sp -1
  51 .IP "  1." 4.2
  52 .\}
  53 Use the shell to pipe another command\*(Aqs standard error, and/or its standard output, to
  54 \fBcourierlogger\fR\*(Aqs standard input\&.
  55 .RE
  56 .sp
  57 .RS 4
  58 .ie n \{\
  59 \h'-04' 2.\h'+01'\c
  60 .\}
  61 .el \{\
  62 .sp -1
  63 .IP "  2." 4.2
  64 .\}
  65 Alternatively,
  66 \fBcourierlogger\fR
  67 itself can start another process, and arrange to have its standard error captured\&.
  68 .RE
  69 .PP
  70 In either case, each read line of text is sent as a syslog message\&.
  71 .SH "OPTIONS"
  72 .PP
  73 \-name=\fItitle\fR
  74 .RS 4
  75 Use
  76 \fItitle\fR
  77 for sending messages to syslog\&.
  78 \fItitle\fR
  79 should be the application\*(Aqs name\&.
  80 .RE
  81 .PP
  82 \-facility=\fIsubsystem\fR
  83 .RS 4
  84 Use
  85 \fIsubsystem\fR
  86 for classifying messages\&. Your syslog facility uses
  87 \fIsubsystem\fR
  88 to determine which log messages are recorded in which log files\&. The currently defined subsystems are:
  89 .sp
  90 .RS 4
  91 .ie n \{\
  92 \h'-04'\(bu\h'+03'\c
  93 .\}
  94 .el \{\
  95 .sp -1
  96 .IP \(bu 2.3
  97 .\}
  98 auth
  99 .RE
 100 .sp
 101 .RS 4
 102 .ie n \{\
 103 \h'-04'\(bu\h'+03'\c
 104 .\}
 105 .el \{\
 106 .sp -1
 107 .IP \(bu 2.3
 108 .\}
 109 authpriv
 110 .RE
 111 .sp
 112 .RS 4
 113 .ie n \{\
 114 \h'-04'\(bu\h'+03'\c
 115 .\}
 116 .el \{\
 117 .sp -1
 118 .IP \(bu 2.3
 119 .\}
 120 console
 121 .RE
 122 .sp
 123 .RS 4
 124 .ie n \{\
 125 \h'-04'\(bu\h'+03'\c
 126 .\}
 127 .el \{\
 128 .sp -1
 129 .IP \(bu 2.3
 130 .\}
 131 cron
 132 .RE
 133 .sp
 134 .RS 4
 135 .ie n \{\
 136 \h'-04'\(bu\h'+03'\c
 137 .\}
 138 .el \{\
 139 .sp -1
 140 .IP \(bu 2.3
 141 .\}
 142 daemon
 143 .RE
 144 .sp
 145 .RS 4
 146 .ie n \{\
 147 \h'-04'\(bu\h'+03'\c
 148 .\}
 149 .el \{\
 150 .sp -1
 151 .IP \(bu 2.3
 152 .\}
 153 ftp
 154 .RE
 155 .sp
 156 .RS 4
 157 .ie n \{\
 158 \h'-04'\(bu\h'+03'\c
 159 .\}
 160 .el \{\
 161 .sp -1
 162 .IP \(bu 2.3
 163 .\}
 164 kern
 165 .RE
 166 .sp
 167 .RS 4
 168 .ie n \{\
 169 \h'-04'\(bu\h'+03'\c
 170 .\}
 171 .el \{\
 172 .sp -1
 173 .IP \(bu 2.3
 174 .\}
 175 lpr
 176 .RE
 177 .sp
 178 .RS 4
 179 .ie n \{\
 180 \h'-04'\(bu\h'+03'\c
 181 .\}
 182 .el \{\
 183 .sp -1
 184 .IP \(bu 2.3
 185 .\}
 186 mail
 187 .RE
 188 .sp
 189 .RS 4
 190 .ie n \{\
 191 \h'-04'\(bu\h'+03'\c
 192 .\}
 193 .el \{\
 194 .sp -1
 195 .IP \(bu 2.3
 196 .\}
 197 news
 198 .RE
 199 .sp
 200 .RS 4
 201 .ie n \{\
 202 \h'-04'\(bu\h'+03'\c
 203 .\}
 204 .el \{\
 205 .sp -1
 206 .IP \(bu 2.3
 207 .\}
 208 security
 209 .RE
 210 .sp
 211 .RS 4
 212 .ie n \{\
 213 \h'-04'\(bu\h'+03'\c
 214 .\}
 215 .el \{\
 216 .sp -1
 217 .IP \(bu 2.3
 218 .\}
 219 user
 220 .RE
 221 .sp
 222 .RS 4
 223 .ie n \{\
 224 \h'-04'\(bu\h'+03'\c
 225 .\}
 226 .el \{\
 227 .sp -1
 228 .IP \(bu 2.3
 229 .\}
 230 uucp
 231 .RE
 232 .sp
 233 .RS 4
 234 .ie n \{\
 235 \h'-04'\(bu\h'+03'\c
 236 .\}
 237 .el \{\
 238 .sp -1
 239 .IP \(bu 2.3
 240 .\}
 241 local0
 242 .RE
 243 .sp
 244 .RS 4
 245 .ie n \{\
 246 \h'-04'\(bu\h'+03'\c
 247 .\}
 248 .el \{\
 249 .sp -1
 250 .IP \(bu 2.3
 251 .\}
 252 local1
 253 .RE
 254 .sp
 255 .RS 4
 256 .ie n \{\
 257 \h'-04'\(bu\h'+03'\c
 258 .\}
 259 .el \{\
 260 .sp -1
 261 .IP \(bu 2.3
 262 .\}
 263 local2
 264 .RE
 265 .sp
 266 .RS 4
 267 .ie n \{\
 268 \h'-04'\(bu\h'+03'\c
 269 .\}
 270 .el \{\
 271 .sp -1
 272 .IP \(bu 2.3
 273 .\}
 274 local3
 275 .RE
 276 .sp
 277 .RS 4
 278 .ie n \{\
 279 \h'-04'\(bu\h'+03'\c
 280 .\}
 281 .el \{\
 282 .sp -1
 283 .IP \(bu 2.3
 284 .\}
 285 local4
 286 .RE
 287 .sp
 288 .RS 4
 289 .ie n \{\
 290 \h'-04'\(bu\h'+03'\c
 291 .\}
 292 .el \{\
 293 .sp -1
 294 .IP \(bu 2.3
 295 .\}
 296 local5
 297 .RE
 298 .sp
 299 .RS 4
 300 .ie n \{\
 301 \h'-04'\(bu\h'+03'\c
 302 .\}
 303 .el \{\
 304 .sp -1
 305 .IP \(bu 2.3
 306 .\}
 307 local6
 308 .RE
 309 .sp
 310 .RS 4
 311 .ie n \{\
 312 \h'-04'\(bu\h'+03'\c
 313 .\}
 314 .el \{\
 315 .sp -1
 316 .IP \(bu 2.3
 317 .\}
 318 local7
 319 .RE
 320 .sp
 321 .if n \{\
 322 .sp
 323 .\}
 324 .RS 4
 325 .it 1 an-trap
 326 .nr an-no-space-flag 1
 327 .nr an-break-flag 1
 328 .br
 329 .ps +1
 330 \fBNote\fR
 331 .ps -1
 332 .br
 333 Not all of the above facility names are implemented on every system\&. Check your system\*(Aqs syslog documentation for information on which facility names are allowed, and which log files record the corresponding messages for each facility\&.
 334 .sp .5v
 335 .RE
 336 .RE
 337 .PP
 338 \-pid=\fIfilename\fR
 339 .RS 4
 340 Save
 341 \fBcourierlogger\fR\*(Aqs process ID in
 342 \fIfilename\fR\&. The
 343 \fI\-pid\fR
 344 option is required when
 345 \fI\-start\fR,
 346 \fI\-stop\fR,
 347 \fI\-restart\fR
 348 are given\&. If
 349 \fI\-pid\fR
 350 is given without any of these,
 351 \fI\-start\fR
 352 is assumed\&.
 353 .RE
 354 .PP
 355 \-start
 356 .RS 4
 357 Run as a daemon\&. The
 358 \fBpid\fR
 359 option is required\&.
 360 \fBcourierlogger\fR
 361 will quietly terminate if another
 362 \fBcourierlogger\fR
 363 process is already running\&. This is used to make sure that only one instance of
 364 program
 365 is running at the same time\&. Specify a different filename with
 366 \fBpid\fR
 367 to start a second copy of
 368 program\&.
 369 .RE
 370 .PP
 371 \-respawn
 372 .RS 4
 373 Restart
 374 program
 375 if it terminates\&. Normally
 376 \fBcourierlogger\fR
 377 itself will terminate when
 378 program
 379 finishes running\&. Use
 380 \fBrespawn\fR
 381 to restart it instead\&.
 382 .RE
 383 .PP
 384 \-restart
 385 .RS 4
 386 Send a
 387 SIGHUP
 388 signal to the courierlogger process (as determined by examining the contents of the file specified by
 389 \fBpid\fR), which will in turn send a
 390 SIGHUP
 391 to its child
 392 program\&. Does nothing if courierlogger is not running\&.
 393 .if n \{\
 394 .sp
 395 .\}
 396 .RS 4
 397 .it 1 an-trap
 398 .nr an-no-space-flag 1
 399 .nr an-break-flag 1
 400 .br
 401 .ps +1
 402 \fBNote\fR
 403 .ps -1
 404 .br
 405 program
 406 must be originally started with the
 407 \fBrespawn\fR
 408 option if sending it a
 409 SIGHUP
 410 causes it to terminate\&.
 411 .sp .5v
 412 .RE
 413 The same thing may be accomplished by sending
 414 SIGHUP
 415 to
 416 \fBcourierlogger\fR
 417 itself\&.
 418 .RE
 419 .PP
 420 \-stop
 421 .RS 4
 422 Send a
 423 SIGTERM
 424 signal to courierlogger, which in turn forwards it on to
 425 program\&. If
 426 program
 427 does not terminate in 8 seconds, kill it with
 428 SIGKILL\&.
 429 .RE
 430 .PP
 431 \-user=\fIuser\fR, \-group=\fIgroup\fR
 432 .RS 4
 433 If running as root, change credentials to the given user and/or group, which may be given as names or numeric ids\&.
 434 .sp
 435 When running a child program, it is started
 436 \fIbefore\fR
 437 privileges are dropped (unless the
 438 \fB\-droproot\fR
 439 option is also given)\&. This gives a means of starting a child as root so it can bind to a privileged port, but still have courierlogger run as a non\-root user\&. For the
 440 \fB\-stop\fR
 441 and
 442 \fB\-restart\fR
 443 options to work, you should configure the child program to drop its privileges to the same userid too\&.
 444 .RE
 445 .PP
 446 \-droproot
 447 .RS 4
 448 Drop root privileges before starting the child process\&. The
 449 \fB\-user\fR
 450 and
 451 \fB\-group\fR
 452 options specify the non\-privileges userid and groupid\&. Without the
 453 \fB\-droproot\fR
 454 option the child process remains a root process, and only the parent
 455 \fBcourierlogger\fR
 456 process drops root privileges\&.
 457 .RE
 458 .PP
 459 \fIprogram\fR [ argument ] \&.\&.\&.
 460 .RS 4
 461 If a program is given
 462 program
 463 will be started as a child process of
 464 \fBcourierlogger\fR, capturing its standard error\&. Otherwise,
 465 \fBcourierlogger\fR
 466 reads message from standard input, and automatically terminates when standard input is closed\&.
 467 .RE
 468 .SH "SEE ALSO"
 469 .PP
 470 \m[blue]\fB\fBcouriertcpd\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2, your syslog man page\&.
 471 .SH "NOTES"
 472 .IP " 1." 4
 473 \fBcouriertcpd\fR(1)
 474 .RS 4
 475 \%[set $man.base.url.for.relative.links]/couriertcpd.html
 476 .RE