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)