umoci

<!-- This comment is necessary to get Hugo to parse this page properly. For whatever reason, it thinks files that start with HTML tags are not Markdown documents (even though this is not actually the case). See <https://github.com/gohugoio/hugo/issues/7296>. --> <p align="center"> <a href="https://umo.ci/" alt="Project Website"> <img src="https://umo.ci/umoci-black.png" alt="umoci" height="130"/></a> </p> <!-- This hack is necessary to work around the fact we cannot conditionally hide these images in Hugo (see <https://github.com/gohugoio/hugo/issues/7398>). Thankfully, GitHub won't render <div> tags, so we can abuse that to hide the badges on the umo.ci website while still showing them in the GitHub README. --> <div style="display: none"> <p align="center"> <a href="https://github.com/opencontainers/umoci/releases/latest" alt="Latest Release"> <img src="https://img.shields.io/github/v/release/opencontainers/umoci"/></a> <a href="https://pkg.go.dev/github.com/opencontainers/umoci" alt="Go Documentation"> <img src="https://img.shields.io/badge/godoc-unstable-red?logo=go"/></a> <a href="https://github.com/opencontainers/umoci/blob/master/COPYING" alt="License: Apache-2.0"> <img src="https://img.shields.io/github/license/opencontainers/umoci"/></a> <br/> <a href="https://github.com/opencontainers/umoci/actions/workflows/ci.yml" alt="Build Status"> <img src="https://github.com/opencontainers/umoci/actions/workflows/ci.yml/badge.svg"/></a> <a href="https://codecov.io/gh/opencontainers/umoci" alt="Code Coverage"> <img src="https://img.shields.io/codecov/c/gh/opencontainers/umoci?logo=codecov"/></a> <a href="https://app.netlify.com/sites/umoci/deploys" alt="Netlify Status"> <img src="https://img.shields.io/netlify/78e5d3da-f8b5-4a8e-8c7b-9e1effb23f2f?logo=netlify"/></a> <br/> <a href="https://bestpractices.coreinfrastructure.org/projects/1084" alt="CII Best Practices"> <img src="https://bestpractices.coreinfrastructure.org/projects/1084/badge"/></a> <a href="https://goreportcard.com/report/github.com/opencontainers/umoci" alt="Go Report Card"> <img src="https://goreportcard.com/badge/github.com/opencontainers/umoci"/></a> <a href="https://observatory.mozilla.org/analyze/umo.ci" alt="Mozilla Observatory Grade"> <img src="https://img.shields.io/mozilla-observatory/grade-score/umo.ci?label=umo.ci&logo=mozilla"/></a> <br/> <a href="https://github.com/opencontainers/umoci/releases" alt="Release Downloads"> <img src="https://img.shields.io/github/downloads/opencontainers/umoci/total"/></a> <a href="https://zenodo.org/badge/latestdoi/72283469" alt="DOI Badge"> <img src="https://zenodo.org/badge/72283469.svg"/></a> <a href="https://matrix.to/#/#opencontainers:matrix.org" alt="Matrix Room"> <img src="https://img.shields.io/matrix/opencontainers:matrix.org?logo=matrix"/></a> </p> <hr/> </div>

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.

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 a release key, whose fingerprint is:

pub   rsa4096 2016-06-21 [SC] [expires: 2031-06-18]
      5F36C6C61B5460124A75F5A69E18AA267DDB8DB4
uid           [ultimate] Aleksa Sarai <asarai@suse.com>
uid           [ultimate] Aleksa Sarai <asarai@suse.de>
sub   rsa4096 2016-06-21 [E] [expires: 2031-06-18]

umoci is also available from several distributions' repositories:

• openSUSE
• Gentoo
• Arch Linux (AUR)

To build umoci from the source code, a simple make should work on most machines, as should make install.

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.

<!-- TODO: Put the man pages on the website... -->

% umoci --help
NAME:
   umoci - umoci modifies Open Container images

USAGE:
   umoci [global options] command [command options] [arguments...]

VERSION:
   0.4.6

AUTHOR:
   Aleksa Sarai <asarai@suse.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)). Information about previous releases including the list of new features, bug fixes and resolved security issues is available in the change log.

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 is considered to be stable despite umoci not being a 1.0 project.

Governance

umoci is an Open Container Initative project, and is thus bound by the OCI Code of Conduct and the OCI Charter. In addition, the umoci project has its own specific governance rules which determine how changes are accepted into the project, how maintainers are added or removed, how releases are proposed and released, and how the governance rules are changed. In the case of any conflict which cannot be resolved by this project's governance rules, the OCI Technical Oversight Board may step in to help resolve the issue.

<!-- TODO: Add proper governance documents. -->

History

umoci was originally developed in 2016 by Aleksa Sarai as part of the openSUSE project, and was donated to the Open Container Initiative as a reference implementation of the OCI image specification in mid-2020.

License

umoci is licensed under the terms of the Apache 2.0 license.

umoci: Umoci Modifies Open Containers' Images
Copyright (C) 2016-2020 SUSE LLC
Copyright (C) 2018 Cisco Systems

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Citation

If you have used umoci in your research, please cite it like you would any other useful software. Here is a handy BibTex citation.

@misc{umoci,
	title = {umoci - Standalone Tool For Manipulating Container Images},
	author = {Aleksa Sarai et al.},
	year = {2016},
	url = {https://umo.ci/},
	doi = {http://dx.doi.org/10.5281/zenodo.1188474},
}

Thank