s6-notifyoncheck.html (8080B)
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-notifyoncheck program</title> 7 <meta name="Description" content="s6: the s6-notifyoncheck program" /> 8 <meta name="Keywords" content="s6 command s6-notifyoncheck notification service check polling" /> 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 s6-notifyoncheck program </h1> 20 21 <p> 22 <tt>s6-notifyoncheck</tt> is a chain-loading program meant to be used 23 in run scripts, in a service that has been declared to honor 24 readiness notification. It implements a policy of running a user-provided 25 executable in the background that polls the service currently being 26 launched, in order to check when it becomes ready. It feeds the 27 result of this check into the s6 notification mechanism. 28 </p> 29 30 <p> 31 s6-notifyoncheck should <strong>only</strong> be used with daemons 32 that can be polled from the outside to check readiness, and that 33 <strong>do not implement readiness notification themselves</strong>. 34 </p> 35 36 <h2> Interface </h2> 37 38 <pre> 39 s6-notifyoncheck [ -d ] [ -3 <em>notiffd</em> ] [ -s <em>initialsleep</em> ] [ -T <em>globaltimeout</em> ] [ -t <em>localtimeout</em> ] [ -w <em>waitingtime</em> ] [ -n <em>n</em> ] [ -c <em>checkprog</em> ] <em>prog...</em> 40 </pre> 41 42 <p> 43 s6-notifyoncheck forks and runs as the child; the parent immediately execs into 44 <em>prog...</em>, the daemon that must be checked for readiness. 45 </p> 46 47 <p> 48 s6-notifyoncheck first waits for a little time, then it spawns the 49 <tt>./data/check</tt> executable and waits for it to exit. If <tt>./data/check</tt> 50 exits 0, then s6-notifyoncheck reports that the service is ready, then 51 exits. If <tt>./data/check</tt> exits anything else, s6-notifyoncheck sleeps 52 for a little time, then spawns <tt>./data/check</tt> again. It loops until 53 <tt>./data/check</tt> succeeds, or 7 attempts fail, or a certain amount of 54 time elapses. 55 </p> 56 57 <h2> Exit codes </h2> 58 59 <p> 60 s6-notifyoncheck can exit before executing into <em>prog</em>: 61 </p> 62 63 <ul> 64 <li> 100: wrong usage </li> 65 <li> 111: system call failed </li> 66 </ul> 67 68 <p> 69 After forking, s6-notifyoncheck (running as the child) can 70 exit with the following exit codes, but those are meaningless 71 because no process will, or should, check them. They are only 72 differentiated for clarity in the code: 73 </p> 74 75 <ul> 76 <li> 0: service readiness achieved and notification sent </li> 77 <li> 1: maximum number of attempts reached, all unsuccessful </li> 78 <li> 2: <em>prog</em> died, so s6-notifyoncheck exited early </li> 79 <li> 3: timed out before readiness was achieved </li> 80 <li> 111: system call failed </li> 81 </ul> 82 83 <h2> Options </h2> 84 85 <ul> 86 <li> <tt>-d</tt> : doublefork. s6-notifyoncheck will run as the 87 grandchild of <em>prog...</em> instead of its direct child. This is useful 88 if <em>prog...</em> never reaps zombies it does not know it has. </li> 89 <li> <tt>-3 <em>notiffd</em></tt> : use <em>notiffd</em> as the 90 file descriptor to send a readiness notification to. By default, this 91 number is automatically read from the <tt>./notification-fd</tt> file. </li> 92 <li> <tt>-s <em>initialsleep</em></tt> : sleep for 93 <em>initialsleep</em> milliseconds before starting to poll the service 94 for readiness. Default is 10 milliseconds. </li> 95 <li> <tt>-T <em>globaltimeout</em></tt> : give up (and leave 96 the service <em>up</em> but not <em>ready</em>) if service readiness still 97 has not been detected after <em>globaltimeout</em> milliseconds. Default 98 is 0, meaning infinite: s6-notifyoncheck will keep polling until it succeeds. </li> 99 <li> <tt>-t <em>localtimeout</em></tt> : on every attempt, if 100 <tt>./data/check</tt> still has not exited after <em>localtimeout</em> milliseconds, 101 kill it and declare that attempt failed. Default is 0, meaning infinite: 102 s6-notifyoncheck will wait forever for <tt>./data/check</tt> to exit. </li> 103 <li> <tt>-w <em>waitingtime</em></tt> : sleep for 104 <em>waitingtime</em> milliseconds between two invocations of <tt>./data/check</tt>. 105 This is basically the polling period. Default is 1000: the service will 106 be polled every second. </li> 107 <li> <tt>-n <em>n</em></tt> : give up after <em>n</em> 108 unsuccessful invocations of <tt>./data/check</tt>. 0 means infinite, i.e. keep 109 polling until it succeeds, or times out, or the service dies first. 110 Default is 7. </li> 111 <li> <tt>-c <em>checkprog...</em></tt> : invoke <em>checkprog...</em> 112 instead of <tt>./data/check</tt>. The <em>checkprog</em> string will be parsed by 113 <a href="//skarnet.org/software/execline/execlineb.html">execlineb</a>, so it 114 can contain a full command line. This option is mainly useful is the program 115 used to poll the service is very simple and can be inlined as a simple 116 command line, to avoid needing to manage a whole script and a <tt>./data/check</tt> 117 file. This option is only supported if the 118 <a href="//skarnet.org/software/execline/">execline</a> package is installed; 119 if it is not, the <tt>-c</tt> option cannot be used and the checking 120 script must always be placed in <tt>./data/check</tt>. </li> 121 </ul> 122 123 <h2> Usage </h2> 124 125 <p> 126 s6-notifyoncheck is designed to make it possible for services to use the 127 <a href="notifywhenup.html">s6 notification mechanism</a> even with daemons 128 that do not natively implement the mechanism of writing a newline to a file 129 descriptor of their choice when they're ready. 130 </p> 131 132 <p> 133 <a href="//skarnet.org/cgi-bin/archive.cgi?2:mss:1607:dfblejammjllfkggpcph">Polling</a> 134 is evil. Please make sure you really have no other choice before writing a 135 <tt>./data/check</tt> program and using s6-notifyoncheck in your run script. 136 If you have access to the source code of the daemon you want to check for 137 readiness, consider patching it to add readiness notification support, which 138 is extremely simple and does not require linking against any s6 library. 139 </p> 140 141 <p> 142 If using a <tt>./data/check</tt> program is your only option: 143 </p> 144 145 <ul> 146 <li> Make sure the <tt>./data</tt> subdirectory is readable and that 147 <tt>./data/check</tt> is executable, exits 0 if the daemon 148 it checks is ready, and exits nonzero if the daemon is not ready. </li> 149 <li> Add a <tt>./notification-fd</tt> file to your service directory, 150 which can contain any number that is not 0, 1 or 2, or anything else 151 explicitly used in your run script. The daemon does not need to care 152 about that file descriptor; from the daemon's point of view, nothing 153 changes. </li> 154 <li> In your run script, insert <tt>s6-notifyoncheck</tt> in the 155 command line that will execute into your daemon. </li> 156 <li> <tt>./data/check</tt> will run as the same user as s6-notifyoncheck. 157 If s6-notifyoncheck runs after the run script's process has lost its 158 root privileges, make sure that <tt>./data/check</tt> is accessible 159 and runnable as that user. </li> 160 <li> Note that s6-notifyoncheck should be used to check if <em>the 161 current service itself</em> is running. You cannot use it to 162 poll for the readiness of another service. </li> 163 <li> s6-notifyoncheck must be run with the service directory as its 164 current working directory. In other words: you cannot use <tt>cd</tt> 165 in your run script before you execute the command line containing 166 s6-notifyoncheck (else you will get a weird error message saying the 167 supervisor is not running). If your service needs to run in a different 168 working directory, you need to change working directories <em>after</em> 169 the s6-notifyoncheck invocation. The 170 <a href="//skarnet.org/software/execline/cd.html">cd</a> utility from 171 the <a href="//skarnet.org/software/execline/">execline</a> package 172 can be used to change working directories in the middle of a command 173 line (and exec the rest of the command line) without invoking a shell. </li> 174 </ul> 175 176 </body> 177 </html>