Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Linux namespaces with unshare

After this lesson: I can use unshare to hide processes, the network and files from a program.

60 min lesson9 commandsSandboxing lab: run untrusted code inside namespaces, cgroups, seccomp and gVisor on one private Ubuntu VM

A program that cannot see the rest

A Linux namespace gives a process its own private view of one thing the kernel shares, such as the processes or the network. Containers are built from them.

That matters because code that cannot see your network or your files cannot steal from them. Today you make each kind by hand with the unshare command and watch what disappears.

By the end of this lesson

Note

I can use unshare to hide processes, the network and files from a program.

Key words

WordWhat it meansExample
Namespacea private copy of one kernel view for some processes
unsharea command that runs a program in new namespacesunshare --net
PID 1the first process in a PID namespace
Mountattaching a file system at a folder
tmpfsan empty file system kept in memory
ID maphow user numbers inside match numbers outside

The cells students fill in are left blank in this preview.

One namespace for each kind of view

Linux has eight kinds of namespace. Five matter most for a sandbox. pid gives a new list of processes. net gives a new network with only a loopback device, switched off. mnt gives a separate set of mounts, so files can be hidden or swapped. uts gives a separate machine name. user maps user numbers, so root inside can be nobody outside.

Each unshare option makes one kind. Every Run here uses sudo, as making most namespaces needs root.

Go to the lab folder

Command
cd ~/lab

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

List processes in a new PID namespace

Command
sudo unshare --pid --fork --mount-proc ps -e -o pid,comm

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Rename the machine inside only

Command
sudo unshare --uts sh -c 'hostname sandbox && hostname'

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Check the name outside

Command
hostname

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

The network and the files can vanish

A new network namespace has no route anywhere. Asking for a route gives Network is unreachable, which is not the Connection refused of lesson 1: there is no network at all.

A mount namespace starts as a copy of the mounts outside, but changes stay inside. Mounting an empty tmpfs over the secrets folder hides the key from everything in that namespace. Outside, the key is still there.

Ask for a route with no network

Command
sudo unshare --net ip route get 1.1.1.1

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Hide the secrets folder

Command
sudo unshare --mount sh -c 'mount -t tmpfs none /home/student/lab/secrets && ls -A /home/student/lab/secrets'

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Check the key outside

Command
cat secrets/api_key.txt

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think a namespace is a security boundary on its own. It hides things, but every namespace still shares one kernel. A kernel bug reached from inside reaches the whole machine, so namespaces are one fence among several.

A user namespace changes who root is

A user namespace maps user numbers. The file /proc/self/uid_map has three numbers a line: the first number inside, the first number outside and how many follow.

Outside, the map covers everyone unchanged. In the Run below, root inside is user 100000 outside, a user who owns nothing. Root inside can still make mounts and namespaces, but the files outside see an ordinary stranger.

Read the ID map outside

Command
cat /proc/self/uid_map

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Read the ID map inside a user namespace

Command
sudo unshare --user --map-users=0:100000:65536 --map-groups=0:100000:65536 cat /proc/self/uid_map

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: what each namespace hid

NamespaceThe Run printedWhat it hides from the agent
pidPID 1 ps, aloneEvery other process
utssandbox, while outside kept its nameThe machine's real name
netNetwork is unreachableEvery network, so call fails
mntan empty secrets folderThe key, with a tmpfs on top
user0 100000 65536Root's power over files outside

The cells students fill in are left blank in this preview.

Try it: choose namespaces for the agent

Code: python
# Which namespace hides which thing from a sandboxed program?
hides = {
    "pid": "the other processes",
    "net": "the network",
    "mnt": "the files, by a different set of mounts",
    "uts": "the machine's name",
    "user": "who is root",
}

wanted = ["net", "mnt"]
for kind in wanted:
    print(kind, "hides", hides[kind])
# Which one would stop agent.py call? Add "pid" and run it again.

About this lab and its source: Sandboxing lab: run untrusted code inside namespaces, cgroups, seccomp and gVisor on one private Ubuntu VM

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.