Skip to content

Advanced features and tasks

While the underlying operating system offers tools and processes to make customizations, the preferred method to change most settings is using the interactive armbian-config tool which is shipped with all Armbian images. It also provides means to install preconfigured applications and advanced services.

Usually, all of the following commands require elevated permissions, and must be run as root or prefixed by the sudo command.

Keyboard layout

This is typically handled by armbian-config. For some corner cases, changing the keyboard layout can also be done with:

Bash
1
dpkg-reconfigure keyboard-configuration

If the chosen standard is not available with the previous command, you may also need to set the keymap config.

Bash
1
2
3
4
5
# Check the actual keymap config
localectl status | grep -i keymap

# Set the desired keymap config. In the example below it is set to 'br-abnt2'
localectl set-keymap br-abnt2

System language

This is typically handled by armbian-config. If necessary, to handle it with system tools, for Debian run:

Bash
1
dpkg-reconfigure locales

And for Ubuntu

Bash
1
update-locale LANG=[options] && dpkg-reconfigure locales

Console font and codepage

Bash
1
dpkg-reconfigure console-setup

Time zone

This is typically handled by armbian-config. If necessary, one can also run:

Bash
1
dpkg-reconfigure tzdata

Default sound output

Note

In recent versions of Debian and Ubuntu, pulseaudio got replaced by pipewire. The following suggestions won’t work in that case.

To check the available sound output options (“sinks”) with pulseaudio:

Bash
1
pacmd list-sinks | less

The default sink will be marked with an asterisk “*“. Press q to exit.

To define a new default sound output:

Bash
1
pacmd set-default-sink <NAME-OF-DESIRED-OPTION>

The name of HDMI sound output devices may change accordingly to the device. If you don’t want to deal with different names, you can run:

Bash
1
pacmd set-default-sink $(pactl list short sinks | grep -i 'hdmi' | awk '{print $2}')

The command to define the default sink is not persistent. To make it persistent, add it to the file ~/.bashrc.

Fix HDMI screen resolution for SunXi/Allwinner SoC

In rare cases, some SunXi/Allwinner boards failed to detect Full-HD support for HDMI and boot with only 720p. This issue should now be resolved, and the following steps are provided only for reference if it still occurs.

Legacy versions

Open the /boot/boot.cmd file with an editor of your choice (e.g. nano) and add or change the disp.screen0_output_mode option to the kernel command line. For a fixed mode (e.g. 1280x720 at 60 Hz), set it to:

Bash
1
disp.screen0_output_mode=1280x720p60

Then run

Bash
1
mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr

Enable a custom screen resolution within X.Org

Sometimes, not all desired resolutions are supported out of the box. The following short howto shows how to enable a custom resolution and add it to your X.Org configuration. It is based on this forum post by user @maxlinux2000 (Thanks!). The xrandr and cvt commands must be executed as the current user in a graphical session, not by the root user!

First, find the matching HDMI output (the x11-xserver-utils package must be installed):

Bash
1
xrandr --listmonitors

Then, calculate the VESA CVT mode line. The following command does this for a custom resolution of 1440x900.

Bash
1
cvt 1440 900

The command will output a new modeline. For our example, it may look like this:

Text Only
1
2
# 1440x900 59.89 Hz (CVT 1.30MA) hsync: 55.93 kHz; pclk: 106.50 MHz
Modeline "1440x900_60.00"  106.50  1440 1528 1672 1904  900 903 909 934 -hsync +vsync )

The new modeline can then be used directly to create and add the new mode, and enable it. The following commands will do that for the output device HDMI-1.

Bash
1
2
3
xrandr --newmode "1440x900_60.00" 106.50 1440 1528 1672 1904 900 903 909 934 -hsync +vsync
xrandr --addmode HDMI-1 1440x900_60.00
xrandr --output HDMI-1 --mode 1440x900_60.00

If it works well, the new mode can also be added to X.Org’s configuration in /etc/X11/xorg.conf.d/ to make it permanently available/active. Otherwise, these commands will have to be executed after every reboot. To load this resolution automatically after starting the device, add the following section to e.g. /etc/X11/xorg.conf.d/40-monitor.conf (create the file if it does not exist):

Text Only
1
2
3
4
5
Section "Monitor"
    Identifier "HDMI-1"
    Modeline "1440x900_60.00" 106.50 1440 1528 1672 1904 900 903 909 934 -hsync +vsync
    Option "PreferredMode" "1440x900"
EndSection

After a restart, the graphical session should automatically be shown in the chosen resolution.

Alter the CPU frequency

Legacy versions

Some boards allow to adjust the CPU speed by editing the file /etc/default/cpufrequtils and alter the min_speed and/or max_speed variable. Changing these values require restarting cpufrequtils.service to activate the new settings:

Bash
1
systemctl restart cpufrequtils.service

Swap for experts

By default, Armbian implements ZRAM (writing nothing to ‘disk’, but compressing memory pages in RAM). In case you often run into out-of-memory (OOM) errors and your device has some capable storage (e.g. a securely attached NVMe or SATA SSD), you might want to use ZSWAP instead.

Check whether your kernel has zswap enabled. If yes, the following command

Bash
1
dmesg | grep zswap

should return some output. If that is the case, create a swapfile or a swap partition the traditional way: edit /etc/default/armbian-zram-config so that it reads SWAP=false. Reboot, and you’re done.

Zswap performs a lot better than the combination of ZRAM and ‘swap on disk’ in parallel.

Switch or downgrade kernels

This is typically handled by armbian-config.

Bash
1
armbian-config --cmd KER001

In rare cases, it can be necessary to downgrade a kernel package, e.g. to fall back to a previous version.

Danger

Version dependencies between packages can create serious conflicts when attempting a package downgrade. If you force anything here, you can easily destroy your system beyond the point of repair. Don’t use that command lightly and better ask twice.

Bash
1
apt install linux-image-current-rockchip64=25.5

Build a wireless driver

The kernels provided by the project should contain the drivers, modules, and firmware to support most commonly used network devices/dongles. If you encounter that you have to build your own module and load it, the following example shows the general procedure because most modules follow the same structure and setup. It is, however, rarely necessary to build and load so-called “out-of-tree” kernel modules as shown in this example. Even the module we use here as an example is already supported by the current kernels.

First, building a module always requires having the kernel headers installed. The correct version can be installed with:

Bash
1
armbian-config --cmd HEAD01

Then download the driver’s sources. Most drivers can probably be found in a Git repository like in our example.

Bash
1
2
git clone https://github.com/morrownr/8821au-20210708.git
cd 8821au-20210708

The build and install instructions can usually be found on the driver’s homepage or in a file called README.md in the source. Read these instructions carefully. Usually, the following commands will suffice and result in an output as shown below.

Bash
1
2
make
make install
Build log
Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
make ARCH=arm64 CROSS_COMPILE= -C /lib/modules/6.6.62-current-sunxi64/build M=/root/8821au-20210708  modules
make[1]: Entering directory '/usr/src/linux-headers-6.6.62-current-sunxi64'
  CC [M]  /root/8821au-20210708/core/rtw_cmd.o
  CC [M]  /root/8821au-20210708/core/rtw_security.o
  CC [M]  /root/8821au-20210708/core/rtw_debug.o
  CC [M]  /root/8821au-20210708/core/rtw_io.o
  CC [M]  /root/8821au-20210708/core/rtw_ioctl_query.o
  CC [M]  /root/8821au-20210708/core/rtw_ioctl_set.o
  CC [M]  /root/8821au-20210708/core/rtw_ieee80211.o
  CC [M]  /root/8821au-20210708/core/rtw_mlme.o
  CC [M]  /root/8821au-20210708/core/rtw_mlme_ext.o
  ...
  [ goes on for a while ]
  ...
  LD [M]  /root/8821au-20210708/8821au.o
  MODPOST /root/8821au-20210708/Module.symvers
  CC [M]  /root/8821au-20210708/8821au.mod.o
  LD [M]  /root/8821au-20210708/8821au.ko
make[1]: Leaving directory '/usr/src/linux-headers-6.6.62-current-sunxi64'

If make succeeded, attempt to load the driver and check the dmesg output.

Bash
1
2
insmod 8821au.ko
usbcore: registered new interface driver rtl8821au

If everything was successful, plug the USB wireless adaptor in and proceed with the network configuration.

Toggle boot output

Boot parameters are edited or changed directly in /boot/boot.cmd (not recommended) or via variables in /boot/armbianEnv.txt:

Diff
1
2
- console=both
+ console=serial

To disable the console entirely (also not recommended and only as an example) one would set console=none.

To recompile boot.cmd to boot.scr if it was changed:

Bash
1
mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr

And reboot.

The serial console on imx6 boards is ttymxc0 (Hummingboard, Cubox-i) or ttymxc1 (Udoo).

Toggle boot verbosity

To change the boot verbosity, alter the verbosity= line in /boot/armbianEnv.txt. The lower the value, the lower the verbosity. The default is 1 and the maximum is 7.

Legacy versions

Using Armbian from version 5.05 to 5.20, you have to touch or delete /boot/.force-verbose to increase the boot verbosity.

Enable boot logs for inspection

If your SBC behaves strange, the first step is to check the power supply and the integrity of the boot media as detailed in the Troubleshooting section. Also, run

Bash
1
armbianmonitor -c "$HOME"

Then look into your kernel logs. Armbian also provides a tool that grabs some information and pastes it to an online pasteboard service. Please increase the boot verbosity to its maximum level (verbosity=7) as shown above, reboot and then run:

Bash
1
sudo armbianmonitor -u

Then copy and past the URL of your log to the forum, mail, etc.

APT mirror selection

Armbian has its own APT repository http://apt.armbian.com and mirrors for armbian-specific packages. The default domain is a round-robin to all mirrors. If you are having trouble updating or expereince slow speeds, you may want to choose a specific mirror.

First, make sure that you have the jq package installed:

Bash
1
apt install -y jq

To get a list of available mirrors from our https://apt.armbian.com/mirrors endpoint in JSON format, run:

Bash
1
curl -s http://apt.armbian.com/mirrors | jq

You will see a result set similar to this (shortened), listing mirrors by region:

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "AS": [
    "http://mirror.twds.com.tw/armbian-apt/",
    "http://mirror.albony.in/armbian/",
    "http://jp.mirrors.naho.moe/armbian/",
    ...
  ],
  "EU": [
    "http://netcup-02.armbian.com/apt/",
    "http://fi.mirror.armbian.de/apt/",
    "http://armbian.nardol.ovh/apt/",
    ...
  ],
  "NA": [
    "http://mirrors.jevincanders.net/armbian/apt/"
  ],
  "OC": [
    "http://au.sbcmirror.org/armbian/apt/"
  ],
  "default": [
    "http://mirrors.jevincanders.net/armbian/apt/",
    "http://netcup-02.armbian.com/apt/",
    "http://fi.mirror.armbian.de/apt/",
    ...
  ]
}

Choose a mirror, edit /etc/apt/sources.list.d/armbian.sources, and replace the URL http(s)://apt.armbian.com with your preferred mirror.

Install Docker

Install either the minimal package …

Bash
1
armbian-config --CON001

… or the fully featured one.

Bash
1
armbian-config --CON002

To test if Docker works correctly:

Bash
1
docker run hello-world

If you get that kind of output, then Docker install went fine:

Bash
1
2
Hello from Docker!
This message shows that your installation appears to be working correctly.