File: courierlogger.html

package info (click to toggle)
courier-authlib 0.58-4%2Betch3
links: PTS
area: main
in suites: etch
size: 16,212 kB
ctags: 1,896
sloc: ansic: 21,550; sh: 14,071; makefile: 866; perl: 842; cpp: 284
file content (634 lines) | stat: -rw-r--r-- 8,583 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML
><HEAD
><link rel='stylesheet' type='text/css' href='manpage.css'>
  <!-- $Id: courierlogger.sgml,v 1.6 2005/07/02 18:32:44 mrsam Exp $ -->
  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
  <!-- distribution information. -->
<meta name="MSSmartTagsPreventParsing" content="TRUE">
<link rel="icon" href="icon.gif" type="image/gif" />
<TITLE
>courierlogger</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="COURIERLOGGER"
></A
>courierlogger</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN10"
></A
><H2
>Name</H2
>courierlogger&nbsp;--&nbsp;Courier syslog wrapper</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN13"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>courierlogger</B
> [-name=<VAR
CLASS="REPLACEABLE"
>title</VAR
>] [-facility=<VAR
CLASS="REPLACEABLE"
>subsystem</VAR
>] [-pid=<VAR
CLASS="REPLACEABLE"
>filename</VAR
>] [-user=<VAR
CLASS="REPLACEABLE"
>user</VAR
>] [-group=<VAR
CLASS="REPLACEABLE"
>group</VAR
>] [-droproot] [[-respawn]  [-start]
             <VAR
CLASS="REPLACEABLE"
>program</VAR
>  [argument...] | -stop | -restart]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN35"
></A
><H2
>DESCRIPTION</H2
><P
><B
CLASS="COMMAND"
>courierlogger</B
>
is a wrapper that captures
another process's error messages, and forwards them
to the system logging facility,
<SPAN
CLASS="QUOTE"
>"syslog"</SPAN
>.</P
><P
>There are two ways to use courierlogger:
<P
></P
><OL
TYPE="1"
><LI
><P
>Use the shell to pipe another command's standard error, and/or its standard
output, to
<B
CLASS="COMMAND"
>courierlogger</B
>'s standard input.</P
></LI
><LI
><P
>Alternatively,
<B
CLASS="COMMAND"
>courierlogger</B
>
itself can start another process, and arrange to have its standard error
captured.</P
></LI
></OL
>
    </P
><P
>In either case, each read line of text is sent as a syslog message.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN49"
></A
><H2
>OPTIONS</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>-name=<VAR
CLASS="REPLACEABLE"
>title</VAR
></DT
><DD
><P
>Use <VAR
CLASS="REPLACEABLE"
>title</VAR
> for sending messages to syslog.
<VAR
CLASS="REPLACEABLE"
>title</VAR
> should be the application's name.</P
></DD
><DT
>-facility=<VAR
CLASS="REPLACEABLE"
>subsystem</VAR
></DT
><DD
><P
>Use <VAR
CLASS="REPLACEABLE"
>subsystem</VAR
> for classifying messages.
Your syslog facility uses <VAR
CLASS="REPLACEABLE"
>subsystem</VAR
> to determine
which log messages are recorded in which log files.
The currently defined subsystems are:</P
><P
></P
><UL
><LI
><P
><TT
CLASS="LITERAL"
>auth</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>authpriv</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>console</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>cron</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>daemon</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>ftp</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>kern</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>lpr</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>mail</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>news</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>security</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>user</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>uucp</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local0</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local1</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local2</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local3</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local4</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local5</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local6</TT
></P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>local7</TT
></P
></LI
></UL
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>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.</P
></TD
></TR
></TABLE
></DIV
></DD
><DT
>-pid=<VAR
CLASS="REPLACEABLE"
>filename</VAR
></DT
><DD
><P
>Save <B
CLASS="COMMAND"
>courierlogger</B
>'s
process ID in <VAR
CLASS="REPLACEABLE"
>filename</VAR
>.
The <TT
CLASS="PARAMETER"
><I
>-pid</I
></TT
> option is required when
<TT
CLASS="PARAMETER"
><I
>-start</I
></TT
>,
<TT
CLASS="PARAMETER"
><I
>-stop</I
></TT
>,
<TT
CLASS="PARAMETER"
><I
>-restart</I
></TT
> are given. If <TT
CLASS="PARAMETER"
><I
>-pid</I
></TT
>
is given without any of these, <TT
CLASS="PARAMETER"
><I
>-start</I
></TT
> is assumed.</P
></DD
><DT
>-start</DT
><DD
><P
>Run as a daemon. The <VAR
CLASS="OPTION"
>pid</VAR
> option is required.
<B
CLASS="COMMAND"
>courierlogger</B
> will quietly terminate if another
<B
CLASS="COMMAND"
>courierlogger</B
> process is already running.
This is used to make sure that only one instance of
<TT
CLASS="FILENAME"
>program</TT
> is running at the same time.
Specify a different filename with <VAR
CLASS="OPTION"
>pid</VAR
> to start a second
copy of <TT
CLASS="FILENAME"
>program</TT
>.</P
></DD
><DT
>-respawn</DT
><DD
><P
>Restart <TT
CLASS="FILENAME"
>program</TT
> if it terminates.
Normally
<B
CLASS="COMMAND"
>courierlogger</B
> itself will terminate when
<TT
CLASS="FILENAME"
>program</TT
> finishes running.
Use <VAR
CLASS="OPTION"
>respawn</VAR
> to restart it instead.</P
></DD
><DT
>-restart</DT
><DD
><P
>Send a <TT
CLASS="LITERAL"
>SIGHUP</TT
> signal to the courierlogger process
(as determined by examining the contents of the file specified by
<VAR
CLASS="OPTION"
>pid</VAR
>), which will in turn send a <TT
CLASS="LITERAL"
>SIGHUP</TT
>
to its child <TT
CLASS="FILENAME"
>program</TT
>.
Does nothing if courierlogger is not running.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
>NOTE:</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><TT
CLASS="FILENAME"
>program</TT
> must be originally started with the
<VAR
CLASS="OPTION"
>respawn</VAR
> option if sending it a <TT
CLASS="LITERAL"
>SIGHUP</TT
>
causes it to terminate.</P
></TD
></TR
></TABLE
></DIV
><P
>The same thing may be accomplished by sending <TT
CLASS="LITERAL"
>SIGHUP</TT
>
to <B
CLASS="COMMAND"
>courierlogger</B
> itself.</P
></DD
><DT
>-stop</DT
><DD
><P
>Send a <TT
CLASS="LITERAL"
>SIGTERM</TT
> signal to courierlogger, which in turn
forwards it on to <TT
CLASS="FILENAME"
>program</TT
>.
If <TT
CLASS="FILENAME"
>program</TT
> does not terminate in 8 seconds, kill it
with <TT
CLASS="LITERAL"
>SIGKILL</TT
>.</P
></DD
><DT
>-user=<VAR
CLASS="REPLACEABLE"
>user</VAR
>, -group=<VAR
CLASS="REPLACEABLE"
>group</VAR
></DT
><DD
><P
>If running as root, change credentials to the given user and/or group, which
may be given as names or numeric ids.</P
><P
>When running a child program, it is started
<I
CLASS="EMPHASIS"
>before</I
> privileges are dropped
(unless the <VAR
CLASS="OPTION"
>-droproot</VAR
> 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 <VAR
CLASS="OPTION"
>-stop</VAR
> and
<VAR
CLASS="OPTION"
>-restart</VAR
> options to work, you should configure the child
program to drop its privileges to the same userid too.</P
></DD
><DT
>-droproot</DT
><DD
><P
>Drop root privileges before starting the child process.
The <VAR
CLASS="OPTION"
>-user</VAR
> and <VAR
CLASS="OPTION"
>-group</VAR
> options specify
the non-privileges userid and groupid.
Without the <VAR
CLASS="OPTION"
>-droproot</VAR
> option the child process remains
a root process, and only the parent <B
CLASS="COMMAND"
>courierlogger</B
>
process drops root privileges.</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>program</VAR
> [ argument ] ...</DT
><DD
><P
>If a program is given <TT
CLASS="FILENAME"
>program</TT
>
will be started as a child process of
<B
CLASS="COMMAND"
>courierlogger</B
>, capturing its standard error.
Otherwise, <B
CLASS="COMMAND"
>courierlogger</B
>
reads message from standard input, and automatically terminates when
standard input is closed.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN214"
></A
><H2
>SEE ALSO</H2
><P
><A
HREF="couriertcpd.html"
TARGET="_top"
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>couriertcpd</SPAN
>(1)</SPAN
></A
>, your syslog man page.</P
></DIV
></BODY
></HTML
>