Skip to content

Commit 35c6e43

Browse files
cypharcyphar
committed
man: add documentation for new setgroups(2) semantics
Add documentation for allow_setgroups, deny_setgroups, the new option format of /etc/sub{uid,gid}, and fix some errors in the groupmod(8) man page that stopped it from building properly on my machine. Signed-off-by: Aleksa Sarai <[email protected]>
1 parent e39264e commit 35c6e43

File tree

4 files changed

+91
-11
lines changed

4 files changed

+91
-11
lines changed

‎man/groupmod.8.xml

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Copyright (c) 1991 , Julianne Frances Haugh
44
Copyright (c) 2007 - 2011, Nicolas François
55
All rights reserved.
6-
6+
77
Redistribution and use in source and binary forms, with or without
88
modification, are permitted provided that the following conditions
99
are met:
@@ -15,7 +15,7 @@
1515
3. The name of the copyright holders or contributors may not be used to
1616
endorse or promote products derived from this software without
1717
specific prior written permission.
18-
18+
1919
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
2020
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2121
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -136,7 +136,7 @@
136136
<option>-n</option>, <option>--new-name</option>&nbsp;<replaceable>NEW_GROUP</replaceable>
137137
</term>
138138
<listitem>
139-
<para>
139+
<para>
140140
The name of the group will be changed from <replaceable>GROUP</replaceable>
141141
to <replaceable>NEW_GROUP</replaceable> name.
142142
</para>
@@ -278,16 +278,19 @@
278278
<para>E_GRP_UPDATE: can't update group file</para>
279279
</listitem>
280280
</varlistentry>
281+
<varlistentry>
281282
<term><replaceable>11</replaceable></term>
282283
<listitem>
283284
<para>E_CLEANUP_SERVICE: can't setup cleanup service</para>
284285
</listitem>
285286
</varlistentry>
287+
<varlistentry>
286288
<term><replaceable>12</replaceable></term>
287289
<listitem>
288290
<para>E_PAM_USERNAME: can't determine your username for use with pam</para>
289291
</listitem>
290292
</varlistentry>
293+
<varlistentry>
291294
<term><replaceable>13</replaceable></term>
292295
<listitem>
293296
<para>E_PAM_ERROR: pam returned an error, see syslog facility id groupmod for the PAM error message</para>

‎man/newgidmap.1.xml

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<!--
33
Copyright (c) 2013 Eric W. Biederman
44
All rights reserved.
5-
5+
66
Redistribution and use in source and binary forms, with or without
77
modification, are permitted provided that the following conditions
88
are met:
@@ -14,7 +14,7 @@
1414
3. The name of the copyright holders or contributors may not be used to
1515
endorse or promote products derived from this software without
1616
specific prior written permission.
17-
17+
1818
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1919
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2020
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -122,12 +122,29 @@
122122
of the above sets, each of the GIDs in the range [lowergid,
123123
lowergid+count] is allowed to the caller according to
124124
<filename>/etc/subgid</filename> before setting
125+
<filename>/proc/[pid]/setgroups</filename> and
125126
<filename>/proc/[pid]/gid_map</filename>.
126127
</para>
128+
127129
<para>
128130
Note that newgidmap may be used only once for a given process.
129131
</para>
130132

133+
<para>
134+
<command>newgidmap</command> also allows you to map a user's own
135+
effective group ID without it being specified in
136+
<filename>/etc/subgid</filename> (in order to match the "unprivileged
137+
user namespaces" feature in Linux 3.8). If this is the only mapping
138+
requested (in order to match the security protections from Linux 3.19),
139+
<command>newgidmap</command> will ensure that
140+
<filename>/proc/[pid]/setgroups</filename> is set to "deny" (either by
141+
writing "deny" itself or seeing that it is already set to "deny"), and
142+
will fail if writing "deny" failed. This restriction is also applied if
143+
any of the mappings given to <command>newgidmap</command> has the
144+
<option>deny_setgroups</option> option set in
145+
<filename>/etc/subgid</filename>.
146+
</para>
147+
131148
</refsect1>
132149

133150
<refsect1 id='options'>

‎man/subgid.5.xml

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<!--
33
Copyright (c) 2013 Eric W. Biederman
44
All rights reserved.
5-
5+
66
Redistribution and use in source and binary forms, with or without
77
modification, are permitted provided that the following conditions
88
are met:
@@ -14,7 +14,7 @@
1414
3. The name of the copyright holders or contributors may not be used to
1515
endorse or promote products derived from this software without
1616
specific prior written permission.
17-
17+
1818
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1919
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2020
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -51,7 +51,7 @@
5151
a user name and a range of subordinate group ids that user
5252
is allowed to use.
5353

54-
This is specified with three fields delimited by colons
54+
This is specified with four fields delimited by colons
5555
(<quote>:</quote>).
5656
These fields are:
5757
</para>
@@ -65,6 +65,9 @@
6565
<listitem>
6666
<para>numerical subordinate group ID count</para>
6767
</listitem>
68+
<listitem>
69+
<para>comma-separated list of options (optional)</para>
70+
</listitem>
6871
</itemizedlist>
6972

7073
<para>
@@ -86,6 +89,42 @@
8689

8790
</refsect1>
8891

92+
<refsect1 id='options'>
93+
<title>OPTIONS</title>
94+
95+
<para>
96+
Options are comma-separated. Empty options are ignored, and if the
97+
field is missing entirely it is treated as an empty string. Attempting
98+
to use an unknown option will cause <command>newgidmap</command> to emit
99+
an error. Setting options from the same option-set multiple times in a
100+
single entry will result in the last option specified taking precedence.
101+
</para>
102+
103+
<variablelist>
104+
<varlistentry>
105+
<term><option>allow_setgroups</option> (default),
106+
<option>deny_setgroups</option></term>
107+
<listitem>
108+
<para>
109+
Specify whether
110+
<citerefentry>
111+
<refentrytitle>setgroups</refentrytitle><manvolnum>2</manvolnum>
112+
</citerefentry>
113+
will be disabled by <command>newgidmap</command>. If more than one
114+
mapping is given to <command>newgidmap</command>, and they have
115+
different <option>*_setgroups</option> options set,
116+
<option>deny_setgroups</option> always takes precedence. See
117+
<citerefentry>
118+
<refentrytitle>newgidmap</refentrytitle><manvolnum>1</manvolnum>
119+
</citerefentry>
120+
for more details.
121+
</para>
122+
</listitem>
123+
</varlistentry>
124+
</variablelist>
125+
126+
</refsect1>
127+
89128
<refsect1 id='files'>
90129
<title>FILES</title>
91130
<variablelist>

‎man/subuid.5.xml

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<!--
33
Copyright (c) 2013 Eric W. Biederman
44
All rights reserved.
5-
5+
66
Redistribution and use in source and binary forms, with or without
77
modification, are permitted provided that the following conditions
88
are met:
@@ -14,7 +14,7 @@
1414
3. The name of the copyright holders or contributors may not be used to
1515
endorse or promote products derived from this software without
1616
specific prior written permission.
17-
17+
1818
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1919
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2020
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -51,7 +51,7 @@
5151
a user name and a range of subordinate user ids that user
5252
is allowed to use.
5353

54-
This is specified with three fields delimited by colons
54+
This is specified with four fields delimited by colons
5555
(<quote>:</quote>).
5656
These fields are:
5757
</para>
@@ -65,6 +65,9 @@
6565
<listitem>
6666
<para>numerical subordinate user ID count</para>
6767
</listitem>
68+
<listitem>
69+
<para>comma-separated list of options (optional)</para>
70+
</listitem>
6871
</itemizedlist>
6972

7073
<para>
@@ -86,6 +89,24 @@
8689

8790
</refsect1>
8891

92+
<refsect1 id='options'>
93+
<title>OPTIONS</title>
94+
95+
<para>
96+
Options are comma-separated. Empty options are ignored, and if the
97+
field is missing entirely it is treated as an empty string. Attempting
98+
to use an unknown option will cause <command>newuidmap</command> to emit
99+
an error. Setting options from the same option-set multiple times in a
100+
single entry will result in the last option specified taking precedence.
101+
</para>
102+
103+
<para>
104+
At the moment, no options are defined for
105+
<filename>/etc/subuid</filename>.
106+
</para>
107+
108+
</refsect1>
109+
89110
<refsect1 id='files'>
90111
<title>FILES</title>
91112
<variablelist>

0 commit comments

Comments
 (0)