title: mount_namespaces(7)

summary: overview of Linux mount namespaces

text:
# mount_namespaces(7)

## NAME
mount_namespaces - overview of Linux mount namespaces

## DESCRIPTION
For an overview of namespaces, see namespaces(7).

Mount namespaces provide isolation of the list of mounts seen by the processes in each namespace instance. Thus, the processes in each of the mount namespace instances will see distinct single-directory hierarchies.

The views provided by the /proc/pid/mounts, /proc/pid/mountinfo, and /proc/pid/mountstats files (all described in proc(5)) correspond to the mount namespace in which the process with the PID pid resides. (All of the processes that reside in the same mount namespace will see the same view in these files.)

A new mount namespace is created using either clone(2) or unshare(2) with the CLONE_NEWNS flag. When a new mount namespace is created, its mount list is initialized as follows:

•

If the namespace is created using clone(2), the mount list of the child's namespace is a copy of the mount list in the parent process's mount namespace.

•

If the namespace is created using unshare(2), the mount list of the new namespace is a copy of the mount list in the caller's previous mount namespace.

Subsequent modifications to the mount list (mount(2) and umount(2)) in either mount namespace will not (by default) affect the mount list seen in the other namespace (but see the following discussion of shared subtrees).

## SHARED SUBTREES
After the implementation of mount namespaces was completed, experience showed that the isolation that they provided was, in some cases, too great. For example, in order to make a newly loaded optical disk available in all mount namespaces, a mount operation was required in each namespace. For this use case, and others, the shared subtree feature was introduced in Linux 2.6.15. This feature allows for automatic, controlled propagation of mount(2) and umount(2) events between namespaces (or, more precisely, between the mounts that are members of a peer group that are propagating events to one another).

Each mount is marked (via mount(2)) as having one of the following propagation types:

MS_SHARED

This mount shares events with members of a peer group. mount(2) and umount(2) events immediately under this mount will propagate to the other mounts that are members of the peer group. Propagation here means that the same mount(2) or umount(2) will automatically occur under all of the other mounts in the peer group. Conversely, mount(2) and umount(2) events that take place under peer mounts will propagate to this mount.

MS_PRIVATE

This mount is private; it does not have a peer group. mount(2) and umount(2) events do not propagate into or out of this mount.

MS_SLAVE

mount(2) and umount(2) events propagate into this mount from a (master) shared peer group. mount(2) and umount(2) events under this mount do not propagate to any peer.

Note that a mount can be the slave of another peer group while at the same time sharing mount(2) and umount(2) events with a peer group of which it is a member. (More precisely, one peer group can be the slave of another peer group.)

MS_UNBINDABLE

This is like a private mount, and in addition this mount can't be bind mounted. Attempts to bind mount this mount (mount(2) with the MS_BIND flag) will fail.

When a recursive bind mount (mount(2) with the MS_BIND and MS_REC flags) is performed on a directory subtree, any bind mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree.

For a discussion of the propagation type assigned to a new mount, see NOTES.

The propagation type is a per-mount-point setting; some mounts may be marked as shared (with each shared mount being a member of a distinct peer group), while others are private (or slaved or unbindable).

Note that a mount's propagation type determines whether mount(2) and umount(2) of mounts immediately under the mount are propagated. Thus, the propagation type does not affect propagation of events for grandchildren and further removed descendant mounts. What happens if the mount itself is unmounted is determined by the propagation type that is in effect for the parent of the mount.

Members are added to a peer group when a mount is marked as shared and either:

(a)

the mount is replicated during the creation of a new mount namespace; or

(b)

a new bind mount is created from the mount.

In both of these cases, the new mount joins the peer group of which the existing mount is a member.

A new peer group is also created when a child mount is created under an existing mount that is marked as shared. In this case, the new child mount is also marked as shared and the resulting peer group consists of all the mounts that are replicated under the peers of parent mounts.

A mount ceases to be a member of a peer group when either the mount is explicitly unmounted, or when the mount is implicitly unmounted because a mount namespace is removed (because it has no more member processes).

The propagation type of the mounts in a mount namespace can be discovered via the "optional fields" exposed in /proc/pid/mountinfo. (See proc(5) for details of this file.) The following tags can appear in the optional fields for a record in that file:

shared:X

This mount is shared in peer group X. Each peer group has a unique ID that is automatically generated by the kernel, and all mounts in the same peer group will show the same ID. (These IDs are assigned starting from the value 1, and may be recycled when a peer group ceases to have any members.)

master:X

This mount is a slave to shared peer group X.

propagate_from:X (since Linux 2.6.26)

This mount is a slave and receives propagation from shared peer group X. This tag will always appear in conjunction with a master:X tag. Here, X is the closest dominant peer group under the process's root directory. If X is the immediate master of the mount, or if there is no dominant peer group under the same root, then only the master:X field is present and not the propagate_from:X field. For further details, see below.

unbindable

This is an unbindable mount.

If none of the above tags is present, then this is a private mount.

### MS_SHARED and MS_PRIVATE example
Suppose that on a terminal in the initial mount namespace, we mark one mount as shared and another as private, and then view the mounts in /proc/self/mountinfo:

```
sh1# mount --make-shared /mntS
sh1# mount --make-private /mntP
sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
77 61 8:17 / /mntS rw,relatime shared:1
83 61 8:15 / /mntP rw,relatime
```

From the /proc/self/mountinfo output, we see that /mntS is a shared mount in peer group 1, and that /mntP has no optional tags, indicating that it is a private mount. The first two fields in each record in this file are the unique ID for this mount, and the mount ID of the parent mount. We can further inspect this file to see that the parent mount of /mntS and /mntP is the root directory, /, which is mounted as private:

```
sh1# cat /proc/self/mountinfo | awk '$1 == 61' | sed 's/ - .*//'
61 0 8:2 / / rw,relatime
```

On a second terminal, we create a new mount namespace where we run a second shell and inspect the mounts:

```
$ PS1='sh2# ' sudo unshare -m --propagation unchanged sh
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
222 145 8:17 / /mntS rw,relatime shared:1
225 145 8:15 / /mntP rw,relatime
```

The new mount namespace received a copy of the initial mount namespace's mounts. These new mounts maintain the same propagation types, but have unique mount IDs. (The --propagation unchanged option prevents unshare(1) from marking all mounts as private when creating a new mount namespace, which it does by default.)

In the second terminal, we then create submounts under each of /mntS and /mntP and inspect the set-up:

```
sh2# mkdir /mntS/a
sh2# mount /dev/sdb6 /mntS/a
sh2# mkdir /mntP/b
sh2# mount /dev/sdb7 /mntP/b
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
222 145 8:17 / /mntS rw,relatime shared:1
225 145 8:15 / /mntP rw,relatime
178 222 8:22 / /mntS/a rw,relatime shared:2
230 225 8:23 / /mntP/b rw,relatime
```

From the above, it can be seen that /mntS/a was created as shared (inheriting this setting from its parent mount) and /mntP/b was created as a private mount.

Returning to the first terminal and inspecting the set-up, we see that the new mount created under the shared mount /mntS propagated to its peer mount (in the initial mount namespace), but the new mount created under the private mount /mntP did not propagate:

```
sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
77 61 8:17 / /mntS rw,relatime shared:1
83 61 8:15 / /mntP rw,relatime
179 77 8:22 / /mntS/a rw,relatime shared:2
```

### MS_SLAVE example
Making a mount a slave allows it to receive propagated mount(2) and umount(2) events from a master shared peer group, while preventing it from propagating events to that master. This is useful if we want to (say) receive a mount event when an optical disk is mounted in the master shared peer group (in another mount namespace), but want to prevent mount(2) and umount(2) events under the slave mount from having side effects in other namespaces.

We can demonstrate the effect of slaving by first marking two mounts as shared in the initial mount namespace:

```
sh1# mount --make-shared /mntX
sh1# mount --make-shared /mntY
sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
132 83 8:23 / /mntX rw,relatime shared:1
133 83 8:22 / /mntY rw,relatime shared:2
```

On a second terminal, we create a new mount namespace and inspect the mounts:

```
sh2# unshare -m --propagation unchanged sh
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
168 167 8:23 / /mntX rw,relatime shared:1
169 167 8:22 / /mntY rw,relatime shared:2
```

In the new mount namespace, we then mark one of the mounts as a slave:

```
sh2# mount --make-slave /mntY
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
168 167 8:23 / /mntX rw,relatime shared:1
169 167 8:22 / /mntY rw,relatime master:2
```

From the above output, we see that /mntY is now a slave mount that is receiving propagation events from the shared peer group with the ID 2.

Continuing in the new namespace, we create submounts under each of /mntX and /mntY:

```
sh2# mkdir /mntX/a
sh2# mount /dev/sda3 /mntX/a
sh2# mkdir /mntY/b
sh2# mount /dev/sda5 /mntY/b
```

When we inspect the state of the mounts in the new mount namespace, we see that /mntX/a was created as a new shared mount (inheriting the "shared" setting from its parent mount) and /mntY/b was created as a private mount:

```
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
168 167 8:23 / /mntX rw,relatime shared:1
169 167 8:22 / /mntY rw,relatime master:2
173 168 8:3 / /mntX/a rw,relatime shared:3
175 169 8:5 / /mntY/b rw,relatime
```

Returning to the first terminal (in the initial mount namespace), we see that the mount /mntX/a propagated to the peer (the shared /mntX), but the mount /mntY/b was not propagated:

```
sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
132 83 8:23 / /mntX rw,relatime shared:1
133 83 8:22 / /mntY rw,relatime shared:2
174 132 8:3 / /mntX/a rw,relatime shared:3
```

Now we create a new mount under /mntY in the first shell:

```
sh1# mkdir /mntY/c
sh1# mount /dev/sda1 /mntY/c
sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
132 83 8:23 / /mntX rw,relatime shared:1
133 83 8:22 / /mntY rw,relatime shared:2
174 132 8:3 / /mntX/a rw,relatime shared:3
178 133 8:1 / /mntY/c rw,relatime shared:4
```

When we examine the mounts in the second mount namespace, we see that in this case the new mount has been propagated to the slave mount, and that the new mount is itself a slave mount (to peer group 4):

```
sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
168 167 8:23 / /mntX rw,relatime shared:1
169 167 8:22 / /mntY rw,relatime master:2
173 168 8:3 / /mntX/a rw,relatime shared:3
175 169 8:5 / /mntY/b rw,relatime
179 169 8:1 / /mntY/c rw,relatime master:4
```

### MS_UNBINDABLE example
One of the primary purposes of unbindable mounts is to avoid the "mount explosion" problem when repeatedly performing bind mounts of a higher-level subtree at a lower-level mount. The problem is illustrated by the following shell session.

Suppose we have a system with the following mounts:

```
# mount | awk '{print $1, $2, $3}'
/dev/sda1 on /
/dev/sdb6 on /mntX
/dev/sdb7 on /mntY
```

Suppose furthermore that we wish to recursively bind mount the root directory under several users' home directories. We do this for the first user, and inspect the mounts:

```
# mount --rbind / /home/cecilia/
# mount | awk '{print $1, $2, $3}'
/dev/sda1 on /
/dev/sdb6 on /mntX
/dev/sdb7 on /mntY
/dev/sda1 on /home/cecilia
/dev/sdb6 on /home/cecilia/mntX
/dev/sdb7 on /home/cecilia/mntY
```

When we repeat this operation for the second user, we start to see the explosion problem:

```
# mount --rbind / /home/henry
# mount | awk '{print $1, $2, $3}'
/dev/sda1 on /
/dev/sdb6 on /mntX
/dev/sdb7 on /mntY
/dev/sda1 on /home/cecilia
/dev/sdb6 on /home/cecilia/mntX
/dev/sdb7 on /home/cecilia/mntY
/dev/sda1 on /home/henry
/dev/sdb6 on /home/henry/mntX
/dev/sdb7 on /home/henry/mntY
/dev/sda1 on /home/henry/home/cecilia
/dev/sdb6 on /home/henry/home/cecilia/mntX
/dev/sdb7 on /home/henry/home/cecilia/mntY
```

Under /home/henry, we have not only recursively added the /mntX and /mntY mounts, but also the recursive mounts of those directories under /home/cecilia that were created in the previous step. Upon repeating the step for a third user, it becomes obvious that the explosion is exponential in nature:

```
# mount --rbind / /home/otto
# mount | awk '{print $1, $2, $3}'
/dev/sda1 on /
/dev/sdb6 on /mntX
/dev/sdb7 on /mntY
/dev/sda1 on /home/cecilia
/dev/sdb6 on /home/cecilia/mntX
/dev/sdb7 on /home/cecilia/mntY
/dev/sda1 on /home/henry
/dev/sdb6 on /home/henry/mntX
/dev/sdb7 on /home/henry/mntY
/dev/sda1 on /home/henry/home/cecilia
/dev/sdb6 on /home/henry/home/cecilia/mntX
/dev/sdb7 on /home/henry/home/cecilia/mntY
/dev/sda1 on /home/otto
/dev/sdb6 on /home/otto/mntX
/dev/sdb7 on /home/otto/mntY
/dev/sda1 on /home/otto/home/cecilia
/dev/sdb6 on /home/otto/home/cecilia/mntX
/dev/sdb7 on /home/otto/home/cecilia/mntY
/dev/sda1 on /home/otto/home/henry
/dev/sdb6 on /home/otto/home/henry/mntX
/dev/sdb7 on /home/otto/home/henry/mntY
/dev/sda1 on /home/otto/home/henry/home/cecilia
/dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX
/dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY
```

The mount explosion problem in the above scenario can be avoided by making each of the new mounts unbindable. The effect of doing this is that recursive mounts of the root directory will not replicate the unbindable mounts. We make such a mount for the first user:

```
# mount --rbind --make-unbindable / /home/cecilia
```

Before going further, we show that unbindable mounts are indeed unbindable:

```
# mkdir /mntZ
# mount --bind /home/cecilia /mntZ
mount: wrong fs type, bad option, bad superblock on /home/cecilia,

       missing codepage or helper program, or other error

       In some cases useful info is found in syslog - try

       dmesg | tail or so.
```

Now we create unbindable recursive bind mounts for the other two users:

```
# mount --rbind --make-unbindable / /home/henry
# mount --rbind --make-unbindable / /home/otto
```

Upon examining the list of mounts, we see there has been no explosion of mounts, because the unbindable mounts were not replicated under each user's directory:

```
# mount | awk '{print $1, $2, $3}'
/dev/sda1 on /
/dev/sdb6 on /mntX
/dev/sdb7 on /mntY
/dev/sda1 on /home/cecilia
/dev/sdb6 on /home/cecilia/mntX
/dev/sdb7 on /home/cecilia/mntY
/dev/sda1 on /home/henry
/dev/sdb6 on /home/henry/mntX
/dev/sdb7 on /home/henry/mntY
/dev/sda1 on /home/otto
/dev/sdb6 on /home/otto/mntX
/dev/sdb7 on /home/otto/mntY
```

### Propagation type transitions
The following table shows the effect that applying a new propagation type (i.e., mount --make-xxxx) has on the existing propagation type of a mount. The rows correspond to existing propagation types, and the columns are the new propagation settings. For reasons of space, "private" is abbreviated as "priv" and "unbindable" as "unbind".

make-shared

make-slave

make-priv

make-unbind

shared

shared

slave/priv [1]

priv

unbind

slave

slave+shared

slave [2]

priv

unbind

slave+shared

slave+shared

slave

priv

unbind

private

shared

priv [2]

priv

unbind

unbindable

shared

unbind [2]

priv

unbind

Note the following details to the table:

[1]

If a shared mount is the only mount in its peer group, making it a slave automatically makes it private.

[2]

Slaving a nonshared mount has no effect on the mount.

### Bind (MS_BIND) semantics
Suppose that the following command is performed:

```
mount --bind A/a B/b
```

Here, A is the source mount, B is the destination mount, a is a subdirectory path under the mount point A, and b is a subdirectory path under the mount point B. The propagation type of the resulting mount, B/b, depends on the propagation types of the mounts A and B, and is summarized in the following table.

source(A)

shared

private

slave

unbind

dest(B)

shared

shared

shared

slave+shared

invalid

nonshared

shared

private

slave

invalid

Note that a recursive bind of a subtree follows the same semantics as for a bind operation on each mount in the subtree. (Unbindable mounts are automatically pruned at the target mount point.)

For further details, see Documentation/filesystems/sharedsubtree.rst in the kernel source tree.

### Move (MS_MOVE) semantics
Suppose that the following command is performed:

```
mount --move A B/b
```

Here, A is the source mount, B is the destination mount, and b is a subdirectory path under the mount point B. The propagation type of the resulting mount, B/b, depends on the propagation types of the mounts A and B, and is summarized in the following table.

source(A)

shared

private

slave

unbind

dest(B)

shared

shared

shared

slave+shared

invalid

nonshared

shared

private

slave

unbindable

Note: moving a mount that resides under a shared mount is invalid.

For further details, see Documentation/filesystems/sharedsubtree.rst in the kernel source tree.

### Mount semantics
Suppose that we use the following command to create a mount:

```
mount device B/b
```

Here, B is the destination mount, and b is a subdirectory path under the mount point B. The propagation type of the resulting mount, B/b, follows the same rules as for a bind mount, where the propagation type of the source mount is considered always to be private.

### Unmount semantics
Suppose that we use the following command to tear down a mount:

```
umount A
```

Here, A is a mount on B/b, where B is the parent mount and b is a subdirectory path under the mount point B. If B is shared, then all most-recently-mounted mounts at b on mounts that receive propagation from mount B and do not have submounts under them are unmounted.

### The /proc/ pid /mountinfo propagate_from tag
The propagate_from:X tag is shown in the optional fields of a /proc/pid/mountinfo record in cases where a process can't see a slave's immediate master (i.e., the pathname of the master is not reachable from the filesystem root directory) and so cannot determine the chain of propagation between the mounts it can see.

In the following example, we first create a two-link master-slave chain between the mounts /mnt, /tmp/etc, and /mnt/tmp/etc. Then the chroot(1) command is used to make the /tmp/etc mount point unreachable from the root directory, creating a situation where the master of /mnt/tmp/etc is not reachable from the (new) root directory of the process.

First, we bind mount the root directory onto /mnt and then bind mount /proc at /mnt/proc so that after the later chroot(1) the proc(5) filesystem remains visible at the correct location in the chroot-ed environment.

```
# mkdir -p /mnt/proc
# mount --bind / /mnt
# mount --bind /proc /mnt/proc
```

Next, we ensure that the /mnt mount is a shared mount in a new peer group (with no peers):

```
# mount --make-private /mnt  # Isolate from any previous peer group
# mount --make-shared /mnt
# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
239 61 8:2 / /mnt ... shared:102
248 239 0:4 / /mnt/proc ... shared:5
```

Next, we bind mount /mnt/etc onto /tmp/etc:

```
# mkdir -p /tmp/etc
# mount --bind /mnt/etc /tmp/etc
# cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
239 61 8:2 / /mnt ... shared:102
248 239 0:4 / /mnt/proc ... shared:5
267 40 8:2 /etc /tmp/etc ... shared:102
```

Initially, these two mounts are in the same peer group, but we then make the /tmp/etc a slave of /mnt/etc, and then make /tmp/etc shared as well, so that it can propagate events to the next slave in the chain:

```
# mount --make-slave /tmp/etc
# mount --make-shared /tmp/etc
# cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
239 61 8:2 / /mnt ... shared:102
248 239 0:4 / /mnt/proc ... shared:5
267 40 8:2 /etc /tmp/etc ... shared:105 master:102
```

Then we bind mount /tmp/etc onto /mnt/tmp/etc. Again, the two mounts are initially in the same peer group, but we then make /mnt/tmp/etc a slave of /tmp/etc:

```
# mkdir -p /mnt/tmp/etc
# mount --bind /tmp/etc /mnt/tmp/etc
# mount --make-slave /mnt/tmp/etc
# cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
239 61 8:2 / /mnt ... shared:102
248 239 0:4 / /mnt/proc ... shared:5
267 40 8:2 /etc /tmp/etc ... shared:105 master:102
273 239 8:2 /etc /mnt/tmp/etc ... master:105
```

From the above, we see that /mnt is the master of the slave /tmp/etc, which in turn is the master of the slave /mnt/tmp/etc.

We then chroot(1) to the /mnt directory, which renders the mount with ID 267 unreachable from the (new) root directory:

```
# chroot /mnt
```

When we examine the state of the mounts inside the chroot-ed environment, we see the following:

```
# cat /proc/self/mountinfo | sed 's/ - .*//'
239 61 8:2 / / ... shared:102
248 239 0:4 / /proc ... shared:5
273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102
```

Above, we see that the mount with ID 273 is a slave whose master is the peer group 105. The mount point for that master is unreachable, and so a propagate_from tag is displayed, indicating that the closest dominant peer group (i.e., the nearest reachable mount in the slave chain) is the peer group with the ID 102 (corresponding to the /mnt mount point before the chroot(1) was performed).

## STANDARDS
Linux.

## HISTORY
Linux 2.4.19.

## NOTES
The propagation type assigned to a new mount depends on the propagation type of the parent mount. If the mount has a parent (i.e., it is a non-root mount point) and the propagation type of the parent is MS_SHARED, then the propagation type of the new mount is also MS_SHARED. Otherwise, the propagation type of the new mount is MS_PRIVATE.

Notwithstanding the fact that the default propagation type for new mount is in many cases MS_PRIVATE, MS_SHARED is typically more useful. For this reason, systemd(1) automatically remounts all mounts as MS_SHARED on system startup. Thus, on most modern systems, the default propagation type is in practice MS_SHARED.

Since, when one uses unshare(1) to create a mount namespace, the goal is commonly to provide full isolation of the mounts in the new namespace, unshare(1) (since util-linux 2.27) in turn reverses the step performed by systemd(1), by making all mounts private in the new namespace. That is, unshare(1) performs the equivalent of the following in the new mount namespace:

```
mount --make-rprivate /
```

To prevent this, one can use the --propagation unchanged option to unshare(1).

An application that creates a new mount namespace directly using clone(2) or unshare(2) may desire to prevent propagation of mount events to other mount namespaces (as is done by unshare(1)). This can be done by changing the propagation type of mounts in the new namespace to either MS_SLAVE or MS_PRIVATE, using a call such as the following:

```
mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
```

For a discussion of propagation types when moving mounts (MS_MOVE) and creating bind mounts (MS_BIND), see Documentation/filesystems/sharedsubtree.rst.

### Restrictions on mount namespaces
Note the following points with respect to mount namespaces:

[1]

Each mount namespace has an owner user namespace. As explained above, when a new mount namespace is created, its mount list is initialized as a copy of the mount list of another mount namespace. If the new namespace and the namespace from which the mount list was copied are owned by different user namespaces, then the new mount namespace is considered less privileged.

[2]

When creating a less privileged mount namespace, shared mounts are reduced to slave mounts. This ensures that mappings performed in less privileged mount namespaces will not propagate to more privileged mount namespaces.

[3]

Mounts that come as a single unit from a more privileged mount namespace are locked together and may not be separated in a less privileged mount namespace. (The unshare(2) CLONE_NEWNS operation brings across all of the mounts from the original mount namespace as a single unit, and recursive mounts that propagate between mount namespaces propagate as a single unit.)

In this context, "may not be separated" means that the mounts are locked so that they may not be individually unmounted. Consider the following example:

```
$ sudo sh
# mount --bind /dev/null /etc/shadow
# cat /etc/shadow       # Produces no output

```

The above steps, performed in a more privileged mount namespace, have created a bind mount that obscures the contents of the shadow password file, /etc/shadow. For security reasons, it should not be possible to umount(2) that mount in a less privileged mount namespace, since that would reveal the contents of /etc/shadow.

Suppose we now create a new mount namespace owned by a new user namespace. The new mount namespace will inherit copies of all of the mounts from the previous mount namespace. However, those mounts will be locked because the new mount namespace is less privileged. Consequently, an attempt to umount(2) the mount fails as show in the following step:

```
# unshare --user --map-root-user --mount \

               strace -o /tmp/log \

               umount /mnt/dir
umount: /etc/shadow: not mounted.
# grep '^umount' /tmp/log
umount2("/etc/shadow", 0)     = -1 EINVAL (Invalid argument)

```

The error message from mount(8) is a little confusing, but the strace(1) output reveals that the underlying umount2(2) system call failed with the error EINVAL, which is the error that the kernel returns to indicate that the mount is locked.

Note, however, that it is possible to stack (and unstack) a mount on top of one of the inherited locked mounts in a less privileged mount namespace:

```
# echo 'aaaaa' > /tmp/a    # File to mount onto /etc/shadow
# unshare --user --map-root-user --mount \

    sh -c 'mount --bind /tmp/a /etc/shadow; cat /etc/shadow'
aaaaa
# umount /etc/shadow

```

The final umount(8) command above, which is performed in the initial mount namespace, makes the original /etc/shadow file once more visible in that namespace.

[4]

Following on from point [3], note that it is possible to umount(2) an entire subtree of mounts that propagated as a unit into a less privileged mount namespace, as illustrated in the following example.

First, we create new user and mount namespaces using unshare(1). In the new mount namespace, the propagation type of all mounts is set to private. We then create a shared bind mount at /mnt, and a small hierarchy of mounts underneath that mount.

```
$ PS1='ns1# ' sudo unshare --user --map-root-user \

                       --mount --propagation private bash
ns1# echo $$        # We need the PID of this shell later
778501
ns1# mount --make-shared --bind /mnt /mnt
ns1# mkdir /mnt/x
ns1# mount --make-private -t tmpfs none /mnt/x
ns1# mkdir /mnt/x/y
ns1# mount --make-private -t tmpfs none /mnt/x/y
ns1# grep /mnt /proc/self/mountinfo | sed 's/ - .*//'
986 83 8:5 /mnt /mnt rw,relatime shared:344
989 986 0:56 / /mnt/x rw,relatime
990 989 0:57 / /mnt/x/y rw,relatime

```

Continuing in the same shell session, we then create a second shell in a new user namespace and a new (less privileged) mount namespace and check the state of the propagated mounts rooted at /mnt.

```
ns1# PS1='ns2# ' unshare --user --map-root-user \

                       --mount --propagation unchanged bash
ns2# grep /mnt /proc/self/mountinfo | sed 's/ - .*//'
1239 1204 8:5 /mnt /mnt rw,relatime master:344
1240 1239 0:56 / /mnt/x rw,relatime
1241 1240 0:57 / /mnt/x/y rw,relatime

```

Of note in the above output is that the propagation type of the mount /mnt has been reduced to slave, as explained in point [2]. This means that submount events will propagate from the master /mnt in "ns1", but propagation will not occur in the opposite direction.

From a separate terminal window, we then use nsenter(1) to enter the mount and user namespaces corresponding to "ns1". In that terminal window, we then recursively bind mount /mnt/x at the location /mnt/ppp.

```
$ PS1='ns3# ' sudo nsenter -t 778501 --user --mount
ns3# mount --rbind --make-private /mnt/x /mnt/ppp
ns3# grep /mnt /proc/self/mountinfo | sed 's/ - .*//'
986 83 8:5 /mnt /mnt rw,relatime shared:344
989 986 0:56 / /mnt/x rw,relatime
990 989 0:57 / /mnt/x/y rw,relatime
1242 986 0:56 / /mnt/ppp rw,relatime
1243 1242 0:57 / /mnt/ppp/y rw,relatime shared:518

```

Because the propagation type of the parent mount, /mnt, was shared, the recursive bind mount propagated a small subtree of mounts under the slave mount /mnt into "ns2", as can be verified by executing the following command in that shell session:

```
ns2# grep /mnt /proc/self/mountinfo | sed 's/ - .*//'
1239 1204 8:5 /mnt /mnt rw,relatime master:344
1240 1239 0:56 / /mnt/x rw,relatime
1241 1240 0:57 / /mnt/x/y rw,relatime
1244 1239 0:56 / /mnt/ppp rw,relatime
1245 1244 0:57 / /mnt/ppp/y rw,relatime master:518

```

While it is not possible to umount(2) a part of the propagated subtree (/mnt/ppp/y) in "ns2", it is possible to umount(2) the entire subtree, as shown by the following commands:

```
ns2# umount /mnt/ppp/y
umount: /mnt/ppp/y: not mounted.
ns2# umount -l /mnt/ppp | sed 's/ - .*//'      # Succeeds...
ns2# grep /mnt /proc/self/mountinfo
1239 1204 8:5 /mnt /mnt rw,relatime master:344
1240 1239 0:56 / /mnt/x rw,relatime
1241 1240 0:57 / /mnt/x/y rw,relatime

```

[5]

The mount(2) flags MS_RDONLY, MS_NOSUID, MS_NOEXEC, and the "atime" flags (MS_NOATIME, MS_NODIRATIME, MS_RELATIME) settings become locked when propagated from a more privileged to a less privileged mount namespace, and may not be changed in the less privileged mount namespace.

This point is illustrated in the following example where, in a more privileged mount namespace, we create a bind mount that is marked as read-only. For security reasons, it should not be possible to make the mount writable in a less privileged mount namespace, and indeed the kernel prevents this:

```
$ sudo mkdir /mnt/dir
$ sudo mount --bind -o ro /some/path /mnt/dir
$ sudo unshare --user --map-root-user --mount \

               mount -o remount,rw /mnt/dir
mount: /mnt/dir: permission denied.

```

[6]

A file or directory that is a mount point in one namespace that is not a mount point in another namespace, may be renamed, unlinked, or removed (rmdir(2)) in the mount namespace in which it is not a mount point (subject to the usual permission checks). Consequently, the mount point is removed in the mount namespace where it was a mount point.

Previously (before Linux 3.18), attempting to unlink, rename, or remove a file or directory that was a mount point in another mount namespace would result in the error EBUSY. That behavior had technical problems of enforcement (e.g., for NFS) and permitted denial-of-service attacks against more privileged users (i.e., preventing individual files from being updated by bind mounting on top of them).

## EXAMPLES
See pivot_root(2).

## SEE ALSO
unshare(1), clone(2), mount(2), mount_setattr(2), pivot_root(2), setns(2), umount(2), unshare(2), proc(5), namespaces(7), user_namespaces(7), findmnt(8), mount(8), pam_namespace(8), pivot_root(8), umount(8)

Documentation/filesystems/sharedsubtree.rst in the kernel source tree.


package: man-pages

title: mq_overview(7)

summary: overview of POSIX message queues

text:
# mq_overview(7)

## NAME
mq_overview - overview of POSIX message queues

## DESCRIPTION
POSIX message queues allow processes to exchange data in the form of messages. This API is distinct from that provided by System V message queues (msgget(2), msgsnd(2), msgrcv(2), etc.), but provides similar functionality.

Message queues are created and opened using mq_open(3); this function returns a message queue descriptor (mqd_t), which is used to refer to the open message queue in later calls. Each message queue is identified by a name of the form /somename; that is, a null-terminated string of up to NAME_MAX (i.e., 255) characters consisting of an initial slash, followed by one or more characters, none of which are slashes. Two processes can operate on the same queue by passing the same name to mq_open(3).

Messages are transferred to and from a queue using mq_send(3) and mq_receive(3). When a process has finished using the queue, it closes it using mq_close(3), and when the queue is no longer required, it can be deleted using mq_unlink(3). Queue attributes can be retrieved and (in some cases) modified using mq_getattr(3) and mq_setattr(3). A process can request asynchronous notification of the arrival of a message on a previously empty queue using mq_notify(3).

A message queue descriptor is a reference to an open message queue description (see open(2)). After a fork(2), a child inherits copies of its parent's message queue descriptors, and these descriptors refer to the same open message queue descriptions as the corresponding message queue descriptors in the parent. Corresponding message queue descriptors in the two processes share the flags (mq_flags) that are associated with the open message queue description.

Each message has an associated priority, and messages are always delivered to the receiving process highest priority first. Message priorities range from 0 (low) to sysconf(_SC_MQ_PRIO_MAX) - 1 (high). On Linux, sysconf(_SC_MQ_PRIO_MAX) returns 32768, but POSIX.1 requires only that an implementation support at least priorities in the range 0 to 31; some implementations provide only this range.

The remainder of this section describes some specific details of the Linux implementation of POSIX message queues.

### Library interfaces and system calls
In most cases the mq_*() library interfaces listed above are implemented on top of underlying system calls of the same name. Deviations from this scheme are indicated in the following table:

Library interface

System call

mq_close(3)

close(2)

mq_getattr(3)

mq_getsetattr(2)

mq_notify(3)

mq_notify(2)

mq_open(3)

mq_open(2)

mq_receive(3)

mq_timedreceive(2)

mq_send(3)

mq_timedsend(2)

mq_setattr(3)

mq_getsetattr(2)

mq_timedreceive(3)

mq_timedreceive(2)

mq_timedsend(3)

mq_timedsend(2)

mq_unlink(3)

mq_unlink(2)

### Versions
POSIX message queues have been supported since Linux 2.6.6. glibc support has been provided since glibc 2.3.4.

### Kernel configuration
Support for POSIX message queues is configurable via the CONFIG_POSIX_MQUEUE kernel configuration option. This option is enabled by default.

### Persistence
POSIX message queues have kernel persistence: if not removed by mq_unlink(3), a message queue will exist until the system is shut down.

### Linking
Programs using the POSIX message queue API must be compiled with cc -lrt to link against the real-time library, librt.

### /proc interfaces
The following interfaces can be used to limit the amount of kernel memory consumed by POSIX message queues and to set the default attributes for new message queues:

/proc/sys/fs/mqueue/msg_default (since Linux 3.5)

This file defines the value used for a new queue's mq_maxmsg setting when the queue is created with a call to mq_open(3) where attr is specified as NULL. The default value for this file is 10. The minimum and maximum are as for /proc/sys/fs/mqueue/msg_max. A new queue's default mq_maxmsg value will be the smaller of msg_default and msg_max. Before Linux 2.6.28, the default mq_maxmsg was 10; from Linux 2.6.28 to Linux 3.4, the default was the value defined for the msg_max limit.

/proc/sys/fs/mqueue/msg_max

This file can be used to view and change the ceiling value for the maximum number of messages in a queue. This value acts as a ceiling on the attr->mq_maxmsg argument given to mq_open(3). The default value for msg_max is 10. The minimum value is 1 (10 before Linux 2.6.28). The upper limit is HARD_MSGMAX. The msg_max limit is ignored for privileged processes (CAP_SYS_RESOURCE), but the HARD_MSGMAX ceiling is nevertheless imposed.

The definition of HARD_MSGMAX has changed across kernel versions:

•

Up to Linux 2.6.32: 131072 / sizeof(void *)

•

Linux 2.6.33 to Linux 3.4: (32768 * sizeof(void *) / 4)

•

Since Linux 3.5: 65,536

/proc/sys/fs/mqueue/msgsize_default (since Linux 3.5)

This file defines the value used for a new queue's mq_msgsize setting when the queue is created with a call to mq_open(3) where attr is specified as NULL. The default value for this file is 8192 (bytes). The minimum and maximum are as for /proc/sys/fs/mqueue/msgsize_max. If msgsize_default exceeds msgsize_max, a new queue's default mq_msgsize value is capped to the msgsize_max limit. Before Linux 2.6.28, the default mq_msgsize was 8192; from Linux 2.6.28 to Linux 3.4, the default was the value defined for the msgsize_max limit.

/proc/sys/fs/mqueue/msgsize_max

This file can be used to view and change the ceiling on the maximum message size. This value acts as a ceiling on the attr->mq_msgsize argument given to mq_open(3). The default value for msgsize_max is 8192 bytes. The minimum value is 128 (8192 before Linux 2.6.28). The upper limit for msgsize_max has varied across kernel versions:

•

Before Linux 2.6.28, the upper limit is INT_MAX.

•

From Linux 2.6.28 to Linux 3.4, the limit is 1,048,576.

•

Since Linux 3.5, the limit is 16,777,216 (HARD_MSGSIZEMAX).

The msgsize_max limit is ignored for privileged process (CAP_SYS_RESOURCE), but, since Linux 3.5, the HARD_MSGSIZEMAX ceiling is enforced for privileged processes.

/proc/sys/fs/mqueue/queues_max

This file can be used to view and change the system-wide limit on the number of message queues that can be created. The default value for queues_max is 256. No ceiling is imposed on the queues_max limit; privileged processes (CAP_SYS_RESOURCE) can exceed the limit (but see BUGS).

### Resource limit
The RLIMIT_MSGQUEUE resource limit, which places a limit on the amount of space that can be consumed by all of the message queues belonging to a process's real user ID, is described in getrlimit(2).

### Mounting the message queue filesystem
On Linux, message queues are created in a virtual filesystem. (Other implementations may also provide such a feature, but the details are likely to differ.) This filesystem can be mounted (by the superuser) using the following commands:

```
# mkdir /dev/mqueue
# mount -t mqueue none /dev/mqueue
```

The sticky bit is automatically enabled on the mount directory.

After the filesystem has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., ls(1) and rm(1)).

The contents of each file in the directory consist of a single line containing information about the queue:

```
$ cat /dev/mqueue/mymq
QSIZE:129     NOTIFY:2    SIGNO:0    NOTIFY_PID:8260
```

These fields are as follows:

QSIZE

Number of bytes of data in all messages in the queue (but see BUGS).

NOTIFY_PID

If this is nonzero, then the process with this PID has used mq_notify(3) to register for asynchronous message notification, and the remaining fields describe how notification occurs.

NOTIFY

Notification method: 0 is SIGEV_SIGNAL; 1 is SIGEV_NONE; and 2 is SIGEV_THREAD.

SIGNO

Signal number to be used for SIGEV_SIGNAL.

### Linux implementation of message queue descriptors
On Linux, a message queue descriptor is actually a file descriptor. (POSIX does not require such an implementation.) This means that a message queue descriptor can be monitored using select(2), poll(2), or epoll(7). This is not portable.

The close-on-exec flag (see open(2)) is automatically set on the file descriptor returned by mq_open(2).

### IPC namespaces
For a discussion of the interaction of POSIX message queue objects and IPC namespaces, see ipc_namespaces(7).

## NOTES
System V message queues (msgget(2), msgsnd(2), msgrcv(2), etc.) are an older API for exchanging messages between processes. POSIX message queues provide a better designed interface than System V message queues; on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues.

Linux does not currently (Linux 2.6.26) support the use of access control lists (ACLs) for POSIX message queues.

## BUGS
Since Linux 3.5 to Linux 3.14, the kernel imposed a ceiling of 1024 (HARD_QUEUESMAX) on the value to which the queues_max limit could be raised, and the ceiling was enforced even for privileged processes. This ceiling value was removed in Linux 3.14, and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling.

As originally implemented (and documented), the QSIZE field displayed the total number of (user-supplied) bytes in all messages in the message queue. Some changes in Linux 3.5 inadvertently changed the behavior, so that this field also included a count of kernel overhead bytes used to store the messages in the queue. This behavioral regression was rectified in Linux 4.2 (and earlier stable kernel series), so that the count once more included just the bytes of user data in messages in the queue.

## EXAMPLES
An example of the use of various message queue functions is shown in mq_notify(3).

## SEE ALSO
getrlimit(2), mq_getsetattr(2), poll(2), select(2), mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_receive(3), mq_send(3), mq_unlink(3), epoll(7), namespaces(7)

branch: sisyphus


namespaces

title: namespaces(7)

summary: overview of Linux namespaces

text:
# namespaces(7)

## NAME
namespaces - overview of Linux namespaces

## DESCRIPTION
A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. One use of namespaces is to implement containers.

This page provides pointers to information on the various namespace types, describes the associated /proc files, and summarizes the APIs for working with namespaces.

### Namespace types
The following table shows the namespace types available on Linux. The second column of the table shows the flag value that is used to specify the namespace type in various APIs. The third column identifies the manual page that provides details on the namespace type. The last column is a summary of the resources that are isolated by the namespace type.

Namespace

Flag

Page

Isolates

Cgroup

CLONE_NEWCGROUP

cgroup_namespaces(7)

Cgroup root directory

IPC

CLONE_NEWIPC

ipc_namespaces(7)

System V IPC, POSIX message queues

Network

CLONE_NEWNET

network_namespaces(7)

Network devices, stacks, ports, etc.

Mount

CLONE_NEWNS

mount_namespaces(7)

Mount points

PID

CLONE_NEWPID

pid_namespaces(7)

Process IDs

Time

CLONE_NEWTIME

time_namespaces(7)

Boot and monotonic clocks

User

CLONE_NEWUSER

user_namespaces(7)

User and group IDs

UTS

CLONE_NEWUTS

uts_namespaces(7)

Hostname and NIS domain name

### The namespaces API
As well as various /proc files described below, the namespaces API includes the following system calls:

clone(2)

The clone(2) system call creates a new process. If the flags argument of the call specifies one or more of the CLONE_NEW* flags listed above, then new namespaces are created for each flag, and the child process is made a member of those namespaces. (This system call also implements a number of features unrelated to namespaces.)

setns(2)

The setns(2) system call allows the calling process to join an existing namespace. The namespace to join is specified via a file descriptor that refers to one of the /proc/pid/ns files described below.

unshare(2)

The unshare(2) system call moves the calling process to a new namespace. If the flags argument of the call specifies one or more of the CLONE_NEW* flags listed above, then new namespaces are created for each flag, and the calling process is made a member of those namespaces. (This system call also implements a number of features unrelated to namespaces.)

ioctl(2)

Various ioctl(2) operations can be used to discover information about namespaces. These operations are described in ioctl_ns(2).

Creation of new namespaces using clone(2) and unshare(2) in most cases requires the CAP_SYS_ADMIN capability, since, in the new namespace, the creator will have the power to change global resources that are visible to other processes that are subsequently created in, or join the namespace. User namespaces are the exception: since Linux 3.8, no privilege is required to create a user namespace.

### The /proc/pid/ns/ directory
Each process has a /proc/pid/ns/ subdirectory containing one entry for each namespace that supports being manipulated by setns(2):

```
$ ls -l /proc/$$/ns | awk '{print $1, $9, $10, $11}'
total 0
lrwxrwxrwx. cgroup -> cgroup:[4026531835]
lrwxrwxrwx. ipc -> ipc:[4026531839]
lrwxrwxrwx. mnt -> mnt:[4026531840]
lrwxrwxrwx. net -> net:[4026531969]
lrwxrwxrwx. pid -> pid:[4026531836]
lrwxrwxrwx. pid_for_children -> pid:[4026531834]
lrwxrwxrwx. time -> time:[4026531834]
lrwxrwxrwx. time_for_children -> time:[4026531834]
lrwxrwxrwx. user -> user:[4026531837]
lrwxrwxrwx. uts -> uts:[4026531838]
```

Bind mounting (see mount(2)) one of the files in this directory to somewhere else in the filesystem keeps the corresponding namespace of the process specified by pid alive even if all processes currently in the namespace terminate.

Opening one of the files in this directory (or a file that is bind mounted to one of these files) returns a file handle for the corresponding namespace of the process specified by pid. As long as this file descriptor remains open, the namespace will remain alive, even if all processes in the namespace terminate. The file descriptor can be passed to setns(2).

In Linux 3.7 and earlier, these files were visible as hard links. Since Linux 3.8, they appear as symbolic links. If two processes are in the same namespace, then the device IDs and inode numbers of their /proc/pid/ns/xxx symbolic links will be the same; an application can check this using the stat.st_dev and stat.st_ino fields returned by stat(2). The content of this symbolic link is a string containing the namespace type and inode number as in the following example:

```
$ readlink /proc/$$/ns/uts
uts:[4026531838]
```

The symbolic links in this subdirectory are as follows:

/proc/pid/ns/cgroup (since Linux 4.6)

This file is a handle for the cgroup namespace of the process.

/proc/pid/ns/ipc (since Linux 3.0)

This file is a handle for the IPC namespace of the process.

/proc/pid/ns/mnt (since Linux 3.8)

This file is a handle for the mount namespace of the process.

/proc/pid/ns/net (since Linux 3.0)

This file is a handle for the network namespace of the process.

/proc/pid/ns/pid (since Linux 3.8)

This file is a handle for the PID namespace of the process. This handle is permanent for the lifetime of the process (i.e., a process's PID namespace membership never changes).

/proc/pid/ns/pid_for_children (since Linux 4.12)

This file is a handle for the PID namespace of child processes created by this process. This can change as a consequence of calls to unshare(2) and setns(2) (see pid_namespaces(7)), so the file may differ from /proc/pid/ns/pid. The symbolic link gains a value only after the first child process is created in the namespace. (Beforehand, readlink(2) of the symbolic link will return an empty buffer.)

/proc/pid/ns/time (since Linux 5.6)

This file is a handle for the time namespace of the process.

/proc/pid/ns/time_for_children (since Linux 5.6)

This file is a handle for the time namespace of child processes created by this process. This can change as a consequence of calls to unshare(2) and setns(2) (see time_namespaces(7)), so the file may differ from /proc/pid/ns/time.

/proc/pid/ns/user (since Linux 3.8)

This file is a handle for the user namespace of the process.

/proc/pid/ns/uts (since Linux 3.0)

This file is a handle for the UTS namespace of the process.

Permission to dereference or read (readlink(2)) these symbolic links is governed by a ptrace access mode PTRACE_MODE_READ_FSCREDS check; see ptrace(2).

### The /proc/sys/user directory
The files in the /proc/sys/user directory (which is present since Linux 4.9) expose limits on the number of namespaces of various types that can be created. The files are as follows:

max_cgroup_namespaces

The value in this file defines a per-user limit on the number of cgroup namespaces that may be created in the user namespace.

max_ipc_namespaces

The value in this file defines a per-user limit on the number of ipc namespaces that may be created in the user namespace.

max_mnt_namespaces

The value in this file defines a per-user limit on the number of mount namespaces that may be created in the user namespace.

max_net_namespaces

The value in this file defines a per-user limit on the number of network namespaces that may be created in the user namespace.

max_pid_namespaces

The value in this file defines a per-user limit on the number of PID namespaces that may be created in the user namespace.

max_time_namespaces (since Linux 5.7)

The value in this file defines a per-user limit on the number of time namespaces that may be created in the user namespace.

max_user_namespaces

The value in this file defines a per-user limit on the number of user namespaces that may be created in the user namespace.

max_uts_namespaces

The value in this file defines a per-user limit on the number of uts namespaces that may be created in the user namespace.

Note the following details about these files:

•

The values in these files are modifiable by privileged processes.

•

The values exposed by these files are the limits for the user namespace in which the opening process resides.

•

The limits are per-user. Each user in the same user namespace can create namespaces up to the defined limit.

•

The limits apply to all users, including UID 0.

•

These limits apply in addition to any other per-namespace limits (such as those for PID and user namespaces) that may be enforced.

•

Upon encountering these limits, clone(2) and unshare(2) fail with the error ENOSPC.

•

For the initial user namespace, the default value in each of these files is half the limit on the number of threads that may be created (/proc/sys/kernel/threads-max). In all descendant user namespaces, the default value in each file is MAXINT.

•

When a namespace is created, the object is also accounted against ancestor namespaces. More precisely:

•

Each user namespace has a creator UID.

•

When a namespace is created, it is accounted against the creator UIDs in each of the ancestor user namespaces, and the kernel ensures that the corresponding namespace limit for the creator UID in the ancestor namespace is not exceeded.

•

The aforementioned point ensures that creating a new user namespace cannot be used as a means to escape the limits in force in the current user namespace.

### Namespace lifetime
Absent any other factors, a namespace is automatically torn down when the last process in the namespace terminates or leaves the namespace. However, there are a number of other factors that may pin a namespace into existence even though it has no member processes. These factors include the following:

•

An open file descriptor or a bind mount exists for the corresponding /proc/pid/ns/* file.

•

The namespace is hierarchical (i.e., a PID or user namespace), and has a child namespace.

•

It is a user namespace that owns one or more nonuser namespaces.

•

It is a PID namespace, and there is a process that refers to the namespace via a /proc/pid/ns/pid_for_children symbolic link.

•

It is a time namespace, and there is a process that refers to the namespace via a /proc/pid/ns/time_for_children symbolic link.

•

It is an IPC namespace, and a corresponding mount of an mqueue filesystem (see mq_overview(7)) refers to this namespace.

•

It is a PID namespace, and a corresponding mount of a proc(5) filesystem refers to this namespace.

## EXAMPLES
See clone(2) and user_namespaces(7).

## SEE ALSO
nsenter(1), readlink(1), unshare(1), clone(2), ioctl_ns(2), setns(2), unshare(2), proc(5), capabilities(7), cgroup_namespaces(7), cgroups(7), credentials(7), ipc_namespaces(7), network_namespaces(7), pid_namespaces(7), user_namespaces(7), uts_namespaces(7), lsns(8), switch_root(8)


netdevice

title: netdevice(7)

text:
# netdevice(7)

## NAME
netdevice - low-level access to Linux network devices

## SYNOPSIS

```
#include <sys/ioctl.h>
#include <net/if.h>
```

## DESCRIPTION
This man page describes the sockets interface which is used to configure network devices.

Linux supports some standard ioctls to configure network devices. They can be used on any socket's file descriptor regardless of the family or type. Most of them pass an ifreq structure:

```
struct ifreq {

    char ifr_name[IFNAMSIZ]; /* Interface name */

    union {

        struct sockaddr ifr_addr;

        struct sockaddr ifr_dstaddr;

        struct sockaddr ifr_broadaddr;

        struct sockaddr ifr_netmask;

        struct sockaddr ifr_hwaddr;

        short           ifr_flags;

        int             ifr_ifindex;

        int             ifr_metric;

        int             ifr_mtu;

        struct ifmap    ifr_map;

        char            ifr_slave[IFNAMSIZ];

        char            ifr_newname[IFNAMSIZ];

        char           *ifr_data;

    };
};
```

AF_INET6 is an exception. It passes an in6_ifreq structure:

```
struct in6_ifreq {

    struct in6_addr     ifr6_addr;

    u32                 ifr6_prefixlen;

    int                 ifr6_ifindex; /* Interface index */
};
```

Normally, the user specifies which device to affect by setting ifr_name to the name of the interface or ifr6_ifindex to the index of the interface. All other members of the structure may share memory.

### Ioctls
If an ioctl is marked as privileged, then using it requires an effective user ID of 0 or the CAP_NET_ADMIN capability. If this is not the case, EPERM will be returned.

SIOCGIFNAME

Given the ifr_ifindex, return the name of the interface in ifr_name. This is the only ioctl which returns its result in ifr_name.

SIOCGIFINDEX

Retrieve the interface index of the interface into ifr_ifindex.

SIOCGIFFLAGS, SIOCSIFFLAGS

Get or set the active flag word of the device. ifr_flags contains a bit mask of the following values: Device flags

IFF_UP

Interface is running.

IFF_BROADCAST

Valid broadcast address set.

IFF_DEBUG

Internal debugging flag.

IFF_LOOPBACK

Interface is a loopback interface.

IFF_POINTOPOINT

Interface is a point-to-point link.

IFF_RUNNING

Resources allocated.

IFF_NOARP

No arp protocol, L2 destination address not set.

IFF_PROMISC

Interface is in promiscuous mode.

IFF_NOTRAILERS

Avoid use of trailers.

IFF_ALLMULTI

Receive all multicast packets.

IFF_MASTER

Master of a load balancing bundle.

IFF_SLAVE

Slave of a load balancing bundle.

IFF_MULTICAST

Supports multicast

IFF_PORTSEL

Is able to select media type via ifmap.

IFF_AUTOMEDIA

Auto media selection active.

IFF_DYNAMIC

The addresses are lost when the interface goes down.

IFF_LOWER_UP

Driver signals L1 up (since Linux 2.6.17)

IFF_DORMANT

Driver signals dormant (since Linux 2.6.17)

IFF_ECHO

Echo sent packets (since Linux 2.6.25)

Setting the active flag word is a privileged operation, but any process may read it.

SIOCGIFPFLAGS, SIOCSIFPFLAGS

Get or set extended (private) flags for the device. ifr_flags contains a bit mask of the following values: Private flags

IFF_802_1Q_VLAN

Interface is 802.1Q VLAN device.

IFF_EBRIDGE

Interface is Ethernet bridging device.

IFF_SLAVE_INACTIVE

Interface is inactive bonding slave.

IFF_MASTER_8023AD

Interface is 802.3ad bonding master.

IFF_MASTER_ALB

Interface is balanced-alb bonding master.

IFF_BONDING

Interface is a bonding master or slave.

IFF_SLAVE_NEEDARP

Interface needs ARPs for validation.

IFF_ISATAP

Interface is RFC4214 ISATAP interface.

Setting the extended (private) interface flags is a privileged operation.

SIOCGIFADDR, SIOCSIFADDR, SIOCDIFADDR

Get, set, or delete the address of the device using ifr_addr, or ifr6_addr with ifr6_prefixlen. Setting or deleting the interface address is a privileged operation. For compatibility, SIOCGIFADDR returns only AF_INET addresses, SIOCSIFADDR accepts AF_INET and AF_INET6 addresses, and SIOCDIFADDR deletes only AF_INET6 addresses. A AF_INET address can be deleted by setting it to zero via SIOCSIFADDR.

SIOCGIFDSTADDR, SIOCSIFDSTADDR

Get or set the destination address of a point-to-point device using ifr_dstaddr. For compatibility, only AF_INET addresses are accepted or returned. Setting the destination address is a privileged operation.

SIOCGIFBRDADDR, SIOCSIFBRDADDR

Get or set the broadcast address for a device using ifr_brdaddr. For compatibility, only AF_INET addresses are accepted or returned. Setting the broadcast address is a privileged operation.

SIOCGIFNETMASK, SIOCSIFNETMASK

Get or set the network mask for a device using ifr_netmask. For compatibility, only AF_INET addresses are accepted or returned. Setting the network mask is a privileged operation.

SIOCGIFMETRIC, SIOCSIFMETRIC

Get or set the metric of the device using ifr_metric. This is currently not implemented; it sets ifr_metric to 0 if you attempt to read it and returns EOPNOTSUPP if you attempt to set it.

SIOCGIFMTU, SIOCSIFMTU

Get or set the MTU (Maximum Transfer Unit) of a device using ifr_mtu. Setting the MTU is a privileged operation. Setting the MTU to too small values may cause kernel crashes.

SIOCGIFHWADDR, SIOCSIFHWADDR

Get or set the hardware address of a device using ifr_hwaddr. The hardware address is specified in a struct sockaddr. sa_family contains the ARPHRD_* device type, sa_data the L2 hardware address starting from byte 0. Setting the hardware address is a privileged operation.

SIOCSIFHWBROADCAST

Set the hardware broadcast address of a device from ifr_hwaddr. This is a privileged operation.

SIOCGIFMAP, SIOCSIFMAP

Get or set the interface's hardware parameters using ifr_map. Setting the parameters is a privileged operation.

```
struct ifmap {

    unsigned long   mem_start;

    unsigned long   mem_end;

    unsigned short  base_addr;

    unsigned char   irq;

    unsigned char   dma;

    unsigned char   port;
};

```

The interpretation of the ifmap structure depends on the device driver and the architecture.

SIOCADDMULTI, SIOCDELMULTI

Add an address to or delete an address from the device's link layer multicast filters using ifr_hwaddr. These are privileged operations. See also packet(7) for an alternative.

SIOCGIFTXQLEN, SIOCSIFTXQLEN

Get or set the transmit queue length of a device using ifr_qlen. Setting the transmit queue length is a privileged operation.

SIOCSIFNAME

Changes the name of the interface specified in ifr_name to ifr_newname. This is a privileged operation. It is allowed only when the interface is not up.

SIOCGIFCONF

Return a list of interface (network layer) addresses. This currently means only addresses of the AF_INET (IPv4) family for compatibility. Unlike the others, this ioctl passes an ifconf structure:

```
struct ifconf {

    int               ifc_len; /* size of buffer */

    union {

        char         *ifc_buf; /* buffer address */

        struct ifreq *ifc_req; /* array of structures */

    };
};

```

If ifc_req is NULL, SIOCGIFCONF returns the necessary buffer size in bytes for receiving all available addresses in ifc_len. Otherwise, ifc_req contains a pointer to an array of ifreq structures to be filled with all currently active L3 interface addresses. ifc_len contains the size of the array in bytes. Within each ifreq structure, ifr_name will receive the interface name, and ifr_addr the address. The actual number of bytes transferred is returned in ifc_len.

If the size specified by ifc_len is insufficient to store all the addresses, the kernel will skip the exceeding ones and return success. There is no reliable way of detecting this condition once it has occurred. It is therefore recommended to either determine the necessary buffer size beforehand by calling SIOCGIFCONF with ifc_req set to NULL, or to retry the call with a bigger buffer whenever ifc_len upon return differs by less than sizeof(struct ifreq) from its original value.

If an error occurs accessing the ifconf or ifreq structures, EFAULT will be returned.

Most protocols support their own ioctls to configure protocol-specific interface options. See the protocol man pages for a description. For configuring IP addresses, see ip(7).

In addition, some devices support private ioctls. These are not described here.

## NOTES
SIOCGIFCONF and the other ioctls that accept or return only AF_INET socket addresses are IP-specific and perhaps should rather be documented in ip(7).

The names of interfaces with no addresses or that don't have the IFF_RUNNING flag set can be found via /proc/net/dev.

AF_INET6 IPv6 addresses can be read from /proc/net/if_inet6 or via rtnetlink(7). Adding a new IPv6 address and deleting an existing IPv6 address can be done via SIOCSIFADDR and SIOCDIFADDR or via rtnetlink(7). Retrieving or changing destination IPv6 addresses of a point-to-point interface is possible only via rtnetlink(7).

## BUGS
glibc 2.1 is missing the ifr_newname macro in <net/if.h>. Add the following to your program as a workaround:

```
#ifndef ifr_newname
#define ifr_newname     ifr_ifru.ifru_slave
#endif
```

## SEE ALSO
proc(5), capabilities(7), ip(7), rtnetlink(7)


netlink

title: netlink(7)

text:
# netlink(7)

## NAME
netlink - communication between kernel and user space (AF_NETLINK)

## SYNOPSIS

```
#include <asm/types.h>
#include <sys/socket.h>
#include <linux/netlink.h>
```

```
netlink_socket = socket(AF_NETLINK, socket_type, netlink_family);
```

## DESCRIPTION
Netlink is used to transfer information between the kernel and user-space processes. It consists of a standard sockets-based interface for user space processes and an internal kernel API for kernel modules. The internal kernel interface is not documented in this manual page. There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is provided only for backward compatibility.

Netlink is a datagram-oriented service. Both SOCK_RAW and SOCK_DGRAM are valid values for socket_type. However, the netlink protocol does not distinguish between datagram and raw sockets.

netlink_family selects the kernel module or netlink group to communicate with. The currently assigned netlink families are:

NETLINK_ROUTE

Receives routing and link updates and may be used to modify the routing tables (both IPv4 and IPv6), IP addresses, link parameters, neighbor setups, queueing disciplines, traffic classes, and packet classifiers (see rtnetlink(7)).

NETLINK_W1 (Linux 2.6.13 to Linux 2.16.17)

Messages from 1-wire subsystem.

NETLINK_USERSOCK

Reserved for user-mode socket protocols.

NETLINK_FIREWALL (up to and including Linux 3.4)

Transport IPv4 packets from netfilter to user space. Used by ip_queue kernel module. After a long period of being declared obsolete (in favor of the more advanced nfnetlink_queue feature), NETLINK_FIREWALL was removed in Linux 3.5.

NETLINK_SOCK_DIAG (since Linux 3.3)

Query information about sockets of various protocol families from the kernel (see sock_diag(7)).

NETLINK_INET_DIAG (since Linux 2.6.14)

An obsolete synonym for NETLINK_SOCK_DIAG.

NETLINK_NFLOG (up to and including Linux 3.16)

Netfilter/iptables ULOG.

NETLINK_XFRM

IPsec.

NETLINK_SELINUX (since Linux 2.6.4)

SELinux event notifications.

NETLINK_ISCSI (since Linux 2.6.15)

Open-iSCSI.

NETLINK_AUDIT (since Linux 2.6.6)

Auditing.

NETLINK_FIB_LOOKUP (since Linux 2.6.13)

Access to FIB lookup from user space.

NETLINK_CONNECTOR (since Linux 2.6.14)

Kernel connector. See Documentation/driver-api/connector.rst (or /Documentation/connector/connector.* in Linux 5.2 and earlier) in the Linux kernel source tree for further information.

NETLINK_NETFILTER (since Linux 2.6.14)

Netfilter subsystem.

NETLINK_SCSITRANSPORT (since Linux 2.6.19)

SCSI Transports.

NETLINK_RDMA (since Linux 3.0)

Infiniband RDMA.

NETLINK_IP6_FW (up to and including Linux 3.4)

Transport IPv6 packets from netfilter to user space. Used by ip6_queue kernel module.

NETLINK_DNRTMSG

DECnet routing messages.

NETLINK_KOBJECT_UEVENT (since Linux 2.6.10)

Kernel messages to user space.

NETLINK_GENERIC (since Linux 2.6.15)

Generic netlink family for simplified netlink usage.

NETLINK_CRYPTO (since Linux 3.2)

Netlink interface to request information about ciphers registered with the kernel crypto API as well as allow configuration of the kernel crypto API.

Netlink messages consist of a byte stream with one or multiple nlmsghdr headers and associated payload. The byte stream should be accessed only with the standard NLMSG_* macros. See netlink(3) for further information.

In multipart messages (multiple nlmsghdr headers with associated payload in one byte stream) the first and all following headers have the NLM_F_MULTI flag set, except for the last header which has the type NLMSG_DONE.

After each nlmsghdr the payload follows.

```
struct nlmsghdr {

    __u32 nlmsg_len;    /* Length of message including header */

    __u16 nlmsg_type;   /* Type of message content */

    __u16 nlmsg_flags;  /* Additional flags */

    __u32 nlmsg_seq;    /* Sequence number */

    __u32 nlmsg_pid;    /* Sender port ID */
};
```

nlmsg_type can be one of the standard message types: NLMSG_NOOP message is to be ignored, NLMSG_ERROR message signals an error and the payload contains an nlmsgerr structure, NLMSG_DONE message terminates a multipart message. Error messages get the original request appended, unless the user requests to cap the error message, and get extra error data if requested.

```
struct nlmsgerr {

    int error;        /* Negative errno or 0 for acknowledgements */

    struct nlmsghdr msg;  /* Message header that caused the error */

    /*

     * followed by the message contents

     * unless NETLINK_CAP_ACK was set

     * or the ACK indicates success (error == 0).

     * For example Generic Netlink message with attributes.

     * message length is aligned with NLMSG_ALIGN()

     */

    /*

     * followed by TLVs defined in enum nlmsgerr_attrs

     * if NETLINK_EXT_ACK was set

     */
};
```

A netlink family usually specifies more message types, see the appropriate manual pages for that, for example, rtnetlink(7) for NETLINK_ROUTE.

Standard flag bits in nlmsg_flags

NLM_F_REQUEST

Must be set on all request messages.

NLM_F_MULTI

The message is part of a multipart message terminated by NLMSG_DONE .

NLM_F_ACK

Request for an acknowledgement on success.

NLM_F_ECHO

Echo this request.

Additional flag bits for GET requests

NLM_F_ROOT

Return the complete table instead of a single entry.

NLM_F_MATCH

Return all entries matching criteria passed in message content. Not implemented yet.

NLM_F_ATOMIC

Return an atomic snapshot of the table.

NLM_F_DUMP

Convenience macro; equivalent to (NLM_F_ROOT|NLM_F_MATCH).

Note that NLM_F_ATOMIC requires the CAP_NET_ADMIN capability or an effective UID of 0.

Additional flag bits for NEW requests

NLM_F_REPLACE

Replace existing matching object.

NLM_F_EXCL

Don't replace if the object already exists.

NLM_F_CREATE

Create object if it doesn't already exist.

NLM_F_APPEND

Add to the end of the object list.

nlmsg_seq and nlmsg_pid are used to track messages. nlmsg_pid shows the origin of the message. Note that there isn't a 1:1 relationship between nlmsg_pid and the PID of the process if the message originated from a netlink socket. See the ADDRESS FORMATS section for further information.

Both nlmsg_seq and nlmsg_pid are opaque to netlink core.

Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or other error occurs. For reliable transfer the sender can request an acknowledgement from the receiver by setting the NLM_F_ACK flag. An acknowledgement is an NLMSG_ERROR packet with the error field set to 0. The application must generate acknowledgements for received messages itself. The kernel tries to send an NLMSG_ERROR message for every failed packet. A user process should follow this convention too.

However, reliable transmissions from kernel to user are impossible in any case. The kernel can't send a netlink message if the socket buffer is full: the message will be dropped and the kernel and the user-space process will no longer have the same view of kernel state. It is up to the application to detect when this happens (via the ENOBUFS error returned by recvmsg(2)) and resynchronize.

### Address formats
The sockaddr_nl structure describes a netlink client in user space or in the kernel. A sockaddr_nl can be either unicast (only sent to one peer) or sent to netlink multicast groups (nl_groups not equal 0).

```
struct sockaddr_nl {

    sa_family_t     nl_family;  /* AF_NETLINK */

    unsigned short  nl_pad;     /* Zero */

    pid_t           nl_pid;     /* Port ID */

    __u32           nl_groups;  /* Multicast groups mask */
};
```

nl_pid is the unicast address of netlink socket. It's always 0 if the destination is in the kernel. For a user-space process, nl_pid is usually the PID of the process owning the destination socket. However, nl_pid identifies a netlink socket, not a process. If a process owns several netlink sockets, then nl_pid can be equal to the process ID only for at most one socket. There are two ways to assign nl_pid to a netlink socket. If the application sets nl_pid before calling bind(2), then it is up to the application to make sure that nl_pid is unique. If the application sets it to 0, the kernel takes care of assigning it. The kernel assigns the process ID to the first netlink socket the process opens and assigns a unique nl_pid to every netlink socket that the process subsequently creates.

nl_groups is a bit mask with every bit representing a netlink group number. Each netlink family has a set of 32 multicast groups. When bind(2) is called on the socket, the nl_groups field in the sockaddr_nl should be set to a bit mask of the groups which it wishes to listen to. The default value for this field is zero which means that no multicasts will be received. A socket may multicast messages to any of the multicast groups by setting nl_groups to a bit mask of the groups it wishes to send to when it calls sendmsg(2) or does a connect(2). Only processes with an effective UID of 0 or the CAP_NET_ADMIN capability may send or listen to a netlink multicast group. Since Linux 2.6.13, messages can't be broadcast to multiple groups. Any replies to a message received for a multicast group should be sent back to the sending PID and the multicast group. Some Linux kernel subsystems may additionally allow other users to send and/or receive messages. As at Linux 3.0, the NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_ROUTE, and NETLINK_SELINUX groups allow other users to receive messages. No groups allow other users to send messages.

### Socket options
To set or get a netlink socket option, call getsockopt(2) to read or setsockopt(2) to write the option with the option level argument set to SOL_NETLINK. Unless otherwise noted, optval is a pointer to an int.

NETLINK_PKTINFO (since Linux 2.6.14)

Enable nl_pktinfo control messages for received packets to get the extended destination group number.

NETLINK_ADD_MEMBERSHIP, NETLINK_DROP_MEMBERSHIP (since Linux 2.6.14)

Join/leave a group specified by optval.

NETLINK_LIST_MEMBERSHIPS (since Linux 4.2)

Retrieve all groups a socket is a member of. optval is a pointer to __u32 and optlen is the size of the array. The array is filled with the full membership set of the socket, and the required array size is returned in optlen.

NETLINK_BROADCAST_ERROR (since Linux 2.6.30)

When not set, netlink_broadcast() only reports ESRCH errors and silently ignore ENOBUFS errors.

NETLINK_NO_ENOBUFS (since Linux 2.6.30)

This flag can be used by unicast and broadcast listeners to avoid receiving ENOBUFS errors.

NETLINK_LISTEN_ALL_NSID (since Linux 4.2)

When set, this socket will receive netlink notifications from all network namespaces that have an nsid assigned into the network namespace where the socket has been opened. The nsid is sent to user space via an ancillary data.

NETLINK_CAP_ACK (since Linux 4.3)

The kernel may fail to allocate the necessary room for the acknowledgement message back to user space. This option trims off the payload of the original netlink message. The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgement.

## VERSIONS
The socket interface to netlink first appeared Linux 2.2.

Linux 2.0 supported a more primitive device-based netlink interface (which is still available as a compatibility option). This obsolete interface is not described here.

## NOTES
It is often better to use netlink via libnetlink or libnl than via the low-level kernel interface.

## BUGS
This manual page is not complete.

## EXAMPLES
The following example creates a NETLINK_ROUTE netlink socket which will listen to the RTMGRP_LINK (network interface create/delete/up/down events) and RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups.

```
struct sockaddr_nl sa;
memset(&sa, 0, sizeof(sa));
sa.nl_family = AF_NETLINK;
sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
bind(fd, (struct sockaddr *) &sa, sizeof(sa));
```

The next example demonstrates how to send a netlink message to the kernel (pid 0). Note that the application must take care of message sequence numbers in order to reliably track acknowledgements.

```
struct nlmsghdr *nh;    /* The nlmsghdr with payload to send */
struct sockaddr_nl sa;
struct iovec iov = { nh, nh->nlmsg_len };
struct msghdr msg;
msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
memset(&sa, 0, sizeof(sa));
sa.nl_family = AF_NETLINK;
nh->nlmsg_pid = 0;
nh->nlmsg_seq = ++sequence_number;
/* Request an ack from kernel by setting NLM_F_ACK */
nh->nlmsg_flags |= NLM_F_ACK;
sendmsg(fd, &msg, 0);
```

And the last example is about reading netlink message.

```
int len;
/* 8192 to avoid message truncation on platforms with

   page size > 4096 */
struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)];
struct iovec iov = { buf, sizeof(buf) };
struct sockaddr_nl sa;
struct msghdr msg;
struct nlmsghdr *nh;
msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
len = recvmsg(fd, &msg, 0);
for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);

     nh = NLMSG_NEXT (nh, len)) {

    /* The end of multipart message */

    if (nh->nlmsg_type == NLMSG_DONE)

        return;

    if (nh->nlmsg_type == NLMSG_ERROR)

        /* Do some error handling */

    ...

    /* Continue with parsing payload */

    ...
}
```

## SEE ALSO
cmsg(3), netlink(3), capabilities(7), rtnetlink(7), sock_diag(7)

information about libnetlink

information about libnl

RFC 3549 "Linux Netlink as an IP Services Protocol"


title: network_namespaces(7)

summary: overview of Linux network namespaces

text:
# network_namespaces(7)

## NAME
network_namespaces - overview of Linux network namespaces

## DESCRIPTION
Network namespaces provide isolation of the system resources associated with networking: network devices, IPv4 and IPv6 protocol stacks, IP routing tables, firewall rules, the /proc/net directory (which is a symbolic link to /proc/pid/net), the /sys/class/net directory, various files under /proc/sys/net, port numbers (sockets), and so on. In addition, network namespaces isolate the UNIX domain abstract socket namespace (see unix(7)).

A physical network device can live in exactly one network namespace. When a network namespace is freed (i.e., when the last process in the namespace terminates), its physical network devices are moved back to the initial network namespace (not to the namespace of the parent of the process).

A virtual network (veth(4)) device pair provides a pipe-like abstraction that can be used to create tunnels between network namespaces, and can be used to create a bridge to a physical network device in another namespace. When a namespace is freed, the veth(4) devices that it contains are destroyed.

Use of network namespaces requires a kernel that is configured with the CONFIG_NET_NS option.

## SEE ALSO
nsenter(1), unshare(1), clone(2), veth(4), proc(5), sysfs(5), namespaces(7), user_namespaces(7), brctl(8), ip(8), ip-address(8), ip-link(8), ip-netns(8), iptables(8), ovs-vsctl(8)


nptl

title: nptl(7)

summary: Native POSIX Threads Library

text:
# nptl(7)

## NAME
nptl - Native POSIX Threads Library

## DESCRIPTION
NPTL (Native POSIX Threads Library) is the GNU C library POSIX threads implementation that is used on modern Linux systems.

### NPTL and signals
NPTL makes internal use of the first two real-time signals (signal numbers 32 and 33). One of these signals is used to support thread cancelation and POSIX timers (see timer_create(2)); the other is used as part of a mechanism that ensures all threads in a process always have the same UIDs and GIDs, as required by POSIX. These signals cannot be used in applications.

To prevent accidental use of these signals in applications, which might interfere with the operation of the NPTL implementation, various glibc library functions and system call wrapper functions attempt to hide these signals from applications, as follows:

•

SIGRTMIN is defined with the value 34 (rather than 32).

•

The sigwaitinfo(2), sigtimedwait(2), and sigwait(3) interfaces silently ignore requests to wait for these two signals if they are specified in the signal set argument of these calls.

•

The sigprocmask(2) and pthread_sigmask(3) interfaces silently ignore attempts to block these two signals.

•

The sigaction(2), pthread_kill(3), and pthread_sigqueue(3) interfaces fail with the error EINVAL (indicating an invalid signal number) if these signals are specified.

•

sigfillset(3) does not include these two signals when it creates a full signal set.

### NPTL and process credential changes
At the Linux kernel level, credentials (user and group IDs) are a per-thread attribute. However, POSIX requires that all of the POSIX threads in a process have the same credentials. To accommodate this requirement, the NPTL implementation wraps all of the system calls that change process credentials with functions that, in addition to invoking the underlying system call, arrange for all other threads in the process to also change their credentials.

The implementation of each of these system calls involves the use of a real-time signal that is sent (using tgkill(2)) to each of the other threads that must change its credentials. Before sending these signals, the thread that is changing credentials saves the new credential(s) and records the system call being employed in a global buffer. A signal handler in the receiving thread(s) fetches this information and then uses the same system call to change its credentials.

Wrapper functions employing this technique are provided for setgid(2), setuid(2), setegid(2), seteuid(2), setregid(2), setreuid(2), setresgid(2), setresuid(2), and setgroups(2).

## STANDARDS
For details of the conformance of NPTL to the POSIX standard, see pthreads(7).

## NOTES
POSIX says that any thread in any process with access to the memory containing a process-shared (PTHREAD_PROCESS_SHARED) mutex can operate on that mutex. However, on 64-bit x86 systems, the mutex definition for x86-64 is incompatible with the mutex definition for i386, meaning that 32-bit and 64-bit binaries can't share mutexes on x86-64 systems.

## SEE ALSO
credentials(7), pthreads(7), signal(7), standards(7)


numa

title: numa(7)

text:
# numa(7)

## NAME
numa - overview of Non-Uniform Memory Architecture

## DESCRIPTION
Non-Uniform Memory Access (NUMA) refers to multiprocessor systems whose memory is divided into multiple memory nodes. The access time of a memory node depends on the relative locations of the accessing CPU and the accessed node. (This contrasts with a symmetric multiprocessor system, where the access time for all of the memory is the same for all CPUs.) Normally, each CPU on a NUMA system has a local memory node whose contents can be accessed faster than the memory in the node local to another CPU or the memory on a bus shared by all CPUs.

### NUMA system calls
The Linux kernel implements the following NUMA-related system calls: get_mempolicy(2), mbind(2), migrate_pages(2), move_pages(2), and set_mempolicy(2). However, applications should normally use the interface provided by libnuma; see "Library Support" below.

### /proc/pid/numa_maps (since Linux 2.6.14)
This file displays information about a process's NUMA memory policy and allocation.

Each line contains information about a memory range used by the process, displaying—among other information—the effective memory policy for that memory range and on which nodes the pages have been allocated.

numa_maps is a read-only file. When /proc/pid/numa_maps is read, the kernel will scan the virtual address space of the process and report how memory is used. One line is displayed for each unique memory range of the process.

The first field of each line shows the starting address of the memory range. This field allows a correlation with the contents of the /proc/pid/maps file, which contains the end address of the range and other information, such as the access permissions and sharing.

The second field shows the memory policy currently in effect for the memory range. Note that the effective policy is not necessarily the policy installed by the process for that memory range. Specifically, if the process installed a "default" policy for that range, the effective policy for that range will be the process policy, which may or may not be "default".

The rest of the line contains information about the pages allocated in the memory range, as follows:

N<node>=<nr_pages>

The number of pages allocated on <node>. <nr_pages> includes only pages currently mapped by the process. Page migration and memory reclaim may have temporarily unmapped pages associated with this memory range. These pages may show up again only after the process has attempted to reference them. If the memory range represents a shared memory area or file mapping, other processes may currently have additional pages mapped in a corresponding memory range.

file=<filename>

The file backing the memory range. If the file is mapped as private, write accesses may have generated COW (Copy-On-Write) pages in this memory range. These pages are displayed as anonymous pages.

heap

Memory range is used for the heap.

stack

Memory range is used for the stack.

huge

Huge memory range. The page counts shown are huge pages and not regular sized pages.

anon=<pages>

The number of anonymous page in the range.

dirty=<pages>

Number of dirty pages.

mapped=<pages>

Total number of mapped pages, if different from dirty and anon pages.

mapmax=<count>

Maximum mapcount (number of processes mapping a single page) encountered during the scan. This may be used as an indicator of the degree of sharing occurring in a given memory range.

swapcache=<count>

Number of pages that have an associated entry on a swap device.

active=<pages>

The number of pages on the active list. This field is shown only if different from the number of pages in this range. This means that some inactive pages exist in the memory range that may be removed from memory by the swapper soon.

writeback=<pages>

Number of pages that are currently being written out to disk.

## STANDARDS
None.

## NOTES
The Linux NUMA system calls and /proc interface are available only if the kernel was configured and built with the CONFIG_NUMA option.

### Library support
Link with -lnuma to get the system call definitions. libnuma and the required <numaif.h> header are available in the numactl package.

However, applications should not use these system calls directly. Instead, the higher level interface provided by the numa(3) functions in the numactl package is recommended. The numactl package is available at ftp://oss.sgi.com/www/projects/libnuma/download/. The package is also included in some Linux distributions. Some distributions include the development library and header in the separate numactl-devel package.

## SEE ALSO
get_mempolicy(2), mbind(2), move_pages(2), set_mempolicy(2), numa(3), cpuset(7), numactl(8)


operator

title: operator(7)

text:
# operator(7)

## NAME
operator - C operator precedence and order of evaluation

## DESCRIPTION
This manual page lists C operators and their precedence in evaluation.

Operator

Associativity

Notes

[] () . -> ++ --

left to right

[1]

++ -- & * + - ~ ! sizeof

right to left

[2]

(type)

right to left

* / %

left to right

+ -

left to right

<< >>

left to right

< > <= >=

left to right

== !=

left to right

&

left to right

^

left to right

|

left to right

&&

left to right

||

left to right

?:

right to left

= *= /= %= += -= <<= >>= &= ^= |=

right to left

,

left to right

The following notes provide further information to the above table:

[1]

The ++ and -- operators at this precedence level are the postfix flavors of the operators.

[2]

The ++ and -- operators at this precedence level are the prefix flavors of the operators.