# Network

Home Assistant Operating System uses NetworkManager to control the host network.

## Configure network

Only a manual configuration using NetworkManager connection files is supported. Without a configuration file, the device will use DHCP by default. These network connection files can be placed on a USB drive and imported to the host as described in [Configuration][configuration-usb].

## Configuration examples

You can read the [NetworkManager manual][nm-manual] or find many configuration examples across the internet. Keep in mind that the system is read-only. If you don't want the IP address to change on every boot, you should modify the UUID property to a generic [UUID4][uuid]. Inside the `\CONFIG\network\` directory on the USB drive or SD card, create a file called `my-network` and add the appropriate contents below:

**NOTE: Please make sure to save this file with UNIX line endings (LF, and not Windows' default CRLF endings). You can do this using Notepad these days!**

### Default

A preinstalled connection profile is provided by default:

```ini
[connection]
id=my-network
uuid=f62bf7c2-e565-49ff-bbfc-a4cf791e6add
type=802-3-ethernet

[ipv4]
method=auto

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

### Wired connection to the LAN

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

[ipv4]
method=auto

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

### Wireless LAN WPA/PSK

```ini
[connection]
id=my-network
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
type=802-11-wireless

[802-11-wireless]
mode=infrastructure
ssid=MY_SSID
# Uncomment below if your SSID is not broadcasted
#hidden=true

[802-11-wireless-security]
auth-alg=open
key-mgmt=wpa-psk
psk=MY_WLAN_SECRET_KEY

[ipv4]
method=auto

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

### Static IP

Replace the following configuration:

```ini
[ipv4]
method=manual
address=192.168.1.111/24;192.168.1.1
dns=8.8.8.8;8.8.4.4;
```

For `address`, the value before the semicolon is the IP address and subnet prefix bitlength. The second value (after the semicolon) is the IP address of the local gateway.

## Tips

### Reset network

If you want to reset the network configuration back to the default DHCP settings, use the following commands on the host:

```bash
# rm /etc/NetworkManager/system-connections/*
# cp /usr/share/system-connections/* /etc/NetworkManager/system-connections/
# nmcli con reload
```

### Powersave

If you have trouble with powersave then apply the following changes:

```ini
[wifi]
# Values are 0 (use default), 1 (ignore/don't touch), 2 (disable) or 3 (enable).
powersave=0
```

## Using `nmcli` to set a static IPv4 address

Log into the the HassOS base system via a console:

```bash
Welcome to Home Assistant
homeassistant login:
```

- Login as `root` (no password needed). At the `ha >` prompt, type `login` (as instructed).

From there you use the `nmcli` configuration tool.

- `# nmcli con show` will list the "HassOS default" connection in use.
- `# nmcli con show "HassOS default"` will list all the properties of the connection.

To start editing the configuration setting for "HassOS default":

```bash
# nmcli con edit "HassOS default"
```

To add your static IP address (select 'yes' for manual method);

```bash
nmcli> set ipv4.addresses 192.168.100.10/24
Do you also want to set 'ipv4.method' to 'manual'? [yes]:
```

In addition, it's recommended to set the DNS server and the local gateway. For most home routers the DNS server will have the same IP address as the router itself. If you are using Pi-Hole or a third-party DNS system then you can set the DNS server to that.

```bash
nmcli> set ipv4.dns 192.168.100.1
nmcli> set ipv4.gateway 192.168.100.1
```

`nmcli> print ipv4` will show you the IPv4 properties of this connection. With `nmcli> save` you will save the changes afterwards.

If you now view the default connection `cat /etc/NetworkManager/system-connections/default` you should see the method is manual and the address is set.

Doing a `nmcli con reload` does not always work, so restart the virtual machine or the physical system.

[nm-manual]: https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html
[configuration-usb]: configuration.md
[uuid]: https://www.uuidgenerator.net/