s6-svlink.html (5482B)
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-svlink program</title> 7 <meta name="Description" content="s6: the s6-svlink program" /> 8 <meta name="Keywords" content="s6 command s6-svlink supervision service start scandir servicedir" /> 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-svlink program </h1> 20 21 <p> 22 <tt>s6-svlink</tt> creates, in a <a href="scandir.html">scan 23 directory</a>, a symlink to a <a href="servicedir.html">service 24 directory</a>, and notifies <a href="s6-svscan.html">s6-svscan</a> 25 that a new service has been registered. It waits until a 26 <a href="s6-supervise.html">s6-supervise</a> supervisor process has 27 been spawned to manage the new service, then exits. 28 </p> 29 30 <p> 31 The point of <tt>s6-svlink</tt> is to help integrate 32 service directories into an existing service manager sequence and 33 eliminate race conditions. 34 </p> 35 36 <h2> Interface </h2> 37 38 <pre> 39 s6-svlink [ -d | -D ] [ -P ] [ -f ] [ -t <em>timeout</em> ] <em>scandir</em> <em>servicedir</em> [ <em>name</em> ] 40 </pre> 41 42 <ul> 43 <li> <tt>s6-svlink</tt> expects a running <a href="s6-svscan.html">s6-svscan</a> 44 process on <em>scandir</em> and a fully functional, but unsupervised, 45 <a href="servicedir.html">service directory</a> in <em>servicedir</em>. </li> 46 <li> It symlinks <em>servicedir</em> into <em>scandir</em>. The symbolic link 47 is named <em>name</em>; if no <em>name</em> argument has been given, the name given 48 to the symbolic link is the basename of <em>servicedir</em>. </li> 49 <li> It sends a command to <a href="s6-svscan.html">s6-svscan</a> to signal it 50 that a new service is available. </li> 51 <li> It waits for an <a href="s6-supervise.html">s6-supervise</a> process to be 52 spawned on <em>servicedir</em>. </li> 53 <li> It exits 0. </li> 54 </ul> 55 56 <h2> Exit codes </h2> 57 58 <ul> 59 <li> 0: success </li> 60 <li> 99: timeout while waiting for the supervisor to start </li> 61 <li> 100: wrong usage </li> 62 <li> 111: system call failed </li> 63 </ul> 64 65 <h2> Options </h2> 66 67 <ul> 68 <li> <tt>-d</tt> : down. The supervisor will be started, but the service 69 itself will remain down. Any <em>servicedir</em><tt>/down</tt> file will be 70 deleted. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have 71 been given, the supervisor auto-starts the service as soon as it runs. </li> 72 <li> <tt>-D</tt> : down, and stay down. The supervisor will be started, 73 but the service itself will remain down. A <em>servicedir</em><tt>/down</tt> file 74 will be created. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have 75 been given, the supervisor auto-starts the service as soon as it runs. </li> 76 <li> <tt>-P</tt> : public. If <em>servicedir</em><tt>/event</tt> does not 77 exist, it will be created as public, i.e. anyone will be able to subscribe to 78 this <a href="fifodir.html">fifodir</a>. By default, it will be created as private, 79 i.e. only processes running with the same gid as the <a href="s6-svscan.html">s6-svscan</a> 80 process will be able to susbscribe to it. </li> 81 <li> <tt>-f</tt> : force permissions. The presence or absence of the <tt>-P</tt> 82 option (i.e. the public or private state of <em>servicedir</em><tt>/event</tt>) will be 83 enforced even if <em>servicedir</em><tt>/event</tt> already exists. By default, 84 <tt>s6-svlink</tt> exits with an error message if <em>servicedir</em><tt>/event</tt> 85 exists and its public/private state mismatches what is requested. </li> 86 <li> <tt>-t <em>timeout</em></tt> : if the supervisor has not started 87 after <em>timeout</em> milliseconds, <tt>s6-svlink</tt> will print a message 88 to stderr and exit 99. By default, <em>timeout</em> is 0, which means no time 89 limit. </li> 90 </ul> 91 92 <h2> Notes </h2> 93 94 <ul> 95 <li> Using <tt>s6-svlink</tt> to start services is a suboptimal pattern: it 96 requires precise manipulations involving use of <a href="libs6/s6-ftrigrd.html">s6-ftrigrd</a> 97 in order to avoid race conditions, so it is relatively expensive. The simpler, 98 more efficient pattern is to have all the supervisors already started at boot 99 time, so the existence of the supervisor can be relied on, and starting the 100 service becomes a trival and instant operation - this is, for instance, how 101 the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager behaves. 102 However, it can be difficult to implement this pattern with other services 103 managers such as OpenRC; in those cases, <tt>s6-svlink</tt>, which starts the 104 supervisors one at a time, can be used instead. </li> 105 <li> If <em>servicedir</em> is logged, i.e. <em>servicedir</em><tt>/log</tt> 106 is also a valid service directory, then <tt>s6-svlink</tt> will wait until 107 supervisors have been spawned for both the service and its logger. </li> 108 <li> <tt>s6-svlink</tt> sends an <a href="s6-svscanctl.html">s6-svscanctl -a</a> 109 command to <em>scandir</em>, which means that the system's view of services 110 will be refreshed. Depending on what links exist in <em>scandir</em>, other 111 services than <em>servicedir</em> may also appear. </li> 112 <li> The symmetrical program to <tt>s6-svlink</tt> is named 113 <a href="s6-svunlink.html">s6-svunlink</a>. </li> 114 </ul> 115 116 </body> 117 </html>