system-json-reference.md

CuOS System Configuration Schema

Schema for configuring CuOS system parameters including networking, update sources, and image versions.

Properties

Name	Type	Description	Required
update_registry	string	URL of the registry used for system updates (e.g., https://update.example.com)
update_registry_proxy	string	URL of the registry proxy used for system updates
update_registry_user	string	Username for accessing the update registry
update_registry_password	string	Password for accessing the update registry
hostname	string	Fully Qualified Domain Name (FQDN) of the system
network	object[]	List of network interface configurations
docker_net_space	string	CIDR notation for Docker container network space (e.g., '10.235.240.0/20') Default: "10.235.240.0/20" Pattern: ^\d{1,3}(\.\d{1,3}){3}/\d{1,2}$
docker_net_space_size	number	Subnet size for Docker container networks (CIDR suffix) Default: 26 Minimum: 0 Maximum: 32
custom_ca_certs		Custom CA certificates to be trusted by the system
swap_size	number	Swap size in GB (will only be extended if enough disk space is available) Default: 8 Minimum: 0
image_size_mb	number	Size of the disk image the factory creates, in MB. Default: 1636, or 2048 for an MBR/FAT boot layout. Build-time only - the system grows the filesystem to the disk it finds on first boot Minimum: 1
init_image	string	CuOS Init App to start: the one container CuOS runs, and from which everything else is started. CuOS IaC is the default one, pinned by cuos-release's release.json Minimal Length: 1
init_image_version	string	Version of the CuOS Init App Minimal Length: 1
init_image_digest	string	Digest of the CuOS Init App for integrity check (optional)
updater_image	string	Image used for updating the system Minimal Length: 1
updater_image_version	string	Version of the updater image Minimal Length: 1
updater_image_digest	string	Digest of the updater image for integrity check (optional)
os_image	string	Operating system image Minimal Length: 1
os_image_version	string	Version of the operating system image Minimal Length: 1
os_image_digest	string	Digest of the OS image for integrity check (optional)
keyboard_model	string	Keyboard Model Pattern: ^[A-Za-z]+[0-9]+$
keyboard_layout	string	Keyboard Layout Pattern: ^[A-Za-z]{2}$
keyboard_variant	string	Keyboard Variant Pattern: ^[A-Za-z0-9_-]{1,32}$
os_root_password	string	Root Password for the operating system: local login or SSH - hash or password
os_root_authorized_keys	string[]	SSH public keys accepted for root login, written to /root/.ssh/authorized_keys on every boot. Key-based login works even without 'os_root_password'; without either, the root account is locked
os_ssh_server	boolean	Activate SSH server for the operating system, on port 4222
console_expert_password	string	Password for the expert menu of the console interface
console_password	string	Password for the console interface - hash or password
product_name	string	Product name shown in the boot menu and the installer, and used as the first part of the built artefact's file name (default: 'CuOS', or 'CuOS IaC' when the init image is a cuos-iac image)
system_name	string	Name of this particular system, used as the second part of the built artefact's file name (default: the hostname, else the configuration file or directory name)
platform	string	Target platform to build for, selecting the '_image' key and falling back to 'os_image' (e.g. 'x86_64', 'rpi-arm64', 'rpi-arm32', 'orangepi-zero3', 'lxc'). Overridden by 'tool.sh --platform'; defaults to the build host's architecture
boot_layout	string	Disk layout and boot chain to build: 'mbr' for an MBR disk with a FAT boot partition (Raspberry Pi, Orange Pi), 'gpt' for a GPT disk with BIOS and UEFI GRUB (PC-style firmware). Only needed for a platform the build tool does not know. Overridden by 'tool.sh --layout' Enum: "mbr", "gpt", "rpi", "grub"

Example

{
    "network": [
        {
            "dhcp": false
        }
    ],
    "docker_net_space": "10.235.240.0/20",
    "docker_net_space_size": 26,
    "swap_size": 8
}

 

network[]: array

List of network interface configurations

Items

Item Properties

Name	Type	Description	Required
name	string	Interface name for interface identification Pattern: ^e[0-9A-Za-z]+$
mac-address	string	MAC address for interface identification Pattern: ^(?:[0-9A-Fa-f]{2}[-:](?:[0-9A-Fa-f]{2}[-:]){4}[0-9A-Fa-f]{2}|[0-9A-Fa-f]{12})$
dhcp	boolean	Enable DHCP for this interface Default: false
ip-address	string	Static IPv4 address (required if DHCP is false) Pattern: ^\d{1,3}(\.\d{1,3}){3}$
network-mask	string	IPv4 subnet mask (required if DHCP is false) Pattern: ^\d{1,3}(\.\d{1,3}){3}$
gateway	string	IPv4 gateway address Pattern: ^\d{1,3}(\.\d{1,3}){3}$
dns-server		DNS server(s) for this interface
ntp-server		NTP server(s) for time synchronization
routes		Static routes for this interface. Can be a single object or an array of objects.

Example

[
    {
        "dhcp": false
    }
]

 

os_root_authorized_keys[]: array

SSH public keys accepted for root login, written to /root/.ssh/authorized_keys on every boot. Key-based login works even without 'os_root_password'; without either, the root account is locked

Items

Item Type: string 

---

This page is generated from system/cuos/system-schema.json, the schema CuOS validates system.json against at boot. Edit the schema, then run npm run docs:system-json.