faq.html (12586B)
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> 2 <html> 3 <head> 4 <title>runit - Frequently asked questions</title> 5 </head> 6 <body> 7 <a href="http://smarden.org/pape/">G. Pape</a><br> 8 <a href="index.html">runit</a><br> 9 <hr> 10 <h1>runit - Frequently asked questions</h1> 11 <hr> 12 <a href="#what"> 13 What's runit, why is it that different 14 </a><br> 15 <a href="#help"> 16 I need some help with runit, what should I do 17 </a><br> 18 <!-- 19 <a href="#service"> 20 What is a service, what a service daemon 21 </a><br> 22 --> 23 <a href="#license"> 24 What's the license, is runit free software 25 </a><br> 26 <p> 27 <a href="#run"> 28 How do I run a service under runit service supervision 29 </a><br> 30 <a href="#create"> 31 How do I create a new service directory 32 </a><br> 33 <!-- 34 <a href="#log"> 35 What is a log service 36 </a><br> 37 --> 38 <a href="#createlog"> 39 How do I create a new service directory with an appendant log service 40 </a><br> 41 <a href="#tell"> 42 How do I tell runit about a new service 43 </a><br> 44 <a href="#control"> 45 How do I start, stop, or restart a service 46 </a><br> 47 <a href="#signal"> 48 How can I send signals to a service daemon 49 </a><br> 50 <a href="#status"> 51 How can I query the status of a service 52 </a><br> 53 <a href="#remove"> 54 How do I remove a service 55 </a><br> 56 <p> 57 <a href="#depends"> 58 How do I make a service depend on another service 59 </a><br> 60 <!-- 61 <a href="#strongdepends"> 62 How can I make a service affect a dependant service 63 </a><br> 64 --> 65 <p> 66 <a href="#runlevels"> 67 What about runlevels 68 </a><br> 69 <a href="#lsb"> 70 What about LSB init scripts compliance 71 </a><br> 72 <p> 73 <a href="#user"> 74 Is it possible to allow a user other than root to control a service 75 </a><br> 76 <a href="#userservices"> 77 Does runit support user-specific services? 78 </a><br> 79 <a href="#readonlyfs"> 80 Does runit work on a read-only filesystem 81 </a><br> 82 83 <hr> 84 <a name="what"><h3> 85 What's runit, why is it that different 86 </h3></a> 87 What is this runit init scheme about? 88 Why is it that different from sysvinit and other init schemes? 89 <p> 90 Answer: 91 Please see the <a href="index.html">introduction</a>, and web page about 92 runit's <a href="benefits.html">benefits</a>. 93 94 <hr> 95 <a name="help"><h3> 96 I need some help with runit, what should I do 97 </h3></a> 98 I have a question, runit is doing something wrong, or I'm doing something 99 wrong, what should I do? 100 <p> 101 Answer: 102 First see the documentation, especially this list of 103 <a href="faq.html">frequently asked questions</a>, and the man pages 104 if you have a question about a specific runit program. 105 If that still doesn't answer your question, try to search the 106 <a href="http://news.gmane.org/gmane.comp.sysutils.supervision.general"> 107 supervision mailing list archive</a>. 108 Finally, if this fails, feel free to post your question to the 109 <a href="http://skarnet.org/lists/">supervision mailing list</a>. 110 111 <!-- 112 <hr> 113 <a name="service"><h3> 114 What is a service, what a service daemon 115 </h3></a> 116 The runit documentation talks about services and service daemons. 117 What actually is a service, and what a service daemon? 118 <p> 119 Answer: 120 --> 121 122 <hr> 123 <a name="license"><h3> 124 What's the license, is runit free software 125 </h3></a> 126 I would like to distribute runit, in source and binary form. 127 Am I allowed to do so? 128 <p> 129 Answer: 130 runit is free software, it's licensed under a three-clause BSD alike 131 license. 132 See the file <tt>package/COPYING</tt> in the runit tarball. 133 134 <hr> 135 <a name="run"><h3> 136 How do I run a service under runit service supervision 137 </h3></a> 138 I want a service to be run under runit service supervision, so that it's 139 automatically started on system boot, and supervised while system uptime. 140 How does that work? 141 <p> 142 Answer: 143 runit doesn't use the usual <tt>/etc/init.d/</tt> init script interface, 144 but uses a directory per service. 145 To integrate a service into the runit init scheme, 146 <a href="#create">create a service directory</a> for the service, and 147 <a href="#tell">tell runit</a> about it. 148 149 <hr> 150 <a name="create"><h3> 151 How do I create a new service directory 152 </h3></a> 153 How do I create a service directory for the use with runit? 154 <p> 155 Answer: 156 Service directories usually are placed into the <tt>/etc/sv/</tt> 157 directory. 158 Create a new directory for your service in <tt>/etc/sv/</tt>, put a 159 <tt>./run</tt> script into it, and make the script executable. 160 Note that for the use with runit, 161 <a href="#service">service daemons</a> must not put themself into the 162 background, but must run in the foreground. 163 Here's a simple example for a <tt>getty</tt> service: 164 <pre> 165 $ cat /etc/sv/getty-2/run 166 #!/bin/sh 167 exec getty 38400 tty2 linux 168 $ 169 </pre> 170 Note the <tt>exec</tt> in the last line, it tells the shell that 171 interprets the script to replace itself with the service daemon 172 <tt>getty</tt>; this is necessary to make 173 <a href="#control">controlling the service</a> work properly. 174 175 <!-- 176 <hr> 177 <a name="log"><h3> 178 What is a log service 179 </h3></a> 180 Additionally to supervising a service runit can supervise an appendant 181 log service. 182 What does that mean? 183 <p> 184 Answer: 185 --> 186 187 <hr> 188 <a name="createlog"><h3> 189 How do I create a new service directory with an appendant log service 190 </h3></a> 191 How do I create a service directory with an appendant log service for the 192 use with runit? 193 <p> 194 Answer: 195 First <a href="#create">create the service directory</a> for the service. 196 Then create a subdirectory <tt>./log</tt> in the service directory, again 197 put a <tt>./run</tt> script into it, and make the script executable. 198 The <tt>./run</tt> script must run a service logging daemon, normally 199 this is the <a href="svlogd.8.html">svlogd</a> program. 200 See the <a href="runsv.8.html">runsv</a> man page for details. 201 Here's an example of a <tt>./log/run</tt> script: 202 <pre> 203 $ cat /etc/sv/socklog-klog/log/run 204 #!/bin/sh 205 exec chpst -ulog svlogd -tt ./main 206 $ 207 </pre> 208 209 <hr> 210 <a name="tell"><h3> 211 How do I tell runit about a new service 212 </h3></a> 213 I created a service directory for a service that should run under runit 214 service supervision. 215 How do I tell runit about the new service directory, so that it picks 216 up and runs the service by default? 217 <p> 218 Answer: 219 Create a symbolic link in <tt>/service/</tt> pointing to the service 220 directory, runit will pick up the service within the next five seconds, 221 and automatically start it on system boot. 222 E.g.: 223 <pre> 224 # ln -s /etc/sv/getty-2 /service/ 225 </pre> 226 227 <hr> 228 <a name="control"><h3> 229 How do I start, stop, or restart a service 230 </h3></a> 231 I want to stop a service temporarily, and probably restart is later, or 232 I want to have it restarted immediately. 233 How can I control a service running under runit service supervision? 234 <p> 235 Answer: 236 Use the <a href="sv.8.html">sv</a> program. 237 E.g., to restart the <tt>socklog-unix</tt> service, do: 238 <pre> 239 # sv restart socklog-unix 240 </pre> 241 242 <hr> 243 <a name="signal"><h3> 244 How can I send signals to a service daemon 245 </h3></a> 246 I want to send a service daemon the HUP signal, to have it re-read its 247 configuration, or I want to send it the INT signal. 248 How can a send signals to a service daemon? 249 <p> 250 Answer: 251 Use the <a href="sv.8.html">sv</a> program. 252 E.g., to send the <tt>dhcp</tt> service the HUP signal, do: 253 <pre> 254 # sv hup dhcp 255 </pre> 256 257 <hr> 258 <a name="status"><h3> 259 How can I query the status of a service 260 </a></h3> 261 I want to now the status of a service, whether it is up and available, 262 or down as requested, or so. 263 How can I find out this information? 264 <p> 265 Answer: 266 User the <a href="sv.8.html">sv</a> program. 267 E.g., to query or check the status of the <tt>socklog-unix</tt> service, 268 do: 269 <pre> 270 # sv status socklog-unix 271 </pre> 272 or 273 <pre> 274 # sv check socklog-unix 275 </pre> 276 277 <hr> 278 <a name="remove"><h3> 279 How do I remove a service 280 </h3></a> 281 I want to remove a service that currently runs under runit service 282 supervision. 283 How do I tell runit? 284 <p> 285 Answer: 286 Remove the symbolic link in <tt>/service/</tt> pointing to the service 287 directory, runit recognizes the removed service within the next five 288 seconds, then stops the service, the optional log service, and finally the 289 supervisor process. 290 E.g.: 291 <pre> 292 # rm /service/getty-2 293 </pre> 294 295 <hr> 296 <a name="depends"><h3> 297 How do I make a service depend on another service 298 </a></h3> 299 I have a service that needs another service to be available before it can 300 start. 301 How can I tell runit about this dependency? 302 <p> 303 Answer: 304 Make sure in the <tt>./run</tt> script of the dependant service that the 305 service it depends on is available before the service daemon starts. 306 The <a href="sv.8.html">sv</a> program can be used for that. 307 E.g. the <tt>cron</tt> service wants the <tt>socklog-unix</tt> system 308 logging service to be available before starting the <tt>cron</tt> service 309 daemon, so no logs get lost: 310 <pre> 311 $ cat /etc/sv/cron/run 312 #!/bin/sh 313 sv start socklog-unix || exit 1 314 exec cron -f 315 $ 316 </pre> 317 See also the <a href="dependencies.html">documentation</a>. 318 319 <!-- 320 <hr> 321 <a name="strongdepends"><h3> 322 How can I make a service affect a dependant service 323 </a></h3> 324 <a href="#depends">This dependency</a> is not enough. 325 I have a service that needs to be stopped or restarted, whenever a service 326 it depends on stops or restarts. 327 How can I tell runit about that a service affects a dependant service in 328 such a way? 329 <p> 330 Answer: 331 First think about whether you really need this, it almost never should be 332 necessary. 333 If you really need this, 334 --> 335 336 <hr> 337 <a name="runlevels"><h3> 338 What about runlevels 339 </a></h3> 340 Other init schemes support runlevels, what about runit? 341 <p> 342 Answer: 343 runit supports runlevels, even more flexible than traditional init schemes. 344 See <a href="runlevels.html">the documentation</a>. 345 346 <hr> 347 <a name="lsb"><h3> 348 What about LSB init scripts compliance 349 </a></h3> 350 I know about the <a href="sv.8.html">sv</a> program to control a service, 351 but have applications that rely on the <tt>/etc/init.d/</tt> scripts 352 interface as defined through LSB. 353 Do I need to change the application to work with runit? 354 <p> 355 Answer: 356 You don't need to change the application. 357 The <a href="sv.8.html">sv</a> program supports the <tt>/etc/init.d/</tt> 358 script interface 359 <a href="http://refspecs.freestandards.org/LSB_2.1.0/LSB-generic/LSB-generic/iniscrptact.html"> 360 as defined through LSB</a>. 361 To make this script interface work for a service, create a symbolic link 362 in <tt>/etc/init.d/</tt>, named as the service daemon, pointing to the 363 <a href="sv.8.html">sv</a> program, e.g. for the <tt>cron</tt> service: 364 <pre> 365 # ln -s /bin/sv /etc/init.d/cron 366 # /etc/init.d/cron restart 367 ok: run: cron: (pid 5869) 0s 368 # 369 </pre> 370 371 <hr> 372 <a name="user"><h3> 373 Is it possible to allow a user other than root to control a service 374 </a></h3> 375 Using the <a href="sv.8.html">sv</a> program to control a service, or query 376 its status informations, only works as root. 377 Is it possible to allow non-root users to control a service too? 378 <p> 379 Answer: 380 Yes, you simply need to adjust file system permissions for the 381 <tt>./supervise/</tt> subdirectory in the service directory. 382 E.g.: to allow the user <tt>burdon</tt> to control the service 383 <tt>dhcp</tt>, change to the <tt>dhcp</tt> service directory, and do 384 <pre> 385 # chmod 755 ./supervise 386 # chown burdon ./supervise/ok ./supervise/control ./supervise/status 387 </pre> 388 This works similarly with groups, of course. 389 390 <hr> 391 <a name="userservices"><h3> 392 Does runit support user-specific services? 393 </a></h3> 394 It's very nice to simply 395 <a href="#tell">create symbolic links</a> to add system-wide services. 396 Does this work for user-specific services too? 397 <p> 398 Answer: 399 Yes. 400 E.g.: to provide the user <tt>floyd</tt> with facility to manage services 401 through <tt>~/service/</tt>, <a href="#createlog">create a service</a> 402 <tt>runsvdir-floyd</tt> with the following run script and a usual log/run 403 script, and <a href="#tell">tell runit</a> about the service 404 <pre> 405 #!/bin/sh 406 exec 2>&1 407 exec chpst -ufloyd runsvdir /home/floyd/service 408 </pre> 409 Now <tt>floyd</tt> can create services on his own, and manage them through 410 symbolic links in <tt>~/service/</tt> to have them run under his user id. 411 412 <hr> 413 <a name="readonlyfs"><h3> 414 Does runit work on a read-only filesystem 415 </a></h3> 416 On my system <tt>/etc/</tt> is mounted read-only by default. 417 runit uses many files in <tt>/etc/</tt> it needs to write to, like 418 <tt>/etc/runit/stopit</tt>, and the <tt>./supervise/</tt> 419 subdirectories in the service directories. 420 How can I make runit work on my system? 421 <p> 422 Answer: 423 Use symbolic links, runit deals with them well, even with dangling 424 symlinks. 425 E.g., make a ramdisk available at a moint point, say <tt>/var/run/</tt>, 426 and create symbolic links for the files and directories that runit needs 427 to write access to pointing into <tt>/var/run/</tt>: 428 <pre> 429 # ln -s /var/run/runit.stopit /etc/runit/stopit 430 # ln -s /var/run/sv.getty-2 /etc/sv/getty-2/supervise 431 </pre> 432 433 <hr> 434 <address><a href="mailto:pape@smarden.org"> 435 Gerrit Pape <pape@smarden.org> 436 </a></address> 437 </body> 438 </html>