Package: util-linux
Version: 2.40.2-8
Severity: normal
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: file '<stdin>':416
troff:<stdin>:416: warning: [page 7, 2.7i]: cannot break line
troff: backtrace: file '<stdin>':421
troff:<stdin>:421: warning: [page 7, 3.2i]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.10.9-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages util-linux depends on:
ii libblkid1 2.40.2-8
ii libc6 2.40-2
ii libcap-ng0 0.8.5-2
ii libcrypt1 1:4.4.36-5
ii libmount1 2.40.2-8
ii libpam-modules 1.5.3-7
ii libpam-runtime 1.5.3-7
ii libpam0g 1.5.3-7
ii libselinux1 3.7-3
ii libsmartcols1 2.40.2-8
ii libsystemd0 256.6-1
ii libtinfo6 6.5-2
ii libudev1 256.6-1
ii libuuid1 2.40.2-8
Versions of packages util-linux recommends:
ii sensible-utils 0.0.24
Versions of packages util-linux suggests:
pn dosfstools <none>
ii kbd 2.6.4-2
ii util-linux-extra 2.40.2-8
pn util-linux-locales <none>
ii wtmpdb 0.13.0-1
-- no debconf information
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of \'nroff -mandoc\'
Add the option \'-t\', if the file contains a table.
Read the output of \'diff -u\' with \'less -R\' or similar.
-.-.
If \'man\' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint unshare.1": (possibly shortened list)
mandoc: unshare.1:33:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:36:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:37:235: STYLE: input text line longer than 80 bytes: The
\fBunshare\fP co...
mandoc: unshare.1:39:621: STYLE: input text line longer than 80 bytes: By
default, a new na...
mandoc: unshare.1:47:317: STYLE: input text line longer than 80 bytes: Mounting
and unmount...
mandoc: unshare.1:54:120: STYLE: input text line longer than 80 bytes: Setting
hostname or ...
mandoc: unshare.1:59:200: STYLE: input text line longer than 80 bytes: The
process will hav...
mandoc: unshare.1:64:220: STYLE: input text line longer than 80 bytes: The
process will hav...
mandoc: unshare.1:69:131: STYLE: input text line longer than 80 bytes: Children
will have a...
mandoc: unshare.1:74:188: STYLE: input text line longer than 80 bytes: The
process will hav...
mandoc: unshare.1:79:119: STYLE: input text line longer than 80 bytes: The
process will hav...
mandoc: unshare.1:84:200: STYLE: input text line longer than 80 bytes: The
process can have...
mandoc: unshare.1:87:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:90:133: STYLE: input text line longer than 80 bytes: Create a
new IPC nam...
mandoc: unshare.1:95:365: STYLE: input text line longer than 80 bytes: Create a
new mount n...
mandoc: unshare.1:100:137: STYLE: input text line longer than 80 bytes: Create
a new network...
mandoc: unshare.1:105:236: STYLE: input text line longer than 80 bytes: Create
a new PID nam...
mandoc: unshare.1:112:133: STYLE: input text line longer than 80 bytes: Create
a new UTS nam...
mandoc: unshare.1:117:134: STYLE: input text line longer than 80 bytes: Create
a new user na...
mandoc: unshare.1:122:136: STYLE: input text line longer than 80 bytes: Create
a new cgroup ...
mandoc: unshare.1:127:260: STYLE: input text line longer than 80 bytes: Create
a new time na...
mandoc: unshare.1:132:362: STYLE: input text line longer than 80 bytes: Fork
the specified \...
mandoc: unshare.1:137:131: STYLE: input text line longer than 80 bytes: When
the \fB\-\-user...
mandoc: unshare.1:142:298: STYLE: input text line longer than 80 bytes: When
\fBunshare\fP t...
mandoc: unshare.1:147:381: STYLE: input text line longer than 80 bytes: Just
before running ...
mandoc: unshare.1:152:360: STYLE: input text line longer than 80 bytes: Just
before running ...
mandoc: unshare.1:157:204: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:162:838: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:164:268: STYLE: input text line longer than 80 bytes: Before
util\-linux v...
mandoc: unshare.1:169:234: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:174:847: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:176:268: STYLE: input text line longer than 80 bytes: Before
util\-linux v...
mandoc: unshare.1:181:508: STYLE: input text line longer than 80 bytes: Map the
first block ...
mandoc: unshare.1:186:670: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:191:297: STYLE: input text line longer than 80 bytes: Run the
program only...
mandoc: unshare.1:196:292: STYLE: input text line longer than 80 bytes:
Recursively set the ...
mandoc: unshare.1:203:500: STYLE: input text line longer than 80 bytes: To be
able to call \...
mandoc: unshare.1:223:91: STYLE: input text line longer than 80 bytes: Set the
group ID whi...
mandoc: unshare.1:228:224: STYLE: input text line longer than 80 bytes: Load
binfmt_misc def...
mandoc: unshare.1:230:235: STYLE: input text line longer than 80 bytes: To
manage the F flag...
mandoc: unshare.1:235:158: STYLE: input text line longer than 80 bytes: Set the
offset of \f...
mandoc: unshare.1:240:157: STYLE: input text line longer than 80 bytes: Set the
offset of \f...
mandoc: unshare.1:253:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:254:286: STYLE: input text line longer than 80 bytes: The
proc and sysfs f...
mandoc: unshare.1:256:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:257:505: STYLE: input text line longer than 80 bytes: The
following comman...
mandoc: unshare.1:268:133: STYLE: input text line longer than 80 bytes: As an
unprivileged u...
mandoc: unshare.1:285:388: STYLE: input text line longer than 80 bytes: As an
unprivileged u...
mandoc: unshare.1:310:441: STYLE: input text line longer than 80 bytes: The
first of the fol...
mandoc: unshare.1:324:295: STYLE: input text line longer than 80 bytes: The
following comman...
mandoc: unshare.1:337:221: STYLE: input text line longer than 80 bytes: The
following comman...
mandoc: unshare.1:360:474: STYLE: input text line longer than 80 bytes: The
\fBpidof\fP(1) c...
mandoc: unshare.1:380:137: STYLE: input text line longer than 80 bytes: The
following exampl...
mandoc: unshare.1:393:164: STYLE: input text line longer than 80 bytes: The
following exampl...
mandoc: unshare.1:408:102: STYLE: input text line longer than 80 bytes: is the
name of the n...
mandoc: unshare.1:418:95: STYLE: input text line longer than 80 bytes: is the
magic number ...
mandoc: unshare.1:433:123: STYLE: input text line longer than 80 bytes: the
file is open by ...
mandoc: unshare.1:437:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:441:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:449:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:453:2: WARNING: skipping paragraph macro: sp after SH
mandoc: unshare.1:454:92: STYLE: input text line longer than 80 bytes: The
\fBunshare\fP co...
-.-.
Lines containing '\c' (' \c' does not make sense):
228:Load binfmt_misc definition in the namespace (implies
\fB\-\-mount\-binfmt\fP). The \fIstring\fP argument is
\f(CR:name:type:offset:magic:mask:interpreter:flags\fP. For more details about
new binary type registration see \c
450:For bug reports, use the issue tracker at \c
454:The \fBunshare\fP command is part of the util\-linux package which can be
downloaded from \c
-.-
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B.
The number of lines affected can be too large to be in a patch.
37:The \fBunshare\fP command creates new namespaces (as specified by the
command\-line options described below) and then executes the specified
\fIprogram\fP. If \fIprogram\fP is not given, then "${SHELL}" is run (default:
\fI/bin/sh\fP).
39:By default, a new namespace persists only as long as it has member
processes. A new namespace can be made persistent even when it has no member
processes by bind mounting /proc/\fIpid\fP/ns/\fItype\fP files to a filesystem
path. A namespace that has been made persistent in this way can subsequently be
entered with \fBnsenter\fP(1) even after the \fIprogram\fP terminates (except
PID namespaces where a permanently running init process is required). Once a
persistent namespace is no longer needed, it can be unpersisted by using
\fBumount\fP(8) to remove the bind mount. See the \fBEXAMPLES\fP section for
more details.
41:\fBunshare\fP since util\-linux version 2.36 uses
\fI/proc/[pid]/ns/pid_for_children\fP and
\fI/proc/[pid]/ns/time_for_children\fP files for persistent PID and TIME
namespaces. This change requires Linux kernel 4.17 or newer.
47:Mounting and unmounting filesystems will not affect the rest of the system,
except for filesystems which are explicitly marked as shared (with \fBmount
\-\-make\-shared\fP; see \fI/proc/self/mountinfo\fP or \fBfindmnt
\-o+PROPAGATION\fP for the \fBshared\fP flags). For further details, see
\fBmount_namespaces\fP(7).
49:\fBunshare\fP since util\-linux version 2.27 automatically sets propagation
to \fBprivate\fP in a new mount namespace to make sure that the new namespace
is really unshared. It\(cqs possible to disable this feature with option
\fB\-\-propagation unchanged\fP. Note that \fBprivate\fP is the kernel default.
54:Setting hostname or domainname will not affect the rest of the system. For
further details, see \fButs_namespaces\fP(7).
59:The process will have an independent namespace for POSIX message queues as
well as System V message queues, semaphore sets and shared memory segments. For
further details, see \fBipc_namespaces\fP(7).
64:The process will have independent IPv4 and IPv6 stacks, IP routing tables,
firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
sockets, etc. For further details, see \fBnetwork_namespaces\fP(7).
69:Children will have a distinct set of PID\-to\-process mappings from their
parent. For further details, see \fBpid_namespaces\fP(7).
74:The process will have a virtualized view of \fI/proc/self/cgroup\fP, and new
cgroup mounts will be rooted at the namespace cgroup root. For further details,
see \fBcgroup_namespaces\fP(7).
79:The process will have a distinct set of UIDs, GIDs and capabilities. For
further details, see \fBuser_namespaces\fP(7).
84:The process can have a distinct view of \fBCLOCK_MONOTONIC\fP and/or
\fBCLOCK_BOOTTIME\fP which can be changed using
\fI/proc/self/timens_offsets\fP. For further details, see
\fBtime_namespaces\fP(7).
90:Create a new IPC namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP.
95:Create a new mount namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP. Note that \fIfile\fP
must be located on a mount whose propagation type is not \fBshared\fP (or an
error results). Use the command \fBfindmnt \-o+PROPAGATION\fP when not sure
about the current setting. See also the examples below.
100:Create a new network namespace. If \fIfile\fP is specified, then the
namespace is made persistent by creating a bind mount at \fIfile\fP.
105:Create a new PID namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP. (Creation of a
persistent PID namespace will fail if the \fB\-\-fork\fP option is not also
specified.)
112:Create a new UTS namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP.
117:Create a new user namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP.
122:Create a new cgroup namespace. If \fIfile\fP is specified, then the
namespace is made persistent by creating a bind mount at \fIfile\fP.
127:Create a new time namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP. The
\fB\-\-monotonic\fP and \fB\-\-boottime\fP options can be used to specify the
corresponding offset in the time namespace.
132:Fork the specified \fIprogram\fP as a child process of \fBunshare\fP rather
than running it directly. This is useful when creating a new PID namespace.
Note that when \fBunshare\fP is waiting for the child process, then it ignores
\fBSIGINT\fP and \fBSIGTERM\fP and does not forward any signals to the child.
It is necessary to send signals to the child process.
142:When \fBunshare\fP terminates, have \fIsigname\fP be sent to the forked
child process. Combined with \fB\-\-pid\fP this allows for an easy and reliable
killing of the entire process tree below \fBunshare\fP. If not given,
\fIsigname\fP defaults to \fBSIGKILL\fP. This option implies \fB\-\-fork\fP.
147:Just before running the program, mount the proc filesystem at
\fImountpoint\fP (default is \fI/proc\fP). This is useful when creating a new
PID namespace. It also implies creating a new mount namespace since the
\fI/proc\fP mount would otherwise mess up existing programs on the system. The
new proc filesystem is explicitly mounted as private (with
\fBMS_PRIVATE\fP|\fBMS_REC\fP).
157:Run the program only after the current effective user ID has been mapped to
\fIuid\fP. If this option is specified multiple times, the last occurrence
takes precedence. This option implies \fB\-\-user\fP.
162:Run the program only after the block of user IDs of size \fIcount\fP
beginning at \fIouteruid\fP has been mapped to the block of user IDs beginning
at \fIinneruid\fP. This mapping is created with \fBnewuidmap\fP(1) if
\fBunshare\fP was run unprivileged. If the range of user IDs overlaps with the
mapping specified by \fB\-\-map\-user\fP, then a "hole" will be removed from
the mapping. This may result in the highest user ID of the mapping not being
mapped. Use \fB\-\-map\-users\fP multiple times to map more than one block of
user IDs. The special value \fBauto\fP will map the first block of user IDs
owned by the effective user from \fI/etc/subuid\fP to a block starting at user
ID 0. The special value \fBall\fP will create a pass\-through map for every
user ID available in the parent namespace. This option implies \fB\-\-user\fP.
169:Run the program only after the current effective group ID has been mapped
to \fIgid\fP. If this option is specified multiple times, the last occurrence
takes precedence. This option implies \fB\-\-setgroups=deny\fP and
\fB\-\-user\fP.
174:Run the program only after the block of group IDs of size \fIcount\fP
beginning at \fIoutergid\fP has been mapped to the block of group IDs beginning
at \fIinnergid\fP. This mapping is created with \fBnewgidmap\fP(1) if
\fBunshare\fP was run unprivileged. If the range of group IDs overlaps with the
mapping specified by \fB\-\-map\-group\fP, then a "hole" will be removed from
the mapping. This may result in the highest group ID of the mapping not being
mapped. Use \fB\-\-map\-groups\fP multiple times to map more than one block of
group IDs. The special value \fBauto\fP will map the first block of user IDs
owned by the effective user from \fI/etc/subgid\fP to a block starting at group
ID 0. The special value \fBall\fP will create a pass\-through map for every
group ID available in the parent namespace. This option implies \fB\-\-user\fP.
181:Map the first block of user IDs owned by the effective user from
\fI/etc/subuid\fP to a block starting at user ID 0. In the same manner, also
map the first block of group IDs owned by the effective group from
\fI/etc/subgid\fP to a block starting at group ID 0. This option is intended to
handle the common case where the first block of subordinate user and group IDs
can map the whole user and group ID space. This option is equivalent to
specifying \fB\-\-map\-users=auto\fP and \fB\-\-map\-groups=auto\fP.
186:Run the program only after the current effective user and group IDs have
been mapped to the superuser UID and GID in the newly created user namespace.
This makes it possible to conveniently gain capabilities needed to manage
various aspects of the newly created namespaces (such as configuring interfaces
in the network namespace or mounting filesystems in the mount namespace) even
when run unprivileged. As a mere convenience feature, it does not support more
sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. This
option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is
equivalent to \fB\-\-map\-user=0 \-\-map\-group=0\fP.
191:Run the program only after the current effective user and group IDs have
been mapped to the same UID and GID in the newly created user namespace. This
option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is
equivalent to \fB\-\-map\-user=$(id \-ru) \-\-map\-group=$(id \-rg)\fP.
196:Recursively set the mount propagation flag in the new mount namespace. The
default is to set the propagation to \fIprivate\fP. It is possible to disable
this feature with the argument \fBunchanged\fP. The option is silently ignored
when the mount namespace (\fB\-\-mount\fP) is not requested.
203:To be able to call \fBsetgroups\fP(2), the calling process must at least
have \fBCAP_SETGID\fP. But since Linux 3.19 a further restriction applies: the
kernel gives permission to call \fBsetgroups\fP(2) only after the GID map
(\fB/proc/\fP\fIpid\fP*/gid_map*) has been set. The GID map is writable by root
when \fBsetgroups\fP(2) is enabled (i.e., \fBallow\fP, the default), and the
GID map becomes writable by unprivileged processes when \fBsetgroups\fP(2) is
permanently disabled (with \fBdeny\fP).
228:Load binfmt_misc definition in the namespace (implies
\fB\-\-mount\-binfmt\fP). The \fIstring\fP argument is
\f(CR:name:type:offset:magic:mask:interpreter:flags\fP. For more details about
new binary type registration see \c
235:Set the offset of \fBCLOCK_MONOTONIC\fP which will be used in the entered
time namespace. This option requires unsharing a time namespace with
\fB\-\-time\fP.
240:Set the offset of \fBCLOCK_BOOTTIME\fP which will be used in the entered
time namespace. This option requires unsharing a time namespace with
\fB\-\-time\fP.
254:The proc and sysfs filesystems mounting as root in a user namespace have to
be restricted so that a less privileged user cannot get more access to
sensitive files that a more privileged user made unavailable. In short the rule
for proc and sysfs is as close to a bind mount as possible.
257:The following command creates a PID namespace, using \fB\-\-fork\fP to
ensure that the executed command is performed in a child process that (being
the first process in the namespace) has PID 1. The \fB\-\-mount\-proc\fP option
ensures that a new mount namespace is also simultaneously created and that a
new \fBproc\fP(5) filesystem is mounted that contains information corresponding
to the new PID namespace. When the \fBreadlink\fP(1) command terminates, the
new namespaces are automatically torn down.
285:As an unprivileged user, create a user namespace where the first 65536 IDs
are all mapped, and the user\(cqs credentials are mapped to the root IDs inside
the namespace. The map is determined by the subordinate IDs assigned in
\fBsubuid\fP(5) and \fBsubgid\fP(5). Demonstrate this mapping by creating a
file with user ID 1 and group ID 1. For brevity, only the user ID mappings are
shown:
310:The first of the following commands creates a new persistent UTS namespace
and modifies the hostname as seen in that namespace. The namespace is then
entered with \fBnsenter\fP(1) in order to display the modified hostname; this
step demonstrates that the UTS namespace continues to exist even though the
namespace had no member processes after the \fBunshare\fP command terminated.
The namespace is then destroyed by removing the bind mount.
324:The following commands establish a persistent mount namespace referenced by
the bind mount \fI/root/namespaces/mnt\fP. In order to ensure that the creation
of that bind mount succeeds, the parent directory (\fI/root/namespaces\fP) is
made a bind mount whose propagation type is not \fBshared\fP.
360:The \fBpidof\fP(1) command prints no output, because the \fBsleep\fP
processes have been killed. More precisely, when the \fBsleep\fP process that
has PID 1 in the namespace (i.e., the namespace\(cqs init process) was killed,
this caused all other processes in the namespace to be killed. By contrast, a
similar series of commands where the \fB\-\-kill\-child\fP option is not used
shows that when \fBunshare\fP terminates, the processes in the PID namespace
are not killed:
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
N.B.
The number of lines affected can be too large to be in a patch.
Line 37, length 235
The \fBunshare\fP command creates new namespaces (as specified by the
command\-line options described below) and then executes the specified
\fIprogram\fP. If \fIprogram\fP is not given, then "${SHELL}" is run (default:
\fI/bin/sh\fP).
Line 39, length 621
By default, a new namespace persists only as long as it has member processes. A
new namespace can be made persistent even when it has no member processes by
bind mounting /proc/\fIpid\fP/ns/\fItype\fP files to a filesystem path. A
namespace that has been made persistent in this way can subsequently be entered
with \fBnsenter\fP(1) even after the \fIprogram\fP terminates (except PID
namespaces where a permanently running init process is required). Once a
persistent namespace is no longer needed, it can be unpersisted by using
\fBumount\fP(8) to remove the bind mount. See the \fBEXAMPLES\fP section for
more details.
Line 41, length 225
\fBunshare\fP since util\-linux version 2.36 uses
\fI/proc/[pid]/ns/pid_for_children\fP and
\fI/proc/[pid]/ns/time_for_children\fP files for persistent PID and TIME
namespaces. This change requires Linux kernel 4.17 or newer.
Line 47, length 317
Mounting and unmounting filesystems will not affect the rest of the system,
except for filesystems which are explicitly marked as shared (with \fBmount
\-\-make\-shared\fP; see \fI/proc/self/mountinfo\fP or \fBfindmnt
\-o+PROPAGATION\fP for the \fBshared\fP flags). For further details, see
\fBmount_namespaces\fP(7).
Line 49, length 306
\fBunshare\fP since util\-linux version 2.27 automatically sets propagation to
\fBprivate\fP in a new mount namespace to make sure that the new namespace is
really unshared. It\(cqs possible to disable this feature with option
\fB\-\-propagation unchanged\fP. Note that \fBprivate\fP is the kernel default.
Line 54, length 120
Setting hostname or domainname will not affect the rest of the system. For
further details, see \fButs_namespaces\fP(7).
Line 59, length 200
The process will have an independent namespace for POSIX message queues as well
as System V message queues, semaphore sets and shared memory segments. For
further details, see \fBipc_namespaces\fP(7).
Line 64, length 220
The process will have independent IPv4 and IPv6 stacks, IP routing tables,
firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
sockets, etc. For further details, see \fBnetwork_namespaces\fP(7).
Line 69, length 131
Children will have a distinct set of PID\-to\-process mappings from their
parent. For further details, see \fBpid_namespaces\fP(7).
Line 74, length 188
The process will have a virtualized view of \fI/proc/self/cgroup\fP, and new
cgroup mounts will be rooted at the namespace cgroup root. For further details,
see \fBcgroup_namespaces\fP(7).
Line 79, length 119
The process will have a distinct set of UIDs, GIDs and capabilities. For
further details, see \fBuser_namespaces\fP(7).
Line 84, length 200
The process can have a distinct view of \fBCLOCK_MONOTONIC\fP and/or
\fBCLOCK_BOOTTIME\fP which can be changed using
\fI/proc/self/timens_offsets\fP. For further details, see
\fBtime_namespaces\fP(7).
Line 90, length 133
Create a new IPC namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP.
Line 95, length 365
Create a new mount namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP. Note that \fIfile\fP
must be located on a mount whose propagation type is not \fBshared\fP (or an
error results). Use the command \fBfindmnt \-o+PROPAGATION\fP when not sure
about the current setting. See also the examples below.
Line 100, length 137
Create a new network namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP.
Line 105, length 236
Create a new PID namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP. (Creation of a
persistent PID namespace will fail if the \fB\-\-fork\fP option is not also
specified.)
Line 112, length 133
Create a new UTS namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP.
Line 117, length 134
Create a new user namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP.
Line 122, length 136
Create a new cgroup namespace. If \fIfile\fP is specified, then the namespace
is made persistent by creating a bind mount at \fIfile\fP.
Line 127, length 260
Create a new time namespace. If \fIfile\fP is specified, then the namespace is
made persistent by creating a bind mount at \fIfile\fP. The \fB\-\-monotonic\fP
and \fB\-\-boottime\fP options can be used to specify the corresponding offset
in the time namespace.
Line 132, length 362
Fork the specified \fIprogram\fP as a child process of \fBunshare\fP rather
than running it directly. This is useful when creating a new PID namespace.
Note that when \fBunshare\fP is waiting for the child process, then it ignores
\fBSIGINT\fP and \fBSIGTERM\fP and does not forward any signals to the child.
It is necessary to send signals to the child process.
Line 137, length 131
When the \fB\-\-user\fP option is given, ensure that capabilities granted in
the user namespace are preserved in the child process.
Line 142, length 298
When \fBunshare\fP terminates, have \fIsigname\fP be sent to the forked child
process. Combined with \fB\-\-pid\fP this allows for an easy and reliable
killing of the entire process tree below \fBunshare\fP. If not given,
\fIsigname\fP defaults to \fBSIGKILL\fP. This option implies \fB\-\-fork\fP.
Line 147, length 381
Just before running the program, mount the proc filesystem at \fImountpoint\fP
(default is \fI/proc\fP). This is useful when creating a new PID namespace. It
also implies creating a new mount namespace since the \fI/proc\fP mount would
otherwise mess up existing programs on the system. The new proc filesystem is
explicitly mounted as private (with \fBMS_PRIVATE\fP|\fBMS_REC\fP).
Line 152, length 360
Just before running the program, mount the binfmt_misc filesystem at
\fImountpoint\fP (default is /proc/sys/fs/binfmt_misc). It also implies
creating a new mount namespace since the binfmt_misc mount would otherwise mess
up existing programs on the system. The new binfmt_misc filesystem is
explicitly mounted as private (with \fBMS_PRIVATE\fP|\fBMS_REC\fP).
Line 157, length 204
Run the program only after the current effective user ID has been mapped to
\fIuid\fP. If this option is specified multiple times, the last occurrence
takes precedence. This option implies \fB\-\-user\fP.
Line 162, length 838
Run the program only after the block of user IDs of size \fIcount\fP beginning
at \fIouteruid\fP has been mapped to the block of user IDs beginning at
\fIinneruid\fP. This mapping is created with \fBnewuidmap\fP(1) if
\fBunshare\fP was run unprivileged. If the range of user IDs overlaps with the
mapping specified by \fB\-\-map\-user\fP, then a "hole" will be removed from
the mapping. This may result in the highest user ID of the mapping not being
mapped. Use \fB\-\-map\-users\fP multiple times to map more than one block of
user IDs. The special value \fBauto\fP will map the first block of user IDs
owned by the effective user from \fI/etc/subuid\fP to a block starting at user
ID 0. The special value \fBall\fP will create a pass\-through map for every
user ID available in the parent namespace. This option implies \fB\-\-user\fP.
Line 164, length 268
Before util\-linux version 2.39, this option expected a comma\-separated
argument of the form \fIouteruid,inneruid,count\fP but that format is now
deprecated for consistency with the ordering used in \fI/proc/[pid]/uid_map\fP
and the \fIX\-mount.idmap\fP mount option.
Line 169, length 234
Run the program only after the current effective group ID has been mapped to
\fIgid\fP. If this option is specified multiple times, the last occurrence
takes precedence. This option implies \fB\-\-setgroups=deny\fP and
\fB\-\-user\fP.
Line 174, length 847
Run the program only after the block of group IDs of size \fIcount\fP beginning
at \fIoutergid\fP has been mapped to the block of group IDs beginning at
\fIinnergid\fP. This mapping is created with \fBnewgidmap\fP(1) if
\fBunshare\fP was run unprivileged. If the range of group IDs overlaps with the
mapping specified by \fB\-\-map\-group\fP, then a "hole" will be removed from
the mapping. This may result in the highest group ID of the mapping not being
mapped. Use \fB\-\-map\-groups\fP multiple times to map more than one block of
group IDs. The special value \fBauto\fP will map the first block of user IDs
owned by the effective user from \fI/etc/subgid\fP to a block starting at group
ID 0. The special value \fBall\fP will create a pass\-through map for every
group ID available in the parent namespace. This option implies \fB\-\-user\fP.
Line 176, length 268
Before util\-linux version 2.39, this option expected a comma\-separated
argument of the form \fIoutergid,innergid,count\fP but that format is now
deprecated for consistency with the ordering used in \fI/proc/[pid]/gid_map\fP
and the \fIX\-mount.idmap\fP mount option.
Line 181, length 508
Map the first block of user IDs owned by the effective user from
\fI/etc/subuid\fP to a block starting at user ID 0. In the same manner, also
map the first block of group IDs owned by the effective group from
\fI/etc/subgid\fP to a block starting at group ID 0. This option is intended to
handle the common case where the first block of subordinate user and group IDs
can map the whole user and group ID space. This option is equivalent to
specifying \fB\-\-map\-users=auto\fP and \fB\-\-map\-groups=auto\fP.
Line 186, length 670
Run the program only after the current effective user and group IDs have been
mapped to the superuser UID and GID in the newly created user namespace. This
makes it possible to conveniently gain capabilities needed to manage various
aspects of the newly created namespaces (such as configuring interfaces in the
network namespace or mounting filesystems in the mount namespace) even when run
unprivileged. As a mere convenience feature, it does not support more
sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. This
option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is
equivalent to \fB\-\-map\-user=0 \-\-map\-group=0\fP.
Line 191, length 297
Run the program only after the current effective user and group IDs have been
mapped to the same UID and GID in the newly created user namespace. This option
implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is equivalent
to \fB\-\-map\-user=$(id \-ru) \-\-map\-group=$(id \-rg)\fP.
Line 196, length 292
Recursively set the mount propagation flag in the new mount namespace. The
default is to set the propagation to \fIprivate\fP. It is possible to disable
this feature with the argument \fBunchanged\fP. The option is silently ignored
when the mount namespace (\fB\-\-mount\fP) is not requested.
Line 203, length 500
To be able to call \fBsetgroups\fP(2), the calling process must at least have
\fBCAP_SETGID\fP. But since Linux 3.19 a further restriction applies: the
kernel gives permission to call \fBsetgroups\fP(2) only after the GID map
(\fB/proc/\fP\fIpid\fP*/gid_map*) has been set. The GID map is writable by root
when \fBsetgroups\fP(2) is enabled (i.e., \fBallow\fP, the default), and the
GID map becomes writable by unprivileged processes when \fBsetgroups\fP(2) is
permanently disabled (with \fBdeny\fP).
Line 223, length 91
Set the group ID which will be used in the entered namespace and drop
supplementary groups.
Line 228, length 224
Load binfmt_misc definition in the namespace (implies \fB\-\-mount\-binfmt\fP).
The \fIstring\fP argument is
\f(CR:name:type:offset:magic:mask:interpreter:flags\fP. For more details about
new binary type registration see \c
Line 229, length 84
.URL "https://www.kernel.org/doc/Documentation/admin\-guide/binfmt\-misc.rst";
"" "."
Line 230, length 235
To manage the F flag in \f(CRflags\fP with \fB\-\-root\fP parameter,
binfmt_misc is mounted twice, once before the chroot to load the interpreter
from the caller filesystem and once after to make it available from the chroot
userspace.
Line 235, length 158
Set the offset of \fBCLOCK_MONOTONIC\fP which will be used in the entered time
namespace. This option requires unsharing a time namespace with \fB\-\-time\fP.
Line 240, length 157
Set the offset of \fBCLOCK_BOOTTIME\fP which will be used in the entered time
namespace. This option requires unsharing a time namespace with \fB\-\-time\fP.
Line 254, length 286
The proc and sysfs filesystems mounting as root in a user namespace have to be
restricted so that a less privileged user cannot get more access to sensitive
files that a more privileged user made unavailable. In short the rule for proc
and sysfs is as close to a bind mount as possible.
Line 257, length 505
The following command creates a PID namespace, using \fB\-\-fork\fP to ensure
that the executed command is performed in a child process that (being the first
process in the namespace) has PID 1. The \fB\-\-mount\-proc\fP option ensures
that a new mount namespace is also simultaneously created and that a new
\fBproc\fP(5) filesystem is mounted that contains information corresponding to
the new PID namespace. When the \fBreadlink\fP(1) command terminates, the new
namespaces are automatically torn down.
Line 268, length 133
As an unprivileged user, create a new user namespace where the user\(cqs
credentials are mapped to the root IDs inside the namespace:
Line 285, length 388
As an unprivileged user, create a user namespace where the first 65536 IDs are
all mapped, and the user\(cqs credentials are mapped to the root IDs inside the
namespace. The map is determined by the subordinate IDs assigned in
\fBsubuid\fP(5) and \fBsubgid\fP(5). Demonstrate this mapping by creating a
file with user ID 1 and group ID 1. For brevity, only the user ID mappings are
shown:
Line 310, length 441
The first of the following commands creates a new persistent UTS namespace and
modifies the hostname as seen in that namespace. The namespace is then entered
with \fBnsenter\fP(1) in order to display the modified hostname; this step
demonstrates that the UTS namespace continues to exist even though the
namespace had no member processes after the \fBunshare\fP command terminated.
The namespace is then destroyed by removing the bind mount.
Line 324, length 295
The following commands establish a persistent mount namespace referenced by the
bind mount \fI/root/namespaces/mnt\fP. In order to ensure that the creation of
that bind mount succeeds, the parent directory (\fI/root/namespaces\fP) is made
a bind mount whose propagation type is not \fBshared\fP.
Line 337, length 221
The following commands demonstrate the use of the \fB\-\-kill\-child\fP option
when creating a PID namespace, in order to ensure that when \fBunshare\fP is
killed, all of the processes within the PID namespace are killed.
Line 360, length 474
The \fBpidof\fP(1) command prints no output, because the \fBsleep\fP processes
have been killed. More precisely, when the \fBsleep\fP process that has PID 1
in the namespace (i.e., the namespace\(cqs init process) was killed, this
caused all other processes in the namespace to be killed. By contrast, a
similar series of commands where the \fB\-\-kill\-child\fP option is not used
shows that when \fBunshare\fP terminates, the processes in the PID namespace
are not killed:
Line 380, length 137
The following example demonstrates the creation of a time namespace where the
boottime clock is set to a point several years in the past:
Line 393, length 164
The following example execute a chroot into the directory
/chroot/powerpc/jessie and install the interpreter /bin/qemu\-ppc\-static to
execute the powerpc binaries.
Line 398, length 563
$\& unshare \-\-map\-root\-user \-\-fork \-\-pid
\-\-load\-interp=":qemu\-ppc:M::\(rs\(rsx7fELF\(rsx01\(rs\(rsx02\(rs\(rsx01\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx02\(rs\(rsx00\(rs\(rsx14:\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsx00\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxfe\(rs\(rsxff\(rs\(rsxff:/bin/qemu\-ppc\-static:OCF"
\-\-root=/chroot/powerpc/jessie /bin/bash \-l
Line 408, length 102
is the name of the new file created below \f(CR/proc/sys/fs/binfmt_misc\fP to
register the interpreter
Line 416, length 193
\f(CR\(rs\(rsx7fELF\(rsx01\(rs\(rsx02\(rs\(rsx01\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx00\(rs\(rsx02\(rs\(rsx00\(rs\(rsx1\fP
Line 418, length 95
is the magic number to recognize the file to interpret (in this case, the ELF
header for PPC32)
Line 421, length 228
\f(CR\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsx00\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxff\(rs\(rsxfe\(rs\(rsxff\(rs\(rsxff\fP
Line 433, length 123
the file is open by the kernel with credential and security tokens of the file
itself and loaded as soon as we register it.
Line 454, length 92
The \fBunshare\fP command is part of the util\-linux package which can be
downloaded from \c
Line 455, length 85
.URL "https://www.kernel.org/pub/linux/utils/util\-linux/"; "Linux Kernel
Archive" "."
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':416
troff:<stdin>:416: warning: [page 7, 2.7i]: cannot break line
troff: backtrace: file '<stdin>':421
troff:<stdin>:421: warning: [page 7, 3.2i]: cannot break line
