github.com/hanks177/podman/v4@v4.1.3-0.20220613032544-16d90015bc83/docs/source/markdown/podman-unshare.1.md (about)

     1  % podman-unshare(1)
     2  
     3  ## NAME
     4  podman\-unshare - Run a command inside of a modified user namespace
     5  
     6  ## SYNOPSIS
     7  **podman unshare** [*options*] [*command*]
     8  
     9  ## DESCRIPTION
    10  Launches a process (by default, *$SHELL*) in a new user namespace. The user
    11  namespace is configured so that the invoking user's UID and primary GID appear
    12  to be UID 0 and GID 0, respectively.  Any ranges which match that user and
    13  group in `/etc/subuid` and `/etc/subgid` are also mapped in as themselves with the
    14  help of the *newuidmap(1)* and *newgidmap(1)* helpers.
    15  
    16  **podman unshare** is useful for troubleshooting unprivileged operations and for
    17  manually clearing storage and other data related to images and containers.
    18  
    19  It is also useful if you want to use the **podman mount** command.  If an unprivileged user wants to mount and work with a container, then they need to execute
    20  **podman unshare**.  Executing **podman mount** fails for unprivileged users unless the user is running inside a **podman unshare** session.
    21  
    22  The unshare session defines two environment variables:
    23  
    24  - **CONTAINERS_GRAPHROOT**: the path to the persistent container's data.
    25  - **CONTAINERS_RUNROOT**: the path to the volatile container's data.
    26  
    27  *IMPORTANT: This command is not available with the remote Podman client.*
    28  
    29  ## OPTIONS
    30  
    31  #### **--help**, **-h**
    32  
    33  Print usage statement
    34  
    35  #### **--rootless-netns**
    36  
    37  Join the rootless network namespace used for CNI and netavark networking. It can be used to
    38  connect to a rootless container via IP address (bridge networking). This is otherwise
    39  not possible from the host network namespace.
    40  
    41  ## Exit Codes
    42  
    43  The exit code from `podman unshare` gives information about why the container
    44  failed to run or why it exited.  When `podman unshare` commands exit with a non-zero code,
    45  the exit codes follow the `chroot` standard, see below:
    46  
    47    **125** The error is with podman **_itself_**
    48  
    49      $ podman unshare --foo; echo $?
    50      Error: unknown flag: --foo
    51      125
    52  
    53    **126** Executing a _contained command_ and the _command_ cannot be invoked
    54  
    55      $ podman unshare /etc; echo $?
    56      Error: fork/exec /etc: permission denied
    57      126
    58  
    59    **127** Executing a _contained command_ and the _command_ cannot be found
    60  
    61      $ podman unshare foo; echo $?
    62      Error: fork/exec /usr/bin/bogus: no such file or directory
    63      127
    64  
    65    **Exit code** _contained command_ exit code
    66  
    67      $ podman unshare /bin/sh -c 'exit 3'; echo $?
    68      3
    69  
    70  ## EXAMPLE
    71  
    72  ```
    73  $ podman unshare id
    74  uid=0(root) gid=0(root) groups=0(root),65534(nobody)
    75  
    76  $ podman unshare cat /proc/self/uid_map /proc/self/gid_map
    77           0       1000          1
    78           1      10000      65536
    79           0       1000          1
    80           1      10000      65536
    81  
    82  $ podman unshare --rootless-netns ip addr
    83  1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    84      link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    85      inet 127.0.0.1/8 scope host lo
    86         valid_lft forever preferred_lft forever
    87      inet6 ::1/128 scope host
    88         valid_lft forever preferred_lft forever
    89  2: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
    90      link/ether 36:0e:4a:c7:45:7e brd ff:ff:ff:ff:ff:ff
    91      inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
    92         valid_lft forever preferred_lft forever
    93      inet6 fe80::340e:4aff:fec7:457e/64 scope link
    94         valid_lft forever preferred_lft forever
    95  3: cni-podman2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    96      link/ether 5e:3a:71:d2:b4:3a brd ff:ff:ff:ff:ff:ff
    97      inet 10.89.1.1/24 brd 10.89.1.255 scope global cni-podman2
    98         valid_lft forever preferred_lft forever
    99      inet6 fe80::5c3a:71ff:fed2:b43a/64 scope link
   100         valid_lft forever preferred_lft forever
   101  4: vethd4ba3a2f@if3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master cni-podman2 state UP group default
   102      link/ether 8a:c9:56:32:17:0c brd ff:ff:ff:ff:ff:ff link-netnsid 0
   103      inet6 fe80::88c9:56ff:fe32:170c/64 scope link
   104         valid_lft forever preferred_lft forever
   105  ```
   106  
   107  
   108  ## SEE ALSO
   109  **[podman(1)](podman.1.md)**, **[podman-mount(1)](podman-mount.1.md)**, **namespaces(7)**, **newuidmap(1)**, **newgidmap(1)**, **user\_namespaces(7)**