Configuration

An ArkOS image is configured through a directory in the ark/arkos/configs subdirectory.

An example configuration is provided for generic, which provides a kernel that should work for most x86/64 systems.

This document breaks down some of the configuration elements.

Architecture

This block controls the architecture the rootfs and initramfs are built for:

config:
  arch:
    arch: "arm64"
    cross_compile_prefix: "aarch64-linux-gnu-"

In this example, we build for aarch64. The two parameters are:

  • arch - The “architecture” you build for (typically in kernel/debian speak, such as amd64 or arm64).
  • cross-compile_prefix - The prefix to apply when compiling code, can leave empty to use host compiler.

Kernel

This block controls the kernel build process. It’s fairly simple:

config:
  kernel:
    url: "https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.15.32.tar.xz"
    patches:
      - "https://cdn.kernel.org/pub/linux/kernel/projects/rt/5.15/patch-5.15.32-rt39.patch.gz"

This instructs the system to use the 5.15.32 version of the kernel, and apply the rt patches for that kernel. Any number of patches can be provided. The kernel is build with olddefconfig based on the kernel-config file in your configuration directory.

Disk

This block controls how the disk image is built:

config:
  disk:
    disk_size_mb: 640
    arkos_image_size_mb: 384
    boot_mode: "uefi"
    refind_url: "https://sourceforge.net/projects/refind/files/0.13.3.1/refind_0.13.3.1-1_amd64.deb"
    ext2_driver_url: "https://github.com/pbatard/efifs/releases/download/v1.8/ext2_x64.efi"

This creates a 640MB disk image, with a 384MB arkos-image partition. It also instructs the system to be a UEFI system.

Some other variables:

  • disk_size_mb - The size of the disk, in megabytes.
  • arkos_image_size_mb - The size of the arkos-image partition, in megabytes
  • boot_mode - Can be uefi or bios, affects partition layout and bootloader
  • refind_url - In UEFI mode, downloads this version of UEFI
  • efi_driver_urls - In UEFI mode, downloads these drivers to use (such as filesystem drivers)

Note that depending on mode (BIOS or UEFI), the refind.conf or extlinux.conf file in your configuration will be copied to the arkos-image partition.

Signature

This section has a single element, the key_name. This should be the name of the key as it exists in your instance of catalog (for example, arkos_bench/release).

Distribution

This builds the rootfs, and is the most complex section. There are a few top-level parameters:

  • name - The distribution name (ie, focal, jammy).
  • variant - The variant to use, you almost always want to use minbase
  • components - The apt repositories to include. You’ll always want at least main
  • hostname - Hostname for your machine
  • packages - List of packages to be automatically installed via apt-get
  • in-root-scripts - List of scripts to copy from your config to the rootfs and run within the chroot

There’s a few other blocks as well. The users list is a list of users. Each user entry consists of a username, password, uid, gid, and list of groups (such as sudo) that user should belong to.

There’s a groups list as well, which consists of a groupname field and a gid.

The keys list contains a list of public keys you want to include in the image. This is necessary to determine if software is signed appropriately or not.

Finally, there’s a systemd-services block, which allows you mark which services you wish to have enabled or disabled.

See the ark/arkos/configs/generic/base.yml for a more complete example.