[RFC PATCH v6 10/26] userland: Add core infrastructure

From: Jarkko Sakkinen

Date: Sat Nov 21 2026 - 20:19:20 EST


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@xxxxxxxxxx>
Signed-off-by: David Howells <dhowells@xxxxxxxxxx>
Signed-off-by: Jarkko Sakkinen <jarkko@xxxxxxxxxx>
---
include/linux/userland.h | 52 +++++++++++++++++++++
include/uapi/linux/userland.h | 25 ++++++++++
init/Kconfig | 10 ++++
kernel/Makefile | 2 +
kernel/userland.c | 87 +++++++++++++++++++++++++++++++++++
5 files changed, 176 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..fa8628e1b89c
--- /dev/null
+++ b/include/linux/userland.h
@@ -0,0 +1,52 @@
+/* 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_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..b339aa2103e1
--- /dev/null
+++ b/kernel/userland.c
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (C) 2017-2019 Red Hat, Inc. All Rights Reserved.
+ * Copyright (C) 2026 Opinsys Oy
+ */
+
+#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