commit 4fdb2d742d33da8ba3768a883f5e32b83464c915
parent 99a142b93bfc0b2e4f801225504d6075a3ac975b
Author: Gerrit Pape <pape@smarden.org>
Date: Fri, 30 Jan 2004 19:12:57 +0000
some doc cleanup.
Diffstat:
7 files changed, 228 insertions(+), 201 deletions(-)
diff --git a/doc/benefits.html b/doc/benefits.html
@@ -16,24 +16,24 @@
<a href="#portability">Portability</a><br>
<a href="#packaging">Packaging friendly</a><br>
<a href="#smallcode">Small code size</a>
-
<hr>
-<i>runit</i>'s service concept is heavily based on the
+<i>runit</i>'s service supervision concept is heavily based on the
<a href="http://cr.yp.to/daemontools.html">daemontools</a>' one, and mostly
-compatible with it. The benefits described in the
-<a href="http://cr.yp.to/daemontools/faq/create.html#why">daemontools faq</a>
-also apply to <i>runit</i>'s service supervision.
+compatible with it.
+The benefits described in the
+<a href="http://cr.yp.to/daemontools/faq/create.html#why">
+daemontools faq</a> also apply to <i>runit</i>'s service supervision.
Many of the benefits described here also apply to the
<a href="http://cr.yp.to/daemontools.html">daemontools</a> package.
Some are described in both places.
-
<hr>
<a name="supervision"><h3>Service supervision</h3></a>
Each service is associated with a <i>service directory</i>, and each
service daemon runs as a child process of a supervising
<a href="runsv.8.html">runsv</a> process running in this directory.
The <a href="runsv.8.html">runsv</a> program provides a reliable interface
-for signalling the service daemon and controlling the service and supervisor.
+for signalling the service daemon and controlling the service and
+supervisor.
Normally the <a href="runsvctrl.8.html">runsvctrl</a> program is used to
send commands through this interface.
The <a href="runsvstat.8.html">runsvstat</a> program can be used to print
@@ -46,15 +46,16 @@ dies, it will be restarted.
Of course you can <a href="runsvctrl.8.html">tell runsv</a> otherwise.
<p>
You don't have such a control interface with <i>sysv init</i> for example.
-Using the control interface to send signals to the service daemon saves a lot
-of extra (non trivial) work to reliably find out the daemon's process id.
-Also <i>sysv init</i> only supports 'respawning' of services started from
-<tt>inittab</tt>.
-
+Using the control interface to send signals to the service daemon saves a
+lot of extra (non trivial) work to reliably find out the daemon's process
+id.
+Also <i>sysv init</i> only supports "respawning" of services
+started from <tt>inittab</tt>.
<hr>
<a name="state"><h3>Clean process state</h3></a>
<i>runit</i> guarantees each service a clean process state, no matter if the
-service is activated for the first time, reactivated, or simply restarted.
+service is activated for the first time or automatically at boot time,
+reactivated, or simply restarted.
This means that the service always is started with the same environment,
resource limits, open file descriptors, and controlling terminals.
<p>
@@ -79,8 +80,8 @@ After rebooting the system this shows up on the screen:
failed.
...
</pre>
-The <tt>food</tt> program is installed in <tt>/opt/foo/bin/</tt>. When
-starting the service for the first time using the init script, the
+The <tt>food</tt> program is installed in <tt>/opt/foo/bin/</tt>.
+When starting the service for the first time using the init script, the
<tt>PATH</tt> environment variable contained <tt>/opt/foo/bin</tt>.
After reboot <tt>init</tt> started the service using the init script, but
with a different value for the <tt>PATH</tt> variable, not containing
@@ -94,7 +95,6 @@ With bad init scripts miraculous things could also happen when just doing
# /etc/init.d/foo-daemon restart
</pre>
at the command line.
-
<hr>
<a name="log"><h3>Reliable logging facility</h3></a>
The <a href="runsv.8.html">runsv</a> program provides a reliable logging
@@ -103,7 +103,8 @@ If configured, <a href="runsv.8.html">runsv</a> creates a pipe, starts and
supervises an additional log service, redirects the log daemon's standard
input to read from the pipe, and redirects the service daemon's standard
output to write to the pipe.
-Restarting the service does not require restarting the log service.
+Restarting the service does not require restarting the log service, and vice
+versa.
A good choice for a log daemon is <i>runit</i>'s service logging daemon
<a href="svlogd.8.html">svlogd</a>, or
<a href="http://cr.yp.to/daemontools/multilog.html">multilog</a> from the
@@ -117,7 +118,6 @@ chroot'ed.
If <a href="runsv.8.html">runsv</a> is told to shutdown a service, e.g. at
system shutdown, it ensures that the log service stays up as long as the
corresponding service daemon is running and possibly writing to the log.
-
<hr>
<a name="fast"><h3>Fast system boot up and shutdown</h3></a>
After the system's one time tasks (stage 1) are done, the system services
@@ -129,8 +129,7 @@ On system shutdown, stage 3 uses <a href="runsv.8.html">runsv</a>'s control
interface to wait until each service daemon is terminated and all logs are
written.
Again, services are taken down in parallel.
-As soon as all services are done, system halt or system reboot is initiated.
-
+As soon as all services are down, system halt or system reboot is initiated.
<hr>
<a name="portability"><h3>Portability</h3></a>
<i>runit</i> comes ready-to-run for Debian GNU/Linux and BSD systems, and
@@ -148,13 +147,12 @@ system's uptime.
<i>runit</i>'s stage 2 is portable across UNIX systems.
<i>runit</i> is well suited for server systems and embedded systems, and
also does its job well on desktop systems.
-
<hr>
<a name="packaging"><h3>Packaging friendly</h3></a>
<i>runit</i>'s stages 1 and 3 are distribution specific.
-They are shell scripts, and an operating system distribution with software
-package management should adapt these scripts if they need support for their
-package management.
+They normally are shell scripts, and an operating system distribution with
+software package management should adapt these scripts if they need support
+for their package management.
The
<a href="http://packages.debian.org/unstable/admin/runit-run.html">
runit-run</a>
@@ -166,26 +164,27 @@ sysvinit</a>.
<p>
Stage 2 already is packaging friendly:
all a software package that provides a service needs to do is to include
-a <i>service directory</i> in the package and to provide a symbolic link
+a <i>service directory</i> in the package, and to provide a symbolic link
to this directory in <tt>/var/service/</tt>.
-The service will be started within five seconds.
+The service will be started within five seconds, and automatically at boot
+time.
The package's install and update scripts can use the reliable control
interface to stop, start, restart, or send signals to the service.
On package removal, the symbolic link simply is removed.
+The service will be taken down automatically.
<hr>
<a name="smallcode"><h3>Small code size</h3></a>
One of the <i>runit</i> project's principles is to keep the code size
-small. As of version 0.8.0 of <i>runit</i>, the <tt>runit.c</tt>
-source contains only about 300 lines of code; the <tt>runsvdir.c</tt>
-source is also about 300 lines of code, the <tt>runsv.c</tt> source about
-500.
+small.
+As of version 0.13.1 of <i>runit</i>, the <tt>runit.c</tt> source contains
+330 lines of code; the <tt>runsvdir.c</tt> source is 274 lines of code, the
+<tt>runsv.c</tt> source 509.
This minimizes the possibility of bugs introduced by programmer's fault,
and makes it more easy for security related people to proofread the source
code.
<p>
-The <i>runit</i> programs have a very small memory footprint and do not
+The <i>runit</i> core programs have a very small memory footprint and do not
allocate memory dynamically.
-
<hr>
<address><a href="mailto:pape@smarden.org">
Gerrit Pape <pape@smarden.org>
diff --git a/doc/dependencies.html b/doc/dependencies.html
@@ -10,15 +10,15 @@
<h1>runit - service dependencies</h1>
<hr>
<i>runit</i>'s service supervision resolves dependencies for service daemons
-designed to be run by an supervisor process automatically.
-The service daemon (or the corresponding <tt>run</tt> and <tt>finish</tt>
-scripts) should behave as follows:
+designed to be run by a supervisor process automatically.
+The service daemon (or the corresponding <tt>run</tt> scripts) should behave
+as follows:
<ul>
<li>before providing the service, check if all services it depends on are
available.
If not, exit with an error, the supervisor will then try again.
<li>write all logs through <i>runit</i>'s logging facility.
- The <a href="runsv.8.html">runsv</a> program takes care that all logs of
+ The <a href="runsv.8.html">runsv</a> program takes care that all logs for
the service are written safely to disk.
Therefore there's no need to depend on a system logging service.
<li>optionally when the service is told to become down, take down other
diff --git a/doc/index.html b/doc/index.html
@@ -43,14 +43,15 @@ replacement for
<a href="ftp://ftp.cistron.nl/pub/people/miquels/sysvinit/">sysvinit</a>
and other init schemes. <i>runit</i> runs on <b>GNU/Linux</b>,
<b>OpenBSD</b>, <b>FreeBSD</b>, <b>MacOSX</b>, <b>Solaris</b>, and can
-easily be adapted to other unix operating systems.
-If <i>runit</i> runs for you on any other operating system, please let me
-know.
+easily be adapted to other Unix operating systems.
+If <i>runit</i> runs for you on any other operating system, please
+<a href="mailto:supervision@list.skarnet.org">let me know</a>.
<p>
<b>Warning:</b> Replacing <i>sysvinit</i> or <i>init</i> can cause the
-system's boot to fail. Make sure you are able to recover and repair your
-system, for example if you run a boot loader, it should be able to pass
-<tt>init=/bin/sh</tt> to the kernel.
+system's boot to fail.
+Make sure you are able to recover and repair your system, for example if you
+run a boot loader, it should be able to pass <tt>init=/bin/sh</tt> to the
+kernel.
<hr>
<i>runit</i> is discussed on the
<a href="http://skarnet.org/lists/#supervision">
@@ -58,8 +59,13 @@ system, for example if you run a boot loader, it should be able to pass
mailing list. To subscribe send an empty email to
<a href="mailto:supervision-subscribe@list.skarnet.org">
<supervision-subscribe@list.skarnet.org></a>.
+<p>
+Mailing list archives are available at
+<a href="http://skarnet.org/lists/archive.cgi?2">skarnet.org</a>, and
+<a href="http://news.gmane.org/gmane.comp.sysutils.supervision.general">
+gmane.org</a>.
<hr>
-The command <a href="runit.8.html">runit</a> is intended to run as Unix
+The program <a href="runit.8.html">runit</a> is intended to run as Unix
process no 1, it is automatically started by the
<a href="runit-init.8.html">runit-init</a> <tt>/sbin/init</tt>-replacement
if this is started by the kernel.
@@ -69,46 +75,49 @@ if this is started by the kernel.
<ul>
<li><b>Stage 1:</b><br>
<i>runit</i> starts <tt>/etc/runit/1</tt> and waits for it to
- terminate. The system's one time initialization tasks are done here.
- <tt>/etc/runit/1</tt> has full control of <tt>/dev/console</tt> to be
+ terminate.
+ The system's one time initialization tasks are done here.
+ <tt>/etc/runit/1</tt> has full control over <tt>/dev/console</tt> to be
able to start an emergency shell if the one time initialization tasks
fail.
<li><b>Stage 2:</b><br>
<i>runit</i> starts <tt>/etc/runit/2</tt> which should not return
- until the system is going to halt or reboot, if it crashes, it will be
- restarted. Normally, <tt>/etc/runit/2</tt> runs
+ until the system is going to halt or reboot; if it crashes, it will be
+ restarted.
+ Normally, <tt>/etc/runit/2</tt> runs
<a href="runsvdir.8.html">runsvdir</a>.
- In Stage 2 <i>runit</i> optionally handles an INT signal
- (ctrl-alt-del keyboard request on Linux/i386).
+ In Stage 2 <i>runit</i> optionally handles an INT signal (ctrl-alt-del
+ keyboard request on Linux/i386).
<li><b>Stage 3:</b><br>
If <i>runit</i> is told to halt or reboot the system, or the Stage 2
returns without errors, it terminates Stage 2 if it is running and runs
- <tt>/etc/runit/3</tt>. The systems tasks to shutdown and halt or
- reboot are done here.
+ <tt>/etc/runit/3</tt>.
+ The systems tasks to shutdown and halt or reboot are done here.
</ul>
These are working examples for Debian woody:
<a href="debian/1">/etc/runit/1</a>,
<a href="debian/2">/etc/runit/2</a>,
<a href="debian/3">/etc/runit/3</a>.
<p>
-The command <a href="runit-init.8.html">runit-init</a> is intended to
-replace <tt>/sbin/init</tt>. sysvinit's command <tt>shutdown</tt> will
-keep working. On *BSD systems use <b><tt>init 0</tt></b> for system halt
-and <b><tt>init 6</tt></b> for reboot.
+The program <a href="runit-init.8.html">runit-init</a> is intended to
+replace <tt>/sbin/init</tt>.
+sysvinit's command <tt>shutdown</tt> will keep working.
+On *BSD systems use <b><tt>init 0</tt></b> for system halt and
+<b><tt>init 6</tt></b> for reboot.
<a href="runlevels.html">Runlevels</a> are handled through the
<a href="runsvdir.8.html">runsvdir</a> and
<a href="runsvchdir.8.html">runsvchdir</a> programs.
Service <a href="dependencies.html">dependencies</a> are resolved
automatically.
<p>
-<i>runit</i> is optimized for reliability and small size. The amount of
-code in process no 1 should be minimal.
+<i>runit</i> is optimized for reliability and small size.
+The amount of code in process no 1 should be minimal.
<hr>
-<b><i>runit</i> in use</b>: I replaced <i>sysvinit</i> with <i>runit</i>
-on several server systems and a laptop running Debian/GNU Linux sarge, woody
-and potato, and did not encounter any problems. Of course also the
-<tt>smarden.org</tt> content server is running with <i>runit</i> as process
-no 1, here is an example:
+<b><i>runit</i> in use</b>:
+I replaced <i>sysvinit</i> successfully with <i>runit</i> on several server
+systems and a laptop running Debian/GNU Linux sarge, woody, and potato.
+Of course also the <tt>smarden.org</tt> content server is running with
+<i>runit</i> as process no 1, here is an example:
<pre>
# strings /proc/1/exe |grep Id
$Id: runit.c,v 1.7 2002/02/13 09:59:52 pape Exp $
@@ -174,13 +183,13 @@ no 1, here is an example:
</pre>
<hr>
See <a href="install.html">How to install runit</a> for installing
-<i>runit</i> and <a href="replaceinit.html">How to replace init</a> for
-smoothly escaping from <i>sysvinit</i>.
+<i>runit</i>, and <a href="replaceinit.html">How to replace init</a> for
+configuring <i>runit</i> to run as process no 1.
<hr>
-If <i>runit</i> on linux is compiled and linked with
-<a href="http://www.fefe.de/dietlibc/">dietlibc</a> it yields in a statically
-linked <tt>runit</tt> binary of 8.5k size and this <tt>ps axuw</tt> output
-on my system:
+If <i>runit</i> on Linux is compiled and linked with the
+<a href="http://www.fefe.de/dietlibc/">dietlibc</a>, it yields in a
+statically linked <tt>runit</tt> binary of 8.5k size and this
+<tt>ps axuw</tt> output on my system:
<pre>
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.0 20 16 ? S 2002 0:02 runit
@@ -193,20 +202,26 @@ for recent informations.
<hr>
Related links:
<ul>
- <li><a href="http://packages.debian.org/runit">
- runit Debian package</a>
- <li><a href="http://www.fefe.de/minit/">
- minit</a>
- <li><a href="http://multivac.cwru.edu/svscan-1/">
- svscan as process 1</a>
- <li><a href="ftp://ftp.cistron.nl/pub/people/miquels/sysvinit/">
- sysvinit</a>
- <li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sbin/init/">
- OpenBSD's init</a>
- <li><a href="http://www.freebsd.org/cgi/cvsweb.cgi/src/sbin/init/">
- FreeBSD's init</a>
- <li><a href="http://www.atnf.csiro.au/~rgooch/linux/boot-scripts/">
- Richard Gooch's Linux Boot Scripts</a>
+<li><a href="http://packages.debian.org/runit">
+runit Debian package</a>
+<li><a href="http://packages.debian.org/runit-run">
+runit-run Debian package</a>
+<li><a href="http://www.freshports.org/sysutils/runit/">
+runit FreeBSD port</a>
+<li><a href="http://rpmfind.net/linux/rpm2html/search.php?query=runit">
+runit RPMs</a>
+<li><a href="http://www.fefe.de/minit/">
+minit</a> - a small yet feature-complete init
+<li><a href="http://multivac.cwru.edu/svscan-1/">
+svscan as process 1</a> - by Paul Jarc
+<li><a href="ftp://ftp.cistron.nl/pub/people/miquels/sysvinit/">
+sysvinit</a> - source code
+<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sbin/init/">
+OpenBSD's init</a> - CVS repository
+<li><a href="http://www.freebsd.org/cgi/cvsweb.cgi/src/sbin/init/">
+FreeBSD's init</a> - CVS repository
+<li><a href="http://www.atnf.csiro.au/~rgooch/linux/boot-scripts/">
+Linux Boot Scripts</a> - from Richard Gooch
</ul>
<hr>
<address><a href="mailto:pape@smarden.org">
diff --git a/doc/replaceinit.html b/doc/replaceinit.html
@@ -26,51 +26,51 @@ If you have installed the precompiled Debian package, start at step 3.
<i>booting</i>, <i>running</i> and <i>shutdown</i> in <tt>/etc/runit/1</tt>,
<tt>/etc/runit/2</tt> and <tt>/etc/runit/3</tt>, create the files now:
<pre>
- # mkdir -p /etc/runit
- # cp -p /package/admin/runit/etc/debian/[123] /etc/runit/
+ # mkdir -p /etc/runit
+ # cp -p /package/admin/runit/etc/debian/[123] /etc/runit/
</pre>
Create also a getty service directory:
<pre>
- # mkdir -p /etc/runit/getty-5
- # cp -p /package/admin/runit/etc/debian/getty-tty5/run /etc/runit/getty-5/
- # cp -p /package/admin/runit/etc/debian/getty-tty5/finish /etc/runit/getty-5/
+ # mkdir -p /etc/runit/getty-5
+ # cp -p /package/admin/runit/etc/debian/getty-tty5/run /etc/runit/getty-5/
+ # cp -p /package/admin/runit/etc/debian/getty-tty5/finish /etc/runit/getty-5/
</pre>
If you want <i>runit</i> to handle the ctrl-alt-del keyboard request, do:
<pre>
- # cp -p /package/admin/runit/etc/debian/ctrlaltdel /etc/runit/
+ # cp -p /package/admin/runit/etc/debian/ctrlaltdel /etc/runit/
</pre>
<h3>Step 2: The runit programs</h3>
The <i>runit</i> programs must reside on the root partition, copy them to
<tt>/sbin</tt>:
<pre>
- # cp -p /package/admin/runit/command/runit* /sbin/
+ # cp -p /package/admin/runit/command/runit* /sbin/
</pre>
<h3>Step 3: The getties</h3>
-At least one getty must run in stage 2 so you are able to login, choose a
-free <tt>tty</tt>, say <tt>tty5</tt>, where <i>sysvinit</i> is not running
-any getty (edit <tt>/etc/inittab</tt> and <tt>kill -HUP 1</tt> if
-needed) and tell <a href="runsvdir.8.html">runsvdir</a> about the getty-5
+At least one getty must run in stage 2 so that you are able to login.
+Choose a free <tt>tty</tt>, say <tt>tty5</tt>, where <i>sysvinit</i> is not
+running any getty (edit <tt>/etc/inittab</tt> and <tt>kill -HUP 1</tt> if
+needed), and tell <a href="runsvdir.8.html">runsvdir</a> about the getty-5
<i>service</i>:
<pre>
- # mkdir -p /var/service
- # ln -s /etc/runit/getty-5 /var/service/
+ # mkdir -p /var/service
+ # ln -s /etc/runit/getty-5 /var/service/
</pre>
Start <i>runit</i>'s stage 2 for testing:
<pre>
- # /etc/runit/2 &
+ # /etc/runit/2 &
</pre>
-And check if the getty is running.
+And check that the getty is running.
<h3>Step 4: Reboot into runit for testing</h3>
-Boot your system with <i>runit</i> for the first time. This does not change
-the default boot behavior of your system, <i>lilo</i> will be told to use
-<i>runit</i> just once:
+Boot your system with <i>runit</i> for the first time.
+This does not change the default boot behavior of your system, <i>lilo</i>
+will be told to use <i>runit</i> just once:
<ul>
- <li>reboot the system
- <li>enter the following on the lilo prompt:<br>
- <tt>init=/sbin/runit-init</tt>
- <li>watch the console output while <i>runit</i> boots up the system
- <li>switch to <tt>tty5</tt> when stage 2 is reached, a <tt>getty</tt>
- should run there, you are able to login.
+<li>reboot the system
+<li>enter the following on the lilo prompt:<br>
+<tt>init=/sbin/runit-init</tt>
+<li>watch the console output while <i>runit</i> boots up the system
+<li>switch to <tt>tty5</tt> when stage 2 is reached, a <tt>getty</tt>
+should run there, you are able to login.
</ul>
If you are not using <i>lilo</i> as boot loader, refer to the documentation
of your boot loader on how to pass <tt>init=/sbin/runit-init</tt> to the
@@ -79,62 +79,66 @@ kernel.
The goal is to migrate all services from <i>sysvinit</i> scheme to the
<a href="http://cr.yp.to/daemontools.html">daemontools</a> design; take a
look at these <a href="runscripts.html">run scripts</a> for popular
-services. The migration can be done smoothly. For those services that are
-not migrated to use <tt>run</tt> scripts yet, add the corresponding
-<tt>init</tt>-script startup to <tt>/etc/runit/1</tt>, e.g.:
-<pre>
- #!/bin/sh
- # one time tasks
+services.
+The migration can be done smoothly.
+For those services that are not migrated to use <tt>run</tt> scripts yet,
+add the corresponding <tt>init</tt>-script startup to <tt>/etc/runit/1</tt>,
+e.g.:
+<pre>
+ #!/bin/sh
+ # one time tasks
- /etc/init.d/kerneld start
- /etc/init.d/rmnologin
+ /etc/init.d/kerneld start
+ /etc/init.d/rmnologin
- touch /etc/runit/stopit
- chmod 0 /etc/runit/stopit
+ touch /etc/runit/stopit
+ chmod 0 /etc/runit/stopit
</pre>
It is possible to just add <tt>/etc/init.d/rc 2</tt> for having all services
from the former runlevel 2 started as one time tasks, but keep the goal above
in mind, supervising services has great advantages.
<p>
Repeat step 4 and 5, using <tt><b>/sbin/runit-init 6</b></tt> to reboot the
-system, until you are satisfied with your services startup. If anything goes
-wrong, reboot the system into the default <i>sysvinit</i> <tt>/sbin/init</tt>
-and repair the <i>runit</i> stages, then start again at step 4.
+system, until you are satisfied with your services startup.
+If anything goes wrong, reboot the system into the default <i>sysvinit</i>
+<tt>/sbin/init</tt> and repair the <i>runit</i> stages, then start again at
+step 4.
<h3>Step 6: Replace /sbin/init</h3>
Now it is time to replace the <i>sysvinit</i> <tt>/sbin/init</tt> binary:
<pre>
- # mv /sbin/init /sbin/init.sysv
- # ln -s runit-init /sbin/init
+ # mv /sbin/init /sbin/init.sysv
+ # ln -s runit-init /sbin/init
</pre>
<h3>Step 7: Final reboot</h3>
The last step is to do the final reboot to boot the system with the new
default Unix process no 1 <i>runit</i>.
<pre>
- # shutdown -r now
+ # shutdown -r now
</pre>
To report success:
<pre>
- # ( uname -a ; cat /etc/runit/[123] ) | mail pape-runit-0.13.1@smarden.org
+ # ( uname -a ; cat /etc/runit/[123] ) |mail pape-runit-0.13.1@smarden.org
</pre>
<hr>
<a name="bsd"><h2>Replacing init (*BSD)</h2></a>
Follow these steps to migrate from <i>init</i> to <i>runit</i> on
<a href="http://www.openbsd.org/">OpenBSD 2.9</a> or
-<a href="http://www.freebsd.org/">FreeBSD 4.4</a>. The
-<tt>/sbin/init</tt> binary is not replaced until step 4.
+<a href="http://www.freebsd.org/">FreeBSD 4.4</a>.
+The <tt>/sbin/init</tt> binary is not replaced until step 4.
<h3>Step 1: The three stages</h3>
<i>runit</i> looks for the three stages implementing the system's
<i>booting</i>, <i>running</i> and <i>shutdown</i> in <tt>/etc/runit/1</tt>,
-<tt>/etc/runit/2</tt> and <tt>/etc/runit/3</tt>, create the files now:
+<tt>/etc/runit/2</tt> and <tt>/etc/runit/3</tt> respectively.
+Create the scripts now:
<pre>
- # mkdir -p /etc/runit
+ # mkdir -p /etc/runit
OpenBSD 2.9:
- # cp -p /package/admin/runit/etc/openbsd/[123] /etc/runit/
+ # cp -p /package/admin/runit/etc/openbsd/[123] /etc/runit/
FreeBSD 4.4:
- # cp -p /package/admin/runit/etc/freebsd/[123] /etc/runit/
+ # cp -p /package/admin/runit/etc/freebsd/[123] /etc/runit/
</pre>
Remove the <tt>svscanboot</tt> startup from <tt>/etc/rc.local</tt> by
deleting the line <tt>csh -cf '/command/svscanboot &'</tt> (this normally
@@ -142,39 +146,40 @@ is the last one); <i>runit</i> will start
<a href="runsvdir.8.html">runsvdir</a> in stage 2 after running
<tt>rc.local</tt> in stage 1.
<pre>
- # vi /etc/rc.local
+ # vi /etc/rc.local
</pre>
<h3>Step 2: The runit programs</h3>
The <i>runit</i> programs must reside on the root partition, install them
into <tt>/sbin</tt>:
<pre>
- # install -m0500 /package/admin/runit/command/runit* /sbin/
+ # install -m0500 /package/admin/runit/command/runit* /sbin/
</pre>
<h3>Step 3: The getties</h3>
-At least one getty must run in stage 2 so you are able to login. To have it
-run on the virtual console no 5, create the getty-5 service directory:
+At least one getty must run in stage 2 so that you are able to login.
+To have it run on the virtual console no 5, create the getty-5 service
+directory:
<pre>
- # mkdir -p /etc/runit/getty-5
+ # mkdir -p /etc/runit/getty-5
OpenBSD 2.9:
- # cp -p /package/admin/runit/etc/openbsd/getty-ttyC4/run /etc/runit/getty-5/
- # cp -p /package/admin/runit/etc/openbsd/getty-ttyC4/finish /etc/runit/getty-5/
+ # cp -p /package/admin/runit/etc/openbsd/getty-ttyC4/run /etc/runit/getty-5/
+ # cp -p /package/admin/runit/etc/openbsd/getty-ttyC4/finish /etc/runit/getty-5/
FreeBSD 4.4:
- # cp -p /package/admin/runit/etc/freebsd/getty-ttyv4/run /etc/runit/getty-5/
- # cp -p /package/admin/runit/etc/freebsd/getty-ttyv4/finish /etc/runit/getty-5/
+ # cp -p /package/admin/runit/etc/freebsd/getty-ttyv4/run /etc/runit/getty-5/
+ # cp -p /package/admin/runit/etc/freebsd/getty-ttyv4/finish /etc/runit/getty-5/
</pre>
and tell <a href="runsvdir.8.html">runsvdir</a> about the <tt>getty-5</tt>
<i>service</i>:
<pre>
- # mkdir -p /var/service
- # ln -s /etc/runit/getty-5 /var/service/
+ # mkdir -p /var/service
+ # ln -s /etc/runit/getty-5 /var/service/
</pre>
Start <i>runit</i>'s stage 2 for testing:
<pre>
- # /etc/runit/2 &
+ # /etc/runit/2 &
</pre>
-And check if the getty is running.
+And check that the getty is running.
<h3>Step 4: Replace the <tt>/sbin/init</tt> binary</h3>
Before replacing the <tt>init</tt> binary, make sure that you are able
to boot your system alternatively, e.g. with a boot floppy, to restore the
@@ -183,40 +188,42 @@ former <tt>/sbin/init</tt> if anything goes wrong.
Make a backup copy of the current <tt>/sbin/init</tt> program and replace
it with <tt>/sbin/runit-init</tt>:
<pre>
- # cp -p /sbin/init /sbin/init.bsd
- # install /sbin/runit-init /sbin/init
+ # cp -p /sbin/init /sbin/init.bsd
+ # install /sbin/runit-init /sbin/init
</pre>
Boot your system with <i>runit</i> for the first time:
<pre>
- # reboot
+ # reboot
</pre>
-Watch the console output while <i>runit</i> boots up the system. Switch
-to the virtual console 5 (CTRL-ALT-F5) when stage 2 is reached, a getty
-should run there, you are able to login.
+Watch the console output while <i>runit</i> boots up the system.
+Switch to the virtual console 5 (CTRL-ALT-F5) when stage 2 is reached, a
+getty should run there, you are able to login.
<p>
Use <b>init 6</b> to reboot and <b>init 0</b> to halt a system that runs
-<i>runit</i>. This will cause <i>runit</i> to enter stage 3 which runs
+<i>runit</i>.
+This will cause <i>runit</i> to enter stage 3 which runs
<tt>/sbin/reboot</tt> or <tt>/sbin/halt</tt> as last command.
<p>
To report success:
<pre>
- # ( uname -a ; cat /etc/runit/[123] ) | mail pape-runit-0.13.1@smarden.org
+ # ( uname -a ; cat /etc/runit/[123] ) | mail pape-runit-0.13.1@smarden.org
</pre>
<h3>Step 5: Service migration</h3>
The goal is to migrate all services from <i>/etc/rc.*</i> scheme to the
<a href="http://cr.yp.to/daemontools.html">daemontools</a> design; take a
look at these <a href="runscripts.html">run scripts</a> for popular
-services. The migration can be done smoothly. By default <i>runit</i>
-runs the <tt>/etc/rc</tt> scripts in stage 1 as a one time task, so the
-services are started automatically:
+services.
+The migration can be done smoothly.
+By default <i>runit</i> runs the <tt>/etc/rc</tt> scripts in stage 1 as a
+one time task, so the services are started automatically:
<pre>
- #!/bin/sh
- # system one time tasks
+ #!/bin/sh
+ # system one time tasks
- /bin/sh /etc/rc autoboot
+ /bin/sh /etc/rc autoboot
- touch /etc/runit/stopit
- chmod 0 /etc/runit/stopit
+ touch /etc/runit/stopit
+ chmod 0 /etc/runit/stopit
</pre>
To migrate a service, create a service directory, disable the service if
it is running, disable the service in <tt>/etc/rc.conf</tt> or remove the
diff --git a/doc/runlevels.html b/doc/runlevels.html
@@ -14,27 +14,28 @@
<a href="#create">Creating runlevels</a>
<hr>
<a name="prepare"><h3>Prepare runit</h3></a>
-If not yet done, configure your system to use <a href="runit.8.html">runit</a>
-as process no 1 by following the <a href="replaceinit.html">instructions</a>.
+If not yet done, configure your system to use
+<a href="runit.8.html">runit</a> as process no 1 by following the
+<a href="replaceinit.html">instructions</a>.
<p>
-Create the following directories and symlinks:
+Create the following directories and symbolic links:
<pre>
# mkdir -p /etc/runit/runsvdir/default
# mkdir -p /etc/runit/runsvdir/single
# ln -s /etc/runit/getty-5 /etc/runit/runsvdir/single/getty-5
# ln -s default /etc/runit/runsvdir/current
</pre>
-Copy the content of <tt>/var/service/</tt> to
-<tt>/etc/runit/runsvdir/current</tt>
-and replace <tt>/var/service</tt> with a symlink:
+Copy the contents of <tt>/var/service/</tt> to
+<tt>/etc/runit/runsvdir/current/</tt> and replace <tt>/var/service</tt>
+with a symbolic link:
<pre>
# cp -pR /var/service/* /etc/runit/runsvdir/current/
# mv -f /var/service /service.old && \
ln -s /etc/runit/runsvdir/current /var/service
</pre>
You have now created two runlevels: <tt>default</tt> and <tt>single</tt>.
-The <tt>current</tt> runlevel is <tt>default</tt>. It is safe to remove
-<tt>/var/service.old</tt> if you don't need it anymore.
+The <tt>current</tt> runlevel is <tt>default</tt>.
+It is safe to remove <tt>/var/service.old</tt> if you don't need it anymore.
<p>
Finally edit <tt>/etc/runit/2</tt> to set the <tt>default</tt> runlevel when
stage 2 starts:
@@ -50,10 +51,10 @@ stage 2 starts:
</pre>
<hr>
<a name="switch"><h3>Switching runlevels</h3></a>
-Switching runlevels with <i>runit</i> is done by
-switching the directory the <a href="runsvdir.8.html">runsvdir</a> program
-is running in. This is done by the <a href="runsvchdir.8.html">runsvchdir</a>
-program, e.g. to switch to the <tt>single</tt> user runlevel, do:
+Switching runlevels with <i>runit</i> is done by switching the directory the
+<a href="runsvdir.8.html">runsvdir</a> program is running in.
+This is done by the <a href="runsvchdir.8.html">runsvchdir</a> program, e.g.
+to switch to the <tt>single</tt> user runlevel, do:
<pre>
# runsvchdir single
</pre>
@@ -62,17 +63,19 @@ To switch back to the <tt>default</tt> runlevel, do:
# runsvchdir default
</pre>
See <a href="runsvdir.8.html">the runsvdir program</a> for a description of
-what happens when <i>runsvdir</i> sees the directory changed. Note that
-there is no guarantee that all services from the <tt>previous</tt> runlevel
-will stop, the <a href="runsv.8.html">runsv</a> processes have sent the
-services a SIGTERM and wait for them to terminate. You can check the status
-of the <tt>previous</tt> runlevel in <tt>/etc/runit/runsvdir/previous/</tt>.
+what happens when <i>runsvdir</i> sees the directory changed.
+Note that there is no guarantee that all services from the <tt>previous</tt>
+runlevel will stop, the <a href="runsv.8.html">runsv</a> processes have sent
+the service daemons a SIGTERM and wait for them to terminate.
+You can check the status of the <tt>previous</tt> runlevel through
+<tt>/etc/runit/runsvdir/previous/</tt>.
<hr>
<a name="create"><h3>Creating new runlevels</h3></a>
To create a new runlevel, simply create a new directory in
-<tt>/etc/runit/runsvdir</tt>. The name of the directory is the name of
-the new runlevel. The name must not start with a dot and must not be
-<tt>current</tt>, <tt>current.new</tt> or <tt>previous</tt>. E.g.:
+<tt>/etc/runit/runsvdir</tt>.
+The name of the directory is the name of the new runlevel.
+The name must not start with a dot and must not be <tt>current</tt>,
+<tt>current.new</tt>, or <tt>previous</tt>, e.g.:
<pre>
# mkdir /etc/runit/runsvdir/maintenance
</pre>
diff --git a/doc/upgrade.html b/doc/upgrade.html
@@ -24,8 +24,8 @@ Replacing init on Solaris is not yet supported.
The service directory now defaults to /var/service instead of /service.
<h3>0.10.0 to 0.11.0 or 0.11.1 or 0.11.2</h3>
This version introduces the new <a href="chpst.8.html">chpst</a> program,
-which changes the process state as specified by command line options, and runs
-another program with this process state.
+which changes the process state as specified by command line options, and
+runs another program with this process state.
<h3>0.9.x to 0.10.0</h3>
No further action from you is required.
<h3>0.8.0 or 0.8.1 to 0.9.x</h3>
@@ -56,23 +56,24 @@ This version introduces runlevel support with the new
<p>
The <a href="runsvdir.8.html">runsvdir</a> and
<a href="runsv.8.html">runsv</a> programs have changed and should be
-restarted. If you want to switch runlevels, <tt>runsvdir</tt> must be
-restarted. This is done on the next reboot or by following these steps:
+restarted.
+If you want to switch runlevels, <tt>runsvdir</tt> must be restarted.
+This is done on the next reboot or by following these steps:
<p>
<ul>
- <li>
+<li>
Login on console 5. Bring all services other than the <tt>getty-5</tt>
service down:
<pre>
# cd /service
# for i in *; do if test "$i" != getty-5; then svc -d $i; fi; done
</pre>
- <li>
+<li>
Check for the services being down:
<pre>
# svstat /service/*
</pre>
- <li>
+<li>
If all services other than the <tt>getty-5</tt> service are down, kill
<tt>runsvdir</tt> by sending it a HUP signal:
<pre>
@@ -90,20 +91,22 @@ combination of daemontools. Please adapt <tt>runit</tt>'s stage 2
(<tt>/etc/runit/2</tt>) to use <tt>runsvdir</tt> instead of
<tt>svscanboot</tt>; see the examples in <tt>/package/admin/runit/etc/</tt>.
The change takes effect on the next reboot or if you stop all services and
-kill <tt>svscan</tt> and <tt>readproctitle</tt>. <tt>runit</tt> then
-automatically restarts stage 2.
+kill <tt>svscan</tt> and <tt>readproctitle</tt>.
+<tt>runit</tt> then automatically restarts stage 2.
<p>
The <a href="svwaitdown.8.html">svwaitdown</a> program has new options: -k
-and -x. They are used in <tt>runit</tt>'s stage 3 (<tt>/etc/runit/3</tt>).
+and -x.
+They are used in <tt>runit</tt>'s stage 3 (<tt>/etc/runit/3</tt>).
Please adapt your <tt>/etc/runit/3</tt> script after the changes to stage 2
have taken effect (<tt>runsvdir</tt> must run instead of
<tt>svscanboot</tt>); see the examples in
<tt>/package/admin/runit/etc/</tt>.
<h3>0.4.1 to 0.5.0</h3>
-There is a new program: <a href="utmpset.8.html">utmpset</a>. This program
-is used in the getty run scripts to enable local login accounting. You might
-want to adapt your getty run scripts <tt>/service/getty-*/run</tt>, see the
-examples in <tt>/package/admin/runit/etc/</tt>.
+There is a new program: <a href="utmpset.8.html">utmpset</a>.
+This program is used in the getty run scripts to enable local login
+accounting.
+You might want to adapt your getty run scripts <tt>/service/getty-*/run</tt>,
+see the examples in <tt>/package/admin/runit/etc/</tt>.
<hr>
<address><a href="mailto:pape@smarden.org">
Gerrit Pape <pape@smarden.org>
diff --git a/doc/useinit.html b/doc/useinit.html
@@ -23,8 +23,8 @@ In any case, you first need to copy the <i>stage 2</i> script to
<tt>/sbin/runsvdir-start</tt>, and create the service directory
<tt>/var/service</tt>:
<pre>
- # install -m0750 /package/admin/runit/etc/2 /sbin/runsvdir-start
- # mkdir -p /var/service
+ # install -m0750 /package/admin/runit/etc/2 /sbin/runsvdir-start
+ # mkdir -p /var/service
</pre>
<hr>
<a href="#sysv">How to use with sysvinit</a><br>
@@ -35,22 +35,22 @@ In any case, you first need to copy the <i>stage 2</i> script to
If your system uses a sysvinit alike init scheme with a <tt>/etc/inittab</tt>
file, do:
<pre>
- # cat >>/etc/inittab <<EOT
- SV:123456:respawn:/sbin/runsvdir-start
- EOT
+ # cat >>/etc/inittab <<EOT
+ SV:123456:respawn:/sbin/runsvdir-start
+ EOT
</pre>
and tell <i>init</i> to re-read its configuration, e.g.:
<pre>
- # init q
+ # init q
</pre>
<hr>
<a name="bsd"><h2>Using with *BSD init</h2></a>
If your system uses a BSD alike init scheme with a <tt>/etc/rc.local</tt>
script, do:
<pre>
- # cat >>/etc/rc.local <<EOT
- csh -cf '/sbin/runsvdir-start &'
- EOT
+ # cat >>/etc/rc.local <<EOT
+ csh -cf '/sbin/runsvdir-start &'
+ EOT
</pre>
and reboot your system.
<hr>
