By default, Incus connects instances to a NAT bridge named incusbr0: they get a private address and reach the internet through the host. This guide shows how to inspect that network, create others, expose a service with a proxy device, and above all how to fix the classic conflict with Docker that leaves containers without networking. Everything was tested on Incus 7.0. For anyone who wants control over instance connectivity.
What you will learn
- How the default network works (incusbr0, NAT).
- Inspect and create networks.
- Expose a service with a proxy device.
- Fix the network conflict with Docker (trap number one).
The default network: incusbr0
At initialisation, Incus creates a managed bridge called incusbr0 in NAT mode. Instances attach to it, receive a private address over DHCP, and reach the internet through the host.
incus network list+----------+----------+---------+-----------------+---------+---------+| NAME | TYPE | MANAGED | IPV4 | USED BY | STATE |+----------+----------+---------+-----------------+---------+---------+| incusbr0 | bridge | YES | 10.173.191.1/24 | 4 | CREATED || eth0 | physical | NO | | 0 | |+----------+----------+---------+-----------------+---------+---------+The detail (subnet, NAT, DNS) comes from incus network show:
incus network show incusbr0# ipv4.address: 10.173.191.1/24# ipv4.nat: "true"Creating a network
You isolate a group of instances on their own network with incus network create:
incus network create labnet ipv4.address=10.20.20.1/24 ipv4.nat=true# Network labnet createdYou then connect an instance to it through a nic device, or by editing its profile:
incus config device add c1 eth1 nic network=labnetExposing a service: the proxy device
An instance on incusbr0 is not reachable from outside the host. To publish a port, you add a proxy device that links a host port to an instance port:
incus config device add c1 web proxy \ listen=tcp:0.0.0.0:8888 connect=tcp:127.0.0.1:80web: connect: tcp:127.0.0.1:80 listen: tcp:0.0.0.0:8888 type: proxyThe instance service (here on port 80) becomes reachable on port 8888 of the host. That is the simplest method; to expose a whole instance on the physical network, put it on a bridged network instead (macvlan, or the host bridge).
Trap number one: the network conflict with Docker
This is the mistake that costs two hours. If Docker is installed on the same host as Incus, its containers lose networking.
An over-strict host firewall (firewalld, ufw) produces the same symptom: you then have to allow DHCP and DNS between incusbr0 and the host.
DNS: integrating with systemd-resolved
On a host using systemd-resolved, resolving instance names (.incus) can fail, because the Incus DNS server handles neither DNSSEC nor DNS-over-TLS. You tell resolved explicitly:
resolvectl dns incusbr0 10.173.191.1resolvectl domain incusbr0 '~incus'resolvectl dnssec incusbr0 offGoing further: OVN
For distributed networks across a multi-node cluster (virtual networks that follow instances from node to node, isolation per project), Incus relies on OVN. That is an advanced topic, reserved for clustered deployments: the incusbr0 bridge covers the vast majority of needs on a single host. See OVN in Incus when you get there.
Key points
- By default, instances sit on the
incusbr0NAT bridge (private address, internet through the host). incus network listandshowinspect;incus network createcreates an isolated network.- A proxy device (
listenandconnect) publishes an instance port on the host. - Trap number one: Docker forces
iptables FORWARD DROPand cuts Incus networking; fix it throughDOCKER-USER. - With systemd-resolved, declare the
incusbr0DNS server, and make it persistent.
FAQ: common questions about Incus networking
The default NAT bridge
incusbr0 is the managed network bridge created when Incus is initialised. It works in NAT:
- instances receive a private address over DHCP;
- they reach the internet through the host.
It is the default network of any instance. You inspect it with incus network show incusbr0 (subnet, NAT, DNS). It covers the vast majority of needs on a single host.
The proxy device
incus config device add c1 web proxy \
listen=tcp:0.0.0.0:8888 connect=tcp:127.0.0.1:80
The instance service (port 80) becomes reachable on port 8888 of the host. That is the simplest method.
To expose a whole instance on the physical network, with its own LAN address, put it on a bridged network or on macvlan instead.
Usually it is Docker
If an instance has an address but neither DNS nor internet, the usual culprit is Docker on the same host: its daemon forces iptables FORWARD DROP, which drops incusbr0 traffic.
The fix, without breaking Docker:
iptables -I DOCKER-USER -i incusbr0 -j ACCEPT
iptables -I DOCKER-USER -o incusbr0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
An over-strict firewall (firewalld or ufw) produces the same symptom.
incus network create
incus network create labnet ipv4.address=10.20.20.1/24 ipv4.nat=true
incus config device add c1 eth1 nic network=labnet
You create an isolated managed network, then connect an instance to it through a nic device, or through its profile.
Handy to compartmentalise groups of instances (front, back, database) onto separate subnets.
Next steps
- Profiles and projects: attach a network to a profile instead of declaring it instance by instance.
- OVN: VPCs and load balancers: the distributed networks a cluster makes possible.
- Remote access and UI: open the Incus API on the network rather than publishing each service through a proxy device.
- Securing Incus: restrict what instances can reach once the network is open.