summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2015-02-07 14:51:06 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2015-02-07 14:51:06 +0000
commit502bfd940bfc39fe4eb256d8bd06cc5a15c098d3 (patch)
tree91df15f90b79f0834510e6db45cbad1630695f11 /doc
parent60cb96c3ce59e7a39000ab173a04792daea2b9c4 (diff)
downloads6-502bfd940bfc39fe4eb256d8bd06cc5a15c098d3.tar.xz
- s6-log overhaul (more stack, less heap), with new directives
- related doc update - version: 2.1.1.0 rc
Diffstat (limited to 'doc')
-rw-r--r--doc/index.html6
-rw-r--r--doc/s6-log.html70
-rw-r--r--doc/upgrade.html9
3 files changed, 65 insertions, 20 deletions
diff --git a/doc/index.html b/doc/index.html
index bf3252a..ab9a620 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -82,11 +82,11 @@ with s6</a> </li>
<li> GNU make, version 4.0 or later. Please be aware that s6 will not build
with an earlier version. </li>
<li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version
-2.2.1.0 or later. It's a build-time requirement. It's also a run-time
+2.3.0.0 or later. It's a build-time requirement. It's also a run-time
requirement if you link against the shared version of the skalibs
library. </li>
<li> <a href="http://skarnet.org/software/execline/">execline</a> version
-2.0.2.0 or later. It's a build-time and run-time requirement. </li>
+2.0.2.1 or later. It's a build-time and run-time requirement. </li>
</ul>
<h3> Licensing </h3>
@@ -99,7 +99,7 @@ library. </li>
<h3> Download </h3>
<ul>
- <li> The current released version of s6 is <a href="s6-2.1.0.1.tar.gz">2.1.0.1</a>. </li>
+ <li> The current released version of s6 is <a href="s6-2.1.1.0.tar.gz">2.1.1.0</a>. </li>
<li> Alternatively, you can checkout a copy of the s6 git repository:
<pre> git clone git://git.skarnet.org/s6 </pre> </li>
</ul>
diff --git a/doc/s6-log.html b/doc/s6-log.html
index 0a525d6..ae54010 100644
--- a/doc/s6-log.html
+++ b/doc/s6-log.html
@@ -53,9 +53,9 @@ exit when reading EOF on stdin. </li>
<li> <tt>-t</tt>&nbsp;: timestamp. Prepends every log line that is written to
a logging directory with a
<a href="http://skarnet.org/software/skalibs/libstddjb/tai.html">TAI64N</a>
-timestamp. </li>
+timestamp. <strong>This option is now deprecated.</strong> </li>
<li> <tt>-e</tt>&nbsp;: timestamp alerts. Prepends every "alert" line with a
-TAI64N timestamp. </li>
+TAI64N timestamp. <strong>This option is now deprecated. </strong> </li>
<li> <tt>-q | -v</tt>&nbsp;: quiet | verbose. Decreases | increases s6-log's
verbosity, i.e. which messages are sent to stderr. The default verbosity is 1.
Currently supported verbosity levels:
@@ -220,8 +220,29 @@ an unpadded, unlimited status file. By default, <em>statussize</em> is 1001. </l
<tt>execlineb</tt> must be found in s6-log's PATH.
If <em>processor</em> is empty, no processor will be set for the next logdirs.
By default, no processor is set. </li>
+ <li> <strong>t</strong>: the logged line will be prepended with a
+<a href="http://skarnet.org/software/skalibs/libstddjb/tai.html">TAI64N
+timestamp</a> (and a space) before being processed by the next action
+directive. Giving the <tt>t</tt> directive several times before an action
+directive has no effect. </li>
+ <li> <strong>T</strong>: the selected line will be prepended with a
+<a href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601
+timestamp</a> for combined date and time representing <em>local time</em>
+according to the system's timezone, with a space (not a 'T')
+between the date and the time and two spaces after the time, before being
+processed by the next action directive. Giving the <tt>T</tt> directive
+several times before an action directive has no effect. </li>
</ul>
+<p>
+ Note that unlike the other control directives, the <tt>t</tt> and
+<tt>T</tt> directives are <em>not sticky</em>: their effect will
+disappear after the next action directive, and they need to be
+reapplied if necessary. If both a <tt>t</tt> and a <tt>T</tt>
+directives are given before an action directive, the TAI64N timestamp
+will always appear before the ISO 8601 timestamp.
+</p>
+
<h3> Action directives </h3>
<p>
@@ -230,9 +251,14 @@ selected lines.
</p>
<ul>
- <li> <strong>e</strong>: alert. s6-log will print "s6-log: alert: ",
+ <li> <strong>2</strong> or <strong>e</strong>: alert. s6-log will print "s6-log: alert: ",
possibly prepended with a timestamp, followed by the first
-<em>alertsize</em> bytes of the line. </li>
+<em>alertsize</em> bytes of the line, to its standard error.
+<strong>The <tt>e</tt> form is deprecated.</strong> </li>
+ <li> <strong>1</strong>: forward to stdout. s6-log will print the selected
+line to its stdout. If any error occurs, e.g. if stdout was a pipe and the
+reading end closed, this directive will be ignored for the rest of
+s6-log's lifetime. </li>
<li> <strong>=<em>statusfile</em></strong>: status. s6-log will atomically
update the <em>statusfile</em> file with the first <em>statussize</em>
bytes of the line, and pad it with newlines. s6-log must have the right
@@ -257,25 +283,26 @@ limit. </li>
<h2> Examples </h2>
<pre>
- s6-log -bt n20 s1000000 /var/log/services/stuff
+ s6-log -b n20 s1000000 t /var/log/services/stuff
</pre>
<p>
- Logs all of stdin, prepending every line with a timestamp, into the
+ Logs all of stdin, prepending every line with a TAI64N timestamp, into the
<tt>/var/log/services/stuff</tt> logdir, with a maximum archive of
20 log files of 1 MB each; makes sure every line has been written
before reading the next one.
</p>
<pre>
- s6-log -t n30 E500 - +fatal: e - +^STAT =/var/log/foobard/status f s10000000 S15000000 !"gzip -nq9" /var/log/foobard
+ s6-log n30 E500 - +fatal: e - +^STAT =/var/log/foobard/status f s10000000 S15000000 T !"gzip -nq9" /var/log/foobard
</pre>
<ul>
<li> Sends alerts to stderr with the 500 first bytes of lines containing "fatal:". </li>
<li> Maintains the <tt>/var/log/foobard/status</tt> file at 1001 bytes,
updating it when it finds a log line starting with "STAT". </li>
- <li> Logs all other lines to logdir <tt>/var/log/foobard</tt>. When <tt>current</tt>
+ <li> Logs all other lines to logdir <tt>/var/log/foobard</tt>, prepending
+them with an ISO 8601 timestamp. When <tt>current</tt>
reaches at least 9998 kB (i.e. 10 MB filesise minus 2kB tolerance), pipe it
through <tt>gzip -nq9</tt> and save the result into a timestamped archive file, with
a maximum of 30 such files or a total of 15 MB of compressed archive files. </li>
@@ -301,14 +328,15 @@ is overpowered for this. We don't need a complete shell script interpreter:
most <em>processor</em> commands will be very simple, with only two or three
words, and we only need a way to turn a string into an <em>argv</em>, i.e. a
command line. </li>
- <li> <a href="http://www.skarnet.org/software/execline/execlineb.html">execlineb</a>
+ <li> <a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a>
was designed just for this: to turn simple strings into command lines.
It is a very fast and lightweight script launcher, that does not do any heavy
startup initialization like <tt>/bin/sh</tt> does. It happens to be the perfect
tool for the job. </li>
- <li> Yes, I also did this on purpose so people have a reason to use the
-<a href="http://www.skarnet.org/software/execline/">execline</a> language. Do not
-look at me like that: it <em>really</em> is the perfect tool for the job. </li>
+ <li> To be perfectly honest: I also did this on purpose so people have a
+reason to use the
+<a href="http://skarnet.org/software/execline/">execline</a> language. But
+seriously, it <em>really</em> is the perfect tool for the job. </li>
</ul>
<h2> Why have another logging mechanism ? </h2>
@@ -318,7 +346,9 @@ look at me like that: it <em>really</em> is the perfect tool for the job. </li>
I'm not being judgmental; I'm just stating the obvious.
</p>
-<a name="diesyslogdiedie"><h3> The syslog design is flawed from the start </h3></a>
+<a name="diesyslogdiedie">
+<h3> The syslog design is flawed from the start </h3>
+</a>
<p>
<a href="http://blog.gerhards.net/2007/08/why-does-world-need-another-syslogd.html">When
@@ -381,7 +411,9 @@ serious alternative yet, except maybe
s6-log improves upon.
</p>
-<a name="loggingchain"><h3> A not-so-modest proposal: the logging chain </h3></a>
+<a name="loggingchain">
+<h3> A not-so-modest proposal: the logging chain </h3>
+</a>
<p>
Unix distributions already do this to some extent, but it's at best
@@ -446,7 +478,9 @@ error messages, and maybe process 1's error messages, are sent to the
system console. </li>
</ul>
-<a name="#howtouse"><h3> What does s6-log have to do with all this ? </h3></a>
+<a name="howtouse">
+<h3> What does s6-log have to do with all this ? </h3>
+</a>
<p>
In a <em>logging chain</em> situation, every service must have
@@ -473,8 +507,10 @@ your system's loggers. </li>
</ul>
-<a name="#network"><h3> You're wrong about being as powerful as
-syslogd: s6-log does not do remote logging. </h3></a>
+<a name="network">
+<h3> You're wrong about being as powerful as
+syslogd: s6-log does not do remote logging. </h3>
+</a>
<p>
You mean you want to send, <em>live</em>, every <em>log line</em>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index c7c0094..3a29aa6 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -17,6 +17,15 @@
<h1> What has changed in s6 </h1>
+<ul>
+ <li> skalibs dependency bumped to 2.3.0.0. </li>
+ <li> execline dependency bumped to 2.0.2.1. </li>
+ <li> New functionality added to <a href="s6-log.html">s6-log</a>. Its
+syntax has been extended; some options are now marked as obsolescent. </li>
+ <li> Access control instated in <a href="s6-fdholderd.html">s6-fdholderd</a>
+for <a href="s6-fdholder-listc.html">listing</a> </li>
+</ul>
+
<h2> in 2.1.0.1 </h2>
<p>