How to add a routed NIC device to a virtual machine - Incus documentation
Description: When adding a routed NIC device to an instance, you must configure the instance to use the link-local gateway IPs as default routes. For containers, this is configured for you automatically. For vi...

Skip to content
Back to top
View this page

# How to add a routed NIC device to a virtual machine

When adding a routed NIC device to an instance, you must configure the instance to use the link-local gateway IPs as default routes. For containers, this is configured for you automatically. For virtual machines, the gateways must be configured manually or via a mechanism like `cloud-init`.

To configure the gateways with `cloud-init`, firstly initialize an instance:

    incus init images:debian/12 bookworm --vm

Then add the routed NIC device:

    incus config device add bookworm eth0 nic nictype=routed parent=my-parent-network ipv4.address=192.0.2.2 ipv6.address=2001:db8::2

In this command, `my-parent-network` is your parent network, and the IPv4 and IPv6 addresses are within the subnet of the parent.

Next we will add some `netplan` configuration to the instance using the `cloud-init.network-config` configuration key:

    cat <<EOF | incus config set bookworm cloud-init.network-config -
    network:
      version: 2
      ethernets:
        enp5s0:
          routes:
          - to: default
            via: 169.254.0.1
            on-link: true
          - to: default
            via: fe80::1
            on-link: true
          addresses:
          - 192.0.2.2/32
          - 2001:db8::2/128
    EOF

This `netplan` configuration adds the static link-local next-hop addresses (`169.254.0.1` and `fe80::1`) that are required. For each of these routes we set `on-link` to `true`, which specifies that the route is directly connected to the interface. We also add the addresses that we configured in our routed NIC device. For more information on `netplan`, see their documentation.

Note

This `netplan` configuration does not include a name server. To enable DNS within the instance, you must set a valid DNS IP address. If there is a `incusbr0` network on the host, the name server can be set to that IP instead.

You can then start your instance with:

    incus start bookworm

Note

Before you start your instance, make sure that you have configured the parent network to enable proxy ARP/NDP.