Host configuration #

A host configuration is a collection of host-specific settings. Examples of such settings include static IP address, network prefix, and default gateway.

Settings #

The host configuration settings are encoded as key-value pairs in JSON format. Parsing of a key-value pair that is omitted or explicitly set to “null” is treated in the exact same way.

ospkg_pointer #

The format of the OS package pointer is determined by a separate trust policy configuration.

If trust_policy.ospkg_fetch_method is set to “network”, then the format is a comma-separated list of HTTP(S) URLs used for downloading an OS package descriptor. List these URLs in order of preference.

If trust_policy.ospkg_fetch_method is set to “initramfs”, then the format is a relative file name specifying where an OS package resides in the initramfs’s “/ospkg/” directory. For example, if the OS package archive and its descriptor are located at “/ospkg/ospkg.{zip,json}”, then “ospkg.json” would be a valid OS package pointer. Any suffix like “.json” and “.foo” will be correctly substituted.

network_mode #

There are two supported network modes: static IP address assignment and dynamic IP address assignment using the DHCP protocol. Specify “static” or “dhcp” to select between the two different network modes.

host_ip #

Static IP address and network prefix to be configured in CIDR notation. For example, “10.0.2.15/25” or “2001:db8::15/64”.

gateway #

IP address of the default gateway to configure in static network mode. For example, “10.0.2.1” or “2001:db8::1”.

dns #

A list of DNS server IP addresses to use for resolving domain names. List these DNS servers in order of preference. For example, ["10.0.2.2", "2001:db8::2"].

If this field is omitted, DNS resolution may not work.

network_interface #

A list of network interfaces that should be considered for configuration. Each network interface is identified by its interface name and MAC address. For example, [{"interface_name": "eth1", "mac_address": "bb:bb:bb:bb:bb:bb"}].

If bonding is enabled, the specified network interfaces should be bonded as a single logical interface. Otherwise a network interface should be selected, preferring the first network interface that is listed and considered to work.

If this field is omitted, implementers should fallback on a guessed network interface.

bonding_mode #

The following bonding mode values can be parsed:

• “balance-rr”
• “active-backup”
• “balance-xor”
• “broadcast”
• “802.3ad”
• “balance-tlb”
• “balance-alb”

It is up to implementers to determine which of these modes are supported.

bond_name #

Name of the logical interface to bond the specified interfaces into (arbitrary string).

Examples #

initramfs configuration #

{
    "ospkg_pointer": "ospkg.json",
    "network_mode": "dhcp"
}

DHCP network configuration #

{
    "ospkg_pointer": "https://example.org/ospkg.json",
    "network_mode": "dhcp",
    "dns": [
        "9.9.9.9",
    ],
    "network_interfaces": [
        {
            "interface_name": "eth0",
            "mac_address": "aa:aa:aa:aa:aa:aa",
        }
    ]
}

Static network configuration with bonding #

{
    "ospkg_pointer": "https://ospkg-01.example.org/ospkg.json,https://ospkg-02.example.org/ospkg.json",
    "network_mode": "static",
    "dns": [
        "9.9.9.9",
        "149.112.112.112",
    ],
    "network_interfaces": [
        {
            "interface_name": "eth1",
            "mac_address": "bb:bb:bb:bb:bb:bb",
        },
        {
            "interface_name": "eth2",
            "mac_address": "cc:cc:cc:cc:cc:cc",
        }
    ],
    "bonding_mode": "802.3ad",
    "bond_name": "bond0"
}