.nh
.TH umoci\-unpack(1) # umoci unpack \- Unpacks an OCI image tag into an runtime bundle
Aleksa Sarai
SEPTEMBER 2018

.SH NAME
.PP
umoci unpack \- Unpacks an OCI image tag into an runtime bundle


.SH SYNOPSIS
.PP
\fBumoci unpack\fP
\fB\-\-image\fP=\fIimage\fP[:\fItag\fP]
[\fB\-\-rootless\fP]
[\fB\-\-uid\-map\fP=\fIvalue\fP]
[\fB\-\-uid\-map\fP=\fIvalue\fP]
[\fB\-\-keep\-dirlinks\fP]
\fIbundle\fP


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


.SH OPTIONS
.PP
The global options are defined in \fBumoci\fP(1).

.PP
\fB\-\-image\fP=\fIimage\fP[:\fItag\fP]
  The OCI image tag which will be extracted to the \fIbundle\fP\&. \fIimage\fP must be a
  path to a valid OCI image and \fItag\fP must be a valid tag in the image. If
  \fItag\fP is not provided it defaults to "latest".

.PP
\fB\-\-rootless\fP
  Enable rootless unpacking support. This allows for \fBumoci\-unpack\fP(1) and
  \fBumoci\-repack\fP(1) to be used as an unprivileged user. Use of this flag
  implies \fB\-\-uid\-map=0:$(id \-u):1\fP and \fB\-\-gid\-map=0:$(id \-g):1\fP, 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
  \fB\-\-rootless\fP, but it will be as close as possible.

.PP
\fB\-\-uid\-map\fP=\fIvalue\fP
  Specifies a UID mapping to use while unpacking (and repacking) layers. This
  is used in a similar fashion to \fBuser\_namespaces\fP(7), and is of the form
  \fBcontainer:host[:size]\fP\&.

.PP
\fB\-\-gid\-map\fP=\fIvalue\fP
  Specifies a GID mapping to use while unpacking (and repacking) layers. This
  is used in a similar fashion to \fBuser\_namespaces\fP(7), and is of the form
  \fBcontainer:host[:size]\fP\&.

.PP
\fB\-\-keep\-dirlinks\fP
  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.


.SH EXAMPLE
.PP
The following downloads an image from a \fBdocker\fP(1) registry using
\fBskopeo\fP(1), unpacks said image and then creates a new container using the
extracted OCI runtime bundle with \fBrunc\fP(8). Then, the image is repacked with
\fBumoci\-repack\fP(1).

.PP
.RS

.nf
% 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

.fi
.RE

.PP
With \fB\-\-rootless\fP it is also possible to do the above example without root
privileges. \fBumoci\fP will generate a configuration that works with rootless
containers in \fBrunc\fP(8).

.PP
.RS

.nf
% 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

.fi
.RE


.SH SEE ALSO
.PP
\fBumoci\fP(1), \fBumoci\-repack\fP(1), \fBrunc\fP(8)