Linux userland API discussions
 help / color / mirror / Atom feed
From: Jarkko Sakkinen <jarkko@kernel.org>
To: linux-fsdevel@vger.kernel.org
Cc: Jarkko Sakkinen <jarkko@kernel.org>,
	bpf@vger.kernel.org, containers@lists.linux.dev,
	linux-api@vger.kernel.org, linux-arch@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,
	Aleksa Sarai <aleksa@amutable.com>,
	Alexander Mikhalitsyn <alex@amutable.com>,
	Alexander Viro <viro@zeniv.linux.org.uk>,
	Andy Lutomirski <luto@amacapital.net>,
	Arnd Bergmann <arnd@arndb.de>,
	Christian Brauner <brauner@kernel.org>,
	David Howells <dhowells@redhat.com>,
	Eric Biggers <ebiggers@kernel.org>,
	Giuseppe Scrivano <giuseppe@scrivano.org>,
	Hugh Dickins <hughd@google.com>, Jan Kara <jack@suse.cz>,
	Jeff Layton <jlayton@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Josef Bacik <josef@toxicpanda.com>, Kees Cook <kees@kernel.org>,
	KP Singh <kpsingh@kernel.org>,
	Lennart Poettering <lennart@poettering.net>,
	Neal Gompa <neal@gompa.dev>, Oleg Nesterov <oleg@redhat.com>,
	Paul Moore <paul@paul-moore.com>,
	Pavel Tikhomirov <ptikhomirov@virtuozzo.com>,
	Serge Hallyn <sergeh@kernel.org>,
	Shuah Khan <skhan@linuxfoundation.org>,
	Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Subject: [RFC PATCH v7 10/26] userland: Add core infrastructure
Date: Sun, 22 Nov 2026 21:35:23 +0200	[thread overview]
Message-ID: <20261122193539.3334213-11-jarkko@kernel.org> (raw)
In-Reply-To: <20261122193539.3334213-1-jarkko@kernel.org>

Linux namespaces can be created and entered individually, but userspace
orchestrators lack a single control object that binds a full detached
namespace set and an init process lifecycle behind a pollable file
descriptor. Because this object manages process lifecycle, wait and
signal delivery, VFS mount delegation, and LSM state rather than
representing an nsfs namespace entity, model it as a distinct userland
abstraction.

Add struct userland, its lifecycle states, reference counting, uAPI
flags, and anonymous inode file operations under CONFIG_USERLAND. Drop
active and passive namespace references on final release, send SIGKILL
to the userland init thread group on close when USERLAND_KILL_ON_CLOSE
is set, and report EPOLLHUP from poll() once the userland reaches
USERLAND_DEAD.

Co-developed-by: David Howells <dhowells@redhat.com>
Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
---
 include/linux/userland.h      | 80 +++++++++++++++++++++++++++++
 include/uapi/linux/userland.h | 25 ++++++++++
 init/Kconfig                  | 10 ++++
 kernel/Makefile               |  2 +
 kernel/userland.c             | 94 +++++++++++++++++++++++++++++++++++
 5 files changed, 211 insertions(+)
 create mode 100644 include/linux/userland.h
 create mode 100644 include/uapi/linux/userland.h
 create mode 100644 kernel/userland.c

diff --git a/include/linux/userland.h b/include/linux/userland.h
new file mode 100644
index 000000000000..9b9fefed63ac
--- /dev/null
+++ b/include/linux/userland.h
@@ -0,0 +1,80 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * Copyright (C) 2017-2019 Red Hat, Inc. All Rights Reserved.
+ * Copyright (C) 2026 Opinsys Oy
+ */
+
+#ifndef _LINUX_USERLAND_H
+#define _LINUX_USERLAND_H
+
+#include <linux/refcount.h>
+#include <linux/spinlock.h>
+#include <linux/wait.h>
+
+struct file;
+struct nsproxy;
+struct pid;
+struct user_namespace;
+
+/**
+ * enum userland_state - Userland lifecycle states
+ * @USERLAND_INIT:	Build phase after ``userland_open()`` before any
+ *			process has entered. ``USERLAND_SHARE_NSFD`` is
+ *			permitted, ID mappings may be configured on the owning
+ *			user namespace, and ``"/"`` must be mounted in the
+ *			mount namespace before entry.
+ * @USERLAND_FORKING:	Bootstrap phase while the first
+ *			``clone3(CLONE_INTO_USERLAND)`` call creates PID 1.
+ *			Concurrent callers wait killably; reverts to
+ *			%USERLAND_INIT if ``copy_process()`` fails, or advances
+ *			to %USERLAND_RUNNING once PID 1 is attached.
+ * @USERLAND_RUNNING:	Live phase while PID 1 is attached. Subsequent
+ *			``clone3(CLONE_INTO_USERLAND)`` calls join the PID
+ *			namespace until teardown begins,
+ *			``USERLAND_GET_NSFD(CLONE_NEWPID)`` and
+ *			``pidfd_send_signal()`` are enabled, and
+ *			``USERLAND_SHARE_NSFD`` returns ``-EBUSY``.
+ * @USERLAND_DEAD:	Terminal phase entered after PID 1 exits and the PID
+ *			namespace has killed and reaped all member processes.
+ *			``poll()`` reports ``EPOLLHUP`` and
+ *			``waitid(P_USERLAND, ...)`` reports PID 1's exit status
+ *			without consuming it.
+ *
+ * State transitions advance from %USERLAND_INIT through %USERLAND_FORKING and
+ * %USERLAND_RUNNING to %USERLAND_DEAD, reverting from %USERLAND_FORKING to
+ * %USERLAND_INIT only if the initial bootstrap fork fails.
+ */
+enum userland_state {
+	USERLAND_INIT		= 0,
+	USERLAND_FORKING	= 1,
+	USERLAND_RUNNING	= 2,
+	USERLAND_DEAD		= 3,
+};
+
+struct userland {
+	refcount_t		usage;
+	int			exit_code;
+	struct user_namespace	*user_ns;
+	struct nsproxy		*ns;
+	struct pid		*init_pid;
+	spinlock_t		lock;		/* Guards userland lifecycle state */
+	wait_queue_head_t	waitq;
+	unsigned int		flags;
+	enum userland_state	state;
+};
+
+#ifdef CONFIG_USERLAND
+void userland_put(struct userland *c);
+bool userland_is_file(struct file *file);
+#else
+static inline void userland_put(struct userland *c)
+{
+}
+
+static inline bool userland_is_file(struct file *file)
+{
+	return false;
+}
+#endif /* CONFIG_USERLAND */
+
+#endif /* _LINUX_USERLAND_H */
diff --git a/include/uapi/linux/userland.h b/include/uapi/linux/userland.h
new file mode 100644
index 000000000000..4a9031f81dda
--- /dev/null
+++ b/include/uapi/linux/userland.h
@@ -0,0 +1,25 @@
+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
+/*
+ * Copyright (C) 2017-2019 Red Hat, Inc. All Rights Reserved.
+ * Copyright (C) 2026 Opinsys Oy
+ */
+
+#ifndef _UAPI_LINUX_USERLAND_H
+#define _UAPI_LINUX_USERLAND_H
+
+/**
+ * enum userland_flags - Flags for userland_open()
+ * @USERLAND_KILL_ON_CLOSE: Send %SIGKILL to userland init on final fd release.
+ * @USERLAND_CLOSE_ON_EXEC: Set %O_CLOEXEC on the returned control fd.
+ * @USERLAND_ALL_FLAGS: Mask of all valid flags accepted by userland_open().
+ *
+ * Every userland created by userland_open() allocates a full set of
+ * detached namespaces owned by a fresh user namespace.
+ */
+enum userland_flags {
+	USERLAND_KILL_ON_CLOSE	= 0x00000001,
+	USERLAND_CLOSE_ON_EXEC	= 0x00000002,
+	USERLAND_ALL_FLAGS	= 0x00000003,
+};
+
+#endif /* _UAPI_LINUX_USERLAND_H */
diff --git a/init/Kconfig b/init/Kconfig
index c8a7cfa60a6e..0c5fada1ba88 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -1283,6 +1283,16 @@ config NET_NS
 
 endif # NAMESPACES
 
+config USERLAND
+	bool "Userland support"
+	depends on NAMESPACES && USER_NS && PID_NS && UTS_NS && IPC_NS && NET_NS && CGROUPS
+	help
+	  Allow user space to open and manage isolated userlands and their init
+	  process lifecycle through an anonymous-inode control file descriptor
+	  via userland_open(), waitid(P_USERLAND), pidfd_send_signal(),
+	  USERLAND_GET_NSFD, USERLAND_SHARE_NSFD, FSCONFIG_SET_USERLAND, and
+	  clone3() with CLONE_INTO_USERLAND.
+
 config CHECKPOINT_RESTORE
 	bool "Checkpoint/restore support"
 	depends on PROC_FS
diff --git a/kernel/Makefile b/kernel/Makefile
index 4ff92e24680c..80eb26639776 100644
--- a/kernel/Makefile
+++ b/kernel/Makefile
@@ -152,6 +152,8 @@ KCOV_INSTRUMENT_kstack_erase.o := n
 
 obj-$(CONFIG_SCF_TORTURE_TEST) += scftorture.o
 
+obj-$(CONFIG_USERLAND) += userland.o
+
 $(obj)/configs.o: $(obj)/config_data.gz
 
 # .config is small, so it is compressed with gzip rather than the image compressor.
diff --git a/kernel/userland.c b/kernel/userland.c
new file mode 100644
index 000000000000..7be0c4b5385b
--- /dev/null
+++ b/kernel/userland.c
@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (C) 2017-2019 Red Hat, Inc. All Rights Reserved.
+ * Copyright (C) 2026 Opinsys Oy
+ */
+
+/**
+ * DOC: Overview
+ *
+ * A userland is an anonymous-inode control object opened by ``userland_open()``
+ * that binds a detached namespace set, an initially empty mount namespace, an
+ * owning user namespace, and an init process lifecycle.
+ */
+#include <linux/poll.h>
+#include <linux/wait.h>
+#include <uapi/linux/wait.h>
+#include <linux/file.h>
+#include <linux/fs.h>
+#include <linux/anon_inodes.h>
+#include <linux/userland.h>
+#include <linux/sched/signal.h>
+#include <linux/sched/task.h>
+#include <linux/slab.h>
+#include <linux/syscalls.h>
+#include <linux/uaccess.h>
+#include <linux/mnt_namespace.h>
+#include <linux/nsproxy.h>
+#include <linux/ns_common.h>
+#include <linux/nsfs.h>
+#include <linux/pid.h>
+#include <linux/pid_namespace.h>
+#include <linux/time_namespace.h>
+#include <linux/user_namespace.h>
+#include <linux/idr.h>
+#include <uapi/linux/userland.h>
+
+void userland_put(struct userland *c)
+{
+	if (!c || !refcount_dec_and_test(&c->usage))
+		return;
+
+	if (c->ns)
+		put_nsproxy(c->ns);
+	if (c->init_pid)
+		put_pid(c->init_pid);
+	if (c->user_ns) {
+		ns_ref_active_put(c->user_ns);
+		put_user_ns(c->user_ns);
+	}
+	kfree(c);
+}
+
+static __poll_t userland_poll(struct file *file, poll_table *wait)
+{
+	struct userland *userland = file->private_data;
+	__poll_t mask = 0;
+
+	poll_wait(file, &userland->waitq, wait);
+
+	if (READ_ONCE(userland->state) == USERLAND_DEAD)
+		mask |= EPOLLHUP;
+
+	return mask;
+}
+
+static int userland_release(struct inode *inode, struct file *file)
+{
+	struct userland *userland = file->private_data;
+
+	if (userland->flags & USERLAND_KILL_ON_CLOSE) {
+		struct pid *pid = NULL;
+
+		scoped_guard(spinlock, &userland->lock) {
+			if (userland->state == USERLAND_RUNNING)
+				pid = get_pid(userland->init_pid);
+		}
+		if (pid) {
+			kill_pid(pid, SIGKILL, true);
+			put_pid(pid);
+		}
+	}
+	userland_put(userland);
+	return 0;
+}
+
+static const struct file_operations userland_fops = {
+	.poll		= userland_poll,
+	.release	= userland_release,
+};
+
+bool userland_is_file(struct file *file)
+{
+	return file->f_op == &userland_fops;
+}
-- 
2.47.3


  parent reply	other threads:[~2026-11-22 19:36 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-22 19:35 [RFC PATCH v7 00/26] userland: Userland containers Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 01/26] userns: Factor out idmap validation and commit helpers Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 02/26] userns: Add userns_set_idmap() system call Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 03/26] arch: Wire up " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 04/26] mount: Add mnt_ns_get_root() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 05/26] mount: Enforce mount_too_revealing() for foreign mntns Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 06/26] mount: Support MOVE_MOUNT_T_MNTNS in move_mount() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 07/26] mount: Support MOVE_MOUNT_CLONE with MOVE_MOUNT_T_MNTNS Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 08/26] userns: Factor out install_user_ns_cred() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 09/26] nsproxy: Expose create_new_namespaces() Jarkko Sakkinen
2026-11-22 19:35 ` Jarkko Sakkinen [this message]
2026-11-22 19:35 ` [RFC PATCH v7 11/26] userland: Track init lifecycle via copy_process() and pid_namespace Jarkko Sakkinen
2026-11-22 20:09   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 12/26] userland: Add userland_open() system call Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 13/26] userland: Add USERLAND_GET_NSFD ioctl Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 14/26] userland: Add USERLAND_SHARE_NSFD ioctl Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 15/26] exit: Support P_USERLAND in waitid() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 16/26] signal: Support userland fds in pidfd_send_signal() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 17/26] fork: Support CLONE_INTO_USERLAND in clone3() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 18/26] fs: Support FSCONFIG_SET_USERLAND in fsconfig() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 19/26] proc: Implement ->set_userland() fs_context operation Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 20/26] ipc/mqueue: " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 21/26] security: Add userland LSM hooks Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 22/26] bpf: Register " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 23/26] arch: Wire up userland_open() system call Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 24/26] docs: Document userland uAPI Jarkko Sakkinen
2026-11-22 20:09   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 25/26] selftests/userland: Add userland test suite Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 26/26] MAINTAINERS: Add entry for USERLAND 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=20261122193539.3334213-11-jarkko@kernel.org \
    --to=jarkko@kernel.org \
    --cc=aleksa@amutable.com \
    --cc=alex@amutable.com \
    --cc=arnd@arndb.de \
    --cc=bpf@vger.kernel.org \
    --cc=brauner@kernel.org \
    --cc=containers@lists.linux.dev \
    --cc=corbet@lwn.net \
    --cc=dhowells@redhat.com \
    --cc=ebiggers@kernel.org \
    --cc=giuseppe@scrivano.org \
    --cc=hughd@google.com \
    --cc=jack@suse.cz \
    --cc=jlayton@kernel.org \
    --cc=josef@toxicpanda.com \
    --cc=kees@kernel.org \
    --cc=kpsingh@kernel.org \
    --cc=lennart@poettering.net \
    --cc=linux-api@vger.kernel.org \
    --cc=linux-arch@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=oleg@redhat.com \
    --cc=paul@paul-moore.com \
    --cc=ptikhomirov@virtuozzo.com \
    --cc=sergeh@kernel.org \
    --cc=skhan@linuxfoundation.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox