Umoci
umoci modifies Open Container images
Install / Use
/learn @opencontainers/UmociREADME
umoci modifies Open Container images.
umoci (pronounced /uːmoˈʨi/ or approximately "oo-mo-tchee") is a reference implementation of the OCI image specification and provides users with the ability to create, manipulate, and otherwise interact with container images. It is designed to be as small and unopinonated as possible, so as to act as a foundation for larger systems to be built on top of. The primary method of using umoci is as a command-line tool:
Extract image "leap" from image directory "opensuse" and place it
inside an OCI runtime-spec bundle at the path "bundle".
% umoci unpack --image opensuse:leap bundle
Make some changes to the root filesystem ("bundle/rootfs").
% runc run -b bundle ctr
ctr-sh$ zypper install -y foobarbaz
ctr-sh$ exit
% echo foo > bundle/rootfs/README
Create a new image (called "new-leap") in the image directory "opensuse",
based on "leap" which contains the changes made to "bundle/rootfs".
% umoci repack --image opensuse:new-leap bundle
Modify the configuration of the "new-leap" image to specify a new author.
% umoci config --image opensuse:new-leap \
> --author="Aleksa Sarai <cyphar@cyphar.com>" \
> --config.workingdir="/var/www"
Garbage-collect any unreferenced blobs in the image directory "opensuse".
% umoci gc --layout opensuse
See the quick start guide for more accessible documentation about how to use umoci. Notable users of umoci include:
- KIWI, which uses umoci to support building both base and derived container images which are then converted to Docker images.
- The Open Build Service, which uses umoci (through KIWI) to support building and publishing container images from its built-in container registry. The openSUSE project has been using this method of building container images in production since 2016.
- Stacker, which uses umoci as its core building primitive, and is used by Cisco to build container images for some of their appliances since 2018.
- LXC provides support for OCI container images through an OCI template, which is implemented as a shell script that wraps umoci. The fact that a container runtime with a vastly different model to OCI container runtimes can make use of umoci is further evidence of its unopinionated design.
- Incus provides support for OCI container images using umoci as well.
If you wish to provide feedback or contribute, read the CONTRIBUTING.md
for this project to refresh your knowledge about how to submit good bug reports
and patches. Information about how to privately submit security disclosures is
also provided.
Install
Pre-built binaries can be downloaded from umoci's releases page. As umoci's builds are reproducible, a cryptographic checksum file is included in the release assets. All of the assets are also signed with one of our release keys, whose fingerprints are:
pub ed25519 2019-06-21 [C]
C9C370B246B09F6DBCFC744C34401015D1D2D386
uid [ultimate] Aleksa Sarai <cyphar@cyphar.com>
sub ed25519 2022-09-30 [S] [expires: 2030-03-25]
B64E4955B29FA3D463F2A9062897FAD2B7E9446F
sub cv25519 2022-09-30 [E] [expires: 2030-03-25]
0C23601C4F4561640663556524325218CEA61CB8
sub ed25519 2022-09-30 [A] [expires: 2030-03-25]
A6BBD7976DBC7617FC73737D2374658C6654AF23
umoci is also available from several distributions' repositories:
<a href="https://repology.org/project/umoci/versions"> <img src="https://repology.org/badge/vertical-allrepos/umoci.svg?columns=4&exclude_unsupported=1" alt="Packaging Status"> </a>To build umoci from the source code, a simple make should work on
most machines, as should make install. If you prefer to use go install, you
can use
% go install github.com/opencontainers/umoci/cmd/umoci@latest
but we recommend using make instead.
Usage
umoci has a subcommand-based command-line. For more detailed information, see
the generated man pages (which you can build with make docs). You can also
read through our quick start guide.
% umoci --help
NAME:
umoci - umoci modifies Open Container images
USAGE:
umoci [global options] command [command options] [arguments...]
VERSION:
0.6.0
AUTHOR:
Aleksa Sarai <cyphar@cyphar.com>
COMMANDS:
raw advanced internal image tooling
help, h Shows a list of commands or help for one command
image:
config modifies the image configuration of an OCI image
unpack unpacks a reference into an OCI runtime bundle
repack repacks an OCI runtime bundle into a reference
new creates a blank tagged OCI image
tag creates a new tag in an OCI image
remove, rm removes a tag from an OCI image
stat displays status information of an image manifest
insert insert content into an OCI image
layout:
gc garbage-collects an OCI image's blobs
init create a new OCI layout
list, ls lists the set of tags in an OCI layout
GLOBAL OPTIONS:
--verbose alias for --log=info
--log value set the log level (debug, info, [warn], error, fatal) (default: "warn")
--help, -h show help
--version, -v print the version
Releases and Stability
We regularly publish new releases, with each release being given a unique identifying version number (as governed by [Semantic Versioning (SemVer)][semver]). Information about previous releases including the list of new features, bug fixes and resolved security issues is available in the [change log][changelog].
Note that while umoci is currently usable as a Go library (and we do have
several users of the Go APIs), the API is explicitly considered unstable
until umoci 1.0 is released. However, the umoci CLI API i
