1podman-unshare(1) General Commands Manual podman-unshare(1)
2
6 podman-unshare - Run a command inside of a modified user namespace
7
10 podman unshare [options] [command]
11
14 Launches a process (by default, $SHELL) in a new user namespace. The
15 user namespace is configured so that the invoking user's UID and pri‐
16 mary GID appear to be UID 0 and GID 0, respectively. Any ranges which
17 match that user and group in /etc/subuid and /etc/subgid are also
18 mapped in as themselves with the help of the newuidmap(1) and
19 newgidmap(1) helpers.
20 podman unshare is useful for troubleshooting unprivileged operations
23 and for manually clearing storage and other data related to images and
24 containers.
25 It is also useful if you want to use the podman mount command. If an
28 unprivileged user wants to mount and work with a container, then they
29 need to execute podman unshare. Executing podman mount fails for un‐
30 privileged users unless the user is running inside a podman unshare
31 session.
32 The unshare session defines two environment variables:
35 • CONTAINERS_GRAPHROOT: the path to the persistent container's
38 data.
39 • CONTAINERS_RUNROOT: the path to the volatile container's data.
41 IMPORTANT: This command is not available with the remote Podman client.
45
48 --help, -h
49 Print usage statement
50 --rootless-netns
53 Join the rootless network namespace used for CNI and netavark network‐
54 ing. It can be used to connect to a rootless container via IP address
55 (bridge networking). This is otherwise not possible from the host net‐
56 work namespace.
57
60 The exit code from podman unshare gives information about why the con‐
61 tainer failed to run or why it exited. When podman unshare commands
62 exit with a non-zero code, the exit codes follow the chroot standard,
63 see below:
64 125 The error is with podman itself
67 $ podman unshare --foo; echo $?
70 Error: unknown flag: --foo
71 125
72 126 Executing a contained command and the command cannot be invoked
76 $ podman unshare /etc; echo $?
79 Error: fork/exec /etc: permission denied
80 126
81 127 Executing a contained command and the command cannot be found
85 $ podman unshare foo; echo $?
88 Error: fork/exec /usr/bin/bogus: no such file or directory
89 127
90 Exit code contained command exit code
94 $ podman unshare /bin/sh -c 'exit 3'; echo $?
97 3
98
102 $ podman unshare id
103 uid=0(root) gid=0(root) groups=0(root),65534(nobody)
104 $ podman unshare cat /proc/self/uid_map /proc/self/gid_map
106 0 1000 1
107 1 10000 65536
108 0 1000 1
109 1 10000 65536
110 $ podman unshare --rootless-netns ip addr
112 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
113 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
114 inet 127.0.0.1/8 scope host lo
115 valid_lft forever preferred_lft forever
116 inet6 ::1/128 scope host
117 valid_lft forever preferred_lft forever
118 2: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
119 link/ether 36:0e:4a:c7:45:7e brd ff:ff:ff:ff:ff:ff
120 inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
121 valid_lft forever preferred_lft forever
122 inet6 fe80::340e:4aff:fec7:457e/64 scope link
123 valid_lft forever preferred_lft forever
124 3: cni-podman2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
125 link/ether 5e:3a:71:d2:b4:3a brd ff:ff:ff:ff:ff:ff
126 inet 10.89.1.1/24 brd 10.89.1.255 scope global cni-podman2
127 valid_lft forever preferred_lft forever
128 inet6 fe80::5c3a:71ff:fed2:b43a/64 scope link
129 valid_lft forever preferred_lft forever
130 4: vethd4ba3a2f@if3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master cni-podman2 state UP group default
131 link/ether 8a:c9:56:32:17:0c brd ff:ff:ff:ff:ff:ff link-netnsid 0
132 inet6 fe80::88c9:56ff:fe32:170c/64 scope link
133 valid_lft forever preferred_lft forever
134
138 podman(1), podman-mount(1), namespaces(7), newuidmap(1), newgidmap(1),
139 user_namespaces(7)
140 podman-unshare(1)