ns_common_types.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2#ifndef _LINUX_NS_COMMON_TYPES_H
  3#define _LINUX_NS_COMMON_TYPES_H
  4
  5#include <linux/atomic.h>
  6#include <linux/ns/nstree_types.h>
  7#include <linux/rbtree.h>
  8#include <linux/refcount.h>
  9#include <linux/types.h>
 10
 11struct cgroup_namespace;
 12struct dentry;
 13struct ipc_namespace;
 14struct mnt_namespace;
 15struct net;
 16struct pid_namespace;
 17struct proc_ns_operations;
 18struct time_namespace;
 19struct user_namespace;
 20struct uts_namespace;
 21
 22extern struct cgroup_namespace init_cgroup_ns;
 23extern struct ipc_namespace init_ipc_ns;
 24extern struct mnt_namespace init_mnt_ns;
 25extern struct net init_net;
 26extern struct pid_namespace init_pid_ns;
 27extern struct time_namespace init_time_ns;
 28extern struct user_namespace init_user_ns;
 29extern struct uts_namespace init_uts_ns;
 30
 31extern const struct proc_ns_operations cgroupns_operations;
 32extern const struct proc_ns_operations ipcns_operations;
 33extern const struct proc_ns_operations mntns_operations;
 34extern const struct proc_ns_operations netns_operations;
 35extern const struct proc_ns_operations pidns_operations;
 36extern const struct proc_ns_operations pidns_for_children_operations;
 37extern const struct proc_ns_operations timens_operations;
 38extern const struct proc_ns_operations timens_for_children_operations;
 39extern const struct proc_ns_operations userns_operations;
 40extern const struct proc_ns_operations utsns_operations;
 41
 42/*
 43 * Namespace lifetimes are managed via a two-tier reference counting model:
 44 *
 45 * (1) __ns_ref (refcount_t): Main reference count tracking memory
 46 *     lifetime. Controls when the namespace structure itself is freed.
 47 *     It also pins the namespace on the namespace trees whereas (2)
 48 *     only regulates their visibility to userspace.
 49 *
 50 * (2) __ns_ref_active (atomic_t): Reference count tracking active users.
 51 *     Controls visibility of the namespace in the namespace trees.
 52 *     Any live task that uses the namespace (via nsproxy or cred) holds
 53 *     an active reference. Any open file descriptor or bind-mount of
 54 *     the namespace holds an active reference. Once all tasks have
 55 *     called exited their namespaces and all file descriptors and
 56 *     bind-mounts have been released the active reference count drops
 57 *     to zero and the namespace becomes inactive. IOW, the namespace
 58 *     cannot be listed or opened via file handles anymore.
 59 *
 60 *     Note that it is valid to transition from active to inactive and
 61 *     back from inactive to active e.g., when resurrecting an inactive
 62 *     namespace tree via the SIOCGSKNS ioctl().
 63 *
 64 * Relationship and lifecycle states:
 65 *
 66 * - Active (__ns_ref_active > 0):
 67 *   Namespace is actively used and visible to userspace. The namespace
 68 *   can be reopened via /proc/<pid>/ns/<ns_type>, via namespace file
 69 *   handles, or discovered via listns().
 70 *
 71 * - Inactive (__ns_ref_active == 0, __ns_ref > 0):
 72 *   No tasks are actively using the namespace and it isn't pinned by
 73 *   any bind-mounts or open file descriptors anymore. But the namespace
 74 *   is still kept alive by internal references. For example, the user
 75 *   namespace could be pinned by an open file through file->f_cred
 76 *   references when one of the now defunct tasks had opened a file and
 77 *   handed the file descriptor off to another process via a UNIX
 78 *   sockets. Such references keep the namespace structure alive through
 79 *   __ns_ref but will not hold an active reference.
 80 *
 81 * - Destroyed (__ns_ref == 0):
 82 *   No references remain. The namespace is removed from the tree and freed.
 83 *
 84 * State transitions:
 85 *
 86 * Active -> Inactive:
 87 *   When the last task using the namespace exits it drops its active
 88 *   references to all namespaces. However, user and pid namespaces
 89 *   remain accessible until the task has been reaped.
 90 *
 91 * Inactive -> Active:
 92 *   An inactive namespace tree might be resurrected due to e.g., the
 93 *   SIOCGSKNS ioctl() on a socket.
 94 *
 95 * Inactive -> Destroyed:
 96 *   When __ns_ref drops to zero the namespace is removed from the
 97 *   namespaces trees and the memory is freed (after RCU grace period).
 98 *
 99 * Initial namespaces:
100 *   Boot-time namespaces (init_net, init_pid_ns, etc.) start with
101 *   __ns_ref_active = 1 and remain active forever.
102 *
103 * @ns_type: type of namespace (e.g., CLONE_NEWNET)
104 * @stashed: cached dentry to be used by the vfs
105 * @ops: namespace operations
106 * @inum: namespace inode number (quickly recycled for non-initial namespaces)
107 * @__ns_ref: main reference count (do not use directly)
108 * @ns_tree: namespace tree nodes and active reference count
109 */
110struct ns_common {
111	u32 ns_type;
112	struct dentry *stashed;
113	const struct proc_ns_operations *ops;
114	unsigned int inum;
115	refcount_t __ns_ref; /* do not use directly */
116	union {
117		struct ns_tree;
118		struct rcu_head ns_rcu;
119	};
120};
121
122#define to_ns_common(__ns)                                    \
123	_Generic((__ns),                                      \
124		struct cgroup_namespace *:       &(__ns)->ns, \
125		const struct cgroup_namespace *: &(__ns)->ns, \
126		struct ipc_namespace *:          &(__ns)->ns, \
127		const struct ipc_namespace *:    &(__ns)->ns, \
128		struct mnt_namespace *:          &(__ns)->ns, \
129		const struct mnt_namespace *:    &(__ns)->ns, \
130		struct net *:                    &(__ns)->ns, \
131		const struct net *:              &(__ns)->ns, \
132		struct pid_namespace *:          &(__ns)->ns, \
133		const struct pid_namespace *:    &(__ns)->ns, \
134		struct time_namespace *:         &(__ns)->ns, \
135		const struct time_namespace *:   &(__ns)->ns, \
136		struct user_namespace *:         &(__ns)->ns, \
137		const struct user_namespace *:   &(__ns)->ns, \
138		struct uts_namespace *:          &(__ns)->ns, \
139		const struct uts_namespace *:    &(__ns)->ns)
140
141#define ns_init_inum(__ns)                                     \
142	_Generic((__ns),                                       \
143		struct cgroup_namespace *: CGROUP_NS_INIT_INO, \
144		struct ipc_namespace *:    IPC_NS_INIT_INO,    \
145		struct mnt_namespace *:    MNT_NS_INIT_INO,    \
146		struct net *:              NET_NS_INIT_INO,    \
147		struct pid_namespace *:    PID_NS_INIT_INO,    \
148		struct time_namespace *:   TIME_NS_INIT_INO,   \
149		struct user_namespace *:   USER_NS_INIT_INO,   \
150		struct uts_namespace *:    UTS_NS_INIT_INO)
151
152#define ns_init_ns(__ns)                                    \
153	_Generic((__ns),                                    \
154		struct cgroup_namespace *: &init_cgroup_ns, \
155		struct ipc_namespace *:    &init_ipc_ns,    \
156		struct mnt_namespace *:    &init_mnt_ns,     \
157		struct net *:              &init_net,       \
158		struct pid_namespace *:    &init_pid_ns,    \
159		struct time_namespace *:   &init_time_ns,   \
160		struct user_namespace *:   &init_user_ns,   \
161		struct uts_namespace *:    &init_uts_ns)
162
163#define ns_init_id(__ns)						\
164	_Generic((__ns),						\
165		struct cgroup_namespace *:	CGROUP_NS_INIT_ID,	\
166		struct ipc_namespace *:		IPC_NS_INIT_ID,		\
167		struct mnt_namespace *:		MNT_NS_INIT_ID,		\
168		struct net *:			NET_NS_INIT_ID,		\
169		struct pid_namespace *:		PID_NS_INIT_ID,		\
170		struct time_namespace *:	TIME_NS_INIT_ID,	\
171		struct user_namespace *:	USER_NS_INIT_ID,	\
172		struct uts_namespace *:		UTS_NS_INIT_ID)
173
174#define to_ns_operations(__ns)                                                                         \
175	_Generic((__ns),                                                                               \
176		struct cgroup_namespace *: (IS_ENABLED(CONFIG_CGROUPS) ? &cgroupns_operations : NULL), \
177		struct ipc_namespace *:    (IS_ENABLED(CONFIG_IPC_NS)  ? &ipcns_operations    : NULL), \
178		struct mnt_namespace *:    &mntns_operations,                                          \
179		struct net *:              (IS_ENABLED(CONFIG_NET_NS)  ? &netns_operations    : NULL), \
180		struct pid_namespace *:    (IS_ENABLED(CONFIG_PID_NS)  ? &pidns_operations    : NULL), \
181		struct time_namespace *:   (IS_ENABLED(CONFIG_TIME_NS) ? &timens_operations   : NULL), \
182		struct user_namespace *:   (IS_ENABLED(CONFIG_USER_NS) ? &userns_operations   : NULL), \
183		struct uts_namespace *:    (IS_ENABLED(CONFIG_UTS_NS)  ? &utsns_operations    : NULL))
184
185#define ns_common_type(__ns)                                \
186	_Generic((__ns),                                    \
187		struct cgroup_namespace *: CLONE_NEWCGROUP, \
188		struct ipc_namespace *:    CLONE_NEWIPC,    \
189		struct mnt_namespace *:    CLONE_NEWNS,     \
190		struct net *:              CLONE_NEWNET,    \
191		struct pid_namespace *:    CLONE_NEWPID,    \
192		struct time_namespace *:   CLONE_NEWTIME,   \
193		struct user_namespace *:   CLONE_NEWUSER,   \
194		struct uts_namespace *:    CLONE_NEWUTS)
195
196#endif /* _LINUX_NS_COMMON_TYPES_H */