umoci

README

umoci modifies Open Container images. See the official website for more accessible documentation about how to use umoci.

umoci intends to be a complete manipulation tool for OCI images. In particular, it should be seen as a more end-user-focused version of the oci-image-tools provided by the OCI. The hope is that all of this tooling will eventually be merged with the upstream repository, so that it is always kept up-to-date by the Open Container Initiative community.

However, currently there is a lot of discussion about the new tooling going into the OCI image tools, and right now I need tooling that can abstract all of the internals of the OCI specification into a single CLI interface. The main purpose of this tool is to serve as example of what I would like to see in an oci-image tool.

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 submit responsible security disclosures is also provided.

Releases

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. You can get pre-built binaries and corresponding source code for each release from the releases page.

Installation

If you wish to build umoci from source, follow these steps to build in with golang.

GOPATH=$HOME
go get -d github.com/openSUSE/umoci
cd $GOPATH/src/github.com/openSUSE/umoci
make install

Your umoci binary will be in $HOME/bin.

Usage

umoci has a subcommand-based command-line. For more detailed information, see the generated man pages (which you can build with make doc). 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.3.1

AUTHOR(S):
   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

   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 image

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

License

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

umoci: Umoci Modifies Open Containers' Images
Copyright (C) 2016-2019 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 you.

Documentation

Index

• Constants
• Variables
• func CreateLayout(imagePath string) (casext.Engine, error)
• func GenerateBundleManifest(mtreeName string, bundlePath string, fsEval mtree.FsEval) error
• func NewImage(engineExt casext.Engine, tagName string) error
• func OpenLayout(imagePath string) (casext.Engine, error)
• func ParseIdmapOptions(meta *Meta, ctx *cli.Context) error
• func Repack(engineExt casext.Engine, tagName string, bundlePath string, meta Meta, ...) error
• func Unpack(engineExt casext.Engine, fromName string, bundlePath string, ...) error
• func WriteBundleMeta(bundle string, meta Meta) error
• type ManifestStat
  • func Stat(ctx context.Context, engine casext.Engine, manifestDescriptor ispec.Descriptor) (ManifestStat, error)
  • func (ms ManifestStat) Format(w io.Writer) error
• type Meta
  • func ReadBundleMeta(bundle string) (Meta, error)
  • func (m Meta) WriteTo(w io.Writer) (int64, error)

Constants

const MetaName = "umoci.json"

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

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

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

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

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

func GenerateBundleManifest

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

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

func NewImage

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

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

func OpenLayout

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

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

func ParseIdmapOptions

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

func Repack(engineExt casext.Engine, tagName string, bundlePath string, meta Meta, history *ispec.History, maskedPaths []string, refreshBundle bool, mutator *mutate.Mutator) error

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

func Unpack

func Unpack(engineExt casext.Engine, fromName string, bundlePath string, mapOptions layer.MapOptions) error

Unpack unpacks an image to the specified bundle path.

func WriteBundleMeta

func WriteBundleMeta(bundle string, meta Meta) error

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

Types

type ManifestStat

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

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

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

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"`
}

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

func ReadBundleMeta(bundle string) (Meta, error)

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

func (Meta) WriteTo

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

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