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 */
197

source code of linux/include/linux/ns/ns_common_types.h