liblog/courierlogger.html

   1 <?xml version="1.0"?>
   2 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>courierlogger</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"/><link rel="start" href="#courierlogger" title="courierlogger"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
   3
   4 Copyright 1998 - 2007 Double Precision, Inc.  See COPYING for distribution
   5 information.
   6
   7 --></head><body><div class="refentry" lang="en" xml:lang="en"><a id="courierlogger" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>courierlogger — Courier syslog wrapper</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">courierlogger</code>  [-name=<em class="replaceable"><code>title</code></em>] [-facility=<em class="replaceable"><code>subsystem</code></em>] [-pid=<em class="replaceable"><code>filename</code></em>] [-user=<em class="replaceable"><code>user</code></em>] [-group=<em class="replaceable"><code>group</code></em>] [-droproot] [[[-respawn]  [-start]
   8              <em class="replaceable"><code>program</code></em>  [argument...]] |  [-stop] |  [-restart]]</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id282594" shape="rect"> </a><h2>DESCRIPTION</h2><p>
   9 <span><strong class="command">courierlogger</strong></span>
  10 is a wrapper that captures
  11 another process's error messages, and forwards them
  12 to the system logging facility,
  13 “<span class="quote">syslog</span>”.</p><p>
  14 There are two ways to use courierlogger:
  15 </p><div class="orderedlist"><ol type="1"><li><p>
  16 Use the shell to pipe another command's standard error, and/or its standard
  17 output, to
  18 <span><strong class="command">courierlogger</strong></span>'s standard input.</p></li><li><p>
  19 Alternatively,
  20 <span><strong class="command">courierlogger</strong></span>
  21 itself can start another process, and arrange to have its standard error
  22 captured.</p></li></ol></div><p>
  23     </p><p>
  24 In either case, each read line of text is sent as a syslog message.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="id282654" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">-name=<em class="replaceable"><code>title</code></em></span></dt><dd><p>
  25 Use <em class="replaceable"><code>title</code></em> for sending messages to syslog.
  26 <em class="replaceable"><code>title</code></em> should be the application's name.</p></dd><dt><span class="term">-facility=<em class="replaceable"><code>subsystem</code></em></span></dt><dd><p>
  27 Use <em class="replaceable"><code>subsystem</code></em> for classifying messages.
  28 Your syslog facility uses <em class="replaceable"><code>subsystem</code></em> to determine
  29 which log messages are recorded in which log files.
  30 The currently defined subsystems are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">auth</code></p></li><li><p><code class="literal">authpriv</code></p></li><li><p><code class="literal">console</code></p></li><li><p><code class="literal">cron</code></p></li><li><p><code class="literal">daemon</code></p></li><li><p><code class="literal">ftp</code></p></li><li><p><code class="literal">kern</code></p></li><li><p><code class="literal">lpr</code></p></li><li><p><code class="literal">mail</code></p></li><li><p><code class="literal">news</code></p></li><li><p><code class="literal">security</code></p></li><li><p><code class="literal">user</code></p></li><li><p><code class="literal">uucp</code></p></li><li><p><code class="literal">local0</code></p></li><li><p><code class="literal">local1</code></p></li><li><p><code class="literal">local2</code></p></li><li><p><code class="literal">local3</code></p></li><li><p><code class="literal">local4</code></p></li><li><p><code class="literal">local5</code></p></li><li><p><code class="literal">local6</code></p></li><li><p><code class="literal">local7</code></p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  31 Not all of the above facility names are implemented on every system.
  32 Check your system's syslog documentation for information on which facility
  33 names are allowed, and which log files record the corresponding messages
  34 for each facility.</p></div></dd><dt><span class="term">-pid=<em class="replaceable"><code>filename</code></em></span></dt><dd><p>
  35 Save <span><strong class="command">courierlogger</strong></span>'s
  36 process ID in <em class="replaceable"><code>filename</code></em>.
  37 The <em class="parameter"><code>-pid</code></em> option is required when
  38 <em class="parameter"><code>-start</code></em>,
  39 <em class="parameter"><code>-stop</code></em>,
  40 <em class="parameter"><code>-restart</code></em> are given. If <em class="parameter"><code>-pid</code></em>
  41 is given without any of these, <em class="parameter"><code>-start</code></em> is assumed.</p></dd><dt><span class="term">-start</span></dt><dd><p>
  42 Run as a daemon. The <code class="option">pid</code> option is required.
  43 <span><strong class="command">courierlogger</strong></span> will quietly terminate if another
  44 <span><strong class="command">courierlogger</strong></span> process is already running.
  45 This is used to make sure that only one instance of
  46 <code class="filename">program</code> is running at the same time.
  47 Specify a different filename with <code class="option">pid</code> to start a second
  48 copy of <code class="filename">program</code>.</p></dd><dt><span class="term">-respawn</span></dt><dd><p>
  49 Restart <code class="filename">program</code> if it terminates.
  50 Normally
  51 <span><strong class="command">courierlogger</strong></span> itself will terminate when
  52 <code class="filename">program</code> finishes running.
  53 Use <code class="option">respawn</code> to restart it instead.</p></dd><dt><span class="term">-restart</span></dt><dd><p>
  54 Send a <code class="literal">SIGHUP</code> signal to the courierlogger process
  55 (as determined by examining the contents of the file specified by
  56 <code class="option">pid</code>), which will in turn send a <code class="literal">SIGHUP</code>
  57 to its child <code class="filename">program</code>.
  58 Does nothing if courierlogger is not running.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  59 <code class="filename">program</code> must be originally started with the
  60 <code class="option">respawn</code> option if sending it a <code class="literal">SIGHUP</code>
  61 causes it to terminate.</p></div><p>
  62 The same thing may be accomplished by sending <code class="literal">SIGHUP</code>
  63 to <span><strong class="command">courierlogger</strong></span> itself.</p></dd><dt><span class="term">-stop</span></dt><dd><p>
  64 Send a <code class="literal">SIGTERM</code> signal to courierlogger, which in turn
  65 forwards it on to <code class="filename">program</code>.
  66 If <code class="filename">program</code> does not terminate in 8 seconds, kill it
  67 with <code class="literal">SIGKILL</code>.</p></dd><dt><span class="term">-user=<em class="replaceable"><code>user</code></em>, -group=<em class="replaceable"><code>group</code></em></span></dt><dd><p>
  68 If running as root, change credentials to the given user and/or group, which
  69 may be given as names or numeric ids.</p><p>When running a child program, it is started
  70 <span class="emphasis"><em>before</em></span> privileges are dropped
  71 (unless the <code class="option">-droproot</code> option is also given).
  72 This gives a means of
  73 starting a child as root so it can bind to a privileged port, but still have
  74 courierlogger run as a non-root user. For the <code class="option">-stop</code> and
  75 <code class="option">-restart</code> options to work, you should configure the child
  76 program to drop its privileges to the same userid too.</p></dd><dt><span class="term">-droproot</span></dt><dd><p>
  77 Drop root privileges before starting the child process.
  78 The <code class="option">-user</code> and <code class="option">-group</code> options specify
  79 the non-privileges userid and groupid.
  80 Without the <code class="option">-droproot</code> option the child process remains
  81 a root process, and only the parent <span><strong class="command">courierlogger</strong></span>
  82 process drops root privileges.</p></dd><dt><span class="term"><em class="replaceable"><code>program</code></em> [ argument ] ... </span></dt><dd><p>
  83 If a program is given <code class="filename">program</code>
  84 will be started as a child process of
  85 <span><strong class="command">courierlogger</strong></span>, capturing its standard error.
  86 Otherwise, <span><strong class="command">courierlogger</strong></span>
  87 reads message from standard input, and automatically terminates when
  88 standard input is closed.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id325631" shape="rect"> </a><h2>SEE ALSO</h2><p>
  89 <a href="couriertcpd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">couriertcpd</span>(1)</span></a>, your syslog man page.</p></div></div></body></html>