Skip to contentSkip to conversation

docs: namespace: Tweak and reword resource control doc

PATCH In review Joel Savitz 3 participants 4 messages Apr 21, 2025 – Apr 29, 2025 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 docs: namespace: Tweak and reword resource control doc

Fix the document title and reword the phrasing to active voice.

---
Changes since v2:
- Fix another typo
Changes since v1:
- Fix spelling of resource

 .../namespaces/resource-control.rst           | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)
Documentation/admin-guide/namespaces/resource-control.rst +12 -12
index 369556e00f0c..553a44803231 100644
@@ -1,17 +1,17 @@
-===========================
-Namespaces research control
-===========================
+====================================
+User namespaces and resource control
+====================================
 
-There are a lot of kinds of objects in the kernel that don't have
-individual limits or that have limits that are ineffective when a set
-of processes is allowed to switch user ids.  With user namespaces
-enabled in a kernel for people who don't trust their users or their
-users programs to play nice this problems becomes more acute.
+The kernel contains many kinds of objects that either don't have
+individual limits or that have limits which are ineffective when
+a set of processes is allowed to switch their UID. On a system
+where the admins don't trust their users or their users' programs,
+user namespaces expose the system to potential misuse of resources.
 
-Therefore it is recommended that memory control groups be enabled in
-kernels that enable user namespaces, and it is further recommended
-that userspace configure memory control groups to limit how much
-memory user's they don't trust to play nice can use.
+In order to mitigate this, we recommend that admins enable memory
+control groups on any system that enables user namespaces.
+Furthermore, we recommend that admins configure the memory control
+groups to limit the maximum memory usable by any untrusted user.
 
 Memory control groups can be configured by installing the libcgroup
 package present on most distros editing /etc/cgrules.conf,
Signature · 1 line
2.45.2
#1 lore raw
Quoted 48 lines · Joel Savitz

Fix the document title and reword the phrasing to active voice.

---
Changes since v2:
- Fix another typo
Changes since v1:
- Fix spelling of resource

 .../namespaces/resource-control.rst           | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)
Documentation/admin-guide/namespaces/resource-control.rst +12 -13
index 369556e00f0c..553a44803231 100644
@@ -1,17 +1,17 @@
-===========================
-Namespaces research control
-===========================
+====================================
+User namespaces and resource control
+====================================
 
-There are a lot of kinds of objects in the kernel that don't have
-individual limits or that have limits that are ineffective when a set
-of processes is allowed to switch user ids.  With user namespaces
-enabled in a kernel for people who don't trust their users or their
-users programs to play nice this problems becomes more acute.
+The kernel contains many kinds of objects that either don't have
+individual limits or that have limits which are ineffective when
+a set of processes is allowed to switch their UID. On a system
+where the admins don't trust their users or their users' programs,
+user namespaces expose the system to potential misuse of resources.
 
-Therefore it is recommended that memory control groups be enabled in
-kernels that enable user namespaces, and it is further recommended
-that userspace configure memory control groups to limit how much
-memory user's they don't trust to play nice can use.
+In order to mitigate this, we recommend that admins enable memory
+control groups on any system that enables user namespaces.
+Furthermore, we recommend that admins configure the memory control
+groups to limit the maximum memory usable by any untrusted user.
 
 Memory control groups can be configured by installing the libcgroup
 package present on most distros editing /etc/cgrules.conf,
--
Quoted 2 lines

2.45.2

Hi,

Just a quick follow up on this. Are the changes acceptable?

Best,
Joel Savitz

Reviewed-by on v3 1/1
#2 lore raw
In reply to Joel Savitz

[Cc'ing Eric, Mauro, and memcg folks]

Quoted 36 lines · Joel Savitz

Fix the document title and reword the phrasing to active voice.

---
Changes since v2:
- Fix another typo
Changes since v1:
- Fix spelling of resource

 .../namespaces/resource-control.rst           | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)
Documentation/admin-guide/namespaces/resource-control.rst +8 -9
index 369556e00f0c..553a44803231 100644
@@ -1,17 +1,17 @@
-===========================
-Namespaces research control
-===========================
+====================================
+User namespaces and resource control
+====================================
 
-There are a lot of kinds of objects in the kernel that don't have
-individual limits or that have limits that are ineffective when a set
-of processes is allowed to switch user ids.  With user namespaces
-enabled in a kernel for people who don't trust their users or their
-users programs to play nice this problems becomes more acute.
+The kernel contains many kinds of objects that either don't have
+individual limits or that have limits which are ineffective when
+a set of processes is allowed to switch their UID. On a system
+where the admins don't trust their users or their users' programs,
+user namespaces expose the system to potential misuse of resources.
 
-Therefore it is recommended that memory control groups be enabled in

Documentation/admin-guide/namespaces/resource-control.rst line 17

Quoted 10 lines
Documentation/admin-guide/namespaces/resource-control.rst +4 -3
-kernels that enable user namespaces, and it is further recommended
-that userspace configure memory control groups to limit how much
-memory user's they don't trust to play nice can use.
+In order to mitigate this, we recommend that admins enable memory
+control groups on any system that enables user namespaces.
+Furthermore, we recommend that admins configure the memory control
+groups to limit the maximum memory usable by any untrusted user.
 
 Memory control groups can be configured by installing the libcgroup
 package present on most distros editing /etc/cgrules.conf,

Looks good, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#3 lore raw
In reply to Joel Savitz
Quoted 11 lines · Joel Savitz

Fix the document title and reword the phrasing to active voice.

---
Changes since v2:
- Fix another typo
Changes since v1:
- Fix spelling of resource

 .../namespaces/resource-control.rst           | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

I've applied this. As a general rule, though, "switch to active voice" is the sort of churn that is best avoided unless you're making more substantive changes. We have a lot of far more pressing problems in the docs...

Thanks,

jon