s6-socklog.html (6531B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-socklog program</title> 7 <meta name="Description" content="s6: the s6-socklog program" /> 8 <meta name="Keywords" content="s6 syslog syslogd log logging daemon root utilities socket unix inet udp datagram protocol" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The <tt>s6-socklog</tt> program </h1> 20 21 <p> 22 <tt>s6-socklog</tt> is a minimal syslog daemon. It reads datagrams 23 from the <tt>/dev/log</tt> Unix domain socket, or from a Unix domain 24 or Internet domain socket of the user's choice, converts the encoded 25 syslog facility and priority names to their human-readable equivalents, 26 and prints the logs to its stdout. 27 </p> 28 29 <p> 30 <tt>s6-socklog</tt> is a reimplementation of the 31 <a href="http://smarden.org/socklog/socklog.8.html">socklog</a> program 32 with a few more features. 33 </p> 34 35 <h2> Interface </h2> 36 37 <pre> 38 s6-socklog [ -d <em>notif</em> ] [ -r ] [ -U | -u <em>uid</em> -g <em>gid</em> -G <em>gidlist</em> ] [ -l <em>linelen</em> ] [ -t <em>lameducktimeout</em> ] [ -x <em>unixsocket</em> | -i <em>ipport</em> ] 39 </pre> 40 41 <ul> 42 <li> <tt>s6-socklog</tt> binds to <tt>/dev/log</tt>. </li> 43 <li> It drops its root privileges. </li> 44 <li> For every datagram it reads, it turns its content into a log line: 45 <ul> 46 <li> Messages are truncated to 1024 characters </li> 47 <li> Trailing nulls or newlines are removed </li> 48 <li> Embedded nulls or newlines are converted to <tt>~</tt> characters (tildes) </li> 49 <li> A <tt><syslogcode></tt> at the beginning of the line is converted to <tt>facility.priority: </tt> </li> 50 </ul> </li> 51 <li> It prints the log line to its stdout, terminated by a newline. </li> 52 <li> It exits 0 on a SIGTERM. </li> 53 </ul> 54 55 <h2> Exit codes </h2> 56 57 <ul> 58 <li> 0: SIGTERM received, clean exit </li> 59 <li> 99: SIGTERM received but the buffer could not be flushed in time, some logs may be lost </li> 60 <li> 100: wrong usage </li> 61 <li> 111: system call failed </li> 62 </ul> 63 64 <h2> Signals </h2> 65 66 <p> 67 <tt>s6-socklog</tt> reacts to the following signals: 68 </p> 69 70 <ul> 71 <li> SIGTERM: exit as soon as possible </li> 72 </ul> 73 74 <h2> Options </h2> 75 76 <ul> 77 <li> <tt>-r</tt> : raw logging. <tt><syslogcode></tt> codes 78 will not be converted to facility/priority names. </li> 79 <li> <tt>-d</tt> <em>notif</em> : when ready 80 (actually bound to its socket), 81 write a newline to file descriptor <em>notif</em> then close it. 82 This allows <tt>s6-socklog</tt> to use the <a href="notifywhenup.html">s6 83 mechanism to notify readiness</a>. <em>notif</em> cannot be less than 3. 84 If this option is not given, no readiness notification is sent. </li> 85 <li> <tt>-u <em>uid</em></tt> : drop user id to <em>uid</em> </li> 86 <li> <tt>-g <em>gid</em></tt> : drop group id to <em>gid</em> </li> 87 <li> <tt>-G <em>gidlist</em></tt> : set supplementary group list 88 to <em>gidlist</em>, which must be given as a comma-separated list of numeric gids, 89 without spaces. </li> 90 <li> <tt>-U</tt> : set user id, group id and supplementary group list 91 to the values of the UID, GID and GIDLIST environment variables. If a <tt>-u</tt>, 92 <tt>-g</tt> or <tt>-G</tt> option is given after <tt>-U</tt>, the command line 93 value overrides the environment variable. </li> 94 <li> <tt>-l</tt> <em>linelen</em> : Set the maximum datagram size to 95 <em>linelen</em>. Default is 1024. It cannot be set to less than 76 or more than 96 1048576. If a datagram is bigger than <em>linelen</em>, it will be truncated to 97 <em>linelen</em> characters, and the logged line will end with a <tt>...</tt> ellipsis 98 to show the truncation. </li> 99 <li> <tt>-t</tt> <em>lameducktimeout</em> : on receipt of a SIGTERM, give 100 <tt>s6-socklog</tt> a grace period of <em>lameducktimeout</em> milliseconds to 101 flush any log lines that are still in its buffer. Default is 0, which means 102 infinite: the program will only exit when its buffer is empty, and may wait 103 forever. If <em>lameducktimeout</em> is nonzero and the timeout expires, the 104 program will exit 99. </li> 105 <li> <tt>-x</tt> <em>unixsocket</em> : bind to a Unix domain socket 106 at <em>unixsocket</em>. Default is <tt>/dev/log</tt>. </li> 107 <li> <tt>-i</tt> <em>ipport</em> : bind to a UDP socket. <em>ipport</em> 108 is a combination of <em>ip</em>, which must be an IPv4 or IPv6 address, and 109 <em>port</em>, which must be an integer. <em>port</em> may be omitted, in which 110 case it defaults to 514. If <em>port</em> is given, <em>ip</em> and <em>port</em> 111 must be separated by a <tt>_</tt> character (an underscore). If <em>ip</em> is 112 IPv4, a <tt>:</tt> (colon) can be used instead of an underscore. When this 113 option is used, <tt>s6-socklog</tt> will prepend every log line with 114 <tt><em>clientip</em>_<em>clientport</em>: </tt>, <em>clientip</em> and 115 <em>clientport</em> being the IP address and port of the client that sent 116 the log datagram.</li> 117 </ul> 118 119 <h2> Typical use </h2> 120 121 <p> 122 <tt>s6-socklog</tt> can be paired with <a href="s6-log.html">s6-log</a> to 123 implement <em>syslogd</em> functionality. <tt>s6-socklog</tt> acts as the 124 <em>frontend</em>: it reads the log lines and processes them, then pipes them 125 to an <a href="s6-log.html">s6-log</a> instance that acts as the <em>backend</em>, 126 i.e. sorts the log lines depending on regular expressions that typically involve 127 the facility and priority names, then stores them into the filesystem. 128 </p> 129 130 <p> 131 The pipe between <tt>s6-socklog</tt> and <a href="s6-log.html">s6-log</a> is 132 typically a <em>logging pipe</em> automatically provided by 133 <a href="s6-svscan.html">s6-svscan</a> when the <tt>s6-log</tt> instance is declared as 134 a logger service for the <tt>s6-socklog</tt> instance. 135 </p> 136 137 <p> 138 The <tt>examples/</tt> subdirectory of the s6 package contains a turnkey 139 <tt>syslogd</tt> service that implements this pattern. 140 </p> 141 142 <h2> Notes </h2> 143 144 <ul> 145 <li> <tt>s6-socklog</tt> cannot be used under <a href="s6-ipcserver.html">s6-ipcserver</a> 146 or another super-server. It does not implement the <tt>socklog ucspi</tt> functionality, 147 which is provided by the <a href="ucspilogd.html">ucspilogd</a> program instead. </li> 148 </ul> 149 150 </body> 151 </html>