diff --git a/man/busctl.xml b/man/busctl.xml index 1add61728bb..8cb9a4bfa59 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -449,6 +449,7 @@ + diff --git a/man/capsule@.service.xml b/man/capsule@.service.xml new file mode 100644 index 00000000000..d20b1dd9a39 --- /dev/null +++ b/man/capsule@.service.xml @@ -0,0 +1,118 @@ + + + + + + + capsule@.service + systemd + + + + capsule@.service + 5 + + + + capsule@.service + System unit for the capsule service manager + + + + capsule@NAME.service + + + + Description + + Service managers for capsules run in + capsule@NAME.service system units, with the capsule name as the + instance identifier. Capsules are way to run additional instances of the service manager, under dynamic + user IDs, i.e. UIDs that are allocated when the capsule service manager is started, and released when it + is stopped. + + In many ways capsule@.service is similar to the per-user + user@.service service manager, but there are a few important distinctions: + + + The capsule service manager utilizes DynamicUser= (see + systemd.exec5) to + allocate a new UID dynamically on invocation. The user name is automatically generated from the capsule + name, by prefixng p_. The UID is released when the service is terminated. The user + service manager on the other hand operates under a statically allocated user ID that must be + pre-existing, before the user service manager is invoked. + + User service managers register themselves with pam8, capsule + service managers do not. + + User service managers typically read their configuration from a + $HOME directory below /home/, capsule service managers from a + $HOME directory below /var/lib/capsules/. + + User service managers are collectively contained in the user.slice + unit, capsule service managers in capsule.slice. Also see + systemd.special7. + + User service managers start the user unit default.target + initially. Capsule service managers invoke the user unit capsule@.target + instead. + + + The capsule service manager and the capsule's bus broker can be reached via the + switch to + systemctl1, + systemd-run1 and + busctl1. + + New capsules can be started via a simple systemctl start + capsule@NAME.service command, and stopped via systemctl + stop capsule@NAME.service. Starting a capsule will implicitly create + a home directory /var/lib/capsules/NAME/, if missing. A + runtime directory is created as /run/capsules/NAME/. To + remove these resources use systemctl clean capsule@NAME.service, + for example with the switch. + + The capsule@.service unit invokes a systemd --user + service manager process. This means unit files are looked for according to the sames rules as for regular user + service managers, for example in + /var/lib/capsules/NAME/.config/systemd/user/. + + Capsule names may be chosen freely by the user, however, they must be suitable as UNIX filenames + (i.e. 255 characters max, and contain no /), and when prefixed with + p- be suitable as a user name matching strict POSIX rules, see User/Group Name Syntax for details. + + + + Examples + + Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up + + # systemctl start capsule@tatze.service +# systemd-run --capsule=tatze --unit=sleeptest.service sleep 999 +# systemctl --capsule=tatze status sleeptest.service +# systemd-run -t --capsule=tatze bash +# systemctl --capsule=tatze stop sleeptest.service +# systemctl stop capsule@tatze.service +# systemctl clean --all capsule@tatze.service + + + + + See Also + + systemd1, + user@.service5, + systemd.service5, + systemd.slice5, + systemd.exec5, + systemd.special7, + systemctl1, + systemd-run1, + busctl1, + pam8 + + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 1f07e606c96..f1ac6288ca6 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -8,6 +8,7 @@ manpages = [ ['bootctl', '1', [], ''], ['bootup', '7', [], ''], ['busctl', '1', [], ''], + ['capsule@.service', '5', [], ''], ['coredump.conf', '5', ['coredump.conf.d'], 'ENABLE_COREDUMP'], ['coredumpctl', '1', [], 'ENABLE_COREDUMP'], ['crypttab', '5', [], 'HAVE_LIBCRYPTSETUP'], diff --git a/man/systemctl.xml b/man/systemctl.xml index a8c12b2f35c..ce560bf2e5b 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2813,6 +2813,7 @@ EOF + diff --git a/man/systemd-run.xml b/man/systemd-run.xml index e891920c630..51041a39f04 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -517,6 +517,7 @@ + diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 988b7175ba8..a8717d65c45 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -96,9 +96,10 @@ umount.target, usb-gadget.target, -.slice, + capsule.slice, + machine.slice, system.slice, user.slice, - machine.slice, -.mount, dbus.service, dbus.socket, @@ -1291,18 +1292,39 @@ -.slice - The root slice is the root of the slice hierarchy. It usually does not contain - units directly, but may be used to set defaults for the whole tree. + The root slice is the root of the slice hierarchy. It usually does not contain units + directly, but may be used to set defaults for the whole tree. + + machine.slice + + By default, all virtual machines and containers registered with + systemd-machined are found in this slice. This is pulled in by + systemd-machined.service. + + + + + + + capsule.slice + + By default, all capsules encapsulated in capsule@.service are found in + this slice. + + + + + system.slice - By default, all system services started by - systemd are found in this slice. + By default, all system services started by systemd are found in this + slice. @@ -1320,17 +1342,6 @@ - - machine.slice - - By default, all virtual machines and containers - registered with systemd-machined are - found in this slice. This is pulled in by - systemd-machined.service. - - - - @@ -1348,16 +1359,31 @@ default.target - This is the main target of the user session, started by default. Various services that - compose the normal user session should be pulled into this target. In this regard, - default.target is similar to multi-user.target in the - system instance, but it is a real unit, not an alias. + This is the main target of the user service manager, started by default when the service + manager is invoked. Various services that compose the normal user session should be pulled into + this target. In this regard, default.target is similar to + multi-user.target in the system instance, but it is a real unit, not an + alias. + + + capsule@.target + + This is the main target of capsule service managers, started by default, instantiated with + the capsule name. This may be used to define different sets of units that are started for + different capsules via generic unit definitions. For details about capsules see + capsule@.service5. + + + + + + In addition, the following units are available which have definitions similar to their system counterparts: exit.target, diff --git a/man/user-system-options.xml b/man/user-system-options.xml index 952ac18a4f9..b7d7882171c 100644 --- a/man/user-system-options.xml +++ b/man/user-system-options.xml @@ -55,4 +55,15 @@ implied. + + + + + + + Execute operation on a capsule. Specify a capsule name to connect to. See + capsule@.service5 for + details about capsules. + + diff --git a/man/user@.service.xml b/man/user@.service.xml index 819fd6feace..ba57f1b3316 100644 --- a/man/user@.service.xml +++ b/man/user@.service.xml @@ -188,6 +188,7 @@ TasksMax=33% systemd.resource-control5 systemd.exec5 systemd.special7 + capsule@.service5 pam8