1.. SPDX-License-Identifier: GPL-2.0
2
3=============
4Sysfs tagging
5=============
6
7(Taken almost verbatim from Eric Biederman's netns tagging patch
8commit msg)
9
10The problem.  Network devices show up in sysfs and with the network
11namespace active multiple devices with the same name can show up in
12the same directory, ouch!
13
14To avoid that problem and allow existing applications in network
15namespaces to see the same interface that is currently presented in
16sysfs, sysfs now has tagging directory support.
17
18By using the network namespace pointers as tags to separate out
19the sysfs directory entries we ensure that we don't have conflicts
20in the directories and applications only see a limited set of
21the network devices.
22
23Each sysfs directory entry may be tagged with a namespace via the
24``void *ns member`` of its ``kernfs_node``.  If a directory entry is tagged,
25then ``kernfs_node->flags`` will have a flag between KOBJ_NS_TYPE_NONE
26and KOBJ_NS_TYPES, and ns will point to the namespace to which it
27belongs.
28
29Each sysfs superblock's kernfs_super_info contains an array
30``void *ns[KOBJ_NS_TYPES]``.  When a task in a tagging namespace
31kobj_nstype first mounts sysfs, a new superblock is created.  It
32will be differentiated from other sysfs mounts by having its
33``s_fs_info->ns[kobj_nstype]`` set to the new namespace.  Note that
34through bind mounting and mounts propagation, a task can easily view
35the contents of other namespaces' sysfs mounts.  Therefore, when a
36namespace exits, it will call kobj_ns_exit() to invalidate any
37kernfs_node->ns pointers pointing to it.
38
39Users of this interface:
40
41- define a type in the ``kobj_ns_type`` enumeration.
42- call kobj_ns_type_register() with its ``kobj_ns_type_operations`` which has
43
44  - current_ns() which returns current's namespace
45  - netlink_ns() which returns a socket's namespace
46  - initial_ns() which returns the initial namespace
47
48- call kobj_ns_exit() when an individual tag is no longer valid
49