umoci-unpack(1)(#)

✨ umoci-unpack ✨

okay so bestie, welcome to umoci-unpack, section 1 of the umoci manual 💖. this one's by Aleksa Sarai, dated SEPTEMBER 2018, and it's literally the page that unpacks your OCI image into a runtime bundle. strap in 🎀

---

🌸 NAME 🌸

umoci unpack — unpacks an OCI image tag into a runtime bundle. no cap, that's the whole job 💅

---

🦋 SYNOPSIS 🦋

umoci unpack --image=image[:tag] [--rootless] [--uid-map=value] [--uid-map=value] [--keep-dirlinks] bundle

(yes, --uid-map=value really does show up twice in there. i don't make the rules, i just relay them 🙈)

---

👑 DESCRIPTION 👑

so what it actually does: it extracts all of the layers — deterministically, bestie, meaning the same input gives you the same output every time ✨ — into an OCI runtime bundle at the path bundle. and while it's at it, it also generates an OCI runtime configuration that corresponds to the image's configuration, so your container actually knows what it is 💖

and there's more!! an mtree(8) specification gets generated at the time of unpacking, which is the whole reason umoci-repack(1) can generate filesystem deltas later on — and that is what lets you create layered OCI images 🧚 it's giving ecosystem, it's giving teamwork, i'm obsessed 🌈

---

💅 OPTIONS 💅

the global options are defined in umoci(1), go check those out too 🫶

• --image=image[:tag] — the OCI image tag that's gonna get extracted into the bundle. image must be a path to a valid OCI image, and tag must be a valid tag in that image. if you don't hand over a tag, it defaults to "latest". so generous of it ⭐
• --rootless — turns on rootless unpacking support, which means umoci-unpack(1) and umoci-repack(1) can both be used as an unprivileged user 🎀 using this flag implies --uid-map=0:$(id -u):1 and --gid-map=0:$(id -g):1, and it also enables several features that fake parts of the unpacking in an attempt to generate an as-close-as-possible extraction of the filesystem.

lowkey important: it is almost always not possible to perfectly extract an OCI image with --rootless. but bestie, it will be as close as possible, and that's the vibe 😭💜

• --uid-map=value — specifies a UID mapping to use while unpacking (and repacking) layers. this works in a similar fashion to user_namespaces(7), and it's of the form container:host[:size].
• --gid-map=value — specifies a GID mapping to use while unpacking (and repacking) layers. same deal, used in a similar fashion to user_namespaces(7), and it's of the form container:host[:size].
• --keep-dirlinks — instead of overwriting directories which are links to other directories when higher layers have an explicit directory, it just writes through the symlink 🌸 this option is inspired by rsync's option of the same name. iconic crossover, honestly 👑

---

🌈 EXAMPLE 🌈

the following downloads an image from a docker(1) registry using skopeo(1), unpacks said image, and then creates a new container using the extracted OCI runtime bundle with runc(8). then the image gets repacked with umoci-repack(1) ✨

% skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
# umoci unpack --image image bundle
# runc run -b bundle ctr
[ container session ]
# umoci repack --image image bundle

and with --rootless you can do all of the above without root privileges 🫶 umoci will generate a configuration that works with rootless containers in runc(8). main character energy, fr fr 💅

% skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
% umoci unpack --image image --rootless bundle
% runc --root $HOME/runc run -b bundle ctr
[ rootless container session ]
% umoci repack --image image --rootless bundle

---

🍓 SEE ALSO 🍓

umoci(1), umoci-repack(1), runc(8)

---

and that's the page, bestie 💖 it's unpack, it lives in the umoci manual, it's umoci-unpack(1)(#) — written by Aleksa Sarai back in September 2018, still slaying to this day 👑✨