github.com/opencontainers/umoci@v0.4.8-0.20240508124516-656e4836fb0d/README.md (about) 1 <!-- 2 This comment is necessary to get Hugo to parse this page properly. For 3 whatever reason, it thinks files that start with HTML tags are not Markdown 4 documents (even though this is not actually the case). See 5 <https://github.com/gohugoio/hugo/issues/7296>. 6 --> 7 8 <p align="center"> 9 <a href="https://umo.ci/" alt="Project Website"> 10 <img src="https://umo.ci/umoci-black.png" alt="umoci" height="130"/></a> 11 </p> 12 13 <!-- 14 This hack is necessary to work around the fact we cannot conditionally hide 15 these images in Hugo (see <https://github.com/gohugoio/hugo/issues/7398>). 16 Thankfully, GitHub won't render <div> tags, so we can abuse that to hide the 17 badges on the umo.ci website while still showing them in the GitHub README. 18 --> 19 <div style="display: none"> 20 <p align="center"> 21 <a href="https://github.com/opencontainers/umoci/releases/latest" alt="Latest Release"> 22 <img src="https://img.shields.io/github/v/release/opencontainers/umoci"/></a> 23 <a href="https://pkg.go.dev/github.com/opencontainers/umoci" alt="Go Documentation"> 24 <img src="https://img.shields.io/badge/godoc-unstable-red?logo=go"/></a> 25 <a href="https://github.com/opencontainers/umoci/blob/master/COPYING" alt="License: Apache-2.0"> 26 <img src="https://img.shields.io/github/license/opencontainers/umoci"/></a> 27 28 <br/> 29 30 <a href="https://github.com/opencontainers/umoci/actions/workflows/ci.yml" alt="Build Status"> 31 <img src="https://github.com/opencontainers/umoci/actions/workflows/ci.yml/badge.svg"/></a> 32 <a href="https://codecov.io/gh/opencontainers/umoci" alt="Code Coverage"> 33 <img src="https://img.shields.io/codecov/c/gh/opencontainers/umoci?logo=codecov"/></a> 34 <a href="https://app.netlify.com/sites/umoci/deploys" alt="Netlify Status"> 35 <img src="https://img.shields.io/netlify/78e5d3da-f8b5-4a8e-8c7b-9e1effb23f2f?logo=netlify"/></a> 36 37 <br/> 38 39 <a href="https://bestpractices.coreinfrastructure.org/projects/1084" alt="CII Best Practices"> 40 <img src="https://bestpractices.coreinfrastructure.org/projects/1084/badge"/></a> 41 <a href="https://goreportcard.com/report/github.com/opencontainers/umoci" alt="Go Report Card"> 42 <img src="https://goreportcard.com/badge/github.com/opencontainers/umoci"/></a> 43 <a href="https://observatory.mozilla.org/analyze/umo.ci" alt="Mozilla Observatory Grade"> 44 <img src="https://img.shields.io/mozilla-observatory/grade-score/umo.ci?label=umo.ci&logo=mozilla"/></a> 45 46 <br/> 47 48 <a href="https://github.com/opencontainers/umoci/releases" alt="Release Downloads"> 49 <img src="https://img.shields.io/github/downloads/opencontainers/umoci/total"/></a> 50 <a href="https://zenodo.org/badge/latestdoi/72283469" alt="DOI Badge"> 51 <img src="https://zenodo.org/badge/72283469.svg"/></a> 52 <a href="https://matrix.to/#/#opencontainers:matrix.org" alt="Matrix Room"> 53 <img src="https://img.shields.io/matrix/opencontainers:matrix.org?logo=matrix"/></a> 54 </p> 55 <hr/> 56 </div> 57 58 **u**moci **m**odifies **O**pen **C**ontainer **i**mages. 59 60 umoci (pronounced [/uːmoˈʨi/][umoci-ipa] or approximately 61 "oo-mo-tchee") is a reference implementation of the [OCI image 62 specification][oci-image-spec] and provides users with the ability to create, 63 manipulate, and otherwise interact with container images. It is designed to be 64 as small and unopinonated as possible, so as to act as a foundation for larger 65 systems to be built on top of. The primary method of using umoci is as a 66 command-line tool: 67 68 ```ShellSession 69 Extract image "leap" from image directory "opensuse" and place it 70 inside an OCI runtime-spec bundle at the path "bundle". 71 % umoci unpack --image opensuse:leap bundle 72 73 Make some changes to the root filesystem ("bundle/rootfs"). 74 % runc run -b bundle ctr 75 ctr-sh$ zypper install -y foobarbaz 76 ctr-sh$ exit 77 % echo foo > bundle/rootfs/README 78 79 Create a new image (called "new-leap") in the image directory "opensuse", 80 based on "leap" which contains the changes made to "bundle/rootfs". 81 % umoci repack --image opensuse:new-leap bundle 82 83 Modify the configuration of the "new-leap" image to specify a new author. 84 % umoci config --image opensuse:new-leap \ 85 > --author="Aleksa Sarai <cyphar@cyphar.com>" \ 86 > --config.workingdir="/var/www" 87 88 Garbage-collect any unreferenced blobs in the image directory "opensuse". 89 % umoci gc --layout opensuse 90 ``` 91 92 See [the quick start guide][quickstart] for more accessible documentation about 93 how to use umoci. Notable users of umoci include: 94 95 * [KIWI][kiwi], which uses umoci to support building both [base and derived 96 container images][kiwi-container] which are then converted to Docker images. 97 * The [Open Build Service][obs], which uses umoci (through [KIWI][kiwi]) to 98 support building and publishing container images from its built-in container 99 registry. The openSUSE project has been using this method of building 100 container images in production since 2016. 101 * [Stacker][stacker], which uses umoci as its core building primitive, and is 102 used by Cisco to build container images for some of their appliances since 103 2018. 104 * [LXC][lxc] provides support for OCI container images through an [OCI 105 template][lxc-oci], which is implemented as a shell script that wraps umoci. 106 The fact that a container runtime with a vastly different model to OCI 107 container runtimes can make use of umoci is further evidence of its 108 unopinionated design. 109 110 If you wish to provide feedback or contribute, read the [`CONTRIBUTING.md`][contributing] 111 for this project to refresh your knowledge about how to submit good bug reports 112 and patches. Information about how to privately submit security disclosures is 113 also provided. 114 115 [quickstart]: https://umo.ci/quick-start/ 116 [umoci-ipa]: http://ipa-reader.xyz/?text=u%CB%90mo%CB%88%CA%A8i&voice=Amy 117 [oci-image-spec]: https://github.com/opencontainers/image-spec 118 [kiwi]: https://osinside.github.io/kiwi/ 119 [kiwi-container]: https://osinside.github.io/kiwi/building/build_docker_container.html 120 [obs]: https://openbuildservice.org/ 121 [stacker]: https://github.com/project-stacker/stacker 122 [lxc]: https://linuxcontainers.org/ 123 [lxc-oci]: https://github.com/lxc/lxc/blob/lxc-4.0.2/templates/lxc-oci.in 124 [contributing]: /CONTRIBUTING.md 125 126 ### Install ### 127 128 Pre-built binaries can be downloaded from [umoci's releases page][releases]. As 129 umoci's builds are reproducible, a cryptographic checksum file is included in 130 the release assets. All of the assets are also signed with a [release 131 key][umoci-keyring], whose fingerprint is: 132 133 ```text 134 pub rsa4096 2016-06-21 [SC] [expires: 2031-06-18] 135 5F36C6C61B5460124A75F5A69E18AA267DDB8DB4 136 uid [ultimate] Aleksa Sarai <asarai@suse.com> 137 uid [ultimate] Aleksa Sarai <asarai@suse.de> 138 sub rsa4096 2016-06-21 [E] [expires: 2031-06-18] 139 ``` 140 141 umoci is also available from several distributions' repositories: 142 143 * [openSUSE](https://software.opensuse.org/package/umoci) 144 * [Gentoo](https://packages.gentoo.org/packages/app-emulation/umoci) 145 * [Arch Linux (AUR)](https://aur.archlinux.org/packages/umoci/) 146 147 To build umoci from the [source code][source], a simple `make` should work on 148 most machines, as should `make install`. 149 150 [releases]: https://github.com/opencontainers/umoci/releases 151 [umoci-keyring]: /umoci.keyring 152 [source]: https://github.com/opencontainers/umoci 153 [go]: https://golang.org/ 154 155 ### Usage ### 156 157 umoci has a subcommand-based command-line. For more detailed information, see 158 the generated man pages (which you can build with `make docs`). You can also 159 read through our [quick start guide][quickstart]. 160 161 <!-- TODO: Put the man pages on the website... --> 162 163 ```text 164 % umoci --help 165 NAME: 166 umoci - umoci modifies Open Container images 167 168 USAGE: 169 umoci [global options] command [command options] [arguments...] 170 171 VERSION: 172 0.4.6 173 174 AUTHOR: 175 Aleksa Sarai <asarai@suse.com> 176 177 COMMANDS: 178 raw advanced internal image tooling 179 help, h Shows a list of commands or help for one command 180 181 image: 182 config modifies the image configuration of an OCI image 183 unpack unpacks a reference into an OCI runtime bundle 184 repack repacks an OCI runtime bundle into a reference 185 new creates a blank tagged OCI image 186 tag creates a new tag in an OCI image 187 remove, rm removes a tag from an OCI image 188 stat displays status information of an image manifest 189 insert insert content into an OCI image 190 191 layout: 192 gc garbage-collects an OCI image's blobs 193 init create a new OCI layout 194 list, ls lists the set of tags in an OCI layout 195 196 GLOBAL OPTIONS: 197 --verbose alias for --log=info 198 --log value set the log level (debug, info, [warn], error, fatal) (default: "warn") 199 --help, -h show help 200 --version, -v print the version 201 ``` 202 203 [quickstart]: https://umo.ci/quick-start/ 204 205 ### Releases and Stability ### 206 207 We regularly publish [new releases][releases], with each release being given a 208 unique identifying version number (as governed by [Semantic Versioning 209 (SemVer)][semver]). Information about previous releases including the list of 210 new features, bug fixes and resolved security issues is available in the 211 [change log][changelog]. 212 213 Note that while umoci is currently usable as a Go library (and we do have 214 several users of the Go APIs), the API is explicitly considered **unstable** 215 until umoci `1.0` is released. However, the umoci CLI API is considered to be 216 stable despite umoci not being a `1.0` project. 217 218 [releases]: https://github.com/opencontainers/umoci/releases 219 [semver]: http://semver.org/ 220 [changelog]: /CHANGELOG.md 221 222 ### Governance ### 223 224 umoci is an Open Container Initative project, and is thus bound by the [OCI 225 Code of Conduct][oci-coc] and the [OCI Charter][oci-charter]. In addition, the 226 umoci project has its own specific [governance rules][governance] which 227 determine how changes are accepted into the project, how maintainers are added 228 or removed, how releases are proposed and released, and how the governance 229 rules are changed. In the case of any conflict which cannot be resolved by this 230 project's governance rules, the [OCI Technical Oversight Board][oci-tob] may 231 step in to help resolve the issue. 232 233 [oci-coc]: https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md 234 [oci-charter]: https://github.com/opencontainers/tob/blob/master/CHARTER.md 235 <!-- TODO: Add proper governance documents. --> 236 [governance]: /GOVERNANCE.md 237 [oci-tob]: https://opencontainers.org/about/tob/ 238 239 ### History ### 240 241 umoci was originally developed in 2016 by Aleksa Sarai as part of the [openSUSE 242 project][opensuse], and was donated to the Open Container Initiative as a 243 reference implementation of the [OCI image specification][oci-image-spec] in 244 mid-2020. 245 246 [opensuse]: https://www.opensuse.org/ 247 [oci-image-spec]: https://github.com/opencontainers/image-spec 248 249 ### License ### 250 251 umoci is licensed under the terms of the Apache 2.0 license. 252 253 ```text 254 umoci: Umoci Modifies Open Containers' Images 255 Copyright (C) 2016-2020 SUSE LLC 256 Copyright (C) 2018 Cisco Systems 257 258 Licensed under the Apache License, Version 2.0 (the "License"); 259 you may not use this file except in compliance with the License. 260 You may obtain a copy of the License at 261 262 http://www.apache.org/licenses/LICENSE-2.0 263 264 Unless required by applicable law or agreed to in writing, software 265 distributed under the License is distributed on an "AS IS" BASIS, 266 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 267 See the License for the specific language governing permissions and 268 limitations under the License. 269 ``` 270 271 ### Citation ### 272 273 If you have used umoci in your research, please cite it like you would any 274 other useful software. Here is a handy BibTex citation. 275 276 ``` 277 @misc{umoci, 278 title = {umoci - Standalone Tool For Manipulating Container Images}, 279 author = {Aleksa Sarai et al.}, 280 year = {2016}, 281 url = {https://umo.ci/}, 282 doi = {http://dx.doi.org/10.5281/zenodo.1188474}, 283 } 284 ``` 285 286 Thank you.