From 6cee0ddeb4146fa3f67c57ef1e3b3fb7e6de892b Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 17 May 2021 15:18:10 +1200
Subject: [PATCH] proc.5: Document /proc/sys/vm/sysctl_hugetlb_shm_group

As a deprecated feature, it appears that the RLIMIT_MEMLOCK
can also be used to permit huge page allocation, but let's
not document that for now.

In the Linux 5.12, see fs/hugetlbfs/inode.c.

static int can_do_hugetlb_shm(void)
{
        kgid_t shm_group;
        shm_group = make_kgid(&init_user_ns, sysctl_hugetlb_shm_group);
        return capable(CAP_IPC_LOCK) || in_group_p(shm_group);
}

...

struct file *hugetlb_file_setup(const char *name, size_t size,
                                vm_flags_t acctflag, struct user_struct **user,
                                int creat_flags, int page_size_log)
{
        ...
        if (creat_flags == HUGETLB_SHMFS_INODE && !can_do_hugetlb_shm()) {
                *user = current_user();
                if (user_shm_lock(size, *user)) {
                        task_lock(current);
                        pr_warn_once("%s (%d): Using mlock ulimits for SHM_HUGETLB is deprecated\n",
                                current->comm, current->pid);
                        task_unlock(current);
                } else {
                        *user = NULL;
                        return ERR_PTR(-EPERM);
                }
        }
        ...
}

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man5/proc.5 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man5/proc.5 b/man5/proc.5
index a28dbdcc7..888535449 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -5603,6 +5603,19 @@ user should run
 .BR sync (1)
 first.
 .TP
+.IR  /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)"
+This writable file contains a group ID that is allowed
+to allocate memory using huge pages.
+If a process has a filesystem group ID or any supplememtary group ID that
+matches this group ID,
+then it can make huge-page allocations without holding the
+.BR CAP_IPC_LOCK
+capability; see
+.BR memfd_create (2),
+.BR mmap (2),
+and
+.BR shmget (2).
+.TP
 .IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)"
 .\" The following is from Documentation/filesystems/proc.txt
 If nonzero, this disables the new 32-bit memory-mapping layout;