--- name: "umoci-insert" section: "1" platform: "linux" package: "umoci" version: "0.6.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/umoci-insert" --- # umoci-insert(1) insert content into an OCI image Aleksa Sarai SEPTEMBER 2018 ## NAME umoci insert - insert content into an OCI image ## SYNOPSIS **umoci insert** **--image**=*image*\[:*tag*\] \[**--tag**=*new-tag*\] \[**--compress**=*compression-type*\] \[**--opaque**\] \[**--rootless**\] \[**--uid-map**=*value*\] \[**--uid-map**=*value*\] \[**--no-history**\] \[**--history.comment**=*comment*\] \[**--history.created\_by**=*created\_by*\] \[**--history.author**=*author*\] \[**--history-created**=*date*\] *source* *target* **umoci insert** \[options\] **--whiteout** *target* ## DESCRIPTION In the first form, insert the contents of *source* into the OCI image given by **--image** -- **overwriting it unless you specify --tag**. This is done by creating a new layer containing just the contents of *source* with a name of *target*. *source* can be either a file or directory, and in the latter case it will be recursed. If **--opaque** is specified then any paths below *target* in the previous image layers (assuming *target* is a directory) will be removed. In the second form, inserts a "deletion entry" into the OCI image for *target* inside the image. This is done by inserting a layer containing just a whiteout entry for the given path. Note that this command works by creating a new layer, so this should not be used to remove (or replace) secrets from an already-built image. See [**umoci-config**(1)](/umoci-config/1.md) and **--config.volume** for how to achieve this correctly by not creating image layers with secrets in the first place. If **--no-history** was not specified, a history entry is appended to the tagged OCI image for this change (with the various **--history.** flags controlling the values used). To view the history, see [**umoci-stat**(1)](/umoci-stat/1.md). ## OPTIONS The global options are defined in [**umoci**(1)](/umoci/1.md). **--image**=*image*\[:*tag*\]\ The source and destination tag for the insertion of *file* at *path* inside\ the container image. *image* must be a path to a valid OCI image and *tag*\ must be a valid tag in the image. If *tag* is not provided it defaults to\ "latest". **--tag**=*new-tag*\ Tag name for the modified image, if unspecified then the original tag\ provided to **--image** will be clobbered. **--compress**=*compression-type*\ Specify the compression type to use when creating a new layer. Supported\ compression types are *none*, *gzip*, and *zstd*. [**umoci-unpack**(1)](/umoci-unpack/1.md)\ transparently supports all compression methods you can specify with\ **--compress**. The special value *auto* will cause [**umoci**(1)](/umoci/1.md) to auto-select the most\ appropriate compression algorithm based on what previous layers are\ compressed with (it will try to use the most recent layer's compression\ algorithm which it supports). Note that *auto* will never select *none*\ compression automatically, as not compressing [**tar**(1)](/tar/1.md) archives is really\ not advisable. If no *compression-type* is provided, it defaults to *auto*. **--opaque**\ (Assuming *target* is a directory.) Add an opaque whiteout entry for *target*\ so that any child path of *target* in previous layers is masked by the new\ entry for *target*, which will just contain the contents of *source*. This\ allows for the complete replacement of a directory, as opposed to the merging\ of directory entries. **--whiteout**\ Add a deletion entry for *target*, so that it is not present in future\ extractions of the image. **--rootless**\ Enable rootless insertion support. This allows for [**umoci-insert**(1)](/umoci-insert/1.md) to be\ used as an unprivileged user. Use of this flag implies **--uid-map=0:$(id**\ **-u):1** and **--gid-map=0:$(id -g):1**, as well as enabling several features\ to fake parts of the recursion process in an attempt to generate an\ as-close-as-possible clone of the filesystem for insertion. **--uid-map**=*value*\ Specifies a UID mapping to use when inserting files. This is used in a\ similar fashion to [**user\_namespaces**(7)](/user_namespaces/7.md), and is of the form\ **container:host\[:size\]**. **--gid-map**=*value*\ Specifies a GID mapping to use when inserting files. This is used in a\ similar fashion to [**user\_namespaces**(7)](/user_namespaces/7.md), and is of the form\ **container:host\[:size\]**. **--no-history**\ Causes no history entry to be added for this operation. **This is not**\ **recommended for use with [umoci-insert(1)](/umoci-insert/1.md), since it results in the history not**\ **including all of the image layers -- and thus will cause confusion with tools**\ **that look at image history.** **--history.comment**=*comment*\ Comment for the history entry corresponding to this modification of the image\ If unspecified, [**umoci**(1)](/umoci/1.md) will generate an implementation-dependent value. **--history.created\_by**=*created\_by*\ CreatedBy entry for the history entry corresponding to this modification of\ the image. If unspecified, [**umoci**(1)](/umoci/1.md) will generate an\ implementation-dependent value. **--history.author**=*author*\ Author value for the history entry corresponding to this modification of the\ image. If unspecified, this value will be the image's author value **after**\ any modifications were made by this call of [**umoci-config**(1)](/umoci-config/1.md). **--history-created**=*date*\ Creation date for the history entry corresponding to this modifications of\ the image. This must be an ISO8601 formatted timestamp (see [**date**(1)](/date/1.md)). If\ unspecified, the current time is used. ## EXAMPLE The following inserts a file **mybinary** into the path **/usr/bin/mybinary** and a directory **myconfigdir** into the path **/etc/myconfigdir**. It should be noted that if **/etc/myconfigdir** already exists in the image, the contents of the two directories are merged (with the newer layer taking precedence). ``` % umoci insert --image oci:foo mybinary /usr/bin/mybinary % umoci insert --image oci:foo myconfigdir /etc/myconfigdir ``` And in these examples we delete **/usr/bin/mybinary** and replace the entirety of **/etc** with **myetcdir** (such that none of the old **/etc** entries will be present on [**umoci-unpack**(1)](/umoci-unpack/1.md)). ``` % umoci insert --image oci:foo --whiteout /usr/bin/mybinary % umoci insert --image oci:foo --opaque myetcdir /etc ``` ## SEE ALSO [**umoci**(1)](/umoci/1.md), [**umoci-repack**(1)](/umoci-repack/1.md), [**umoci-raw-add-layer**(1)](/umoci-raw-add-layer/1.md)