Merging upstream version 4.23.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 180 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man5/capsule@.service.5 b/upstream/debian-unstable/man5/capsule@.service.5
new file mode 100644
index 00000000..b18401aa
--- /dev/null
+++ b/upstream/debian-unstable/man5/capsule@.service.5
@@ -0,0 +1,180 @@
+'\" t
+.TH "CAPSULE@\&.SERVICE" "5" "" "systemd 256~rc3" "capsule@.service"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+capsule@.service \- System unit for the capsule service manager
+.SH "SYNOPSIS"
+.PP
+capsule@\fINAME\fR\&.service
+.SH "DESCRIPTION"
+.PP
+Service managers for capsules run in
+capsule@\fINAME\fR\&.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\&.
+.PP
+In many ways
+capsule@\&.service
+is similar to the per\-user
+user@\&.service
+service manager, but there are a few important distinctions:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The capsule service manager utilizes
+\fIDynamicUser=\fR
+(see
+\fBsystemd.exec\fR(5)) 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\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+User service managers register themselves with
+\fBpam\fR(8), capsule service managers do not\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+User service managers typically read their configuration from a
+\fI$HOME\fR
+directory below
+/home/, capsule service managers from a
+\fI$HOME\fR
+directory below
+/var/lib/capsules/\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+User service managers are collectively contained in the
+user\&.slice
+unit, capsule service managers in
+capsule\&.slice\&. Also see
+\fBsystemd.special\fR(7)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+User service managers start the user unit
+default\&.target
+initially\&. Capsule service managers invoke the user unit
+capsule@\&.target
+instead\&.
+.RE
+.PP
+The capsule service manager and the capsule\*(Aqs bus broker can be reached via the
+\fB\-\-capsule=\fR
+switch to
+\fBsystemctl\fR(1),
+\fBsystemd-run\fR(1)
+and
+\fBbusctl\fR(1)\&.
+.PP
+New capsules can be started via a simple
+\fBsystemctl start capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR
+command, and stopped via
+\fBsystemctl stop capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR\&. Starting a capsule will implicitly create a home directory
+/var/lib/capsules/\fINAME\fR/, if missing\&. A runtime directory is created as
+/run/capsules/\fINAME\fR/\&. To remove these resources use
+\fBsystemctl clean capsule@\fR\fB\fINAME\fR\fR\fB\&.service\fR, for example with the
+\fB\-\-what=all\fR
+switch\&.
+.PP
+The
+capsule@\&.service
+unit invokes a
+\fBsystemd \-\-user\fR
+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/\fINAME\fR/\&.config/systemd/user/\&.
+.PP
+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
+\m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[1]\d\s+2
+for details\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# 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
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBuser@.service\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)
+.SH "NOTES"
+.IP " 1." 4
+User/Group Name Syntax
+.RS 4
+\%https://systemd.io/USER_NAMES
+.RE