diff --git a/doc/frontend.html b/doc/frontend.html
index 14d4a09c1f22c941feafd56179c8085747124a73..bad81c0f8441a41fd5a1650cc854c384307be4d2 100644
--- a/doc/frontend.html
+++ b/doc/frontend.html
@@ -92,8 +92,8 @@ the number sign '#' in front of the opening square bracket like this:</p>
The following is a break down of how to write these syntaxes:</p>
<ul>
<li>
- <tt>inline </tt> : An inline <em>value</em> must be on the same
- line of its corresponding <em>key</em>.
+ <tt>inline </tt> : An inline <em>value</em>. Must be on the same
+ line with its corresponding <em>key</em>.
<p>Valid syntax:</p><p>
</p><ul>
<pre>@type = classic</pre>
@@ -111,7 +111,7 @@ classic</pre>
<li>
<tt>quotes </tt> : A <em>value</em> between
- double-quotes must stay on the same line of its corresponding <em>key</em>.
+ double-quotes. Must be on the same line with its corresponding <em>key</em>.
</li>
<p>Valid syntax:</p>
<ul>
@@ -126,8 +126,8 @@ is not allowed"</pre>
<li>
<tt>brackets </tt> : Multiple <em>values</em> between
- brackets '()' need to be separated
- by spaces. A line break can be used instead.
+ parentheses '()'. Values need to be separated
+ with a space. A line break can be used instead.
</li>
<p>Valid syntax:</p>
<ul>
@@ -146,8 +146,8 @@ fooC
<br><hr>
<li>
- <tt>uint </tt> : A number <em>value</em>
- must be on the same line of its corresponding <em>key</em>.
+ <tt>uint </tt> : A positive whole number.
+ Must be on the same line with its corresponding <em>key</em>.
</li>
<p>Valid syntax:</p>
<ul>
@@ -161,8 +161,8 @@ fooC
</ul>
<br><hr>
<li>
- <tt>slash </tt> : A <em>value</em> beginning by a slashe '/'
- and must stay on the same line of its corresponding <em>key</em>.
+ <tt>path </tt> : An absolute path beginning with a forward slash '/'.
+ Must be on the same line with its corresponding <em>key</em>.
</li>
<p>Valid syntax:</p>
<ul>
@@ -177,10 +177,8 @@ long/path</pre>
<br><hr>
<li>
- <tt>pair </tt> : same as <tt>inline</tt> syntax.
+ <tt>pair </tt> : same as <tt>inline</tt>.
</li>
- <!-- Yes you're right but this is allow me to give example, in particular
- the one with the double-equal -->
<p>Valid syntax:</p>
<ul>
<pre>MYKEY = MYVALUE</pre>
@@ -277,9 +275,9 @@ MYVALUE</pre>
are not allowed.
<br>The <em>order is of importance</em> (!). If fooA depends on fooB and fooB
depends on fooC the order needs to be:
- <pre>@depends=(fooA fooB fooC)</pre>
+ <pre>@depends=(FooA BooA CooA)</pre>
It is unnecessary to manually define chained sets of dependencies.
- The parser will properly handle this for you.
+ The parser will properly handle this for you. For example,
If fooA depends on fooB—no matter the underlying implementation of fooB,
and although the current implementation of fooB depends on fooC—you should
just put fooB in the <tt>@depends</tt> key field of fooA. When starting the set,
@@ -290,6 +288,29 @@ MYVALUE</pre>
Beware though that if fooA depends on fooC, you need to add both fooB and fooC
to the dependencies of fooA.
</li>
+
+ <!-- Taking an another example :
+ FooA depens of FooB which depends of FooC, your service file can just declare FooB and
+ the parser will automatically add FooB because in your service file of FooB you declare
+ FooC as dependencies, so
+
+ FooA service file is : @depends=( FooB )
+ FooB service file is : @depends=( FooC )
+
+ Now we have FooA service BooA service and CooA service, FooA depends on BooA which
+ depends of CooA.
+ FooA service : @depends = ( BooA ) ;
+ BooA service : @depends = ( BooB BooC BooD CooA ) ;
+ CooA service : @depends = ( CooB CooC) ;
+
+ the complete chained dependency should be :
+ FooA service : @depends = ( BooA BooB BooC BooD CooA CooB CooC ) ;
+ BooA service : @depends = ( BooB BooC BooD CooA CooB CooC )
+ CooA service : @depends = ( CooB CooC) ;
+ So you're right, the sentence is not clear.
+
+ -->
+
</ul>
<br><hr style="border: 1px dashed #000000">
@@ -504,7 +525,7 @@ MYVALUE</pre>
<li><h4>@runas</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
- <p><tt>mandatory </tt> : no (!)</p>
+ <p><tt>mandatory </tt> : no</p>
<p><tt>syntax </tt> : inline</p>
<p><tt>valid value </tt> :</p>
<ul>
@@ -513,9 +534,8 @@ MYVALUE</pre>
last command of the service.</p>
</ul>
<p><tt><strong>Note:</strong></tt> (!) The service needs to be first started
- with root. Only root can pass on privileges. This field has
- <strong>no effects</strong> in other cases.</p>
- <!-- error from my part this field is NOT mandatory :) -->
+ with root if you want to hand over priviliges to a user. Only root can pass on privileges. This field has
+ <strong>no effect</strong> for other use cases.</p>
<hr style="border: 1px dashed #000000">
@@ -523,10 +543,10 @@ MYVALUE</pre>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory </tt> : yes (!)—if the <tt>@build</tt> key is set to <em>custom</em>.</p>
- <p><tt>syntax </tt> : quotes, slash</p>
+ <p><tt>syntax </tt> : quotes, path</p>
<p><tt>valid value </tt> :</p>
<ul>
- <li>Any valid interpreter installed on your system.</li>
+ <li>A valid path to an interpreter installed on your system.</li>
<p>This will set the language that will be used to read and write the <tt>@execute</tt> key <em>value</em>.</p>
</ul>
@@ -557,48 +577,42 @@ MYVALUE</pre>
<p>This section is exactly the same as <tt><a href="#start">[start]</a></tt> and shares the same keys. With the exception that
it will only be considered when creating the file "<em>finish</em>" for a <em>classic</em> or <em>longrun</em> service
and when creating the file "<em>down</em>" for a <em>oneshot</em> service to create its content.</p>
-<!--yes perfect -->
-
<br><hr>
<h2 id="logger">Section: [logger]</h2>
<p>This section is <em>optional</em>.</p>
-<p>It will only have an effect when the value <tt>log</tt> is added to the
-<tt>@options</tt> key in the <tt>[main]</tt> section.</p>
-<p>This section can contain the <tt>@build,@runas,@shebang,@execute</tt> key field
-with the same behaviour than the section <tt><a href="#start">start</a>,<a href="#stop">stop</a></tt>
-and the <tt>@timeout-finish,@timeout-kill</tt> key field with the same behaviour than the section
-<tt><a href="#main">main</a> </tt>more :</p>
-<!-- the section logger can be
-[logger]
-@build =
-@runas =
-@shebang
-@execute
-@timeout-finish
-@timeout-kill
-
-more
-
-@destination =
-@backup =
-@maxsize =
-@timestamp-->
+<p>The value <tt>log</tt> must be added to the
+<tt>@options</tt> key in the <tt>[main]</tt> section for <tt>[logger]</tt> to have any effect.</p>
+<p>This section extends the <tt>@build, @runas, @shebang</tt> and <tt>@execute</tt>
+key fields from <tt><a href="#start">[start]</a>/<a href="#stop">[stop]</a></tt>
+and the <tt>@timeout-finish</tt> and <tt>@timeout-kill</tt> key
+fields from <tt><a href="#main">[main]</a> </tt>. These are also valid keys
+for <tt>[logger]</tt> and behave the same way they do in the other sections but they can be not specified—see<a href="logex">example</a> below.
+In such case the default behaviour for those key are apply.</p>
+<p>Furthermore there are some keys specific to the log.</p>
+
+<!-- the logger is a service as any another service so the key @build,@runas, @timeout-finish as exactly the same behaviour. So yes by default
+the run file for the logger will be written in execlineb script, the runas if it's set will be run s6-log with the given user and so on... EXACTLY the
+same behaviour. -->
<h3>Valid <em>key</em> names:</h3>
<ul>
-
+
+ <li><h4>@build, @runas, @shebang, @execute — See <tt><a href="#start">[start]</a></tt></h4></li>
+ <li><h4>@timeout-finish, @timeout-kill — See <tt><a href="#start">[main]</a></tt></h4></li>
+
+ <hr style="border: 1px dashed #000000">
+
<li><h4>@destination</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory </tt> : no</p>
- <p><tt>syntax </tt> : slash</p>
+ <p><tt>syntax </tt> : path</p>
<p><tt>valid value </tt> :</p>
<ul>
<li>Any valid path on the system.</li>
- <!-- the slash syntax was modified, slash mean absoluth path -->
- <p>The directory where to save the log file. This directory is automatically created. Obviously,
+ <p>The directory where to save the log file. This directory is automatically created. Obviously,
the current user of the process need to have sufficient permissions on the destination directory
to be able to create it. The default directory is <tt>/var/log/66/servicename</tt> for <tt>root</tt> and
<tt>$HOME/.66/log/servicename</tt> for any regular user. The default can also be changed at compile-time by
@@ -651,7 +665,19 @@ more
the time and two spaces after the time, before being processed by
the next action directive.</p></li>
</ul>
-
+ <p id="#logex">The following give you two examples of the possible <tt>[logger]</tt> section definition.</p>
+ <pre> [logger]
+ @build = auto
+ @runas = user
+ @timeout-finish = 10000
+
+ @destination = /run/log
+ @backup = 10
+ @timestamp = ISO</pre>
+ <pre> [logger]
+ @destination = /run/log
+ @backup = 10
+ @timestamp = ISO</pre>
</ul>
<br><hr>
diff --git a/doc/marian.html b/doc/marian.html
new file mode 100644
index 0000000000000000000000000000000000000000..38605a99830dfd1a70e70c81257d7d3fd50c6181
--- /dev/null
+++ b/doc/marian.html
@@ -0,0 +1,738 @@
+<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>66: the frontend service file</title>
+ <meta name="Description" content="Documentation for the frontend service file of the 66 system tools which is a better method to manage all your different services in a centralized way.">
+ <meta name="Keywords" content="66 frontend service file supervision format key value ini">
+ <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+<body>
+
+<p>
+<a href="index.html">66</a><br>
+<a href="//obarun.org/">www.obarun.org</a>
+</p>
+
+<h1> The frontend service file </h1>
+
+<p>
+The <a href="https://skarnet.org/software/s6">s6</a> and <a href="https://skarnet.org/software/s6">s6-rc</a>
+programs each handle and use several kinds of services and different files. It is quite complex to
+understand and manage the relationship between all those files and services. If you're interested in the details
+you should read <a href="https://skarnet.org/software/s6/servicedir.html">the documentation for the s6 servicedir</a>
+and also about <a href="https://wiki.obarun.org/doku.php?id=s6services"><em>classic</em></a>, <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html">
+<em>oneshot</em>, <em>longrun</em> and <em>bundle</em> services</a> on Obarun. The frontend service file of 66 tools allows you to deal with all these different services in
+a centralized manner in one single place.<br>
+By default 66 tools expect to find any service file in <tt>/etc/66/service</tt> although this
+can be changed at compile-time by passing the <tt>--with-service-path=<em>DIR</em></tt>
+option to <tt>./configure.</tt></p>
+
+<p>The frontend service file has a format of INI with a specific syntax on the key field.
+The name of the file usually corresponds to the name of the daemon and does not
+have any extension or prefix.
+
+</p><p>The file is made of <em>sections</em> which can contain one or more <em>key value</em> pairs
+where the <em>key</em> name can contain special characters like <em>'-' (hyphen)</em> or <em>'_' (low line)</em>
+except the character <em>'@' (commercial at)</em> which is reserved.</p>
+
+<h3>File name examples</h3>
+<pre>/etc/66/service/dhcpcd</pre>
+<pre>/etc/66/service/very_long_name</pre>
+
+<h3>File content examples</h3>
+<pre> [main]
+ @type = classic
+ @name = ntpd
+ @description = "ntpd daemon"
+ @user = ( root )
+ @options = ( log env )
+
+ [start]
+ @build = auto
+ @execute = ( foreground { mkdir -p -m 0755 ${RUNDIR} }
+ execl-cmdline -s { ntpd ${CMD_ARGS} } )
+
+ [environment]
+ !RUNDIR=/run/openntpd
+ !CMD_ARGS=-d -s
+ </pre>
+
+<p>The parser will not accept any empty <em>value</em>. If a
+<em>key</em> is set, the <em>value</em> cannot be empty. Comments are allowed
+using the number sign '#'. Empty lines are also allowed.<br>
+<em>Key names</em> are <strong>case sensitive</strong> and <em>cannot be
+modified</em>. Most names should be specific enough to avoid confusion.<br>
+The sections can be declared in any order but as a good practice
+the <tt>[main]</tt> section should be declared first. That way the parser
+can read the file as fast as possible.</p>
+
+<h2>Sections</h2>
+
+<p>All sections need to be declared with the name written between square brackets '[]'
+and must be of lowercase letters <strong>only</strong>. This means that special characters, uppercase letters and numbers are not allowed in the name of a section. An <em>entire</em> section can be commented out by placing
+the number sign '#' in front of the opening square bracket like this:</p>
+
+<pre> #[stop]</pre>
+
+<p>The frontend service file allows the following section names: </p>
+<ul>
+ <li><a href="#main">[main]</a></li>
+ <li><a href="#start">[start]</a></li>
+ <li><a href="#stop">[stop]</a></li>
+ <li><a href="#logger">[logger]</a></li>
+ <li><a href="#environment">[environment]</a></li>
+</ul>
+<p>Although a section can be mandatory not all of its key fields must be necessarily so.</p>
+
+<hr>
+
+<h2>Syntax legend</h2>
+
+ <p> The <em>value</em> of a <em>key</em> is parsed in a specific format depending on the key.
+ The following is a break down of how to write these syntaxes:</p>
+ <ul>
+ <li>
+ <tt>inline </tt> : An inline <em>value</em> must be on the same
+ line of its corresponding <em>key</em>.
+ <p>Valid syntax:</p><p>
+ </p><ul>
+ <pre>@type = classic</pre>
+ <pre>@type=classic</pre>
+ </ul>
+
+ <p>(!) Invalid syntax:</p>
+ <ul>
+ <pre>@type=
+classic</pre>
+ </ul>
+
+ </li>
+ <br><hr>
+
+ <li>
+ <tt>quotes </tt> : A <em>value</em> between
+ double-quotes must stay on the same line of its corresponding <em>key</em>.
+ </li>
+ <p>Valid syntax:</p>
+ <ul>
+ <pre>@description = " some awesome description "</pre>
+ <pre>@description="some awesome description"</pre>
+ </ul>(!) Invalid syntax:<p></p>
+ <ul>
+ <pre>@description = "line break inside a double-quote
+is not allowed"</pre>
+ </ul>
+ <br><hr>
+
+ <li>
+ <tt>brackets </tt> : Multiple <em>values</em> between
+ brackets '()' need to be separated
+ by spaces. A line break can be used instead.
+ </li>
+ <p>Valid syntax:</p>
+ <ul>
+ <pre>@depends = ( fooA fooB fooC )</pre>
+ <pre>@depends=(fooA fooB fooC)</pre>
+ <pre>@depends=(
+fooA
+fooB
+fooC
+)</pre>
+ </ul>
+ <p>(!) Invalid syntax:</p>
+ <ul>
+ <pre>@depends = (fooAfooBfooC)</pre>
+ </ul>
+ <br><hr>
+
+ <li>
+ <tt>uint </tt> : A number <em>value</em>
+ must be on the same line of its corresponding <em>key</em>.
+ </li>
+ <p>Valid syntax:</p>
+ <ul>
+ <pre>@notify = 3</pre>
+ <pre>@notify=3</pre>
+ </ul>
+ <p>(!) Invalid syntax:
+ </p><ul>
+ <pre>@notify=
+3</pre>
+ </ul>
+ <br><hr>
+ <li>
+ <tt>slash </tt> : A <em>value</em> containing
+ one or more slashes '/' must stay on the same line of its corresponding <em>key</em>.
+ </li>
+ <p>Valid syntax:</p>
+ <ul>
+ <pre>@destination = /etc/66 </pre>
+ <pre>@destination=/etc/66 </pre>
+ </ul>
+ <p>(!) Invalid syntax:</p>
+ <ul>
+ <pre>@destination=/a/very/
+long/path</pre>
+ </ul>
+ <br><hr>
+
+ <li>
+ <tt>pair </tt> : For a <em>key=value</em> pair
+ to be valid it must stay on one single line.
+ </li>
+ <!-- Isn't pair exactly the same as line/inline? Looks completely superfluous to me. -->
+ <p>Valid syntax:</p>
+ <ul>
+ <pre>MYKEY = MYVALUE</pre>
+ <pre>anotherkey=anothervalue</pre>
+ <pre>anotherkey=where_value=/can_contain/equal/Character</pre>
+ </ul>
+ <p>(!) Invalid syntax:</p>
+ <ul>
+ <pre>MYKEY=
+MYVALUE</pre>
+ </ul>
+ </ul>
+
+<br><hr>
+
+<h2 id="main">Section: [main]</h2>
+
+<p>This section is <em>mandatory</em>. (!)</p>
+
+<h3>Valid <em>key</em> names:</h3>
+
+<ul>
+
+ <li><h4>@type</h4></li>
+ <h5>Corresponds to the file "<em>type</em>" of s6-rc programs.</h5>
+ <p>Declare the type of the service.</p>
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : inline</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li><tt>classic </tt> : declares the service as "classic".</li>
+ <li><tt>bundle </tt> : declares the service as <tt>bundle</tt> service.</li>
+ <li><tt>longrun </tt> : declares the service as <tt>longrun</tt> service.</li>
+ <li><tt>oneshot </tt> : declares the service as <tt>oneshot</tt> service.</li>
+ </ul>
+ <p><em><tt><strong>Note:</strong></tt></em> If you don't care about dependencies between services or if you don't need
+ specific tasks to get done before running the daemon, "classic" is the best pick.</p><br>
+
+ <br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@name</h4></li>
+ <h5>Corresponds to the <em>name of the service directory</em> of s6 and s6-rc programs.</h5>
+ <p>Name of the service.</p>
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : inline</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Any name can be set as a <em>value</em>. A good pratice is to use the
+ same name of the frontend service file.</li>
+ </ul>
+
+ <br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@description</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p>A short description of the service.</p>
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : quote</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Anything you want.</li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@user</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p>Declare the permissions of the service.</p>
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Any valid user of the system. If you don't
+ know in advance the name of the user who will deal with the service,
+ you can use the term '<tt>user</tt>'. In that case every user of the
+ system will be able to deal with the service.
+ <br>(!) Be aware that <em>root is not automatically added</em>.
+ If you don't declare <tt>root</tt> in this field, you will <em>not be able
+ to use the service even with root privileges.</em></li>
+ </ul>
+
+ <br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@depends</h4></li>
+ <h5>Corresponds to the file "<em>dependencies</em>" of s6-rc programs.</h5>
+ <p>Declare dependencies of the service.</p>
+ <p><tt>mandatory </tt> : no—this field has no effect if the
+ type of the service is "classic"</em>.</p>
+ <p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>The <em>name</em> of any valid service with type
+ <tt>bundle</tt>, <tt>longrun</tt> or <tt>oneshot</tt>. Services of type <tt>classic</tt>
+ are not allowed.
+ <br>The <em>order is of importance</em> (!). If fooA depends on fooB and fooB
+ depends on fooC the order needs to be:
+ <pre>@depends=(fooA fooB fooC)</pre>
+ It is unnecessary to manually define chained sets of dependencies.
+ The parser will properly handle this for you.
+ If fooA depends on fooB—no matter the underlying implementation of fooB,
+ and although the current implementation of fooB depends on fooC—you should
+ just put fooB in the <tt>@depends</tt> key field of fooA. When starting the set,
+ 66-enable will parse and enable fooA, fooB and fooC and 66-start will start
+ fooC first, then fooB, then fooA.
+ If the underlying implementation of fooB changes at any moment and does not depend on fooC anymore,
+ you will just have to modify the <tt>@depends</tt> field for fooB.
+ Beware though that if fooA depends on fooC, you need to add both fooB and fooC
+ to the dependencies of fooA.
+ </li>
+ </ul>
+
+ <br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@contents</h4></li>
+ <h5>Corresponds to the file "<em>contents</em>" of s6-rc programs.</h5>
+ <p>Declare the contents of a bundle service.</p>
+ <p><tt>mandatory </tt> : yes (!)—for services of type <tt>bundle</tt>.
+ <em>Optional</em> for services of type <tt>oneshot</tt> or <tt>longrun</tt>.
+ No effect at all for services of type <tt>classic</tt>.</p>
+ <p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>The name of any valid service of type <tt>bundle</tt>, <tt>longrun</tt> or <tt>oneshot</tt>. Services of type <tt>classic</tt>
+ are not allowed.
+ </li>
+ </ul>
+
+ <br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@options</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li><tt>log </tt> : automatically create a logger for the service.
+ The behavior of the logger can be adjusted in the corresponding
+ section—see <a href="#logger">[logger]</a>.</li>
+ <li><tt>env </tt> : enable the use of the <tt>[environment]</tt>
+ section for the service—see <a href="#environment">[environment]</a>.</li>
+ <li><tt>pipeline </tt> : automatically create a pipeline between
+ the service and the logger. For more information read
+ <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html">the s6-rc documentation</a>.</li>
+ </ul>
+ <p><em><strong>Note:</strong></em> The <em>funnel</em> feature of pipelining is not implemented yet.</p>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@flags</h4></li>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li><tt>nosetsid </tt> :
+ <h5>Corresponds to the file "<em>nosetsid</em>" of s6-rc and s6 programs</h5>
+ <p>This will create the file <tt>nosetsid</tt></p>
+ <p>Once this file was created the service will be run in the same process group
+ as the supervisor of the service <a href="https://skarnet.org/software/s6/s6-supervise.html">(s6-supervise)</a>. Without this file the service will have its own process group and is started as a session leader.</p>
+ </li><li><tt>down </tt> :
+ <h5>Corresponds to the file "<em>down</em>" of s6-rc and s6 programs.</h5>
+ This will create the file <tt>down</tt><br><br>
+ Once this file was created the default state of the service will be considered <em>down</em>,
+ not <em>up</em>: the service will not automatically be started until it receives a
+ <tt>66-start</tt> command. Without this file the default state of the service will be <em>up</em> and started automatically.
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@notify</h4></li>
+ <h5>Corresponds to the file "<em>notification-fd</em>" of s6-rc programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>notification-fd</tt>.
+ Once this file was created the service supports
+ <a href="https://skarnet.org/software/s6/notifywhenup.html">readiness
+ notification</a>. The <em>value</em> equals <em>the number of the file descriptor
+ that the service writes its readiness notification to.</em> (For instance,
+ it should be 1 if the daemon is <a href="https://skarnet.org/software/s6/s6-ipcserverd.html">s6-ipcserverd</a>
+ run with the -1 option.) When the service is started or restarted and
+ this file is present and contains a valid descriptor number, <tt>66-start</tt>
+ will wait for the notification from the service and broadcast readiness,
+ i.e. any <a href="66-svctl.html">66-svctl -U</a> process will be triggered.
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@timeout-finish</h4></li>
+ <h5>Corresponds to the file "<em>timeout-finish</em>" of s6-rc and s6 programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>timeout-finish</tt>.
+ Once this file was created the <em>value</em> will equal the number of milliseconds
+ after which the <tt>./finish</tt> script—if it exists—will be killed with a
+ SIGKILL. The default is <tt>5000</tt>; finish scripts are killed if they're
+ still alive after 5 seconds. A value of <tt>0</tt> allows finish scripts to run forever.
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@timeout-kill</h4></li>
+ <h5>Corresponds to the file "<em>timeout-kill</em>" of s6-rc and s6 programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid values </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>timeout-kill</tt>.
+ Once this file was created and the <em>value</em> is not <tt>0</tt>, then on reception of a <tt><a href="66-stop.html">66-stop</a></tt>
+ command—which sends a SIGTERM and a SIGCONT to the service—a timeout
+ of <tt>value</tt> milliseconds is set. If the service is still not
+ dead after <tt>value</tt> milliseconds it will receive a SIGKILL.
+ If the file does not exist, or contains <tt>0</tt> or an invalid value,
+ then the service is never forcibly killed (unless, of course, a
+ <a href="https://skarnet.org/software/s6/s6-svc.html">s6-svc -k</a> command is sent).
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@timeout-up</h4></li>
+ <h5>Corresponds to the file "<em>timeout-up</em>" of s6-rc programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>timeout-up</tt>.
+ Once this file was created the <em>value</em> will equal the maximum
+ number of milliseconds that <tt><a href="66-start.html">66-start</a></tt> will wait
+ for successful completion of the service start. If starting the service
+ takes longer than this <em>value</em>, <tt>66-start</tt> will declare the transition
+ a failure. If the <em>value</em> is <tt>0</tt>, no timeout
+ is defined and <tt>66-start</tt> will wait for the service to start
+ until the <tt>maxdeath</tt> is reached. Without this file a <em>value</em> of <tt>3000</tt> (3 seconds) will be
+ taken by default.
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@timeout-down</h4></li>
+ <h5>Corresponds to the file "<em>timeout-down</em>" of s6-rc programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>timeout-down</tt>.
+ Once this file was created the <em>value</em> will equal the maximum
+ number of milliseconds <tt><a href="66-stop.html">66-stop</a></tt> will wait
+ for successful completion of the service stop. If starting the service
+ takes longer than this <em>value</em>, <tt>66-stop</tt> will declare the transition
+ a failure. If the <em>value</em> is <tt>0</tt>, no timeout
+ is defined and <tt>66-stop</tt> will wait for the service to start
+ until the <tt>maxdeath</tt> is reached. Without this file a <em>value</em> of <tt>3000</tt> (3 seconds) will be
+ taken by default.
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@maxdeath</h4></li>
+ <h5>Corresponds to the file "<em>max-death-tally</em>" of s6-rc and s6 programs.</h5>
+ <p><tt>mandatory </tt> : no
+ </p><p><tt>syntax </tt> : uint</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid number.
+ <p>This will create the file <tt>max-death-tally</tt>.
+ Once this file was created the <em>value</em> will equal the maximum
+ number of service death events that the supervisor will keep track of. If
+ the service dies more than this number of times, the oldest event will
+ be forgotten and the transition (<tt>66-start</tt> or <tt>66-stop</tt>) will
+ be declared as failed. Tracking death events is useful,
+ for example, when throttling service restarts. The <em>value</em>
+ cannot be greater than <tt>4096</tt>. Without this file a default of <tt>3</tt>
+ is used.</p>
+ </li>
+ </ul>
+</ul>
+
+<br><hr>
+
+<h2 id="start">Section: [start]</h2>
+
+<p>This section is <em>mandatory</em>. (!)</p>
+
+<h3>Valid <em>key</em> names:</h3>
+
+<ul>
+
+ <li><h4>@build</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : inline</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li><tt>auto </tt> : creates the service script file
+ as <a href="https://skarnet.org/software/execline/">execline</a> script.</li>
+ <p>The corresponding file to start the service will automatically be written in
+ <a href="https://skarnet.org/software/execline/">execline</a> format with
+ the <tt>@execute</tt> key <em>value</em>.</p>
+ <li><tt>custom </tt> : creates the service script file
+ in the language set in the <tt>@shebang</tt> key <em>value</em>.</li>
+ <p>The corresponding file to start the service will be written
+ in the language set in the <tt>@shebang</tt> key <em>value</em>.</p>
+ </li>
+ </ul>
+
+<br><hr style="border: 1px dashed #000000">
+
+ <li><h4>@runas</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : inline</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid user set on the system</li>
+ <p>This will pass the privileges of the service to the given user before starting the daemon.</p>
+ </ul>
+ <p><tt><strong>Note:</strong></tt> (!) The daemon needs to be first started
+ with root. Only root can pass on privileges. This field has
+ no effects in other cases.</p>
+ <!-- This is very confusing!
+
+ You say this is mandatory but then make a note about how this has no other use case. What other use case could there possibly be if this is mandatory?
+
+ Will my service not start if I do not run it as root? You say the field has no effect but if this field is mandatory will my whole service error out?
+
+ Do you mean something like: "If not started with root, the service will not start at all!"? Do all services need to be run as root?
+
+ Also from what I understand and read a "daemon" is a running instance of a service, ain't that so? Then how can I start a daemon seperately from a service? Because that is how it sounds.
+
+ It's completely understandable what this key does. It's just that the note instead of explaining the key, raises doubt. To clear this confusion I propose to either: not use the word daemon and clearly explain the alternative effects—if there were any possible—or briefly explain how I possibly can mess things up with this key. -->
+
+ <hr style="border: 1px dashed #000000">
+
+ <li><h4>@shebang</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+
+ <p><tt>mandatory </tt> : yes (!)—if the <tt>@build</tt> key is set to <em>custom</em>.</p>
+ <p><tt>syntax </tt> : quotes, slash</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid interpreter installed on your system.</li>
+ <p>This will set the language that will be used to read and write the <tt>@execute</tt> key <em>value</em>.</p>
+ </ul>
+
+ <hr style="border: 1px dashed #000000">
+
+ <li><h4>@execute</h4></li>
+ <h5>Corresponds to the file "<em>run</em>" for a <em>classic</em> or
+ <em>longrun</em> service and to the file "<em>up</em>" for
+ a <em>oneshot</em> service.</h5>
+
+ <p><tt>mandatory </tt> : yes (!)</p>
+ <p><tt>syntax </tt> : bracket</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>The command to execute when starting the daemon.</li>
+ <!-- The same as with @runas, why all of a sudden is it a daemon now? Could this be better named service here or would that be incorrect? -->
+ </ul>
+ <p><tt><strong>Note:</strong></tt> The field will be used as is. No changes will be applied at all. It's the
+ responsability of the author to make sure that the content of this field is correct.</p>
+
+</ul>
+
+<br><hr>
+
+<h2 id="stop">Section: [stop]</h2>
+
+<p>This section is <em>optional</em>.</p>
+
+<p>This section is exactly the same as <tt><a href="#start">[start]</a></tt> and shares the same keys. With the exception that
+it will only be considered when creating the file "<em>finish</em>" for a <em>classic</em> or <em>longrun</em> service
+and when creating the file "<em>down</em>" for a <em>oneshot</em> service to create its content.</p>
+<!-- Did I get that right? ._." -->
+
+<br><hr>
+
+<h2 id="logger">Section: [logger]</h2>
+
+<p>This section is <em>optional</em>.</p>
+<p>It will only have an effect when the value <tt>log</tt> is added to the
+<tt>@options</tt> key in the <tt>[main]</tt> section.</p>
+<p>This section accepts the <tt>@build,@runas,@shebang,@execute</tt> key field
+as the manner as the section <tt><a href="#start">start</a>,<a href="#stop">stop</a></tt>
+and <tt>@timeout-finish,@timeout-kill</tt> key field as the section
+<tt><a href="#main">main</a> </tt>more :</p>
+<!-- You completely lost me here. I can not make any sense of this paragraph, sorry. -->
+
+<h3>Valid <em>key</em> names:</h3>
+
+<ul>
+
+ <li><h4>@destination</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no</p>
+ <p><tt>syntax </tt> : slash</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid path on the system.</li>
+ <!-- Only absolute or relative as well?
+ Must this directory be present? Is that what valid means here?
+ Or will it be created if not?
+ Could be:
+ "Any existing absolute path on the system" or
+ "An absolute path"
+ -->
+ <p>The directory where to save the log file. <!-- "The path must exist and be writable by [...?]." --> The default is <tt>/var/log/66/servicename</tt> for <tt>root</tt> and
+ <tt>$HOME/.66/log/servicename</tt> for any regular user. The default can also be changed at compile-time by
+ passing the <tt>--with-system-logpath=<em>DIR</em></tt> option
+ for root and <tt>--with-user-logpath=<em>DIR</em></tt> for a user to <tt>./configure.</tt></p>
+ </ul>
+
+ <hr style="border: 1px dashed #000000">
+
+ <li><h4>@backup</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no</p>
+ <p><tt>syntax </tt> : uint</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid number.</li>
+ <p>The log directory will keep <em>value</em> files.
+ The next log to be saved will replace the oldest file present. By default 3 files are kept.</p>
+ </ul>
+
+ <hr style="border: 1px dashed #000000">
+
+ <li><h4>@maxsize</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no</p>
+ <p><tt>syntax </tt> : uint</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>Any valid number.</li>
+ <p>A new log file will be created every time the current one approaches <em>value</em>
+ bytes. By default, filesize is <tt>1000000</tt>; it cannot be set lower than <tt>4096</tt>
+ or higher than <tt>268435455</tt>.</p>
+ </ul>
+
+ <hr style="border: 1px dashed #000000">
+
+ <li><h4>@timestamp</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no</p>
+ <p><tt>syntax </tt> : inline</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <li>TAI
+ <p>The logged line will be preceded by a TAI64N timestamp
+ (and a space) before being processed by the next action directive.</p></li>
+ <li>ISO
+ <p>The selected line will be preceded by a ISO 8601 timestamp for
+ combined date and time representing local time according to the
+ systems 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.</p></li>
+ </ul>
+
+</ul>
+
+<br><hr>
+
+<h2 id="environment">Section: [environment]</h2>
+
+<p>This section is <em>optional</em>.</p>
+<p>It will only have an effect when the value <tt>env</tt> is added to the
+<tt>@options</tt> key in the <tt>[main]</tt> section.</p>
+<p>A file named <em>key</em> with the <em>value</em> as contain will be
+created by default at /etc/66/env/name_of_daemon directory. The default can also be changed at compile-time by
+ passing the <tt>--with-service-path=<em>DIR</em></tt> option to <tt>./configure</tt>.</p>
+
+<h3>Valid <em>key</em> names:</h3>
+
+<ul>
+ <li><h4>Any <em>key=value</em> pair</h4></li>
+ <h5>Without equivalent, this key is unique to 66 tools.</h5>
+ <p><tt>mandatory </tt> : no</p>
+ <p><tt>syntax </tt> : pair</p>
+ <p><tt>valid value </tt> :</p>
+ <ul>
+ <p>You can define any variables that you want to add to the environment
+ of the service. For example:</p>
+<pre>
+ [environment]
+ RUNDIR=/run/openntpd
+ CMD_ARGS=-d -s
+</pre>
+ <p>The '!' character can be put in front
+ of the <em>key=value</em> pair like this :</p>
+<pre>
+ [environment]
+ !RUNDIR=/run/openntpd
+ !CMD_ARGS=-d -s
+</pre>
+ <p>This will explicitly <em>not</em> set the <em>value</em>
+ of the <em>key</em> for the runtime process but only at the start of the daemon. <!-- Service?! -->
+ In this example the <em>key=value</em> pair passed to the command line does not need
+ to be present in the general environment variable of the daemon.</p> <!-- Service?! -->
+ </ul>
+ </ul>
+ <br><hr>
+
+<h2>A word about the @execute key</h2>
+
+<p>As described above the <tt>@execute</tt> key can be written
+in any language as long as you define the key <tt>@build</tt> as <em>custom</em>
+and the <tt>@shebang</tt> key to the language interpreter to use. For example
+if you want to write your <tt>@execute</tt> field with bash :
+<pre> @build = custom
+ @shebang = "/usr/bin/bash"
+ @execute = (
+ echo "This script displays available services"
+ for i in $(ls /etc/66/service); do
+ echo "daemon : ${i} is available"
+ done
+ )
+</pre>
+This is an unnecessary example but it shows how to construct this use case. The parser will
+put your <tt>@shebang</tt> at the beginning of the script and copy the contents of the <tt>@execute</tt> field. So, the resulting file will be :
+<pre> #!/usr/bin/bash
+ echo "This script displays available services"
+ for i in $(ls /etc/66/service); do
+ echo "daemon : ${i} is available"
+ done</pre>
+When using this sort of custom function <tt>@runas</tt> has <strong>no effect</strong>. You must define with care what you want to happen in a <em>custom</em>
+case.</p>
+<p>Furthermore when you set <tt>@build</tt> to <em>auto</em> the parser will take care about the
+redirection of the ouput of the daemon <!-- Service?! --> when the logger is activated. When setting <tt>@build</tt> to <em>custom</em> though the parser will not do this automatically. You need to explicitly tell it to:
+<pre> #!/usr/bin/bash
+ exec 2>&1
+ echo "This script redirects file descriptor 2 to the file descriptor 1"
+ echo "Then the logger reads the file descriptor 1 and you have"
+ echo "the error of the daemon written into the appropriate file"</pre>
+</p>
+<p>Finally you need to take care about how you define your environment variable
+in the section <tt><a href="#environment">[environment]</a></tt>. When setting <tt>@build</tt> to <em>auto</em> the parser will also take care about the '!' character if you use it. This character will have <strong>no effect</strong> in the case of <em>custom</em>.
+</p>
+<p>This same behavior applies to the <tt><a href="#logger">[logger]</a></tt> section.
+The fields <tt>@destination, @backup, @maxsize</tt> and <tt>@timestamp</tt> will have <strong>no effect</strong>
+in a <em>custom</em> case. You need to explicitly define the program to use the logger and the options
+for it in your <tt>@execute</tt> field.</p>
+</ul></body></html>