umoci

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 21, 2025 License: Apache-2.0 Imports: 26 Imported by: 25

README

umoci

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 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:

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.

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

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

VERSION:
   0.5.0

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.

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-2025 SUSE LLC
Copyright (C) 2018, 2020 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 you.

Documentation

Overview

Package umoci provides the top-level Go APIs for umoci functionality. Note that the umoci Go API is not yet considered stable -- we will aim to document any breaking changes in our changelogs but users should verify that updates will not break their usage of umoci.

Index

Constants

View Source
const MetaName = "umoci.json"

MetaName is the name of umoci's metadata file that is stored in all bundles extracted by umoci.

View Source
const MetaVersion = "2"

MetaVersion is the version of Meta supported by this code. The value is only bumped for updates which are not backwards compatible.

Variables

View Source
var MtreeKeywords = []mtree.Keyword{
	"size",
	"type",
	"uid",
	"gid",
	"mode",
	"link",
	"nlink",
	"tar_time",
	"sha256digest",
	"xattr",
}

MtreeKeywords is the set of keywords used by umoci for verification and diff generation of a bundle. This is based on mtree.DefaultKeywords, but is hardcoded here to ensure that vendor changes don't mess things up.

Functions

func CreateLayout added in v0.4.2

func CreateLayout(imagePath string) (casext.Engine, error)

CreateLayout creates an existing OCI image layout, and fails if it already exists.

func FullVersion added in v0.4.7

func FullVersion() string

FullVersion returns a fully-qualified version string if one is available. NOTE: This function will return "unknown" if umoci is being used as a "go

get" dependency or binary.

func GenerateBundleManifest added in v0.4.2

func GenerateBundleManifest(mtreeName string, bundlePath string, fsEval mtree.FsEval) (Err error)

GenerateBundleManifest creates and writes an mtree of the rootfs in the given bundle path, using the supplied fsEval method.

func NewImage added in v0.4.6

func NewImage(engineExt casext.Engine, tagName string) error

NewImage creates a new empty image (tag) in the existing layout.

func OpenLayout added in v0.4.2

func OpenLayout(imagePath string) (casext.Engine, error)

OpenLayout opens an existing OCI image layout, and fails if it does not exist.

func ParseIdmapOptions added in v0.4.2

func ParseIdmapOptions(meta *Meta, ctx *cli.Context) error

ParseIdmapOptions sets up the mapping options for Meta, using the arguments specified on the command line.

func Repack added in v0.4.6

func Repack(engineExt casext.Engine, tagName, bundlePath string,
	meta Meta,
	history *ispec.History,
	filters []mtreefilter.FilterFunc,
	refreshBundle bool,
	mutator *mutate.Mutator,
	layerCompressor mutate.Compressor,
) (Err error)

Repack repacks a bundle into an image adding a new layer for the changed data in the bundle.

If layerCompressor is nil, the compression algorithm is auto-selected.

func Unpack added in v0.4.6

func Unpack(engineExt casext.Engine, fromName, bundlePath string, unpackOptions layer.UnpackOptions) (Err error)

Unpack unpacks an image to the specified bundle path.

func WriteBundleMeta added in v0.4.2

func WriteBundleMeta(bundle string, meta Meta) (Err error)

WriteBundleMeta writes an umoci.json file to the given bundle path.

Types

type ManifestStat added in v0.4.2

type ManifestStat struct {

	// History stores the history information for the manifest.
	History []historyStat `json:"history"`
}

ManifestStat has information about a given OCI manifest. TODO: Implement support for manifest lists, this should also be able to

contain stat information for a list of manifests.

func Stat added in v0.4.2

func Stat(ctx context.Context, engine casext.Engine, manifestDescriptor ispec.Descriptor) (ManifestStat, error)

Stat computes the ManifestStat for a given manifest blob. The provided descriptor must refer to an OCI Manifest.

func (ManifestStat) Format added in v0.4.2

func (ms ManifestStat) Format(w io.Writer) error

Format formats a ManifestStat using the default formatting, and writes the result to the given writer. TODO: This should really be implemented in a way that allows for users to

define their own custom templates for different blocks (meaning that
this should use text/template rather than using tabwriters manually.

type Meta added in v0.4.2

type Meta struct {
	// Version is the version of umoci used to unpack the bundle. This is used
	// to future-proof the umoci.json information.
	Version string `json:"umoci_version"`

	// From is a copy of the descriptor pointing to the image manifest that was
	// used to unpack the bundle. Essentially it's a resolved form of the
	// --image argument to umoci-unpack(1).
	From casext.DescriptorPath `json:"from_descriptor_path"`

	// MapOptions is the parsed version of --uid-map, --gid-map and --rootless
	// arguments to umoci-unpack(1). While all of these options technically do
	// not need to be the same for corresponding umoci-unpack(1) and
	// umoci-repack(1) calls, changing them is not recommended and so the
	// default should be that they are the same.
	MapOptions layer.MapOptions `json:"map_options"`

	// WhiteoutMode indicates what style of whiteout was written to disk
	// when this filesystem was extracted.
	// NOTE: This field has been deprecated, as the feature was completely
	// broken. See <https://github.com/opencontainers/umoci/issues/574> for
	// more details.
	DeprecatedWhiteoutMode int `json:"whiteout_mode,omitempty"`
}

Meta represents metadata about how umoci unpacked an image to a bundle and other similar information. It is used to keep track of information that is required when repacking an image and other similar bundle information.

func ReadBundleMeta added in v0.4.2

func ReadBundleMeta(bundle string) (_ Meta, Err error)

ReadBundleMeta reads and parses the umoci.json file from a given bundle path.

func (Meta) WriteTo added in v0.4.2

func (m Meta) WriteTo(w io.Writer) (int64, error)

WriteTo writes a JSON-serialised version of Meta to the given io.Writer.

Directories

Path Synopsis
cmd
umoci
Package main is the cli implementation of umoci.
Package main is the cli implementation of umoci.
Package internal (and all subpackages) are for internal-to-umoci APIs.
Package internal (and all subpackages) are for internal-to-umoci APIs.
Package mutate implements various functionality to allow for the modification of container images in a much higher-level fashion than available from github.com/opencontainers/umoci/oci/cas.
Package mutate implements various functionality to allow for the modification of container images in a much higher-level fashion than available from github.com/opencontainers/umoci/oci/cas.
oci
cas
Package cas provides a generic interface for the content-addressable store that underlies OCI images.
Package cas provides a generic interface for the content-addressable store that underlies OCI images.
cas/dir
Package dir implements the basic local directory-backed layout backend for the OCI content-addressible store.
Package dir implements the basic local directory-backed layout backend for the OCI content-addressible store.
casext
Package casext provides extensions to the standard cas.Engine interface, allowing for generic functionality to be used on top of any implementation of cas.Engine.
Package casext provides extensions to the standard cas.Engine interface, allowing for generic functionality to be used on top of any implementation of cas.Engine.
casext/blobcompress
Package blobcompress provides a somewhat implementation-agnostic mechanism for blobcompression and deblobcompression of an io.Reader.
Package blobcompress provides a somewhat implementation-agnostic mechanism for blobcompression and deblobcompression of an io.Reader.
casext/mediatype
Package mediatype provides OCI-mimetype-based extensibility of umoci by allowing umoci Go API users to extend the set of supported mimetypes to a somewhat-limited extent.
Package mediatype provides OCI-mimetype-based extensibility of umoci by allowing umoci Go API users to extend the set of supported mimetypes to a somewhat-limited extent.
config/convert
Package convert implements the OCI image specification "default runtime configuration" conversion specification in a fairly unopinionated way.
Package convert implements the OCI image specification "default runtime configuration" conversion specification in a fairly unopinionated way.
config/generate
Package generate provides an API for modifying the OCI image configuration object in a slightly less manual way than constructing structs and doing nil checks manually.
Package generate provides an API for modifying the OCI image configuration object in a slightly less manual way than constructing structs and doing nil checks manually.
layer
Package layer implements the creation and extraction of OCI specification layers.
Package layer implements the creation and extraction of OCI specification layers.
pkg
fseval
Package fseval provides a generic interface for all filesystem operations done by umoci when working in the image rootfs, which allows for alternative implementations of the filesystem operations to be easily swapped in.
Package fseval provides a generic interface for all filesystem operations done by umoci when working in the image rootfs, which allows for alternative implementations of the filesystem operations to be easily swapped in.
funchelpers
Package funchelpers provides small helpers related to writing easy-to-understand Go functions.
Package funchelpers provides small helpers related to writing easy-to-understand Go functions.
hardening
Package hardening implements security hardening measures within umoci.
Package hardening implements security hardening measures within umoci.
idtools
Package idtools provides helpers for dealing with Linux ID mappings.
Package idtools provides helpers for dealing with Linux ID mappings.
iohelpers
Package iohelpers provides basic extensions to the helpers provided by the Go stdlib "io" module.
Package iohelpers provides basic extensions to the helpers provided by the Go stdlib "io" module.
mtreefilter
Package mtreefilter provides helpers to construct filters that can be applied on mtree manifests, allowing you to filter out changes from being included in a tar diff layer.
Package mtreefilter provides helpers to construct filters that can be applied on mtree manifests, allowing you to filter out changes from being included in a tar diff layer.
pathtrie
Package pathtrie provides a minimal implementation of a trie where each node is a path component, allowing you to efficiently store metadata about a path-based structure and iterate over subtrees within said structure.
Package pathtrie provides a minimal implementation of a trie where each node is a path component, allowing you to efficiently store metadata about a path-based structure and iterate over subtrees within said structure.
system
Package system provides ergonomic wrappers for operating system APIs.
Package system provides ergonomic wrappers for operating system APIs.
testutils
Package testutils provides helpers for umoci's test suite.
Package testutils provides helpers for umoci's test suite.
unpriv
Package unpriv provides rootless emulation of CAP_DAC_READ_SEARCH without the need for rootless user namespaces.
Package unpriv provides rootless emulation of CAP_DAC_READ_SEARCH without the need for rootless user namespaces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL