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