s6-instance-create.html (4515B)
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-instance-create program</title> 7 <meta name="Description" content="s6: the s6-instance-create program" /> 8 <meta name="Keywords" content="s6 command s6-instance-create instance dynamic instantiation instanced services creation s6-svlink" /> 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-instance-create program </h1> 20 21 <p> 22 s6-instance-create creates a new instance of a currently supervised 23 <a href="instances.html">instanced service</a>. 24 </p> 25 26 <h2> Interface </h2> 27 28 <pre> 29 s6-instance-create [ -d | -D ] [ -P ] [ -f ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>name</em> 30 </pre> 31 32 <ul> 33 <li> s6-instance-create expects a running, supervised 34 <a href="instances.html">instanced service</a> in <em>servicedir</em>. 35 This service typically has been created by linking the result of an 36 <a href="s6-instance-maker.html">s6-instance-maker</a> invocation into 37 an existing <a href="scandir.html">scan directory</a>. </li> 38 <li> s6-instance-create creates a new instance of that service, named 39 <em>name</em>. Depending on the given options, it may start it 40 immediately, or keep it down until a later 41 <a href="s6-instance-control.html">s6-instance-control</a> invocation. </li> 42 <li> It waits for the new instance to be ready to take commands from 43 <a href="s6-instance-control.html">s6-instance-control</a>. </li> 44 <li> It exits 0. </li> 45 </ul> 46 47 <h2> Exit codes </h2> 48 49 <ul> 50 <li> 0: success </li> 51 <li> 99: timeout while waiting for the instance supervisor to start </li> 52 <li> 100: wrong usage </li> 53 <li> 111: system call failed </li> 54 </ul> 55 56 <h2> Options </h2> 57 58 <ul> 59 <li> <tt>-d</tt> : down. The instance supervisor will be started, but the instance 60 itself will remain down. Any <tt>down</tt> file for the instance will be 61 deleted. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have 62 been given, the supervisor auto-starts the instance as soon as it runs. </li> 63 <li> <tt>-D</tt> : down, and stay down. The instance supervisor will be started, 64 but the instance itself will remain down. A <tt>down</tt> file 65 will be created for the instance. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have 66 been given, the supervisor auto-starts the instance as soon as it runs. </li> 67 <li> <tt>-P</tt> : public. Everyone will be able to subscribe to the 68 instance supervisor's notification. By default, only processes running with the same gid 69 as the instanced service can subscribe to it. </li> 70 <li> <tt>-f</tt> : force permissions. You should never need to use this 71 option, it is only there for testing purposes. </li> 72 <li> <tt>-t <em>timeout</em></tt> : if the instance supervisor has not started 73 after <em>timeout</em> milliseconds, s6-instance-create will print a message 74 to stderr and exit 99. By default, <em>timeout</em> is 0, which means no time 75 limit. </li> 76 </ul> 77 78 <h2> Notes </h2> 79 80 <ul> 81 <li> s6-instance-create is similar to 82 <a href="s6-svlink.html">s6-svlink</a>, because it uses the same underlying 83 library functions. Under the hood, an instance is a regular service running 84 on a supervision tree that is specific to the instanced service, and 85 s6-instance-create adds a service directory to that tree and ensures it gets 86 supervised. </li> 87 <li> If the template for the service is logged, then s6-instance-create will 88 wait until supervisors have been spawned for both the instance and its logger. </li> 89 <li> s6-instance-create and <a href="s6-instance-delete.html">s6-instance-delete</a> 90 are relatively expensive operations, because they have to recursively copy or 91 delete directories and use the <a href="libs6/ftrigr.html">synchronization mechanism</a> 92 with the instance supervisor, compared to 93 <a href="s6-instance-control.html">s6-instance-control</a> which only has to send 94 commands to already existing supervisors. If you are going to turn instances on and 95 off on a regular basis, it is more efficient to keep the instance existing and control 96 it with <a href="s6-instance-control.html">s6-instance-control</a> than it is to 97 repeatedly create and delete it. </li> 98 </ul> 99 100 </body> 101 </html>