# Network Manager

Setup the base NetworkManager config/networking. This will help with making the Internet side of networking more dynamic and responsive to devices being added/removed.

## Connection Priority

We assume LAN/Ethernet > WiFi > 3G/LTE for WAN connection priority. This is the standard priority order that NetworkManager uses internally.

If you plug the internet into the LAN/Ethernet port of your Lollipop it will take priority over a WiFi adapter configured for internet which will take priority over a 3G/LTE USB modem configured for internet.

## Configuration Files

The main configuration files for NetworkManager exist in ```/etc/NetworkManager```. It is *NOT* recommended to edit these files directly. Usually editing the files directly will result in broken networking.

## Device Naming

NetworkManager uses the underlying Linux device naming conventions. To put it bluntly: it's a mess.

You'll see a number of devices when running ```nmcli dev show``` and it may not be obvious which devices are which. Some tricks for helping identify network devices are below.

- ```eth#``` is an on-board, internal ethernet device (the networking jack kind)
- ```wlan#``` is an on-board, internal WiFi device
- ```w######``` is a USB or external WiFi device. It'll usually start with ```w``` and have a lot of other "junk" after it
- ```gsm#``` is a USB cellular modem. These normally only show after ModemManager has been setup and has activated a cellular modem.

## ProTip / Initial Setup

The ```nmtui``` command can be used for an ncurses graphical interface for NetworkManager. This is particularly handy if you want to setup a quick WiFi access point for initial configuration.

## Helpful NetworkManager Commands

The below will outline some useful NetworkManager commands that can be used to help with setup and configuration of a Lollipop's network.

### Get Status

Some commands that help getting the status of NetworkManager

- ```nmcli networking connectivity```
- ```nmcli monitor```
- ```nmcli device monitor```
- ```nmcli connection monitor```

### Enable / Disable ALL

Handy if you want to shut down *all* networking for some reason

```nmcli networking on|off```

### Radio Control

Control WiFi / GSM radios

#### Wifi

```nmcli radio wifi [on|off]```

#### 3G/LTE

```nmcli radio wwan [on|off]```

### Connection / Device Related

Some useful commands for adjusting connection/device status

- Reload changes: ```nmcli connection reload```
- Show active connections: ```nmcli connection show --active```
- Show all connections: ```nmcli connection show```
  - This will have an ```id``` column that can be used in the below commands
- Enable a connection: ```nmcli connection up [id]```
- Disable a connection: ```nmcli connection down [id]```
- See the status of a networking device (WiFi adapter for example): ```nmcli device status```
- See the information about a networking device: ```nmcli device show [ifname]```
- Add a new connection: ```nmcli connection add ...```. See below for some examples on how to use this command.
- Modify a connection: ```nmcli connection modify ...```. The name and setings you'd like to apply will come afer the ```modify``` portion of the command.
  - See [this website (link)](https://www.tecmint.com/configure-network-connections-using-nmcli-tool-in-linux/) for some examples and more information.

### Inspiration / Further Reading

- [https://developer.gnome.org/NetworkManager/stable/NetworkManager.html](https://developer.gnome.org/NetworkManager/stable/NetworkManager.html)
- [https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html)
- [https://developer.gnome.org/NetworkManager/stable/nmcli.html](https://developer.gnome.org/NetworkManager/stable/nmcli.html)
- [https://developer.gnome.org/NetworkManager/stable/nmcli-examples.html](https://developer.gnome.org/NetworkManager/stable/nmcli-examples.html)

## Install / Enable Network Manager

``` bash

apt update
apt install network-manager \
    network-manager-openvpn network-manager-pptp \
    ebtables ipset dnsmasq-base
# Enable the service
systemctl enable NetworkManager
# Start the service
systemctl start NetworkManager

```

## Disable Non NetworkManager Networking

By default Armbian sets up at least one network device "behind the scenes" and keeps it "outside" NetworkManager. Given we want to manage our Lollipop through NetworkManager, we need to make a small tweak.

Edit ```/etc/network/interfaces``` and make sure eth0 directives aren't present. Also make sure the ```/etc/network/interfaces.d``` directory is empty.

Reboot after above cleanup of interfaces file.

## Set Hostname

``` bash

nmcli general hostname [hostname] # Additional parm sets hostname
systemctl reboot # Reboot to pickup the change

```

## Disable Orange Pi Zero Internal WiFi

If you're using an Orange Pi Zero, the internal WiFi adapter is unstable at best. The following will disable the adapter.

*Note: this ONLY applies to the Orange Pi Zero (not the ```Plus``` or ```2``` models)*

``` bash

nmcli device status # Verify the internal WiFi is shwoing as wlan0
nmcli device disconnect wlan0 # Run this if it shows as connected
nmcli device set wlan0 autoconnect no

```

## Setup Networking

Some configuration via ```nmcli``` for various networks/interfaces/devices that may or may not be in use at any given moment. These commands just make NetworkManager aware of the overall topology and connections. Routing, firewall and more is setup later.

*Note: Add autoconnect false if you don't want the connection auto started if a device is present*

### Clear Existing

Run ```nmcli connection show``` to get a list of active network connections. We will want to remove all of these.

Run ```nmcli connection del [UUID]``` for each UUID listed in the previous commands output.

### WiFi 2.4ghz Access Point

This setup will configure the Lollipop's internal WiFi adapter as an access point. NetworkManager assumes you'll have only *one* Access Point active per device at a time. If you'd prefer your wireless access point use 5ghz AND your hardware is capable of 5ghz, skip this step. *Example: the OrangePi PC Plus must be configured as a 2.4ghz access point, unless you are configuring an upgraded or external adapter capable of 5ghz.*

2.4ghz is a good choice and a default for most commerical access points for compatibility with WiFi clients. This is recommended if you're not sure.

*Note: You can use ```802-11-wireless.channel #``` in the below command to force a channel to be used*

``` bash

# Get the ifname of the wifi adapter with `nmcli dev show`

# HostAP mode (2.4ghz / wireless access point)
#     includes network sharing
nmcli connection add save yes \
    type wifi \
    con-name wifi-ap-24 \
    ifname [wifi iface] \
    ssid 24.lolipop.domain.tld \
    -- \
    ipv4.method shared \
    ipv4.addresses 172.17.17.17/24 \
    ipv6.method ignore \
    802-11-wireless.mode ap \
    802-11-wireless.band bg \
    802-11-wireless.channel 11 \
    802-11-wireless-security.key-mgmt wpa-psk \
    802-11-wireless-security.proto rsn \
    802-11-wireless-security.psk MyPassword

```

### WiFi 5ghz Access Point

This setup will configure the Lollipop's internal WiFi adapter as an access point. NetworkManager assumes you'll have only *one* Access Point active per device at a time. This section assumes you'd prefer to use 5ghz for WiFi.

5ghz is a good choice if you want more reliable and faster WiFi *IF* your clients support 5ghz. This is *not* recommended if you're not sure.

*Note: You can use ```802-11-wireless.channel #``` in the below command to force a channel to be used*

``` bash

# Get the ifname of the wifi adapter with `nmcli dev show`

# HostAP mode (5ghz / wireless access point)
#     includes network sharing
nmcli connection add save yes \
    type wifi \
    con-name wifi-ap-50 \
    ifname [wifi iface] \
    ssid 50.lolipop.domain.tld \
    -- \
    ipv4.method shared \
    ipv4.addresses 172.18.18.18/24 \
    ipv6.method ignore \
    802-11-wireless.mode ap \
    802-11-wireless.band a \
    802-11-wireless.channel 40 \
    802-11-wireless-security.key-mgmt wpa-psk \
    802-11-wireless-security.proto rsn \
    802-11-wireless-security.psk MyPassword

```

### WAN - WiFi Bridge

This will configure a WiFi adapter in client mode to provide internet to a Lollipop.

``` bash

# Get list of access points in the area
nmcli dev wifi list

# Get the ifname of the client wifi adapter with `nmcli dev show`

# WAN via Client mode (wireless bridge)
#    Note the ASK flag so you're prompted to enter user/pass type infos
nmcli connection add save yes \
    type wifi \
    con-name wan-wifi \
    ifname [wifi iface] \
    ssid [ssidFromAbove] \
    -- \
    wifi-sec.key-mgmt wpa-psk \
    wifi-sec.psk [wpaPassword]
nmcli device set [wifi iface] autoconnect yes

```

### WAN - Ethernet (External USB Adapter)

We recommend using a USB Ethernet adapter for the internet connection of a Lollipop. That said: if you do *not* have access to a USB ethernet adapter, you can substitute ```eth0``` (or equivalent for your board) in the below to configure the internal / on-board ethernet as an internet connection.

*Note: It's assumed you'll be using a USB Ethernet adapter for WAN if needed. This matches the overall use of USB devices that are plugged/unplugged as necessary for WAN needs*

``` bash

# WAN via ethernet cable
nmcli connection add save yes \
    type ethernet \
    con-name wan-eth \
    ifname eth1 \
    -- \
    ipv4.method auto \
    ipv6.method auto
nmcli device set eth1 autoconnect yes

```

### Management Ethernet

This is a wholly optional step. This sets up the internal ethernet adapter to be an *INTERNAL, NON-INETERNET* device. The setup will allow you to use a switch to share internet with other devices on a local network.

If you do not have a USB ethernet device, do *NOT* run this configuration step. Instead, configure your on-board adapter (see above) for internet.

*Note: It's assumed the on-board ethernet adapter will be used for management and an EXTERNAL USB Ethernet adapter used for WAN (if needed)*

``` bash

# Management via usb ethernet adapter
#     includes network sharing
nmcli connection add save yes \
    type ethernet \
    con-name mgmt \
    ifname eth0 \
    -- \
    ipv4.method shared \
    ipv4.addr 172.16.16.16/24 \
    ipv6.method ignore
nmcli device set eth0 autoconnect yes

```

### WAN - GSM (3G/LTE)

See [Modem Manager](modem_manager.md) for details on integrating a 3G/LTE modem into the networking setup.

## Auto Config

Once the above is setup Network Manager should handle the auto configuration of your WAN/LAN/Modems/etc for you.

## Real World Uses and Troubleshooting

If you're using your Lollipop as a router and have a collection of preferred networks, at the command line (and/or using Cockpit), to switch access points on the fly:

```nmcli con down wan-wifi-connection-name
nmcli con up wan-wifi-connection-name```

If you receive an error message like ```Warning: password for '802-11-wireless-security.psk' not given in 'passwd-file' and nmcli cannot ask without '--ask' option. Error: Connection activation failed.``` the workaround is to include --ask in your nmcli con up command:

```nmcli --ask con up wan-wifi-name```

If you receive the following error with a WiFi network/access point you may have to delete and re-create the connection. We haven't found a reliable fix for this particular warning/error.

```Warning: password for ‘802-11-wireless-security.psk’ not given in ‘passwd-file’ and nmcli cannot ask without ‘--ask’ option. Error: Connection activation failed.```