Skip to content

bachorp/ocidd

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ocidd

ocidd is a program that fetches a raw (gzipped) blob from an OCI registry and writes it to some volume. This can help to simplify system installation and to avoid reliance on certain infrastructure (virtualization, storage network, ..) or specialized installers (Cloud-init, Kickstart, ..).

Bundled in an appropriate initial RAM-disk (initrd/initramfs), ocidd can be used, for example, for a fully automated installation of bare-metal hosts from a PXE. We provide prebuilt vmlinuz+initramfs (x86_64, arm64).

Usage

For automatic installation, the arguments dd.of, dd.bs, as well as either one of oci.tag and oci.blob must be supplied to ocidd. Missing parameters can be supplied interactively.

init will forward the kernel parameters as arguments to ocidd. For automatic network setup, the parameter ip (e.g. ip=dhcp) should be used (this is a kernel feature that is available in a default kernel build but is notably excluded from most Linux distributions).
If ocidd fails (e.g. due to missing network or an I/O error), init will launch an emergency shell. Otherwise, it will initiate a reboot.

Parameter Description Example
oci.tag OCI tag to fetch. There must be exactly one layer of media type application/octet-stream+gzip. Mutually exclusive with oci.blob. oci.tag=registry.example.com/repos/mydisk:v0
oci.blob OCI blob to fetch. Must be a gzip-compressed raw disk image. Mutually exclusive with oci.tag. oci.blob=registry.example.com/repos/mydisk@sha256:243786d4bef167ff79122d052ded386cbac007e71bdb9e15d6ffbf31b6dbe54d
oci.allow_no_tls If set, fetching manifests/blobs without TLS is allowed. Corresponds to oras' --plain-http.
dd.of Disk to write to. dd.of=/dev/sda
dd.bs Block size to during write. dd.bs=64k
wait If set, confirmation will be prompted before installing.

Building

The following compose services are provided:

  • initramfs for building a ram disk containing ocidd, an appropriate init script, as well as the required tools busybox, oras, and jq, and a CA-bundle taken from Alpine.
  • vmlinuz for building a linux kernel with the default configuration.
  • registry for running a simple OCI registry (without TLS) for testing purposes.

To ensure builds are reproducible, dates need to be provided for the kernel version/the mtime of files in the initramfs:

echo "KERNEL_BUILD_TIMESTAMP='$(date)'" > .env
echo "FS_MTIME='$(date -u -Iseconds)'" >> .env

Testing

See test.py for testing using QEMU.