Skip to content
All posts
2 min readtebakopackagingtutorial

Advanced payloads: The image toolbox (3 of 5)

The advanced payloads series: the image toolbox.

The Tebako team

github.com/tamatebako
Note

Post 3 of 5 in the series Advanced payloads.

○ ○ ● ○ ○

  1. Advanced payloads: Trace: see what your payload touches

  2. Advanced payloads: Jails and profiles: decide what it may touch

  3. Advanced payloads: The image toolbox (this post)

  4. Advanced payloads: Runtimes and native code

  5. Advanced payloads: packed-mn: one download, any document

Payloads are files, and files have formats. This post’s subject is the image toolbox: the file formats a payload can take, and the mount machinery — multiple images and stacked mounts — that turns them into one filesystem for a process.

The image toolbox one payload — your choice of file format limnifs the default write format dwarfs high-density read format zip the ubiquitous one auto detected by magic bytes multi-mount several images, one process, each at its declared path stacked mounts base image / overlay at /opt/tool a writable seal on top

Figure 1 — Formats choose how the bytes are stored; multi-mount brings several images into one process; stacked mounts layer them, longest prefix wins.

The formats

  • LimniFS — the default write format. It balances density and mount speed, and tfs mkimage writes it unless another format is named.

  • DwarFS — the high-density read format. It suits large, rarely changing payloads where size matters most.

  • Zip — the widely supported format. It is slightly larger, mounts anywhere, and opens with ordinary tools when tebako is not present.

A payload names its format in its manifest, and readers detect it from the file’s magic bytes, so no reader configuration is ever needed. What a payload is never depends on the format: the format answers exactly one question, namely how to read these bytes.

Multi-mount

A process mounts as many images as its composition declares, each at its own path — the application at /, the fonts at /usr/share/fonts/acme, a toolkit at /opt/inkscape. Mounts nest, and dispatch is by longest prefix, so a mounted toolkit can itself contain mounted images.

Stacked mounts

Any mount can carry an overlay — a writable seal declared at press time. Reads fall through to the base image; writes land in the seal and vanish when the process exits, unless the seal is committed. That is how a read-only payload supports a workload that must write, without ever mutating the base bytes.

The verbs

Everything is inspectable with the tfs commands introduced in the basics: info, ls, cat, extract — plus mkimage to create, exec to run a program inside an image, needs to draft policy from a journal, and mount to mount an image by hand.

What you can do now

This post has chosen formats for what each does well, brought many images into one process, and placed writable work on a declared seal. The next post is about what runs inside: runtimes and native code.

Note

Continue with part 4 of 5: Runtimes and native code.