Debian Codegraph @

upstream/debian-unstable/man5/[email protected]

raw
1 '\" t
2 .TH "CAPSULE@\&.SERVICE" "5" "" "systemd 261~rc3" "[email protected]"
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 [email protected] \- System unit for the capsule service manager
24 .SH "SYNOPSIS"
25 .PP
26 capsule@\fINAME\fR\&.service
27 .SH "DESCRIPTION"
28 .PP
29 Service managers for capsules run in
30 capsule@\fINAME\fR\&.service
31 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\&.
32 .PP
33 In many ways
34 capsule@\&.service
35 is similar to the per\-user
36 user@\&.service
37 service manager, but there are a few important distinctions:
38 .sp
39 .RS 4
40 .ie n \{\
41 \h'-04'\(bu\h'+03'\c
42 .\}
43 .el \{\
44 .sp -1
45 .IP \(bu 2.3
46 .\}
47 The capsule service manager utilizes
48 \fIDynamicUser=\fR
49 (see
50 \fBsystemd.exec\fR(5)) to allocate a new UID dynamically on invocation\&. The user name is automatically generated from the capsule name, by prefixing
51 "c\-"\&. 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\&.
52 .RE
53 .sp
54 .RS 4
55 .ie n \{\
56 \h'-04'\(bu\h'+03'\c
57 .\}
58 .el \{\
59 .sp -1
60 .IP \(bu 2.3
61 .\}
62 User service managers register themselves with
63 \fBpam\fR(8), capsule service managers do not\&.
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 User service managers typically read their configuration from a
75 \fI$HOME\fR
76 directory below
77 /home/, capsule service managers from a
78 \fI$HOME\fR
79 directory below
80 /var/lib/capsules/\&.
81 .RE
82 .sp
83 .RS 4
84 .ie n \{\
85 \h'-04'\(bu\h'+03'\c
86 .\}
87 .el \{\
88 .sp -1
89 .IP \(bu 2.3
90 .\}
91 User service managers are collectively contained in the
92 user\&.slice
93 unit, capsule service managers in
94 capsule\&.slice\&. Also see
95 \fBsystemd.special\fR(7)\&.
96 .RE
97 .sp
98 .RS 4
99 .ie n \{\
100 \h'-04'\(bu\h'+03'\c
101 .\}
102 .el \{\
103 .sp -1
104 .IP \(bu 2.3
105 .\}
106 User service managers start the user unit
107 default\&.target
108 initially\&. Capsule service managers invoke the user unit
109 capsule@\&.target
110 instead\&.
111 .RE
112 .PP
113 The capsule service manager and the capsule\*(Aqs bus broker can be reached via the
114 \fB\-\-capsule=\fR
115 switch to
116 \fBsystemctl\fR(1),
117 \fBsystemd-run\fR(1)
118 and
119 \fBbusctl\fR(1)\&.
120 .PP
121 New capsules can be started via a simple
122 \fBsystemctl start capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR
123 command, and stopped via
124 \fBsystemctl stop capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR\&. Starting a capsule will implicitly create a home directory
125 /var/lib/capsules/\fINAME\fR/, if missing\&. A runtime directory is created as
126 /run/capsules/\fINAME\fR/\&. To remove these resources use
127 \fBsystemctl clean capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR, for example with the
128 \fB\-\-what=all\fR
129 switch\&.
130 .PP
131 The
132 capsule@\&.service
133 unit invokes a
134 \fBsystemd \-\-user\fR
135 service manager process\&. This means unit files are looked for according to the sames rules as for regular user service managers, for example in
136 /var/lib/capsules/\fINAME\fR/\&.config/systemd/user/\&.
137 .PP
138 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
139 "/"), and when prefixed with
140 "c\-"
141 be suitable as a user name matching strict POSIX rules, see
142 \m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[1]\d\s+2
143 for details\&.
144 .PP
145 Added in version 256\&.
146 .SH "EXAMPLES"
147 .PP
148 \fBExample\ \&1.\ \&Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up\fR
149 .sp
150 .if n \{\
151 .RS 4
152 .\}
153 .nf
154 # systemctl start capsule@tatze\&.service
155 # systemd\-run \-\-capsule=tatze \-\-unit=sleeptest\&.service sleep 999
156 # systemctl \-\-capsule=tatze status sleeptest\&.service
157 # systemd\-run \-t \-\-capsule=tatze bash
158 # systemctl \-\-capsule=tatze stop sleeptest\&.service
159 # systemctl stop capsule@tatze\&.service
160 # systemctl clean \-\-all capsule@tatze\&.service
161 .fi
162 .if n \{\
163 .RE
164 .\}
165 .SH "SEE ALSO"
166 .PP
167 \fBsystemd\fR(1), \[email protected]\fR(5), \fBsystemd.service\fR(5), \fBsystemd.slice\fR(5), \fBsystemd.exec\fR(5), \fBsystemd.special\fR(7), \fBsystemctl\fR(1), \fBsystemd-run\fR(1), \fBbusctl\fR(1), \fBpam\fR(8)
168 .SH "NOTES"
169 .IP " 1." 4
170 User/Group Name Syntax
171 .RS 4
172 \%https://systemd.io/USER_NAMES
173 .RE