Writing Init Scripts

2025-09-12T22:00:09Z

Eznix86: Add missing docs for start, stop, restart, and Daemon, Forking, Logging

{{Draft}}

== Introduction ==

Alpine Linux uses the [https://github.com/OpenRC/openrc OpenRC] init system to start services. Don't confuse OpenRC init with our system init (the first process that is executed aka pid 1). Many of the current init.d script found in Alpine Linux are taken from Gentoo. If you want to save time you could search [https://packages.gentoo.org/categories Gentoo's repository] for an existing initscript for your service. You can also check [https://wiki.gentoo.org/wiki/Handbook:X86/Working/Initscripts#Writing_initscripts Gentoo's wiki] for some additional OpenRC information.

<strong>NOTE</strong>: OpenRC recently added [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md documentation] on how to write proper Init scripts. Make sure you read it!

If you cannot find an init.d script from Gentoo, or you just want to start to write your own init.d scripts, we provide you with some basic information on how to write simple OpenRC init scripts.

Primary information about the OpenRC format can be found in the [https://manpages.org/openrc-run/8 OpenRC man page openrc-run].

<pre>
apk add openrc-doc
man openrc-run
</pre>

== Things to avoid ==

* Prefer standard OpenRC variables such as <code>command_args</code>, <code>command_user</code> etc. (see [https://www.mankier.com/8/openrc-run openrc-run(8)]); do not create unnecessary config variables like <code>FOO_OPTS</code>, <code>FOO_USER</code> etc. If you want to predefine the default value in init.d script, use common idiom <code>: ${command_user=foo}</code>.

* Use snake_case for naming extra configuration variables (to be consistent with the OpenRC variables and other init scripts in Alpine). Do not prefix them with the service name, try to be consistent with existing init scripts (e.g. <code>cfgfile</code>, <code>cfgdir</code>, <code>logfile</code>, <code>cachedir</code>, <code>listen_on</code>, <code>start_wait</code>, …).

== Minimal Templates ==

Every init.d script you write needs to start with a [https://en.wikipedia.org/wiki/Shebang_(Unix) shebang] like:

<code>#!/sbin/openrc-run</code>

=== Services relying on OpenRC exclusively ===

<pre>
#!/sbin/openrc-run

command=/path/to/command
</pre>

=== Services supervised by [https://www.skarnet.org/software/s6/ s6] ===

Notes:

* Install and configure the <code>s6-scan</code> service to start on system boot
* Exclude <code>start()</code>, <code>stop()</code> and <code>status()</code> functions in order for s6 supervision to work reliably. OpenRC has built-in equivalent functions which invoke the necessary s6 commands.
* Include a <code>depend()</code> stanza to ensure that the <code>s6-svscan</code> service is already running.
* Add a <code>start_pre()</code> stanza to symlink the service directory into the scan directory, because the <code>/etc/init.d/bootmisc</code> scripts cleans out the <code>/run</code> directory on system boot.

<pre>
#!/sbin/openrc-run

name="foo"
supervisor="s6"
s6_service_path="${RC_SVCDIR}/s6-scan/${name}"

depend() {
need s6-svscan
}

start_pre() {
if [ ! -L "${RC_SVC_DIR}/s6-scan/${name}" ]; then
ln -s "/path/to/${name}/service/dir" "${RC_SVCDIR}/s6-scan/${name}"
fi
}
</pre>

The rest of the below basic example could be omitted, but that would most probably leave you with an non working initd script.

== Basic example ==

<pre>
#!/sbin/openrc-run

name=$RC_SVCNAME
cfgfile="/etc/$RC_SVCNAME/$RC_SVCNAME.conf"
command="/usr/bin/my_daemon"
command_args="--my-daemon-args"
command_user="my_system_user"
pidfile="/run/$RC_SVCNAME/$RC_SVCNAME.pid"
start_stop_daemon_args="--args-for-start-stop-daemon"
command_background="yes"

depend() {
need net
}

start_pre() {
checkpath --directory --owner $command_user:$command_user --mode 0775 \
/run/$RC_SVCNAME /var/log/$RC_SVCNAME
}
</pre>

== start, stop, restart functions ==

OpenRC defined a few basic functions ie: start, stop, restart. These functions are defined by default but can be overwritten by defining your own set of functions.
This is generally only necessary if you want to do something special which is not provided by the default start/stop/restart implementations.

=== start ===

<pre>
start() {
ebegin "Starting mydaemon"
start-stop-daemon --start \
--exec /usr/sbin/mydaemon \
--pidfile /var/run/mydaemon.pid \
-- \
--args-for-mydaemon
eend $?
}
</pre>

=== stop ===
<pre>

stop() {
ebegin "Stopping mydaemon"
start-stop-daemon --stop \
--exec /usr/sbin/mydaemon \
--pidfile /var/run/mydaemon.pid
eend $?
}

</pre>
=== restart ===

<pre>

restart() {
ebegin "Restarting mydaemon"
svc_stop
svc_start
eend $?
}

</pre>
== Daemon, Forking, Logging ==

If your daemon supports running in the foreground, set <code>command_background="yes"</code> and add a <code>--no-fork</code> or <code>--foreground</code> option to <code>command_args</code>. This prevents the daemon from forking itself into the background, so OpenRC can handle backgrounding.

When you use <code>command_background="yes"</code>, you must also set a <code>pidfile</code>. This allows OpenRC to track and manage the daemon process correctly.

If your daemon does not support running in the foreground, you can use <code>start-stop-daemon</code> directly in your <code>start()</code> function to launch the service and manage forking and pidfiles manually.

For logging, use a <code>logfile</code> variable if your daemon supports it, or redirect output in your <code>start()</code> function.

Example for a daemon that supports foreground mode:

<pre>
command_args="--no-fork --logfile /var/log/my_daemon.log"
command_background="yes"
pidfile="/run/my_daemon.pid"
</pre>

Example for a daemon that does not support foreground mode, using <code>start-stop-daemon</code>:

<pre>
start() {
ebegin "Starting mydaemon"
start-stop-daemon --start \
--exec /usr/bin/mydaemon \
--pidfile /run/mydaemon.pid \
--background \
--make-pidfile \
-- \
--logfile /var/log/mydaemon.log
eend $?
}
</pre>

[[Category:Booting]]

Alpine Linux - User contributions [en]

Writing Init Scripts