NAME

       umoci unpack - Unpacks an OCI image tag into an runtime bundle

SYNOPSIS

       umoci  unpack  --image=image[:tag]  [--rootless]  [--uid-map=value]  [--uid-map=value]  [--keep-dirlinks]
       bundle

DESCRIPTION

       Extracts all of the layers (deterministically) to an OCI runtime bundle at the path bundle,  as  well  as
       generating  an  OCI  runtime configuration that corresponds to the image's configuration. In addition, an
       mtree(8) specification is generated at the time of unpacking to allow filesystem deltas to  be  generated
       by umoci-repack(1) and thus allowing for the creation of layered OCI images.

OPTIONS

       The global options are defined in umoci(1).

       --image=image[:tag]
         The OCI image tag which will be extracted to the bundle. image must be a
         path to a valid OCI image and tag must be a valid tag in the image. If
         tag is not provided it defaults to "latest".

       --rootless
         Enable rootless unpacking support. This allows for umoci-unpack(1) and
         umoci-repack(1) to be used as an unprivileged user. Use of this flag
         implies --uid-map=0:$(id -u):1 and --gid-map=0:$(id -g):1, as well as
         enabling several features to fake parts of the unpacking in an attempt to
         generate an as-close-as-possible extraction of the filesystem. Note that it
         is almost always not possible to perfectly extract an OCI image with
         --rootless, but it will be as close as possible.

       --uid-map=value
         Specifies a UID mapping to use while unpacking (and repacking) layers. This
         is used in a similar fashion to user_namespaces(7), and is of the form
         container:host[:size].

       --gid-map=value
         Specifies a GID mapping to use while unpacking (and repacking) layers. This
         is used in a similar fashion to user_namespaces(7), and is of the form
         container:host[:size].

       --keep-dirlinks
         Instead of overwriting directories which are links to other directories when
         higher layers have an explicit directory, just write through the symlink.
         This option is inspired by rsync's option of the same name.

EXAMPLE

       The  following  downloads an image from a docker(1) registry using skopeo(1), unpacks said image and then
       creates a new container using the extracted OCI runtime bundle with runc(8). Then, the image is  repacked
       with umoci-repack(1).

       % skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
       # umoci unpack --image image bundle
       # runc run -b bundle ctr
       [ container session ]
       # umoci repack --image image bundle

       With  --rootless it is also possible to do the above example without root privileges. umoci will generate
       a configuration that works with rootless containers in runc(8).

       % skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
       % umoci unpack --image image --rootless bundle
       % runc --root $HOME/runc run -b bundle ctr
       [ rootless container session ]
       % umoci repack --image image --rootless bundle

SEE ALSO

       umoci(1), umoci-repack(1), runc(8)

unpack                                                umoci                                   umoci-unpack(1)(#)