All of lore.kernel.org
 help / color / mirror / Atom feed
From: Jarkko Sakkinen <jarkko@kernel.org>
To: linux-fsdevel@vger.kernel.org
Cc: Jarkko Sakkinen <jarkko@kernel.org>,
	linux-api@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org, linux-kselftest@vger.kernel.org,
	linux-mm@kvack.org, linux-security-module@vger.kernel.org,
	Alexander Mikhalitsyn <alex@amutable.com>,
	Alexander Viro <viro@zeniv.linux.org.uk>,
	Andy Lutomirski <luto@amacapital.net>,
	Christian Brauner <brauner@kernel.org>,
	David Howells <dhowells@redhat.com>, Jan Kara <jack@suse.cz>,
	Jonathan Corbet <corbet@lwn.net>,
	Josef Bacik <josef@toxicpanda.com>, Kees Cook <kees@kernel.org>,
	Neal Gompa <neal@gompa.dev>, Paul Moore <paul@paul-moore.com>,
	Serge Hallyn <sergeh@kernel.org>,
	Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Subject: [RFC PATCH v5 23/25] docs: Document root namespace uAPI
Date: Sat, 21 Nov 2026 02:08:42 +0200	[thread overview]
Message-ID: <20261121000844.1863324-24-jarkko@kernel.org> (raw)
In-Reply-To: <20261121000844.1863324-1-jarkko@kernel.org>

Userspace container managers need a clear specification of rootns state
transitions, control ioctls, mount-tree construction, user namespace ID
mapping, credential rules, and process creation semantics.

Add Documentation/userspace-api/rootns.rst to include the kernel-doc
sections, ioctl descriptions, and system call reference from
kernel/rootns.c, kernel/user_namespace.c, include/uapi/linux/rootns.h,
include/uapi/linux/nsfs.h, fs/fsopen.c, and fs/namespace.c, and register
the rootns ioctl magic in ioctl-number.rst.

Co-developed-by: David Howells <dhowells@redhat.com>
Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
---
 Documentation/userspace-api/index.rst         |  1 +
 .../userspace-api/ioctl/ioctl-number.rst      |  1 +
 Documentation/userspace-api/rootns.rst        | 65 +++++++++++++++++++
 3 files changed, 67 insertions(+)
 create mode 100644 Documentation/userspace-api/rootns.rst

diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index a68b1bea57a8..56d0ac4eb087 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -17,6 +17,7 @@ System calls
    :maxdepth: 1
 
    unshare
+   rootns
    futex2
    ebpf/index
    ioctl/index
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index dbe462040999..d8dc926ea283 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -385,6 +385,7 @@ Code  Seq#    Include File                                             Comments
 0xB8  01-02  uapi/misc/mrvl_cn10k_dpi.h                                Marvell CN10K DPI driver
 0xB8  all    uapi/linux/mshv.h                                         Microsoft Hyper-V /dev/mshv driver
                                                                        <mailto:linux-hyperv@vger.kernel.org>
+0xB9  00-0F  uapi/linux/rootns.h                                       Root namespace uAPI
 0xBA  00-0F  uapi/linux/liveupdate.h                                   Pasha Tatashin
                                                                        <mailto:pasha.tatashin@soleen.com>
 0xC0  00-0F  linux/usb/iowarrior.h
diff --git a/Documentation/userspace-api/rootns.rst b/Documentation/userspace-api/rootns.rst
new file mode 100644
index 000000000000..ef18ed59ba4a
--- /dev/null
+++ b/Documentation/userspace-api/rootns.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+Root namespace uAPI
+===================
+
+Overview
+========
+
+.. kernel-doc:: kernel/rootns.c
+   :doc: Overview
+
+Flags
+=====
+
+.. kernel-doc:: include/uapi/linux/rootns.h
+   :identifiers: rootns_flags
+
+Ioctls
+======
+
+.. kernel-doc:: include/uapi/linux/rootns.h
+   :doc: ROOTNS_GET_NSFD
+
+.. kernel-doc:: include/uapi/linux/rootns.h
+   :identifiers: rootns_wait_args
+
+.. kernel-doc:: include/uapi/linux/rootns.h
+   :doc: ROOTNS_WAIT
+
+.. kernel-doc:: include/uapi/linux/rootns.h
+   :doc: ROOTNS_KILL
+
+System calls
+============
+
+.. kernel-doc:: kernel/rootns.c
+   :identifiers: sys_rootns
+
+Process creation
+================
+
+.. kernel-doc:: kernel/rootns.c
+   :doc: CLONE_INTO_ROOTNS
+
+Filesystem configuration
+========================
+
+.. kernel-doc:: fs/fsopen.c
+   :doc: FSCONFIG_SET_ROOTNS
+
+Mount tree installation
+=======================
+
+.. kernel-doc:: fs/namespace.c
+   :doc: MOVE_MOUNT_T_MNTNS
+
+User namespace ID mapping
+=========================
+
+.. kernel-doc:: include/uapi/linux/nsfs.h
+   :identifiers: userns_idmap_extent userns_idmap_flags userns_idmap
+
+.. kernel-doc:: kernel/user_namespace.c
+   :identifiers: sys_userns_set_idmap
-- 
2.47.3


  parent reply	other threads:[~2026-11-21  0:10 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-21  0:08 [RFC PATCH v5 00/25] rootns: fd-bound process closures Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 01/25] userns: Factor out idmap validation and commit helpers Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 02/25] userns: Add userns_set_idmap() system call Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 03/25] arch: Wire up " Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 04/25] mount: Add mnt_ns_get_root() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 05/25] mount: Enforce mount_too_revealing() for foreign mntns Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 06/25] mount: Support MOVE_MOUNT_T_MNTNS in move_mount() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 07/25] mount: Support MOVE_MOUNT_CLONE with MOVE_MOUNT_T_MNTNS Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 08/25] userns: Factor out install_user_ns_cred() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 09/25] nsfs: Add nsproxy_open_namespace() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 10/25] nsproxy: Pass nsproxy to create_new_namespaces() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 11/25] rootns: Add core infrastructure for root namespaces Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 12/25] rootns: Track init lifecycle via copy_process() and pid_namespace Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 13/25] rootns: Add rootns() system call Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 14/25] rootns: Add ROOTNS_WAIT ioctl Jarkko Sakkinen
2026-11-21  0:17   ` Jarkko Sakkinen
2026-11-21  0:18     ` Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 15/25] rootns: Add ROOTNS_KILL ioctl Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 16/25] fork: Support CLONE_INTO_ROOTNS in clone3() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 17/25] fs: Support FSCONFIG_SET_ROOTNS in fsconfig() Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 18/25] proc: Implement ->set_rootns() fs_context operation Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 19/25] ipc/mqueue: " Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 20/25] security: Add rootns LSM hooks Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 21/25] bpf: Register " Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 22/25] arch: Wire up rootns() system call Jarkko Sakkinen
2026-11-21  0:08 ` Jarkko Sakkinen [this message]
2026-11-21  0:08 ` [RFC PATCH v5 24/25] selftests/rootns: Add root namespace test suite Jarkko Sakkinen
2026-11-21  0:08 ` [RFC PATCH v5 25/25] MAINTAINERS: Add entry for ROOT NAMESPACE Jarkko Sakkinen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261121000844.1863324-24-jarkko@kernel.org \
    --to=jarkko@kernel.org \
    --cc=alex@amutable.com \
    --cc=brauner@kernel.org \
    --cc=corbet@lwn.net \
    --cc=dhowells@redhat.com \
    --cc=jack@suse.cz \
    --cc=josef@toxicpanda.com \
    --cc=kees@kernel.org \
    --cc=linux-api@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-kselftest@vger.kernel.org \
    --cc=linux-mm@kvack.org \
    --cc=linux-security-module@vger.kernel.org \
    --cc=luto@amacapital.net \
    --cc=neal@gompa.dev \
    --cc=paul@paul-moore.com \
    --cc=sergeh@kernel.org \
    --cc=viro@zeniv.linux.org.uk \
    --cc=zygmunt.krynicki@canonical.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.