[PATCH v3] docs: namespace: Tweak and reword resource control doc

[PATCH v3] docs: namespace: Tweak and reword resource control doc

[Joel Savitz]

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

Signed-off-by: Joel Savitz <jsavitz@redhat.com>
---
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(-)

diff --git a/Documentation/admin-guide/namespaces/resource-control.rst b/Documentation/admin-guide/namespaces/resource-control.rst
index 369556e00f0c..553a44803231 100644
--- a/Documentation/admin-guide/namespaces/resource-control.rst
+++ b/Documentation/admin-guide/namespaces/resource-control.rst
@@ -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,
-- 
2.45.2

Re: [PATCH v3] docs: namespace: Tweak and reword resource control doc

[Joel Savitz]

On Mon, Apr 21, 2025 at 12:17 PM Joel Savitz <jsavitz@redhat.com> wrote:
>
> Fix the document title and reword the phrasing to active voice.
>
> Signed-off-by: Joel Savitz <jsavitz@redhat.com>
> ---
> 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(-)
>
> diff --git a/Documentation/admin-guide/namespaces/resource-control.rst b/Documentation/admin-guide/namespaces/resource-control.rst
> index 369556e00f0c..553a44803231 100644
> --- a/Documentation/admin-guide/namespaces/resource-control.rst
> +++ b/Documentation/admin-guide/namespaces/resource-control.rst
> @@ -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,
> --
> 2.45.2
>

Hi,

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

Best,
Joel Savitz

Re: [PATCH v3] docs: namespace: Tweak and reword resource control doc

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2545 bytes --]

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

On Mon, Apr 21, 2025 at 12:17:23PM -0400, Joel Savitz wrote:
> Fix the document title and reword the phrasing to active voice.
> 
> Signed-off-by: Joel Savitz <jsavitz@redhat.com>
> ---
> 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(-)
> 
> diff --git a/Documentation/admin-guide/namespaces/resource-control.rst b/Documentation/admin-guide/namespaces/resource-control.rst
> index 369556e00f0c..553a44803231 100644
> --- a/Documentation/admin-guide/namespaces/resource-control.rst
> +++ b/Documentation/admin-guide/namespaces/resource-control.rst
> @@ -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,

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3] docs: namespace: Tweak and reword resource control doc

[Jonathan Corbet]

Joel Savitz <jsavitz@redhat.com> writes:

> Fix the document title and reword the phrasing to active voice.
>
> Signed-off-by: Joel Savitz <jsavitz@redhat.com>
> ---
> 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