liblog/courierlogger.1

   1 .\"  <!-- $Id: courierlogger.sgml,v 1.9 2007/04/22 15:05:16 mrsam Exp $ -->
   2 .\"  <!-- Copyright 2004-2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: courierlogger
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
   7 .\"      Date: 04/22/2007
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "COURIERLOGGER" "1" "04/22/2007" "Double Precision, Inc." "Double Precision, Inc."
  12 .\" disable hyphenation
  13 .nh
  14 .\" disable justification (adjust text to left margin only)
  15 .ad l
  16 .SH "NAME"
  17 courierlogger \- Courier syslog wrapper
  18 .SH "SYNOPSIS"
  19 .HP 14
  20 \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]]
  21 .SH "DESCRIPTION"
  22 .PP
  23
  24 \fBcourierlogger\fR
  25 is a wrapper that captures another process's error messages, and forwards them to the system logging facility,
  26 \(lqsyslog\(rq.
  27 .PP
  28 There are two ways to use courierlogger:
  29 .RS 4
  30 \h'-04' 1.\h'+02'Use the shell to pipe another command's standard error, and/or its standard output, to
  31 \fBcourierlogger\fR's standard input.
  32 .RE
  33 .RS 4
  34 \h'-04' 2.\h'+02'Alternatively,
  35 \fBcourierlogger\fR
  36 itself can start another process, and arrange to have its standard error captured.
  37 .RE
  38 .sp
  39 .RE
  40 .PP
  41 In either case, each read line of text is sent as a syslog message.
  42 .SH "OPTIONS"
  43 .PP
  44 \-name=\fItitle\fR
  45 .RS 4
  46 Use
  47 \fItitle\fR
  48 for sending messages to syslog.
  49 \fItitle\fR
  50 should be the application's name.
  51 .RE
  52 .PP
  53 \-facility=\fIsubsystem\fR
  54 .RS 4
  55 Use
  56 \fIsubsystem\fR
  57 for classifying messages. Your syslog facility uses
  58 \fIsubsystem\fR
  59 to determine which log messages are recorded in which log files. The currently defined subsystems are:
  60 .RS 4
  61 \h'-04'\(bu\h'+03'auth
  62 .RE
  63 .RS 4
  64 \h'-04'\(bu\h'+03'authpriv
  65 .RE
  66 .RS 4
  67 \h'-04'\(bu\h'+03'console
  68 .RE
  69 .RS 4
  70 \h'-04'\(bu\h'+03'cron
  71 .RE
  72 .RS 4
  73 \h'-04'\(bu\h'+03'daemon
  74 .RE
  75 .RS 4
  76 \h'-04'\(bu\h'+03'ftp
  77 .RE
  78 .RS 4
  79 \h'-04'\(bu\h'+03'kern
  80 .RE
  81 .RS 4
  82 \h'-04'\(bu\h'+03'lpr
  83 .RE
  84 .RS 4
  85 \h'-04'\(bu\h'+03'mail
  86 .RE
  87 .RS 4
  88 \h'-04'\(bu\h'+03'news
  89 .RE
  90 .RS 4
  91 \h'-04'\(bu\h'+03'security
  92 .RE
  93 .RS 4
  94 \h'-04'\(bu\h'+03'user
  95 .RE
  96 .RS 4
  97 \h'-04'\(bu\h'+03'uucp
  98 .RE
  99 .RS 4
 100 \h'-04'\(bu\h'+03'local0
 101 .RE
 102 .RS 4
 103 \h'-04'\(bu\h'+03'local1
 104 .RE
 105 .RS 4
 106 \h'-04'\(bu\h'+03'local2
 107 .RE
 108 .RS 4
 109 \h'-04'\(bu\h'+03'local3
 110 .RE
 111 .RS 4
 112 \h'-04'\(bu\h'+03'local4
 113 .RE
 114 .RS 4
 115 \h'-04'\(bu\h'+03'local5
 116 .RE
 117 .RS 4
 118 \h'-04'\(bu\h'+03'local6
 119 .RE
 120 .RS 4
 121 \h'-04'\(bu\h'+03'local7
 122 .RE
 123 .IP "" 4
 124 .sp
 125 .it 1 an-trap
 126 .nr an-no-space-flag 1
 127 .nr an-break-flag 1
 128 .br
 129 \fBNote\fR
 130 Not all of the above facility names are implemented on every system. Check your system's syslog documentation for information on which facility names are allowed, and which log files record the corresponding messages for each facility.
 131 .RE
 132 .PP
 133 \-pid=\fIfilename\fR
 134 .RS 4
 135 Save
 136 \fBcourierlogger\fR's process ID in
 137 \fIfilename\fR. The
 138 \fI\-pid\fR
 139 option is required when
 140 \fI\-start\fR,
 141 \fI\-stop\fR,
 142 \fI\-restart\fR
 143 are given. If
 144 \fI\-pid\fR
 145 is given without any of these,
 146 \fI\-start\fR
 147 is assumed.
 148 .RE
 149 .PP
 150 \-start
 151 .RS 4
 152 Run as a daemon. The
 153 \fBpid\fR
 154 option is required.
 155 \fBcourierlogger\fR
 156 will quietly terminate if another
 157 \fBcourierlogger\fR
 158 process is already running. This is used to make sure that only one instance of
 159 \fIprogram\fR
 160 is running at the same time. Specify a different filename with
 161 \fBpid\fR
 162 to start a second copy of
 163 \fIprogram\fR.
 164 .RE
 165 .PP
 166 \-respawn
 167 .RS 4
 168 Restart
 169 \fIprogram\fR
 170 if it terminates. Normally
 171 \fBcourierlogger\fR
 172 itself will terminate when
 173 \fIprogram\fR
 174 finishes running. Use
 175 \fBrespawn\fR
 176 to restart it instead.
 177 .RE
 178 .PP
 179 \-restart
 180 .RS 4
 181 Send a
 182 SIGHUP
 183 signal to the courierlogger process (as determined by examining the contents of the file specified by
 184 \fBpid\fR), which will in turn send a
 185 SIGHUP
 186 to its child
 187 \fIprogram\fR. Does nothing if courierlogger is not running.
 188 .sp
 189 .it 1 an-trap
 190 .nr an-no-space-flag 1
 191 .nr an-break-flag 1
 192 .br
 193 \fBNote\fR
 194
 195 \fIprogram\fR
 196 must be originally started with the
 197 \fBrespawn\fR
 198 option if sending it a
 199 SIGHUP
 200 causes it to terminate.
 201
 202 The same thing may be accomplished by sending
 203 SIGHUP
 204 to
 205 \fBcourierlogger\fR
 206 itself.
 207 .RE
 208 .PP
 209 \-stop
 210 .RS 4
 211 Send a
 212 SIGTERM
 213 signal to courierlogger, which in turn forwards it on to
 214 \fIprogram\fR. If
 215 \fIprogram\fR
 216 does not terminate in 8 seconds, kill it with
 217 SIGKILL.
 218 .RE
 219 .PP
 220 \-user=\fIuser\fR, \-group=\fIgroup\fR
 221 .RS 4
 222 If running as root, change credentials to the given user and/or group, which may be given as names or numeric ids.
 223 .sp
 224 When running a child program, it is started
 225 \fIbefore\fR
 226 privileges are dropped (unless the
 227 \fB\-droproot\fR
 228 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
 229 \fB\-stop\fR
 230 and
 231 \fB\-restart\fR
 232 options to work, you should configure the child program to drop its privileges to the same userid too.
 233 .RE
 234 .PP
 235 \-droproot
 236 .RS 4
 237 Drop root privileges before starting the child process. The
 238 \fB\-user\fR
 239 and
 240 \fB\-group\fR
 241 options specify the non\-privileges userid and groupid. Without the
 242 \fB\-droproot\fR
 243 option the child process remains a root process, and only the parent
 244 \fBcourierlogger\fR
 245 process drops root privileges.
 246 .RE
 247 .PP
 248 \fIprogram\fR [ argument ] ...
 249 .RS 4
 250 If a program is given
 251 \fIprogram\fR
 252 will be started as a child process of
 253 \fBcourierlogger\fR, capturing its standard error. Otherwise,
 254 \fBcourierlogger\fR
 255 reads message from standard input, and automatically terminates when standard input is closed.
 256 .RE
 257 .SH "SEE ALSO"
 258 .PP
 259
 260 \fI\fBcouriertcpd\fR(1)\fR\&[1], your syslog man page.
 261 .SH "REFERENCES"
 262 .IP " 1." 4
 263 \fBcouriertcpd\fR(1)
 264 .RS 4
 265 \%couriertcpd.html
 266 .RE