umoci-unpack(1)(#)

Aleksa Sarai SEPTEMBER 2018

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)