diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2015-01-16 01:36:48 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2015-01-16 01:36:48 +0000 |
| commit | 83853a80eb18238796154164f9ea776b0c167ab7 (patch) | |
| tree | a8087bab87fb1cf09a63f3b0619389a2ce3b2e37 /doc | |
| parent | 87c5b2118efcee65eeda3f743d081ea9c2b866d9 (diff) | |
| download | s6-83853a80eb18238796154164f9ea776b0c167ab7.tar.xz | |
- s6-svlisten and s6-svlisten1
- Synchronous s6-svc
- version 2.0.2.0, rc
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 2 | ||||
| -rw-r--r-- | doc/s6-svc.html | 37 | ||||
| -rw-r--r-- | doc/s6-svlisten.html | 100 | ||||
| -rw-r--r-- | doc/s6-svlisten1.html | 81 |
4 files changed, 212 insertions, 8 deletions
diff --git a/doc/index.html b/doc/index.html index 9e3dde3..5423e12 100644 --- a/doc/index.html +++ b/doc/index.html @@ -115,6 +115,8 @@ a user interface to control those processes and monitor service states. <li><a href="s6-svok.html">The <tt>s6-svok</tt> program</a></li> <li><a href="s6-svstat.html">The <tt>s6-svstat</tt> program</a></li> <li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li> +<li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li> +<li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li> <li><a href="s6-notifywhenup.html">The <tt>s6-notifywhenup</tt> program</a> </li> </ul> diff --git a/doc/s6-svc.html b/doc/s6-svc.html index 606cc16..0ca3bd7 100644 --- a/doc/s6-svc.html +++ b/doc/s6-svc.html @@ -27,7 +27,7 @@ knowing their PIDs, and without using horrible hacks such as .pid files. <h2> Interface </h2> <pre> - s6-svc [ -abqhkti12fFpcoduxO ] <em>servicedir</em> + s6-svc [ -D | -U ] [ -t <em>timeout</em> ] [ -abqhkti12pcoduxO ] <em>servicedir</em> </pre> <p> @@ -62,7 +62,17 @@ normally never be used on a working system. </li> <li> <tt>-O</tt> : Once at most. Do not restart the supervised process when it dies. If it is down when the command is received, do not even start it. </li> - <li> <tt>-f</tt>, <tt>-F</tt> : unused for now. </li> + <li> <tt>-t <em>timeout</em></tt> : if the <tt>-D</tt> or +<tt>-U</tt> option has been given, <tt>-t</tt> specifies a timeout +(in milliseconds) after which s6-svc will exit 1 with an error message if +the service still hasn't reached the desired state. By default, the +timeout is 0, which means that s6-svc will block indefinitely. </li> + <li> <tt>-D</tt> : s6-svc will not exit until the service is down. </li> + <li> <tt>-U</tt> : s6-svc will not exit until the service is up and +<a href="notifywhenup.html">ready</a> as notified by the daemon itself. +Be careful to only use this command on services that send readiness +notifications and are managed by <a href="s6-notifywhenup.html">s6-notifywhenup</a>, +else the command will never be successful. </li> </ul> <h2> Usage examples </h2> @@ -81,9 +91,15 @@ the process represented by the <tt>/service/sshd</tt> service directory - typically the sshd server. </p> -<pre> s6-svc -d /service/ftpd </pre> +<pre> s6-svc -Dd /service/ftpd </pre> <p> - Take down the ftpd server. + Take down the ftpd server and block until the process is really down. +</p> + +<pre> s6-svc -Uu -t 5000 /service/ftpd </pre> +<p> + Bring up the ftpd server and block until it has sent notification that it +is ready. Exit 1 if it is still not ready after 5 seconds. </p> <pre> s6-svc -a /service/httpd/log </pre> @@ -94,11 +110,16 @@ process is <a href="s6-log.html">s6-log</a>, this triggers a log rotation. <h2> Internals </h2> -<p> -s6-svc writes control commands into the <tt><em>servicedir</em>/supervise/control</tt> +<ul> + <li> s6-svc writes control commands into the <tt><em>servicedir</em>/supervise/control</tt> FIFO. A s6-supervise process running on <em>servicedir</em> will be listening to this FIFO, -and will read and interpret those commands. -</p> +and will read and interpret those commands. </li> + <li> When invoked with the <tt>-D</tt> or <tt>-U</tt> option, s6-svc executes into +<a href="s6-svlisten1.html">s6-svlisten1</a>, which will listen to service state +changes and spawn another s6-svc instance (without the <tt>-D</tt> or <tt>-U</tt> +option) that will send the commands to the service. Any error message written during +the waiting period will mention it is being written by s6-svlisten1; this is normal. </li> +</ul> </body> </html> diff --git a/doc/s6-svlisten.html b/doc/s6-svlisten.html new file mode 100644 index 0000000..eeb0a91 --- /dev/null +++ b/doc/s6-svlisten.html @@ -0,0 +1,100 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-svlisten program</title> + <meta name="Description" content="s6: the s6-svlisten program" /> + <meta name="Keywords" content="s6 command s6-svlisten notification service waiting" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The s6-svlisten program </h1> + +<p> + s6-svlisten runs a program while listening on notifications from +a collection of supervised services, and blocks until they all go up, or down. +</p> + +<p> + s6-svlisten only waits for notifications; it never polls. +</p> + +<h2> Interface </h2> + +<p> + In an execline script: +</p> + +<pre> + s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t <em>timeout</em> ] { <em>servicedir</em> <em>servicedir...</em> } <em>prog...</em> +</pre> + +<p> + Outside of an execline script: +</p> + +<pre> + s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>servicedir...</em> "" <em>prog...</em> +</pre> + +<ul> + <li> s6-svlisten checks the state of one or more <a href="servicedir.html">service +directories</a> given as arguments in the first block and monitor +their state changes. </li> + <li> It spawns <em>prog...</em> as a child right after getting the +initial state of all the monitored services. </li> + <li> It then blocks until the wanted state happens, then exits 0. </li> +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-u</tt> : up. s6-svlisten will wait until the services are up, as +reported by s6-supervise. +This is the default; it is not reliable, but it does not depend on specific +support in the service programs. See <a href="notifywhenup.html">this page</a> +for details. </li> + <li> <tt>-U</tt> : really up. s6-svlisten will wait until the services are +up <em>and</em> ready as reported by the services themselves. This requires +specific support in the service programs, and the use of +<a href="s6-notifywhenup.html">s6-notifywhenup</a> in the service's run script. +See the explanation on <a href="notifywhenup.html">this page</a>. </li> + <li> <tt>-d</tt> : down. s6-svlisten will wait until the services are down. </li> + <li> <tt>-o</tt> : or. s6-svlisten will wait until <em>one</em> of the +given services comes up or down. </li> + <li> <tt>-a</tt> : and. s6-svlisten will wait until <em>all</em> of the +given services come up or down. This is the default. </li> + <li> <tt>-t <em>timeout</em></tt> : if the requested events have not +happened after <em>timeout</em> milliseconds, s6-svlisten will print a message +to stderr and exit 1. By default, <em>timeout</em> is 0, which means no time +limit. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-svlisten is the service-specific version of +<a href="s6-ftrig-listen.html">s6-ftrig-listen</a>. The point of s6-svlisten +is to use it to spawn a program such as <a href="s6-svc.html">s6-svc</a>, +in order to send signals to services while making sure to catch their +state changes - thus avoiding the race condition that occurs when running +<a href="s6-svc.html">s6-svc</a> then <a href="s6-svwait.html">s6-svwait</a> +sequentially. </li> + <li> s6-svlisten needs to handle a variable length list of service directories. +For that, it uses an encoding provided by +<a href="http://skarnet.org/software/execline/">execline</a>, so it's best +to only use it in execline scripts (only the execline syntax is guaranteed +to not change). There is a variant of s6-svlisten that does not use execline +syntax, but only handles one service directory: +<a href="s6-svlisten1.html">s6-svlisten1</a>. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-svlisten1.html b/doc/s6-svlisten1.html new file mode 100644 index 0000000..f6565ed --- /dev/null +++ b/doc/s6-svlisten1.html @@ -0,0 +1,81 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-svlisten1 program</title> + <meta name="Description" content="s6: the s6-svlisten1 program" /> + <meta name="Keywords" content="s6 command s6-svlisten1 notification service waiting" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The s6-svlisten1 program </h1> + +<p> + s6-svlisten1 runs a program while listening on notifications from a +supervised service, and blocks until said service goes up, or down. +</p> + +<p> + s6-svlisten1 only waits for notifications; it never polls. +</p> + +<h2> Interface </h2> + +<pre> + s6-svlisten [ -U | -u | -d ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-svlisten1 checks the state of the <em>servicedir</em> +<a href="servicedir.html">service directory</a> and monitor its +state changes. </li> + <li> It spawns <em>prog...</em> as a child right after getting the +initial state of the service. </li> + <li> It then blocks until the wanted state happens, then exits 0. </li> +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-u</tt> : up. s6-svlisten1 will wait until the service is up, as +reported by s6-supervise. +This is the default; it is not reliable, but it does not depend on specific +support in the service programs. See <a href="notifywhenup.html">this page</a> +for details. </li> + <li> <tt>-U</tt> : really up. s6-svlisten1 will wait until the service is +up <em>and</em> ready as reported by the daemon itself. This requires +specific support in the daemon program, and the use of +<a href="s6-notifywhenup.html">s6-notifywhenup</a> in the service's run script. +See the explanation on <a href="notifywhenup.html">this page</a>. </li> + <li> <tt>-d</tt> : down. s6-svlisten1 will wait until the service is down. </li> + <li> <tt>-t <em>timeout</em></tt> : if the requested event has not +happened after <em>timeout</em> milliseconds, s6-svlisten1 will print a message +to stderr and exit 1. By default, <em>timeout</em> is 0, which means no time +limit. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-svlisten1 is the service-specific version of +<a href="s6-ftrig-listen1.html">s6-ftrig-listen1</a>. The point of s6-svlisten1 +is to use it to spawn a program such as <a href="s6-svc.html">s6-svc</a>, +in order to send signals to a service while making sure to catch its +state changes - thus avoiding the race condition that occurs when running +<a href="s6-svc.html">s6-svc</a> then <a href="s6-svwait.html">s6-svwait</a> +sequentially. </li> + <li> The <a href="s6-svlisten.html">s6-svlisten</a> program is an extension +of s6-svlisten1. It can watch the state of several services at once; however, +its syntax makes it best used in <a href="http://skarnet.org/software/execline/">execline</a> +scripts only. </li> +</ul> + +</body> +</html> |