umoci-raw-add-layer(1)(#)

✨ umoci-raw-add-layer ✨

okay bestie, welcome to umoci-raw-add-layer(1) — the add-layer page from the umoci manual, written by Aleksa Sarai back in SEPTEMBER 2018. she's giving very specific, very expert energy, and we're gonna go through her together 💅

---

🎀 NAME 🎀

umoci raw add-layer — add a layer archive verbatim to an image

---

🦋 SYNOPSIS 🦋

umoci raw add-layer --image=image [--tag=tag] [--compress=compression-type]
[--no-history] [--history.comment=comment] [--history.created_by=created_by]
[--history.author=author] [--history-created=date] new-layer.tar

---

🌸 DESCRIPTION 🌸

so basically, this adds the uncompressed layer archive that new-layer.tar points at verbatim to the image. and when we say verbatim we mean verbatim verbatim — no changes get made to the layer at all, which means any OCI-specific tar extensions (like .wh. whiteout files, yes those) get included unmodified. no touchy, no fixy.

because of that whole "we will not be editing anything for you" situation, this command is only recommended for expert users. if you're newer to all this, bestie, please go look at umoci-repack(1) to create your layers instead — she's got you 🫶

and at the moment? umoci raw add-layer only supports appending layers to the end of the image layer list. that's it, that's the whole vibe. no inserting in the middle, no rearranging. end of the line only, periodt.

---

💖 OPTIONS 💖

the global options are defined over in umoci(1), so go say hi to her too.

• --image=image[:tag] — the source tag to use as the base of the image that's gonna be holding the new layer. image has to be a path to a valid OCI image, and tag has to be a valid tag in the image. if you don't hand over a tag, it defaults to "latest" 💫
• --tag=tag — the destination tag to use for the newly created image. tag has to be a valid tag in the image. if you don't provide tag, it defaults to the tag you specified in --image — which means it's overwriting it 🙈
• --compress=compression-type — tell it what compression type to use when it's creating a new layer. the supported compression types are none, gzip, and zstd. and umoci-unpack(1) transparently supports all the compression methods you can specify with --compress, so she's flexible like that ✨ the special value auto makes umoci(1) auto-select the most appropriate compression algorithm based on what the previous layers are compressed with — it'll try to use the most recent layer's compression algorithm, as long as it supports it. but heads up: auto will never pick none compression on its own, because not compressing tar(1) archives is, and I quote, really not advisable 💀 if no compression-type is provided, it defaults to auto.
• --no-history — causes no history entry to be added for this operation. this is not recommended for use with umoci-raw-add-layer(1), because it results in the history not including all of the image layers — which will cause confusion with tools that look at image history. so like, don't, unless you know exactly why you're doing it 🫠
• --history.comment=comment — the comment for the history entry that corresponds to this modification of the image. if you leave it unspecified, umoci(1) will generate an implementation-dependent value for you.
• --history.created_by=created_by — the 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 — the 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 — the creation date for the history entry corresponding to this modification of the image. this has to be an ISO8601 formatted timestamp (see date(1)). if unspecified, the current time is used ⏰

---

🌈 EXAMPLE 🌈

the following takes an existing diff directory, creates a new archive from it, and then inserts it into an existing image. note that the new archive is not compressed — umoci will compress the archive for you, she's got it like that 💅

% tar cfC diff-layer.tar diff/ .
% umoci raw add-layer --image oci:foo diff-layer.tar

---

👑 SEE ALSO 👑

umoci(1), umoci-repack(1)

---

and that's the whole page, bestie 🎀 this one came from the umoci source, section raw, dated SEPTEMBER 2018, and it lives under the name umoci-raw-add-layer(1) — so if you ever need to find her again, that's the address. go forth and append layers, but like, carefully ✨🦋