Automatic first boot configuration

Reading presets from local config

It is possible to configure your device automatically at first boot. Settings like: root password, IP address, connecting to wireless.

After flashing an image to boot media, mount it and add a file containing your config to /root/.not_logged_in_yet

Tip

You may also mount the image and edit it prior to flashing, if this is preferable.

Loading a remote config

It is also possible to load this config file from a remote server, as above, however the only directive you should include is:

PRESET_CONFIGURATION="http://path/to/config/file"

Configuration directives

• The directives in this file are specified using key="value" format.
• The presets are applied at first boot by the root autologin on the console, so a headless board configures itself without anyone logging in.
• Once the file sets PRESET_ROOT_PASSWORD or PRESET_USER_NAME, first login runs unattended: a question whose directive is unset takes its default instead of waiting for an answer (see the table). Only the account details themselves (user name, passwords, real name) are still asked for if missing, so for a fully-unattended setup specify at least PRESET_ROOT_PASSWORD, PRESET_USER_NAME, PRESET_USER_PASSWORD and PRESET_DEFAULT_REALNAME.
• Without either of those two, first login is interactive: leave a directive unset or comment it out to be asked for it.
• Armbian Imager writes this file for you from its first-boot settings.

Caution

No validation of this network config is performed, wrong settings will lead to broken network.
Armbian supports netplan.io, this is the preferred config method.
See netplan guides for various example configurations.
Netplan config is stored in /etc/netplan/.

Configuration directive	[default] | option	Description:
PRESET_CONFIGURATION	http://path/to/config/file	See Loading a remote config
PRESET_NET_CHANGE_DEFAULTS	[0] | 1	Change default network settings if unset, no network changes will be applied
PRESET_NET_ETHERNET_ENABLED	0 | 1	Enable Ethernet, ignored if WiFi enabled
PRESET_NET_WIFI_ENABLED	0 | 1	Enable WiFi, takes priority over Ethernet
PRESET_NET_WIFI_SSID	MySSID	WiFi SSID
PRESET_NET_WIFI_KEY	MyWPA-PSK	WiFi Pre-Shared Key (Password), stored in plaintext
PRESET_NET_WIFI_COUNTRYCODE	CC	Country code, required for WiFi e.g. GB, US, DE; see Wikipedia/ISO_3166
PRESET_CONNECT_WIRELESS	Y | n	Answers “Connect via wireless?”, asked when first login finds no internet connection and the board has a WiFi adapter. n skips it; unattended runs default to n
PRESET_NET_USE_STATIC	[0] | 1	Use the static IP provided, DHCP is the default Applies to WiFi when PRESET_NET_WIFI_ENABLED=1 (Ethernet then stays on DHCP), otherwise to Ethernet. One static address only; it can’t be set on both Leaving any value unset will result in a broken config
PRESET_NET_STATIC_IP	xxx.xxx.xxx.xxx	Static IPv4 address, dotted decimal notation Must be a host address in the gateway’s subnet, not the network or broadcast address (e.g. not .0 or .255 in a /24)
PRESET_NET_STATIC_MASK	xxx.xxx.xxx.xxx	Subnet mask, typically 255.255.255.0
PRESET_NET_STATIC_GATEWAY	xxx.xxx.xxx.xxx	Default gateway address
PRESET_NET_STATIC_DNS	x.x.x.x x.x.x.x	DNS Servers to use, separated by spaces or commas. If unsure: CloudFlare is 1.1.1.1 1.0.0.1 Google is 8.8.8.8 8.8.4.4
SET_LANG_BASED_ON_LOCATION	Y | n	“Set user language based on your location?”; unattended runs default to Y
PRESET_LOCALE	locale	Locale e.g. en_GB.UTF-8, de_DE.UTF-8, zh_TW.UTF-8 Unattended runs without it take the first locale for the detected location
PRESET_TIMEZONE	timezone	Timezone e.g. Etc/UTC Unattended runs without it use the detected timezone, or keep the image’s if none was detected
PRESET_ROOT_PASSWORD	[1234] | password	Preset root password Stored in plaintext, SSH keys are safer!
PRESET_ROOT_KEY	https://path/to/key.file	Fetches public key from specified URL for root user
PRESET_USER_NAME	username	Username to create
PRESET_USER_PASSWORD	password	Preset created user password Stored in plaintext, SSH keys are safer!
PRESET_USER_KEY	https://path/to/key.file	Fetches public key from specified URL for created user
PRESET_DEFAULT_REALNAME	Real Name	RealName to use for created user
PRESET_USER_SHELL	shell	Currently only bash (default) or zsh (armbian-zsh) supported; unattended runs default to bash

Sample config file

The following is an example configuration, it may be used as a template

#/root/.not_logged_in_yet
# Network Settings
PRESET_NET_CHANGE_DEFAULTS="1"
## Ethernet
PRESET_NET_ETHERNET_ENABLED="1"     #   Ignored due to WiFi
## WiFi
PRESET_NET_WIFI_ENABLED="1"
PRESET_NET_WIFI_SSID="MySSID"
PRESET_NET_WIFI_KEY="MyWiFiKEY"
PRESET_NET_WIFI_COUNTRYCODE="GB"
PRESET_CONNECT_WIRELESS="n"
## Static IP
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="8.8.8.8 8.8.4.4"

# System
SET_LANG_BASED_ON_LOCATION="y"
PRESET_LOCALE="en_US.UTF-8"
PRESET_TIMEZONE="Etc/UTC"

# Root
PRESET_ROOT_PASSWORD="RootPassword"
PRESET_ROOT_KEY=""

# User
PRESET_USER_NAME="armbian"
PRESET_USER_PASSWORD="UserPassword"
PRESET_USER_KEY=""
PRESET_DEFAULT_REALNAME="Armbian user"
PRESET_USER_SHELL="bash"

Tip

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

tl;dr;

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

Provisioning script

/root/provisioning.sh is executed once as root after the first successful login, either manual or automated. It’s used to perform final system setup tasks like installing packages, configuring the system, or enabling services.

The example script updates package lists, installs htop, sets a custom hostname.

#!/bin/bash
set -e
echo "Provisioning started"
apt update && apt install -y htop
hostnamectl set-hostname my-device
echo "Provisioning complete"