USERBINDMOUNT(1)

✨ USERBINDMOUNT ✨

okay bestie, sit down, hydrate, and let me tell you about a little command from the General Commands Manual section (that's section 1, iykyk) called userbindmount 💅

---

💖 NAME 💖

userbindmount — a bind-mount utility for user-namespaces 🌸

---

🦋 SYNOPSIS 🦋

userbindmount [options] [source target [source target [...]]] [ -- [cmd
[args]]]

---

🎀 DESCRIPTION 🎀

So. userbindmount is a utility command built on top of libuserbindmount ✨

It does two main character things: it can run one or more bind-mount operations, and it can create a user-namespace where bind-mount is allowed 👑

And the best part? This command does not need root access or any specific capabilities to run — provided user-namespaces are supported (peep NOTES, bestie, don't skip it 🫶).

The command line arguments are a list of source-target pairs, one pair for each bind-mount operation. A new namespace gets created if you ask for it with the specific option (-n or --newns) or if there's a -- hanging out in the command line. If source is a double quoted string, then the value of that string becomes the content of the file mounted on target 🌈. The trailing -- followed by a command and its arguments defines the command to run in the new namespace. (If you omit the command, $SHELL gets launched 💜)

Also: if the corresponding source is the tag -, the contents of the file to be mounted on target are read from standard input 📥

---

✨ OPTIONS ✨

userbindmount accepts the following options, and there are exactly three, so no excuses, learn them:

• -n, --newns — create a new user-namespace 🧚
• -s, --sysadm — add the CAP_SYS_ADMIN ambient capability to the current or newly created userspace 🔥
• -v, --verbose — verbose mode: print debugging information on the actions taken by the program. it's giving commentary track 💀

---

📝 NOTES 📝

User namespaces require a kernel that is configured with the CONFIG_USER_NS option. And heads up: in some distributions (e.g. Debian) user namespaces must be enabled by writing 1 to /proc/sys/kernel/unprivileged_userns_clone. no cap, that's just how it is 🙈

---

🌟 EXAMPLES 🌟

okay this is the fun part, let's go 👑

Example one: mounts the file /tmp/resolv.conf instead of /etc/resolv.conf. The purpose of this example is to redefine the name servers for the name resolution.

$ cat /etc/resolv.conf
nameserver 127.0.0.1
$ echo "nameserver 9.9.9.9" > /tmp/resolv.conf
$ userbindmount -v /tmp/resolv.conf /etc/resolv.conf -- bash
creating a user_namespace
mounting /tmp/resolv.conf on /etc/resolv.conf
starting bash
$ cat /etc/resolv.conf
nameserver 9.9.9.9
$ exit
$

Example two: creates a namespace where bind-mount is allowed, and then mounts /tmp/resolv.conf on /etc/resolv.conf. (It uses busybox instead of mount(8) as the latter does not support the capabilities, yet).

$ userbindmount -s -- bash
$ cat /etc/resolv.conf
nameserver 127.0.0.1
$ echo "nameserver 9.9.9.9" > /tmp/resolv.conf
$ busybox mount --bind /tmp/resolv.conf /etc/resolv.conf
$ cat /etc/resolv.conf
nameserver 9.9.9.9
$ exit
$

Alternative equivalent commands for "userbindmount -s -- bash" are "userbindmount -sn" or "userbindmount -s --". yes, three ways to say the same thing, pick your fighter ⭐

---

Several bind-mounts can be done in a user-namespace started with the -s option. No more namespaces are needed in this case 💅 The contents of the file to mount can be taken from stdin if source is "-".

$ userbindmount -sn
$ echo "nameserver 9.9.9.9" | userbindmount - /etc/resolv.conf
$ cat /etc/resolv.conf
nameserver 9.9.9.9
$ exit

---

It is possible to set the contents of a mounted file directly in the command line, which is honestly so convenient:

$ userbindmount $'"nameserver 9.9.9.9\n"' /etc/resolv.conf -- bash
$ cat /etc/resolv.conf
nameserver 9.9.9.9
$ exit

---

⚠️ Please note that the following command: $ echo "nameserver 9.9.9.9" | userbindmount - /etc/resolv.conf -- bash works but the bash running in the new namespace terminates immediately as it reads the end-of-file on its standard input. so like, it works, it just leaves the party instantly 😭

---

🔍 SEE ALSO 🔍

• libuserbindmount(3)
• mount(8)
• user_namespaces(7)
• capabilities(7)

go read them, bestie, they're the supporting cast 🎀

---

💀 BUGS 💀

Bug reports should be addressed to <info@virtualsquare.org> — tell them everything, they want to know 🫶

---

👑 AUTHORS 👑

Renzo Davoli <renzo@cs.unibo.it> — thank you for the lore 💖

---

VirtualSquare Labs • August 22, 2017 — that's the whole USERBINDMOUNT(1) situation, mwah, slay, periodt 🌈✨💅