man/capsule@.service.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="capsule_.service">
   7   <refentryinfo>
   8     <title>capsule@.service</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>capsule@.service</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>capsule@.service</refname>
  19     <refpurpose>System unit for the capsule service manager</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename>capsule@<replaceable>NAME</replaceable>.service</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>Service managers for capsules run in
  30     <filename>capsule@<replaceable>NAME</replaceable>.service</filename> system units, with the capsule name as the
  31     instance identifier. Capsules are way to run additional instances of the service manager, under dynamic
  32     user IDs, i.e. UIDs that are allocated when the capsule service manager is started, and released when it
  33     is stopped.</para>
  34
  35     <para>In many ways <filename>capsule@.service</filename> is similar to the per-user
  36     <filename>user@.service</filename> service manager, but there are a few important distinctions:</para>
  37
  38     <itemizedlist>
  39       <listitem><para>The capsule service manager utilizes <varname>DynamicUser=</varname> (see
  40       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>) to
  41       allocate a new UID dynamically on invocation. The user name is automatically generated from the capsule
  42       name, by prefixng <literal>p_</literal>. The UID is released when the service is terminated. The user
  43       service manager on the other hand operates under a statically allocated user ID that must be
  44       pre-existing, before the user service manager is invoked.</para></listitem>
  45
  46       <listitem><para>User service managers register themselves with <citerefentry
  47       project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, capsule
  48       service managers do not.</para></listitem>
  49
  50       <listitem><para>User service managers typically read their configuration from a
  51       <varname>$HOME</varname> directory below <filename>/home/</filename>, capsule service managers from a
  52       <varname>$HOME</varname> directory below <filename>/var/lib/capsules/</filename>.</para></listitem>
  53
  54       <listitem><para>User service managers are collectively contained in the <filename>user.slice</filename>
  55       unit, capsule service managers in <filename>capsule.slice</filename>. Also see
  56       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
  57
  58       <listitem><para>User service managers start the user unit <filename>default.target</filename>
  59       initially. Capsule service managers invoke the user unit <filename>capsule@.target</filename>
  60       instead.</para></listitem>
  61     </itemizedlist>
  62
  63     <para>The capsule service manager and the capsule's bus broker can be reached via the
  64     <option>--capsule=</option> switch to
  65     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  66     <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
  67     <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  68
  69     <para>New capsules can be started via a simple <command>systemctl start
  70     capsule@<replaceable>NAME</replaceable>.service</command> command, and stopped via <command>systemctl
  71     stop capsule@<replaceable>NAME</replaceable>.service</command>. Starting a capsule will implicitly create
  72     a home directory <filename>/var/lib/capsules/<replaceable>NAME</replaceable>/</filename>, if missing. A
  73     runtime directory is created as <filename>/run/capsules/<replaceable>NAME</replaceable>/</filename>. To
  74     remove these resources use <command>systemctl clean capsule@<replaceable>NAME</replaceable>.service</command>,
  75     for example with the <option>--what=all</option> switch.</para>
  76
  77     <para>The <filename>capsule@.service</filename> unit invokes a <command>systemd --user</command>
  78     service manager process. This means unit files are looked for according to the sames rules as for regular user
  79     service managers, for example in
  80     <filename>/var/lib/capsules/<replaceable>NAME</replaceable>/.config/systemd/user/</filename>.</para>
  81
  82     <para>Capsule names may be chosen freely by the user, however, they must be suitable as UNIX filenames
  83     (i.e. 255 characters max, and contain no <literal>/</literal>), and when prefixed with
  84     <literal>p-</literal> be suitable as a user name matching strict POSIX rules, see <ulink
  85     url="https://systemd.io/USER_NAMES">User/Group Name Syntax</ulink> for details.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Examples</title>
  90     <example>
  91       <title>Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up</title>
  92
  93       <programlisting># systemctl start capsule@tatze.service
  94 # systemd-run --capsule=tatze --unit=sleeptest.service sleep 999
  95 # systemctl --capsule=tatze status sleeptest.service
  96 # systemd-run -t --capsule=tatze bash
  97 # systemctl --capsule=tatze stop sleeptest.service
  98 # systemctl stop capsule@tatze.service
  99 # systemctl clean --all capsule@tatze.service</programlisting>
 100     </example>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>See Also</title>
 105     <para>
 106       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 107       <citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 108       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 109       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 110       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 111       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 112       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 113       <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 114       <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 115       <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 116     </para>
 117   </refsect1>
 118 </refentry>