documentation/docs/User-Guide_Networking.md

Networking

Armbian uses Netplan.io to describe networking configurations. Netplan is a utility to easily configure Linux networking, using a declarative approach. If you want to configure your network manually, it is as simple as editing and creating Netplan yaml files (see the yaml configuration reference at the Netplan docs).

Netplan is used to configure networks on all Armbian images, no matter if minimal or desktop, Debian or Ubuntu. However, the networking backends are different based on if you choose a minimal image or not.

Minimal images (networkd)

Minimal images are using the systemd-networkd backend, which has a smaller footprint compared to Network-Manager. systemd-networkd is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service is great for simple connections, but can also be useful to set up complex network configurations.

Default Armbian configuration

By default, your device will run using DHCP on all ethernet interfaces to be able to automatically receive an IP address from your router.

/etc/netplan/10-dhcp-all-interfaces.yaml:

network:
  version: 2
  renderer: networkd
  ethernets:
    all-eth-interfaces:
      match:
        name: "*"
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes

Configuration examples

Setting a fixed IP address

The following example configures a static IP 192.168.1.199 for the eth0 interface. Please adjust the example to your likings.

Tip

Find out the name of your device's Ethernet interface with the command ip addr. It's usually something like eth0, enp4s3 or lan.

/etc/netplan/20-static-ip.yaml:

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0: # Change this to your ethernet interface
      addresses:
      - 192.168.1.199/24
      routes:
      - to: default
        via: 192.168.1.1
      nameservers:
       addresses:
         - 9.9.9.9
         - 1.1.1.1

See also the Netplan docs for reference.

Connecting to a wireless network

It is recommended to make a separate config file for wireless network.

Create the following file:

sudo nano /etc/netplan/30-wifis-dhcp.yaml:

network:
  version: 2
  renderer: networkd
  wifis:
    wlan0:
      dhcp4: true
      dhcp6: true
      access-points:
        "Your-SSID":
          password: "your-password"

Replace SSID with the name of the network you want to connect to and wlan0 with the wifi interface used on your system.

Tip

Find out the name of your device's WiFi interface with the command ip addr.

See also the Netplan docs for reference.

Applying your configuration

Once you are done configuring your network, it's time to test syntax and apply it.

1. Fix config file permissions

According to the Netplan docs, the permissions must be restricted to the root user.

sudo chmod 600 /etc/netplan/*.yaml

2. Test if the syntax is correct and if your device can still connect

sudo netplan try

3. Apply the configuration

sudo netplan apply

CLI and desktop images (Network-Manager)

Server CLI and desktop images are using the Network-Manager backend. You can use similar methods for configuring your network as with the networkd backend used on minimal images.

Setting a fixed IP address

The following example configures a static IP 192.168.1.199 for the eth0 interface. Please adjust the example to your likings.

Tip

Find out the name of your device's Ethernet interface with the command ip addr. It's usually something like eth0, enp4s3 or lan.

/etc/netplan/20-static-ip.yaml:

network:
  version: 2
  renderer: NetworkManager # Different than 'networkd'
  ethernets:
    eth0: # Change this to your ethernet interface
      addresses:
      - 192.168.1.199/24
      routes:
      - to: default
        via: 192.168.1.1
      nameservers:
       addresses:
         - 9.9.9.9
         - 1.1.1.1

See also the Netplan docs for reference.

Alternatively, you can also use Network-Manager directly via the command line or GUI tools on your desktop:

nmtui-edit eth0

Replace eth0 with the name of your Ethernet Interface.

Connecting to a wireless network

For connecting to a wireless network, you can use the same method as mention above for use with networkd on minimal images. Just make sure to replace renderer: networkd with renderer: NetworkManager.

Alternatively, you can also use Network-Manager directly via the command line or GUI tools on your desktop:

nmtui-connect SSID

Replace SSID with the name of your wireless network.

Automatic configuration on first boot

It is possible to network configurations which are automatically applied when you first boot your device after flashing a fresh image by writing to the file /root/.not_logged_in_yet which is read at your first login.

Mount your live image before your first boot and use this example for reference:

# Set PRESET_NET_CHANGE_DEFAULTS to 1 to apply any network related settings below.

PRESET_NET_CHANGE_DEFAULTS="1"

# Enable WiFi or Ethernet.
# NB: If both are enabled, WiFi will take priority and Ethernet will be disabled.

PRESET_NET_ETHERNET_ENABLED=1
PRESET_NET_WIFI_ENABLED=1

# Enter your WiFi credentials
# SECURITY WARNING: Your wifi keys will be stored in plaintext, no encryption.

PRESET_NET_WIFI_SSID='MySSID'
PRESET_NET_WIFI_KEY='MyWiFiKEY'

# Country code to properly adjust the WiFi for your country. 

# E.g. 'GB', 'US' or 'DE' (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
PRESET_NET_WIFI_COUNTRYCODE='GB'

# If you want to use a static IP, you may set it here

PRESET_NET_USE_STATIC=1
PRESET_NET_STATIC_IP='192.168.0.100'
PRESET_NET_STATIC_MASK='255.255.255.0'
PRESET_NET_STATIC_GATEWAY='192.168.0.1'
PRESET_NET_STATIC_DNS='9.9.9.9 1.1.1.1'

If you want to use first run automatic configuration at build time, check this GitHub pull request.

In short:

1. Copy the template with cp extensions/preset-firstrun.sh userpatches/extensions/
2. Edit the template userpatches/extensions/preset-firstrun.sh according to your situation
3. Build your Armbian image using the additional parameter ENABLE_EXTENSIONS=preset-firstrun

Note

This method also creates a new user, sets passwords and more!