Configure networking

Home Assistant OS uses NetworkManager for the host network. Out of the box there is no connection profile at all: NetworkManager connects wired interfaces automatically, with DHCP for IPv4 and automatic configuration for IPv6.

1. The UI: under Settings > System > Network. Most users never need anything else.
2. The CLI: ha network covers what the UI does, and more, like VLANs.
3. NetworkManager directly: connection files on a CONFIG USB drive, or nmcli on the host. For anything the first two do not support.

When you change a setting through the UI or the CLI, the Supervisor updates the active connection profile of that interface. If there is none, it creates one named Supervisor <interface>, like Supervisor eth0. So a profile you wrote yourself can be changed later by a user in the UI.

ha network info lists the interfaces. default is a shortcut for the primary interface. To go back to DHCP on it:

ha network update default --ipv4-method auto

A static IPv4 address:

ha network update eth0 --ipv4-method static \
  --ipv4-address 192.168.1.10/24 --ipv4-gateway 192.168.1.1 \
  --ipv4-nameserver 192.168.1.1

Wi-Fi works too, on boards that have it. A wired connection is more reliable, so recommend that where you can:

ha network update wlan0 --ipv4-method auto \
  --wifi-mode infrastructure --wifi-ssid "My network" \
  --wifi-auth wpa-psk --wifi-psk "My password"

Run ha network update --help for every option.

NetworkManager reads connection profiles in its keyfile format from /etc/NetworkManager/system-connections, which is persistent. You can put files there on the host shell, or ship them in the network/ folder of a CONFIG USB drive. The drive replaces all existing connections with its own.

Only connection files are supported. Changes to NetworkManager.conf itself are not, it is part of the read-only image. The NetworkManager settings reference documents every option.

Give each connection its own UUID, generated once, like with uuidgen. Without a fixed UUID, the connection changes identity, and can get a different address after every boot. Save files with Unix line endings (LF).

[connection]
id=my-network
uuid=d55162b4-6152-4310-9312-8f4c54d86afa
type=ethernet

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Replace the [ipv4] section:

[ipv4]
method=manual
address1=192.168.1.111/24,192.168.1.1
dns=192.168.1.1;

address1 is the address with its prefix length, then the gateway.

[connection]
id=my-wifi
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
type=wifi

[wifi]
mode=infrastructure
ssid=MY_SSID
# Uncomment when the network does not broadcast its name
# hidden=true

[wifi-security]
auth-alg=open
key-mgmt=wpa-psk
psk=MY_PASSWORD

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Home Assistant OS turns Wi-Fi power saving off by default. To turn it on for one connection, add powersave=3 to its [wifi] section.

On the host shell, nmcli gives you all of NetworkManager. nmcli con show lists the profiles. For example, to set a static address on a profile named Supervisor eth0:

nmcli con mod "Supervisor eth0" ipv4.method manual \
  ipv4.addresses 192.168.1.10/24 ipv4.gateway 192.168.1.1 \
  ipv4.dns 192.168.1.1
nmcli con up "Supervisor eth0"

If there is no profile yet, create one with nmcli con add, or set the interface once through the CLI first.

To throw away every connection profile and go back to the defaults, remove them on the host shell and reboot:

rm -r /mnt/overlay/etc/NetworkManager/system-connections/*
reboot

Most of these come from NetworkManager.conf in the image:

• mDNS and LLMNR are on for every connection, so the system answers to homeassistant.local.
• NetworkManager checks connectivity every 10 minutes, against checkonline.home-assistant.io.
• Docker's bridges and virtual interfaces are not managed by NetworkManager.
• Time servers that a DHCP server announces are passed on to systemd-timesyncd, by the NetworkManager dispatcher script 10-ntp.