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
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6: the s6-socklog program</title>
<meta name="Description" content="s6: the s6-socklog program" />
<meta name="Keywords" content="s6 syslog syslogd log logging daemon root utilities socket unix inet udp datagram protocol" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">s6</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>s6-socklog</tt> program </h1>
<p>
<tt>s6-socklog</tt> is a minimal syslog daemon. It reads datagrams
from the <tt>/dev/log</tt> Unix domain socket, or from a Unix domain
or Internet domain socket of the user's choice, converts the encoded
syslog facility and priority names to their human-readable equivalents,
and prints the logs to its stdout.
</p>
<p>
<tt>s6-socklog</tt> is a reimplementation of the
<a href="http://smarden.org/socklog/socklog.8.html">socklog</a> program
with a few more features.
</p>
<h2> Interface </h2>
<pre>
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> ]
</pre>
<ul>
<li> <tt>s6-socklog</tt> binds to <tt>/dev/log</tt>. </li>
<li> It drops its root privileges. </li>
<li> For every datagram it reads, it turns its content into a log line:
<ul>
<li> Messages are truncated to 1024 characters </li>
<li> Trailing nulls or newlines are removed </li>
<li> Embedded nulls or newlines are converted to <tt>~</tt> characters (tildas) </li>
<li> A <tt><syslogcode></tt> at the beginning of the line is converted to <tt>facility.priority: </tt> </li>
</ul> </li>
<li> It prints the log line to its stdout, terminated by a newline. </li>
<li> It exits 0 on a SIGTERM. </li>
</ul>
<h2> Exit codes </h2>
<ul>
<li> 0: SIGTERM received, clean exit </li>
<li> 99: SIGTERM received but the buffer could not be flushed in time, some logs may be lost </li>
<li> 100: wrong usage </li>
<li> 111: system call failed </li>
</ul>
<h2> Signals </h2>
<p>
<tt>s6-socklog</tt> reacts to the following signals:
</p>
<ul>
<li> SIGTERM: exit as soon as possible </li>
</ul>
<h2> Options </h2>
<ul>
<li> <tt>-r</tt> : raw logging. <tt><syslogcode></tt> codes
will not be converted to facility/priority names. </li>
<li> <tt>-d</tt> <em>notif</em> : when ready
(actually bound to its socket),
write a newline to file descriptor <em>notif</em> then close it.
This allows <tt>s6-socklog</tt> to use the <a href="notifywhenup.html">s6
mechanism to notify readiness</a>. <em>notif</em> cannot be lesser than 3.
If this option is not given, no readiness notification is sent. </li>
<li> <tt>-u <em>uid</em></tt> : drop user id to <em>uid</em> </li>
<li> <tt>-g <em>gid</em></tt> : drop group ID to <em>gid</em> </li>
<li> <tt>-G <em>gidlist</em></tt> : set supplementary group list
to <em>gidlist</em>, which must be given as a comma-separated list of numeric GIDs,
without spaces. </li>
<li> <tt>-U</tt> : set user ID, group ID and supplementary group list
to the values of the UID, GID and GIDLIST environment variables. If a <tt>-u</tt>,
<tt>-g</tt> or <tt>-G</tt> option is given after <tt>-U</tt>, the command line
value overrides the environment variable. </li>
<li> <tt>-l</tt> <em>linelen</em> : Set the maximum datagram size to
<em>linelen</em>. Default is 1024. It cannot be set to less than 80 or more than
1048576. If a datagram is bigger than <em>linelen</em>, it will be truncated to
<em>linelen</em> characters, and the logged line will end with a <tt>...</tt> ellipsis
to show the truncation. </li>
<li> <tt>-t</tt> <em>lameducktimeout</em> : on receipt of a SIGTERM, give
<tt>s6-socklog</tt> a grace period of <em>lameducktimeout</em> milliseconds to
flush any log lines that are still in its buffer. Default is 0, which means
infinite: the program will only exit when its buffer is empty, and may wait
forever. If <em>lameducktimeout</em> is nonzero and the timeout expires, the
program will exit 99. </li>
<li> <tt>-x</tt> <em>unixsocket</em> : bind to a Unix domain socket
at <em>unixsocket</em>. Default is <tt>/dev/log</tt>. </li>
<li> <tt>-i</tt> <em>ipport</em> : bind to a UDP socket. <em>ipport</em>
is a combination of <em>ip</em>, which must be an IPv4 or IPv6 address, and
<em>port</em>, which must be an integer. <em>port</em> may be omitted, in which
case it defaults to 514. If <em>port</em> is given, <em>ip</em> and <em>port</em>
must be separated by a <tt>_</tt> character (an underscore). If <em>ip</em> is
IPv4, a <tt>:</tt> (colon) can be used instead of an underscore. When this
option is used, <tt>s6-socklog</tt> will prepend every log line with
<tt><em>clientip</em>_<em>clientport</em>: </tt>, <em>clientip</em> and
<em>clientport</em> being the IP address and port of the client that sent
the log datagram.</li>
</ul>
<h2> Typical use </h2>
<p>
<tt>s6-socklog</tt> can be paired with <a href="s6-log.html">s6-log</a> to
implement <em>syslogd</em> functionality. <tt>s6-socklog</tt> acts as the
<em>frontend</em>: it reads the log lines and processes them, then pipes them
to an <a href="s6-log.html">s6-log</a> instance that acts as the <em>backend</em>,
i.e. sorts the log lines depending on regular expressions that typically involve
the facility and priority names, then stores them into the filesystem.
</p>
<p>
The pipe between <tt>s6-socklog</tt> and <a href="s6-log.html">s6-log</a> is
typically a <em>logging pipe</em> automatically provided by
<a href="s6-svscan.html">s6-svscan</a> when the <tt>s6-log</tt> instance is declared as
a logger service for the <tt>s6-socklog</tt> instance.
</p>
<p>
The <tt>examples/</tt> subdirectory of the s6 package contains a turnkey
<tt>syslogd</tt> service that implements this pattern.
</p>
<h2> Notes </h2>
<ul>
<li> <tt>s6-socklog</tt> cannot be used under <a href="s6-ipcserver.html">s6-ipcserver</a>
or another super-server. It does not implement the <tt>socklog ucspi</tt> functionality,
which is provided by the <a href="ucspilogd.html">ucspilogd</a> program instead. </li>
</ul>
</body>
</html>
|
