Network

IncusOS supports complex network configurations consisting of interfaces, bonds, and VLANs. By default, IncusOS will configure each discovered interface to automatically acquire IPv4/IPv6 addresses, DNS, and NTP information from the local network. More complex network setups can be configured via an install seed, or post-install via the network API.

Before applying any new/updated network configuration, basic validation checks are performed. If this check fails, or the network fails to come up properly as reported by systemd-networkd, the changes will be reverted to minimize the chance of accidentally knocking the IncusOS system offline.

Be aware that changing network configuration may result in a brief period of time when the system is unreachable over the network.

Configuration options

Interfaces, bonds, and VLANs have a significant number of fields, which are largely self-descriptive and can be viewed in the API definition.

One special feature of note is the handling of hardware addresses (MACs). Both interfaces and bonds associate their configuration with the hardware address, which can be specified in two ways:

• Raw MAC: Specify the hardware address directly, such as 10:66:6a:e5:6a:1c.

• Interface name: If an interface name is provided, such as enp5s0, at startup IncusOS will attempt to get its MAC address and substitute that value in the configuration. This is useful when installing IncusOS across multiple physically identical servers with only a single install seed.

The following configuration options can be set:

• interfaces: Zero or more interfaces that should be configured for the system.

• bonds: Zero or more bonds that should be configured for the system.

• vlans: Zero or more VLANs that should be configured for the system.

• dns: Optionally, configure custom DNS information for the system.

• ntp: Optionally, configure custom NTP server(s) for the system.

• proxy: Optionally, configure a proxy for the system.

Examples

Configure two network interfaces, one with IPv4 and the other with IPv6:

{
    "interfaces": [
        {"name": "ip4iface",
         "hwaddr": "enp5s0",
         "addresses": ["dhcp4"]},
        {"name": "ip6iface",
         "hwaddr": "enp6s0",
         "addresses": ["slaac"]}
    ]
}

Configure a VLAN with ID 123 on top of an active-backup bond composed of two interfaces with MTU of 9000 and LLDP enabled:

{
    "bonds": [
        {"name:", "management",
         "mode": "active-backup",
         "mtu": 9000,
         "lldp": true,
         "members": ["enp5s0", "enp6s0"],
         "roles": ["management", "interfaces"]
        }
    ],
    "vlans": [
        {"name": "uplink",
         "parent": "management",
         "id": 123,
         "addresses": ["dhcp4", "slaac"]
        }
    ]
}

Configure custom DNS and NTP for IncusOS:

{
    "dns": {
        "hostname": "server01",
        "domain": "example.com",
        "search_domains": ["example.com", "example.org"],
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    "ntp": {
        "timeservers": ["ntp.example.com"]
    }
}