github.com/opencontainers/umoci@v0.4.8-0.20240508124516-656e4836fb0d/doc/man/umoci-unpack.1.md (about)

     1  % umoci-unpack(1) # umoci unpack - Unpacks an OCI image tag into an runtime bundle
     2  % Aleksa Sarai
     3  % SEPTEMBER 2018
     4  # NAME
     5  umoci unpack - Unpacks an OCI image tag into an runtime bundle
     6  
     7  # SYNOPSIS
     8  **umoci unpack**
     9  **--image**=*image*[:*tag*]
    10  [**--rootless**]
    11  [**--uid-map**=*value*]
    12  [**--uid-map**=*value*]
    13  [**--keep-dirlinks**]
    14  *bundle*
    15  
    16  # DESCRIPTION
    17  Extracts all of the layers (deterministically) to an OCI runtime bundle at the
    18  path *bundle*, as well as generating an OCI runtime configuration that
    19  corresponds to the image's configuration. In addition, an **mtree**(8)
    20  specification is generated at the time of unpacking to allow filesystem deltas
    21  to be generated by **umoci-repack**(1) and thus allowing for the creation of
    22  layered OCI images.
    23  
    24  # OPTIONS
    25  The global options are defined in **umoci**(1).
    26  
    27  **--image**=*image*[:*tag*]
    28    The OCI image tag which will be extracted to the *bundle*. *image* must be a
    29    path to a valid OCI image and *tag* must be a valid tag in the image. If
    30    *tag* is not provided it defaults to "latest".
    31  
    32  **--rootless**
    33    Enable rootless unpacking support. This allows for **umoci-unpack**(1) and
    34    **umoci-repack**(1) to be used as an unprivileged user. Use of this flag
    35    implies **--uid-map=0:$(id -u):1** and **--gid-map=0:$(id -g):1**, as well as
    36    enabling several features to fake parts of the unpacking in an attempt to
    37    generate an as-close-as-possible extraction of the filesystem. Note that it
    38    is almost always not possible to perfectly extract an OCI image with
    39    **--rootless**, but it will be as close as possible.
    40  
    41  **--uid-map**=*value*
    42    Specifies a UID mapping to use while unpacking (and repacking) layers. This
    43    is used in a similar fashion to **user_namespaces**(7), and is of the form
    44    **container:host[:size]**.
    45  
    46  **--gid-map**=*value*
    47    Specifies a GID mapping to use while unpacking (and repacking) layers. This
    48    is used in a similar fashion to **user_namespaces**(7), and is of the form
    49    **container:host[:size]**.
    50  
    51  **--keep-dirlinks**
    52    Instead of overwriting directories which are links to other directories when
    53    higher layers have an explicit directory, just write through the symlink.
    54    This option is inspired by rsync's option of the same name.
    55  
    56  # EXAMPLE
    57  The following downloads an image from a **docker**(1) registry using
    58  **skopeo**(1), unpacks said image and then creates a new container using the
    59  extracted OCI runtime bundle with **runc**(8). Then, the image is repacked with
    60  **umoci-repack**(1).
    61  
    62  ```
    63  % skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
    64  # umoci unpack --image image bundle
    65  # runc run -b bundle ctr
    66  [ container session ]
    67  # umoci repack --image image bundle
    68  ```
    69  
    70  With **--rootless** it is also possible to do the above example without root
    71  privileges. **umoci** will generate a configuration that works with rootless
    72  containers in **runc**(8).
    73  
    74  ```
    75  % skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
    76  % umoci unpack --image image --rootless bundle
    77  % runc --root $HOME/runc run -b bundle ctr
    78  [ rootless container session ]
    79  % umoci repack --image image --rootless bundle
    80  ```
    81  
    82  # SEE ALSO
    83  **umoci**(1), **umoci-repack**(1), **runc**(8)