umoci-insert(1)(#)

🌸 NAME 🌸

umoci insert — insert content into an OCI image 💖

okay bestie, real quick before we dive in: this is the umoci-insert(1) manual page, and it was written by Aleksa Sarai back in SEPTEMBER 2018 and it has been iconic ever since, no cap. 🎀

---

✨ 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 💫

so there are two whole vibes this command can serve, and they are not the same vibe, so let's break it down. 🦋

Form one, bestie: you insert the contents of source into the OCI image given by --image — and heads up, this overwrites it unless you specify --tag. How? By creating a whole new layer that contains just the contents of source, with a name of target. source can be either a file or a directory, and if it's a directory, bestie, it gets recursed. And if --opaque is specified, then any paths below target in the previous image layers (assuming target is a directory) will be removed. gone. deleted. 💀

Form two, also iconic: this inserts a "deletion entry" into the OCI image for target inside the image. It does that by inserting a layer containing just a whiteout entry for the given path. 🫶

⚠️ okay this part is IMPORTANT, do not skip it. This command works by creating a new layer, so it should NOT be used to remove (or replace) secrets from an already-built image. Like, the secret is still in there. That's not a vibe. See umoci-config(1) and --config.volume for how to achieve this correctly — by not creating image layers with secrets in the first place. periodt. 💅

Also: if --no-history was not specified, a history entry gets appended to the tagged OCI image for this change (with the various --history. flags controlling the values used). Wanna go look at the history? See umoci-stat(1). ✨

---

👑 OPTIONS 👑

The global options are defined in umoci(1). (iykyk 💜)

• --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 — the tag name for the modified image. If unspecified, then the original tag you gave to --image gets clobbered. bye bestie. 💀
• --compress=compression-type — specify the compression type to use when creating a new layer. The supported compression types are none, gzip, and zstd. And good news: umoci-unpack(1) transparently supports all compression methods you can specify with --compress. 🌈

The special value auto will cause umoci(1) 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). But note that auto will never select none compression automatically, as not compressing tar(1) 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. full glow-up for that directory fr fr ✨
• --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 umoci-insert(1) 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. we love an accessible queen 💅
• --uid-map=value — specifies a UID mapping to use when inserting files. This is used in a similar fashion to user_namespaces(7), 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), 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), 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. like, imagine the drama 😭
• --history.comment=comment — comment for the history entry corresponding to this modification of the image. If unspecified, umoci(1) 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) 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). ✨
• --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)). 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. And 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). main character energy for the new layer honestly. 👑

% 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 insert --image oci:foo --whiteout /usr/bin/mybinary
% umoci insert --image oci:foo --opaque myetcdir /etc

---

🦋 SEE ALSO 🦋

umoci(1), umoci-repack(1), umoci-raw-add-layer(1)

---

and that's the whole page bestie!! 💖 this one came from the umoci manual set, page umoci-insert(1)(#), and the footer is literally just insert over umoci over umoci-insert(1)(#) — so go forth and insert things, you absolute legend. slay. 💅✨🎀