aboutsummaryrefslogtreecommitdiffstats
path: root/modules/Working/pages/openrc.adoc
blob: 9fe464ce0a9ae56dd109362db35cfd3c9652a343 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
= Working with OpenRC
// MAINT: openrc, whole page

OpenRC is the init system used in alpine.
The init system manages the services, startup and shutdown of your computer.

[NOTE]
====
In this section, the canonical names of utilities are used.
For instance, `rc-service` instead of `service`.
For many of these, the traditional name (e.g `service`) is also available, but that is not the case for all of them.
If in doubt, use the canonical name, as is shown in this document.
====

== Normal Usage

=== Manipulating Services

==== Runtime Service Manipulation
// MAINT: rc-service

You manipulate services on a running system using the `rc-service` command.
This allows you to start, stop, and check the status of a given service, amongst other things.
See the following basic examples:

[source,sh]
----
rc-service networking stop <1>
rc-service sshd start <2>
rc-service chronyd status <3>
----
<1> Stop the networking service.
<2> Start the sshd service.
<3> See the status of the chronyd service.

`rc-service` also supports a few flags, which are primarily useful for scripting.
// TODO: link rc-service(8)
You can see the full list in the `rc-service(8)` manual page.
Of particular interest are the following:

-c | --ifcrashed::
Only run the specified command if the service has crashed.
-N | --ifnotstarted::
Only run the specified command if the service is not currently started.
-s | --ifstarted::
Only run the specified command if the service is currently started.

NOTE: Services may define additional commands you can use. See more on this in <<_custom_service_commands>>.

==== On-Boot Service Manipulation
// MAINT: rc-update

OpenRC operates under a system called "runlevels".
More on that in <<_switching_runlevels>> and <<_custom_runlevels>>.
Enabling a service means putting it in a runlevel, usually one that will get loaded automatically (but not necessarily so!).
Disabling a service involves removing it from one or more runlevels.
This is all done using the `rc-update` utility, which updates various runlevels.
It may be used as such:

[source,sh]
----
rc-update show -v <1>
rc-update add sshd default <2>
rc-update add sshd <3>
rc-update delete sshd <4>
rc-update delete chronyd -a <5>
----
<1> View the current services in any runlevel. The `-v` flag will also show various services that are not in any runlevel.
<2> Add the sshd service to the default runlevel.
<3> If you do not specify a runlevel, your current one will be used. This is equivalent to the 2nd example under normal operation.
<4> Remove the sshd service from the current runlevel, as with add.
<5> Remove the chronyd service from all runlevels.

=== Configuring Services

Various services may need additional configuration.
Most will have dedicated configuration files in `/etc` - you can see documentation on the specific service for more details.
However, some services need configuration applied to them as part of the launch procedure - such as passing a flag to the binary when first started.
This can be done in the `/etc/conf.d` directory, under the name of the service in question.
For example, for a service named "base", the configuration file would be `/etc/conf.d/base`.

=== System Status
// MAINT: rc-status

The `rc-status` utility is a fast way to view the current state of your system's services.
By default, it will list all the services in the current runlevel.
You can select a different runlevel by specifying it, for instance, `rc-status boot` will list all the services in the boot runlevel.
It also accepts various flags that change what it does.
// TODO: link rc-status(8)
As per usual, the full list is available in the `rc-status(8)` manual page.
Here are the more interesting ones:

-c | --crashed::
Show a list of all the crashed services.
-l | --list::
List all the available runlevels.
-s | --servicelist::
Show a list of all the services.

== Advanced Usage

=== Custom Runlevels

==== Creating

Most users will be happy with just the default runlevel.
Other users will want more.
A runlevel is simply a directory in `/etc/runlevels`, and an enabled service is a symlink to the `init.d` file.
For example, adding the `sshd` service to the `default` runlevel is creating a symlink to `/etc/init.d/sshd` in `/etc/runlevels/default`.
Creating a new runlevel thus involves creating a new directory under `/etc/runlevels`.

==== Runlevel Stacking

Most of the time, you do not want to shut down all of your `default` services if you're switching to the `office` runlevel.
Runlevel "inheritance" is acheived through runlevel stacking.
If you pass the `-s` flag to `rc-update`, you can actually add a runlevel to a runlevel.
For example, if you wanted to have an `office` runlevel that would be the same as `default`, but with the `myvpn` service started, you would do the following to set that up:

[source,sh]
----
mkdir /etc/runlevels/office
rc-update -s add default office
rc-update add myvpn office
----

==== Switching Runlevels

Once you have a custom runlevel you want to switch to, you can do so using the `openrc` command.
As per the above example, you would use `openrc office` to switch to your new runlevel, and `openrc default` to switch back.

=== System Configuration
// TODO: expand

System-wide configuration of OpenRC happens in `/etc/rc.conf`.

=== Multi-Services

In some cases, you may want the same bit of code to do different things under different circumstances.
For example, normally, the difference between various instances of `agetty` are just the tty they run on.
In these cases, you can use symlinks to manage dynamic configuration differences.

Consider `agetty` - it determines what port (tty) to run on by calculating `${RC_SVCNAME#*.}`.
This means that if your service name is `agetty.foo`, the port variable will have "foo" as its value.
The intended way to use this is by symlinking the "base" service (`agetty`) to the desired target (`agetty.foo`).

This mechanism also allows you to specify custom configuration for that service, for more details, see <<_extended_conf_d_names>>.

=== Custom Service Commands

Commands other than `start`, `stop` and `status` may be available.
A common example is `save`, used by `iptables`.
Their usage is identical to that of the built-in ones.
You can look inside the `init.d` script at various `extra*commands` variables which give a listing of the available ones.
// TODO: what's extra_started_commands etc?

=== Extended `conf.d` Names
// MAINT: the insanity in sh/opnenrc-init.sh.in

There are 4 total files that may play a role in the configuration of a service.
Assume that `base` stands for the name of the base server, `ext` is the extension (as per <<_multi_services>>) and `runlevel` is the runlevel it's in.
Under those conditions, the files involved are:

`/etc/conf.d/base.runlevel`::
OpenRC will try loading this file if the full name of the service is not the same as the base name of the service.
`/etc/conf.d/base`::
If OpenRC tried loading `/etc/conf.d/base.runlevel` and failed, it will try loading this file.
`/etc/conf.d/base.ext.runlevel`::
OpenRC will always try loading this file, but only after the above two have happened.
`/etc/conf.d/base.ext`::
If loading `/etc/conf.d/base.ext.runlevel` failed, OpenRC will try to load this file.

As far as most people are concerned, OpenRC will first load `/etc/conf.d/base` and then overlay `/etc/conf.d/base.ext` on top of it.