1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- Copyright 2004-2007 Double Precision, Inc. See COPYING for -->
<!-- distribution information. -->
<refentry id="courierlogger">
<refmeta>
<refentrytitle>courierlogger</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Double Precision, Inc.</refmiscinfo>
</refmeta>
<refnamediv>
<refname>courierlogger</refname>
<refpurpose>Courier syslog wrapper</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>courierlogger</command>
<arg>-name=<replaceable>title</replaceable></arg>
<arg>-facility=<replaceable>subsystem</replaceable></arg>
<arg>-pid=<replaceable>filename</replaceable></arg>
<arg>-user=<replaceable>user</replaceable></arg>
<arg>-group=<replaceable>group</replaceable></arg>
<arg>-droproot</arg>
<group>
<arg><arg choice='opt'>-respawn</arg> <arg choice='opt'>-start</arg>
<replaceable>program</replaceable> <arg rep='repeat'>argument</arg></arg>
<arg>-stop</arg>
<arg>-restart</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="courierlogger_description">
<title>DESCRIPTION</title>
<para>
<command>courierlogger</command>
is a wrapper that captures
another process's error messages, and forwards them
to the system logging facility,
<quote>syslog</quote>.</para>
<para>
There are two ways to use courierlogger:
<orderedlist>
<listitem>
<para>
Use the shell to pipe another command's standard error, and/or its standard
output, to
<command>courierlogger</command>'s standard input.</para>
</listitem>
<listitem>
<para>
Alternatively,
<command>courierlogger</command>
itself can start another process, and arrange to have its standard error
captured.</para>
</listitem>
</orderedlist>
</para>
<para>
In either case, each read line of text is sent as a syslog message.</para>
</refsect1>
<refsect1 id="courierlogger_options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>-name=<replaceable>title</replaceable></term>
<listitem>
<para>
Use <replaceable>title</replaceable> for sending messages to syslog.
<replaceable>title</replaceable> should be the application's name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-facility=<replaceable>subsystem</replaceable></term>
<listitem>
<para>
Use <replaceable>subsystem</replaceable> for classifying messages.
Your syslog facility uses <replaceable>subsystem</replaceable> to determine
which log messages are recorded in which log files.
The currently defined subsystems are:</para>
<itemizedlist>
<listitem><para><literal>auth</literal></para></listitem>
<listitem><para><literal>authpriv</literal></para></listitem>
<listitem><para><literal>console</literal></para></listitem>
<listitem><para><literal>cron</literal></para></listitem>
<listitem><para><literal>daemon</literal></para></listitem>
<listitem><para><literal>ftp</literal></para></listitem>
<listitem><para><literal>kern</literal></para></listitem>
<listitem><para><literal>lpr</literal></para></listitem>
<listitem><para><literal>mail</literal></para></listitem>
<listitem><para><literal>news</literal></para></listitem>
<listitem><para><literal>security</literal></para></listitem>
<listitem><para><literal>user</literal></para></listitem>
<listitem><para><literal>uucp</literal></para></listitem>
<listitem><para><literal>local0</literal></para></listitem>
<listitem><para><literal>local1</literal></para></listitem>
<listitem><para><literal>local2</literal></para></listitem>
<listitem><para><literal>local3</literal></para></listitem>
<listitem><para><literal>local4</literal></para></listitem>
<listitem><para><literal>local5</literal></para></listitem>
<listitem><para><literal>local6</literal></para></listitem>
<listitem><para><literal>local7</literal></para></listitem>
</itemizedlist>
<note>
<para>
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.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>-pid=<replaceable>filename</replaceable></term>
<listitem>
<para>
Save <command>courierlogger</command>'s
process ID in <replaceable>filename</replaceable>.
The <parameter>-pid</parameter> option is required when
<parameter>-start</parameter>,
<parameter>-stop</parameter>,
<parameter>-restart</parameter> are given. If <parameter>-pid</parameter>
is given without any of these, <parameter>-start</parameter> is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-start</term>
<listitem>
<para>
Run as a daemon. The <option>pid</option> option is required.
<command>courierlogger</command> will quietly terminate if another
<command>courierlogger</command> process is already running.
This is used to make sure that only one instance of
<filename>program</filename> is running at the same time.
Specify a different filename with <option>pid</option> to start a second
copy of <filename>program</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-respawn</term>
<listitem>
<para>
Restart <filename>program</filename> if it terminates.
Normally
<command>courierlogger</command> itself will terminate when
<filename>program</filename> finishes running.
Use <option>respawn</option> to restart it instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-restart</term>
<listitem>
<para>
Send a <literal>SIGHUP</literal> signal to the courierlogger process
(as determined by examining the contents of the file specified by
<option>pid</option>), which will in turn send a <literal>SIGHUP</literal>
to its child <filename>program</filename>.
Does nothing if courierlogger is not running.</para>
<note>
<para>
<filename>program</filename> must be originally started with the
<option>respawn</option> option if sending it a <literal>SIGHUP</literal>
causes it to terminate.</para>
</note>
<para>
The same thing may be accomplished by sending <literal>SIGHUP</literal>
to <command>courierlogger</command> itself.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-stop</term>
<listitem>
<para>
Send a <literal>SIGTERM</literal> signal to courierlogger, which in turn
forwards it on to <filename>program</filename>.
If <filename>program</filename> does not terminate in 8 seconds, kill it
with <literal>SIGKILL</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-user=<replaceable>user</replaceable>, -group=<replaceable>group</replaceable></term>
<listitem>
<para>
If running as root, change credentials to the given user and/or group, which
may be given as names or numeric ids.</para>
<para>When running a child program, it is started
<emphasis>before</emphasis> privileges are dropped
(unless the <option>-droproot</option> 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 <option>-stop</option> and
<option>-restart</option> options to work, you should configure the child
program to drop its privileges to the same userid too.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-droproot</term>
<listitem>
<para>
Drop root privileges before starting the child process.
The <option>-user</option> and <option>-group</option> options specify
the non-privileges userid and groupid.
Without the <option>-droproot</option> option the child process remains
a root process, and only the parent <command>courierlogger</command>
process drops root privileges.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>program</replaceable> [ argument ] ... </term>
<listitem>
<para>
If a program is given <filename>program</filename>
will be started as a child process of
<command>courierlogger</command>, capturing its standard error.
Otherwise, <command>courierlogger</command>
reads message from standard input, and automatically terminates when
standard input is closed.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="courierlogger_see_also">
<title>SEE ALSO</title>
<para>
<ulink url="couriertcpd.html"><citerefentry><refentrytitle>couriertcpd</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>, your syslog man page.</para>
</refsect1>
</refentry>
|
