Debian Codegraph @

upstream/debian-unstable/man8/systemd-soft-reboot.service.8

raw
1 '\" t
2 .TH "SYSTEMD\-SOFT\-REBOOT\&.SERVICE" "8" "" "systemd 261~rc3" "systemd-soft-reboot.service"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-soft-reboot.service \- Userspace reboot operation
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-soft\-reboot\&.service
27 .SH "DESCRIPTION"
28 .PP
29 systemd\-soft\-reboot\&.service
30 is a system service that is pulled in by
31 soft\-reboot\&.target
32 and is responsible for performing a userspace\-only reboot operation\&. When invoked, it will send the
33 \fBSIGTERM\fR
34 signal to any processes left running (but does not wait for the processes to exit), and follow up with
35 \fBSIGKILL\fR\&. If the
36 /run/nextroot/
37 directory exists (which may be a regular directory, a directory mount point or a symlink to either) then it will switch the file system root to it\&. It then reexecutes the service manager off the (possibly now new) root file system, which will enqueue a new boot transaction as in a normal reboot\&.
38 .PP
39 Such a userspace\-only reboot operation permits updating or resetting the entirety of userspace with minimal downtime, as the reboot operation does
40 \fInot\fR
41 transition through:
42 .sp
43 .RS 4
44 .ie n \{\
45 \h'-04'\(bu\h'+03'\c
46 .\}
47 .el \{\
48 .sp -1
49 .IP \(bu 2.3
50 .\}
51 The second phase of regular shutdown, as implemented by
52 \fBsystemd-shutdown\fR(8)\&.
53 .RE
54 .sp
55 .RS 4
56 .ie n \{\
57 \h'-04'\(bu\h'+03'\c
58 .\}
59 .el \{\
60 .sp -1
61 .IP \(bu 2.3
62 .\}
63 The third phase of regular shutdown, i\&.e\&. the return to the initrd context\&.
64 .RE
65 .sp
66 .RS 4
67 .ie n \{\
68 \h'-04'\(bu\h'+03'\c
69 .\}
70 .el \{\
71 .sp -1
72 .IP \(bu 2.3
73 .\}
74 The hardware reboot operation\&.
75 .RE
76 .sp
77 .RS 4
78 .ie n \{\
79 \h'-04'\(bu\h'+03'\c
80 .\}
81 .el \{\
82 .sp -1
83 .IP \(bu 2.3
84 .\}
85 The firmware initialization\&.
86 .RE
87 .sp
88 .RS 4
89 .ie n \{\
90 \h'-04'\(bu\h'+03'\c
91 .\}
92 .el \{\
93 .sp -1
94 .IP \(bu 2.3
95 .\}
96 The boot loader initialization\&.
97 .RE
98 .sp
99 .RS 4
100 .ie n \{\
101 \h'-04'\(bu\h'+03'\c
102 .\}
103 .el \{\
104 .sp -1
105 .IP \(bu 2.3
106 .\}
107 The kernel initialization\&.
108 .RE
109 .sp
110 .RS 4
111 .ie n \{\
112 \h'-04'\(bu\h'+03'\c
113 .\}
114 .el \{\
115 .sp -1
116 .IP \(bu 2.3
117 .\}
118 The initrd initialization\&.
119 .RE
120 .PP
121 However, this form of reboot comes with drawbacks as well:
122 .sp
123 .RS 4
124 .ie n \{\
125 \h'-04'\(bu\h'+03'\c
126 .\}
127 .el \{\
128 .sp -1
129 .IP \(bu 2.3
130 .\}
131 The OS update remains incomplete, as the kernel is not reset and continues running\&.
132 .RE
133 .sp
134 .RS 4
135 .ie n \{\
136 \h'-04'\(bu\h'+03'\c
137 .\}
138 .el \{\
139 .sp -1
140 .IP \(bu 2.3
141 .\}
142 Kernel settings (such as
143 /proc/sys/
144 settings, a\&.k\&.a\&. "sysctl", or
145 /sys/
146 settings) are not reset\&.
147 .RE
148 .PP
149 These limitations may be addressed by various means, which are outside of the scope of this documentation, such as kernel live\-patching and sufficiently comprehensive
150 /etc/sysctl\&.d/
151 files\&.
152 .SH "RESOURCE PASS\-THROUGH"
153 .PP
154 Various runtime OS resources can passed from a system runtime to the next, through the userspace reboot operation\&. Specifically:
155 .sp
156 .RS 4
157 .ie n \{\
158 \h'-04'\(bu\h'+03'\c
159 .\}
160 .el \{\
161 .sp -1
162 .IP \(bu 2.3
163 .\}
164 File descriptors placed in the file descriptor store of services that remain active until the very end are passed to the next boot, where they are placed in the file descriptor store of the same unit\&. For this to work, units must declare
165 \fIDefaultDependencies=no\fR
166 (and avoid a manual
167 \fIConflicts=shutdown\&.target\fR
168 or similar) to ensure they are not terminated as usual during the system shutdown operation\&. Alternatively, use
169 \fIFileDescriptorStorePreserve=\fR
170 to allow the file descriptor store to remain pinned even when the unit is down\&. See
171 \fBsystemd.service\fR(5)
172 for details about the file descriptor store\&.
173 .RE
174 .sp
175 .RS 4
176 .ie n \{\
177 \h'-04'\(bu\h'+03'\c
178 .\}
179 .el \{\
180 .sp -1
181 .IP \(bu 2.3
182 .\}
183 Similar to this, file descriptors associated with
184 \&.socket
185 units remain open (and connectible) if the units are not stopped during the transition\&. (Achieved by
186 \fIDefaultDependencies=no\fR\&.)
187 .RE
188 .sp
189 .RS 4
190 .ie n \{\
191 \h'-04'\(bu\h'+03'\c
192 .\}
193 .el \{\
194 .sp -1
195 .IP \(bu 2.3
196 .\}
197 The
198 /run/
199 file system remains mounted and populated and may be used to pass state information between such userspace reboot cycles\&.
200 .RE
201 .sp
202 .RS 4
203 .ie n \{\
204 \h'-04'\(bu\h'+03'\c
205 .\}
206 .el \{\
207 .sp -1
208 .IP \(bu 2.3
209 .\}
210 Service processes may continue to run over the transition, past soft\-reboot and into the next session, if they are placed in services that remain active until the very end of shutdown (which again is achieved via
211 \fIDefaultDependencies=no\fR)\&. They must also be set up to avoid being killed by the aforementioned
212 \fBSIGTERM\fR
213 and
214 \fBSIGKILL\fR
215 via
216 \fISurviveFinalKillSignal=yes\fR, and also be configured to avoid being stopped on isolate via
217 \fIIgnoreOnIsolate=yes\fR\&. They also have to be configured to be stopped on normal shutdown, reboot and maintenance mode\&. Finally, they have to be ordered after
218 \fBbasic\&.target\fR
219 to ensure correct ordering on boot\&. Note that in case any new or custom units are used to isolate to, or that implement an equivalent shutdown functionality, they will also have to be configured manually for correct ordering and conflicting\&. For example:
220 .sp
221 .if n \{\
222 .RS 4
223 .\}
224 .nf
225 [Unit]
226 Description=My Surviving Service
227 SurviveFinalKillSignal=yes
228 IgnoreOnIsolate=yes
229 DefaultDependencies=no
230 After=basic\&.target
231 Conflicts=reboot\&.target kexec\&.target poweroff\&.target halt\&.target rescue\&.target emergency\&.target
232 Before=shutdown\&.target rescue\&.target emergency\&.target
233
234 [Service]
235 Type=oneshot
236 ExecStart=sleep infinity
237 .fi
238 .if n \{\
239 .RE
240 .\}
241 .RE
242 .sp
243 .RS 4
244 .ie n \{\
245 \h'-04'\(bu\h'+03'\c
246 .\}
247 .el \{\
248 .sp -1
249 .IP \(bu 2.3
250 .\}
251 On top of the above, templated units also need a configuration file for their slice, as they by default use a slice named after the non\-templated part of the unit\&. For example, for a
252 foo@test\&.service
253 instance, a
254 system\-foo\&.slice
255 unit may be added with the following content:
256 .sp
257 .if n \{\
258 .RS 4
259 .\}
260 .nf
261 [Unit]
262 SurviveFinalKillSignal=yes
263 IgnoreOnIsolate=yes
264 DefaultDependencies=no
265 .fi
266 .if n \{\
267 .RE
268 .\}
269 .RE
270 .sp
271 .RS 4
272 .ie n \{\
273 \h'-04'\(bu\h'+03'\c
274 .\}
275 .el \{\
276 .sp -1
277 .IP \(bu 2.3
278 .\}
279 File system mounts may remain mounted during the transition, and complex storage attached, if configured to remain until the very end of the shutdown process\&. (Also achieved via
280 \fIDefaultDependencies=no\fR, and by avoiding
281 \fIConflicts=umount\&.target\fR)
282 .RE
283 .sp
284 .RS 4
285 .ie n \{\
286 \h'-04'\(bu\h'+03'\c
287 .\}
288 .el \{\
289 .sp -1
290 .IP \(bu 2.3
291 .\}
292 If the unit publishes a service over D\-Bus, the connection needs to be re\-established after soft\-reboot as the D\-Bus broker will be stopped and then started again\&. When using the
293 \fBsd-bus\fR(3)
294 library this can be achieved by adapting the following example\&.
295 .sp
296 .if n \{\
297 .RS 4
298 .\}
299 .nf
300 /* SPDX\-License\-Identifier: MIT\-0 */
301
302 /* A D\-Bus service that automatically reconnects when the system bus is
303 * restarted\&.
304 *
305 * Compile with \*(Aqcc sd_bus_service_reconnect\&.c $(pkg\-config \-\-libs \-\-cflags libsystemd)\*(Aq
306 *
307 * To allow the program to take ownership of the name \*(Aqorg\&.freedesktop\&.ReconnectExample\*(Aq,
308 * add the following as /etc/dbus\-1/system\&.d/org\&.freedesktop\&.ReconnectExample\&.conf
309 * and then reload the broker with \*(Aqsystemctl reload dbus\*(Aq:
310
311 <?xml version="1\&.0"?> <!\-\-*\-nxml\-*\-\->
312 <!DOCTYPE busconfig PUBLIC "\-//freedesktop//DTD D\-BUS Bus Configuration 1\&.0//EN"
313 "http://www\&.freedesktop\&.org/standards/dbus/1\&.0/busconfig\&.dtd">
314 <busconfig>
315 <policy user="root">
316 <allow own="org\&.freedesktop\&.ReconnectExample"/>
317 <allow send_destination="org\&.freedesktop\&.ReconnectExample"/>
318 <allow receive_sender="org\&.freedesktop\&.ReconnectExample"/>
319 </policy>
320
321 <policy context="default">
322 <allow send_destination="org\&.freedesktop\&.ReconnectExample"/>
323 <allow receive_sender="org\&.freedesktop\&.ReconnectExample"/>
324 </policy>
325 </busconfig>
326
327 *
328 * To get the property via busctl:
329 *
330 * $ busctl \-\-user get\-property org\&.freedesktop\&.ReconnectExample \e
331 * /org/freedesktop/ReconnectExample \e
332 * org\&.freedesktop\&.ReconnectExample \e
333 * Example
334 * s "example"
335 */
336
337 #include <errno\&.h>
338 #include <stdio\&.h>
339 #include <stdlib\&.h>
340 #include <systemd/sd\-bus\&.h>
341
342 #define _cleanup_(f) __attribute__((cleanup(f)))
343
344 static int log_error(int r, const char *str) {
345 fprintf(stderr, "%s failed: %s\en", str, strerror(\-r));
346 return r;
347 }
348
349 typedef struct object {
350 const char *example;
351 sd_bus **bus;
352 sd_event **event;
353 } object;
354
355 static int property_get(
356 sd_bus *bus,
357 const char *path,
358 const char *interface,
359 const char *property,
360 sd_bus_message *reply,
361 void *userdata,
362 sd_bus_error *error) {
363
364 object *o = userdata;
365
366 if (strcmp(property, "Example") == 0)
367 return sd_bus_message_append(reply, "s", o\->example);
368
369 return sd_bus_error_setf(error,
370 SD_BUS_ERROR_UNKNOWN_PROPERTY,
371 "Unknown property \*(Aq%s\*(Aq",
372 property);
373 }
374
375 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html */
376 static const sd_bus_vtable vtable[] = {
377 SD_BUS_VTABLE_START(0),
378 SD_BUS_PROPERTY(
379 "Example", "s",
380 property_get,
381 0,
382 SD_BUS_VTABLE_PROPERTY_CONST),
383 SD_BUS_VTABLE_END
384 };
385
386 static int setup(object *o);
387
388 static int on_disconnect(sd_bus_message *message, void *userdata, sd_bus_error *ret_error) {
389 int r;
390
391 r = setup((object *)userdata);
392 if (r < 0) {
393 object *o = userdata;
394 r = sd_event_exit(*o\->event, r);
395 if (r < 0)
396 return log_error(r, "sd_event_exit()");
397 }
398
399 return 1;
400 }
401
402 /* Ensure the event loop exits with a clear error if acquiring the well\-known
403 * service name fails */
404 static int request_name_callback(sd_bus_message *m, void *userdata, sd_bus_error *ret_error) {
405 int r;
406
407 if (!sd_bus_message_is_method_error(m, NULL))
408 return 1;
409
410 const sd_bus_error *error = sd_bus_message_get_error(m);
411
412 if (sd_bus_error_has_names(error, SD_BUS_ERROR_TIMEOUT, SD_BUS_ERROR_NO_REPLY))
413 return 1; /* The bus is not available, try again later */
414
415 fprintf(stderr, "Failed to request name: %s\en", error\->message);
416 object *o = userdata;
417 r = sd_event_exit(*o\->event, \-sd_bus_error_get_errno(error));
418 if (r < 0)
419 return log_error(r, "sd_event_exit()");
420
421 return 1;
422 }
423
424 static int setup(object *o) {
425 int r;
426
427 /* If we are reconnecting, then the bus object needs to be closed, detached
428 * from the event loop and recreated\&.
429 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_detach_event\&.html
430 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_close_unref\&.html
431 */
432 if (*o\->bus) {
433 r = sd_bus_detach_event(*o\->bus);
434 if (r < 0)
435 return log_error(r, "sd_bus_detach_event()");
436 *o\->bus = sd_bus_close_unref(*o\->bus);
437 }
438
439 /* Set up a new bus object for the system bus, configure it to wait for D\-Bus
440 * to be available instead of failing if it is not, and start it\&. All the
441 * following operations are asynchronous and will not block waiting for D\-Bus
442 * to be available\&.
443 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_new\&.html
444 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_address\&.html
445 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_bus_client\&.html
446 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_negotiate_creds\&.html
447 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_watch_bind\&.html
448 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_set_connected_signal\&.html
449 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_start\&.html
450 */
451 r = sd_bus_new(o\->bus);
452 if (r < 0)
453 return log_error(r, "sd_bus_new()");
454 r = sd_bus_set_address(*o\->bus, "unix:path=/run/dbus/system_bus_socket");
455 if (r < 0)
456 return log_error(r, "sd_bus_set_address()");
457 r = sd_bus_set_bus_client(*o\->bus, 1);
458 if (r < 0)
459 return log_error(r, "sd_bus_set_bus_client()");
460 r = sd_bus_negotiate_creds(*o\->bus, 1, SD_BUS_CREDS_UID|SD_BUS_CREDS_EUID|SD_BUS_CREDS_EFFECTIVE_CAPS);
461 if (r < 0)
462 return log_error(r, "sd_bus_negotiate_creds()");
463 r = sd_bus_set_watch_bind(*o\->bus, 1);
464 if (r < 0)
465 return log_error(r, "sd_bus_set_watch_bind()");
466 r = sd_bus_start(*o\->bus);
467 if (r < 0)
468 return log_error(r, "sd_bus_start()");
469
470 /* Publish an interface on the bus, specifying our well\-known object access
471 * path and public interface name\&.
472 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html
473 * https://dbus\&.freedesktop\&.org/doc/dbus\-tutorial\&.html
474 */
475 r = sd_bus_add_object_vtable(*o\->bus,
476 NULL,
477 "/org/freedesktop/ReconnectExample",
478 "org\&.freedesktop\&.ReconnectExample",
479 vtable,
480 o);
481 if (r < 0)
482 return log_error(r, "sd_bus_add_object_vtable()");
483 /* By default, the service is only assigned an ephemeral name\&. Also add a
484 * well\-known one, so that clients know whom to call\&. This needs to be
485 * asynchronous, as D\-Bus might not be yet available\&. The callback will check
486 * whether the error is expected or not, in case it fails\&.
487 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_request_name\&.html
488 */
489 r = sd_bus_request_name_async(*o\->bus,
490 NULL,
491 "org\&.freedesktop\&.ReconnectExample",
492 0,
493 request_name_callback,
494 o);
495 if (r < 0)
496 return log_error(r, "sd_bus_request_name_async()");
497 /* When D\-Bus is disconnected this callback will be invoked, which will set up
498 * the connection again\&. This needs to be asynchronous, as D\-Bus might not yet
499 * be available\&.
500 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_match_signal_async\&.html
501 */
502 r = sd_bus_match_signal_async(*o\->bus,
503 NULL,
504 "org\&.freedesktop\&.DBus\&.Local",
505 NULL,
506 "org\&.freedesktop\&.DBus\&.Local",
507 "Disconnected",
508 on_disconnect,
509 NULL,
510 o);
511 if (r < 0)
512 return log_error(r, "sd_bus_match_signal_async()");
513 /* Attach the bus object to the event loop so that calls and signals are
514 * processed\&.
515 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_attach_event\&.html
516 */
517 r = sd_bus_attach_event(*o\->bus, *o\->event, 0);
518 if (r < 0)
519 return log_error(r, "sd_bus_attach_event()");
520
521 return 0;
522 }
523
524 int main(int argc, char **argv) {
525 /* The bus should be relinquished before the program terminates\&. The cleanup
526 * attribute allows us to do it nicely and cleanly whenever we exit the block\&.
527 */
528 _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
529 _cleanup_(sd_event_unrefp) sd_event *event = NULL;
530 object o = {
531 \&.example = "example",
532 \&.bus = &bus,
533 \&.event = &event,
534 };
535 int r;
536
537 /* Create an event loop data structure, with default parameters\&.
538 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_default\&.html
539 */
540 r = sd_event_default(&event);
541 if (r < 0)
542 return log_error(r, "sd_event_default()");
543
544 /* By default, the event loop will terminate when all sources have disappeared,
545 * so we have to keep it \*(Aqoccupied\*(Aq\&. Register signal handling to do so\&.
546 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_add_signal\&.html
547 */
548 r = sd_event_add_signal(event, NULL, SIGINT|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL);
549 if (r < 0)
550 return log_error(r, "sd_event_add_signal(SIGINT)");
551
552 r = sd_event_add_signal(event, NULL, SIGTERM|SD_EVENT_SIGNAL_PROCMASK, NULL, NULL);
553 if (r < 0)
554 return log_error(r, "sd_event_add_signal(SIGTERM)");
555
556 r = setup(&o);
557 if (r < 0)
558 return EXIT_FAILURE;
559
560 /* Enter the main loop, it will exit only on sigint/sigterm\&.
561 * https://www\&.freedesktop\&.org/software/systemd/man/sd_event_loop\&.html
562 */
563 r = sd_event_loop(event);
564 if (r < 0)
565 return log_error(r, "sd_event_loop()");
566
567 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_release_name\&.html */
568 r = sd_bus_release_name(bus, "org\&.freedesktop\&.ReconnectExample");
569 if (r < 0)
570 return log_error(r, "sd_bus_release_name()");
571
572 return 0;
573 }
574 .fi
575 .if n \{\
576 .RE
577 .\}
578 .sp
579 .RE
580 .PP
581 Even though passing resources from one soft reboot cycle to the next is possible this way, we strongly suggest to use this functionality sparingly only, as it creates a more fragile system as resources from different versions of the OS and applications might be mixed with unforeseen consequences\&. In particular it is recommended to
582 \fIavoid\fR
583 allowing processes to survive the soft reboot operation, as this means code updates will necessarily be incomplete, and processes typically pin various other resources (such as the file system they are backed by), thus increasing memory usage (as two versions of the OS/application/file system might be kept in memory)\&. Leaving processes running during a soft\-reboot operation requires disconnecting the service comprehensively from the rest of the OS, i\&.e\&. minimizing IPC and reducing sharing of resources with the rest of the OS\&. A possible mechanism to achieve this is the concept of
584 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[1]\d\s+2, but make sure no resource from the host\*(Aqs OS filesystems is pinned via
585 \fIBindPaths=\fR
586 or similar unit settings, otherwise the old, originating filesystem will remain mounted as long as the unit is running\&.
587 .SH "NOTES"
588 .PP
589 Note that because
590 \fBsystemd-shutdown\fR(8)
591 is not executed, the executables in
592 /usr/lib/systemd/system\-shutdown/
593 are not executed either\&.
594 .PP
595 Note that
596 systemd\-soft\-reboot\&.service
597 (and related units) should never be executed directly\&. Instead, trigger system shutdown with a command such as
598 \fBsystemctl soft\-reboot\fR\&.
599 .PP
600 Note that if a new root file system has been set up on
601 "/run/nextroot/", a
602 \fBsoft\-reboot\fR
603 will be performed when the
604 \fBreboot\fR
605 command is invoked\&.
606 .SH "SEE ALSO"
607 .PP
608 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd.special\fR(7), \fBsystemd-poweroff.service\fR(8), \fBsystemd-suspend.service\fR(8), \fBbootup\fR(7)
609 .SH "NOTES"
610 .IP " 1." 4
611 Portable Services
612 .RS 4
613 \%https://systemd.io/PORTABLE_SERVICES
614 .RE