github.com/containers/podman/v5@v5.1.0-rc1/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 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 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  Execute specified command in rootless user namespace:
    73  ```
    74  $ podman unshare id
    75  uid=0(root) gid=0(root) groups=0(root),65534(nobody)
    76  ```
    77  
    78  Show user namespace mappings for rootless containers:
    79  ```
    80  $ podman unshare cat /proc/self/uid_map /proc/self/gid_map
    81           0       1000          1
    82           1      10000      65536
    83           0       1000          1
    84           1      10000      65536
    85  ```
    86  
    87  
    88  Show rootless netns information in user namespace for rootless containers:
    89  ```
    90  $ podman unshare --rootless-netns ip addr
    91  1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    92      link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    93      inet 127.0.0.1/8 scope host lo
    94         valid_lft forever preferred_lft forever
    95      inet6 ::1/128 scope host
    96         valid_lft forever preferred_lft forever
    97  2: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
    98      link/ether aa:8c:0b:73:98:f6 brd ff:ff:ff:ff:ff:ff
    99      inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
   100         valid_lft forever preferred_lft forever
   101      inet6 fd00::a88c:bff:fe73:98f6/64 scope global dynamic mngtmpaddr
   102         valid_lft 86389sec preferred_lft 14389sec
   103      inet6 fe80::a88c:bff:fe73:98f6/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)**