armbian/documentation
0
0
Fork 0
mirror of https://github.com/armbian/documentation.git synced 2026-01-06 10:13:36 -08:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to last discussed state (#760)

Browse Source 
* Typo fix

* Typo fix

* Add link to collaboration guidelines

* Reorder the SD cards hints

* Use the same form in the whole document

Don't mix SD-card and SD card. Decide for one (split form).

* Comma fixes

* Rephrase

* Some minor updates to the Upates section

* Minor update to the Troubleshotting section

* Minor rephrase to the report bugs section

* Rephrase link to Configuration page

* Use admonition for dist-upgrade instructions

* Change title

* Rephrase intro into page

* Update standard customizations

Links are broken for now!

* Update sound section

* Update sections about screen resolutions

* Update CPU freq section

* Update swap section

* Update package downgrade section

* Update toogle boot output section

* Update other boot related sections

* Disable the network configuration section

* Update the APT mirror config section

* Move all configuration tasks into the Advanced section

* Whitespace fix

* Move kernel section and fix command

* Move the example for building a driver

* Move the docker example

* Drop the User-Guide_Advanced-Features.md file

Everyting has been merged into User-Guide_Advanced-Configuration.md

* Fix links to armbian-config

* Fix a bunch of links

* Drop redundant sub-section

This has been moed to Getting started

* Fix a bunch of typos

* Update docs/User-Guide_Getting-Started.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Typo and grammatical fixes pointed out by coderabbitai

* Fix markdown related issues pointed out by coderabbitai

* Drop old section about network configuration

* Move legacy info into admonition

* Add nore about pipewire replacing pulseaudio

* Add minor detail that xrandr requires a graphical session

* Add a bit more content to building out-of-tree modules

* The cpufreq workaround is for legacy versions only

* Clarify the situation when this workaround is necessary

* Add link to armbian-config

* Merge kernel switch and downgrade and update example

* Rephrase according to coderabbitai

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Fix two typos discovered by the coderabbitai

---------

Co-authored-by: Werner <3305006+EvilOlaf@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Daniel Leidert
2025-06-23 13:08:53 +02:00
committed by GitHub
parent 79db8e9efb
commit a8b503be86
6 changed files with 463 additions and 526 deletions
Download Patch File Download Diff File Expand all files Collapse all files

381
docs/User-Guide_Advanced-Configuration.md Normal file
View File

@@ -0,0 +1,381 @@
# 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_](User-Guide_Armbian-Config.md) tool which is shipped with all Armbian images. It also provides means to install [preconfigured applications and advanced services](User-Guide_Armbian-Software.md).
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_](User-Guide_Armbian-Config/Localisation.md#change-keyboard-layout). For some corner cases, changing the keyboard layout can also be done with:
```sh
dpkg-reconfigure keyboard-configuration
```
If the chosen standard is not available with the previous command, you may also need to set the keymap config.
```sh
# 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_](User-Guide_Armbian-Config/Localisation.md#change-locales-reconfigure-the-language-and-character-set). If necessary, to handle it with system tools, for [Debian](https://wiki.debian.org/ChangeLanguage) run:
```sh
dpkg-reconfigure locales
```
And for [Ubuntu](https://help.ubuntu.com/community/Locale)
```sh
update-locale LANG=[options] && dpkg-reconfigure locales
```
## Console font and codepage
```sh
dpkg-reconfigure console-setup
```
## Time zone
This is typically handled by [_armbian-config_](User-Guide_Armbian-Config/Localisation.md#change-global-timezone). If necessary, one can also run:
```sh
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:
```sh
pacmd list-sinks | less
```
The default sink will be marked with an asterisk "\*". Press <kbd>q</kbd> to exit.
To define a new default sound output:
```sh
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:
```sh
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.
!!! tip "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`](https://linux-sunxi.org/Display#HDMI) option to the kernel command line. For a fixed mode (e.g. 1280x720 at 60 Hz), set it to:
```sh
disp.screen0_output_mode=1280x720p60
```
Then run
```sh
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](https://forum.armbian.com/topic/10403-add-undetected-hdmi-resolution-to-x11xorg/) 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):
```sh
xrandr --listmonitors
```
Then, calculate the VESA CVT mode line. The following command does this for a custom resolution of 1440x900.
```sh
cvt 1440 900
```
The command will output a new modeline. For our example, it may look like this:
```
# 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_.
```sh
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):
```
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
<!--TODO: new boards? -->
!!! tip "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:
```sh
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
```sh
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_](User-Guide_Armbian-Config/System.md#alternative-kernels).
```bash
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.
```sh
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:
```sh
armbian-config --cmd HEAD01
```
Then download the driver's sources. Most drivers can probably be found in a Git repository like in our example.
```sh
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.
```sh
make
make install
```
??? "Build log"
```text
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.
```sh
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](User-Guide_Networking.md).
## Toggle boot output
[Boot parameters](http://redsymbol.net/linux-kernel-boot-parameters/) are edited or changed directly in `/boot/boot.cmd` (**not recommended**) or via variables in `/boot/armbianEnv.txt`:
```diff
- 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:
```sh
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
<!-- TODO: Isn't this better suited for Troubleshooting; at least cross-link from there here -->
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`.
!!! tip "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_](User-Guide_Troubleshooting.md) section. Also, run
```sh
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:
```sh
sudo armbianmonitor -u
```
Then copy and past the URL of your log to the [forum, mail, etc](index.md#where-to-find-additional-help).
## 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:
```sh
apt install -y jq
```
To get a list of available mirrors from our `https://apt.armbian.com/mirrors` endpoint in JSON format, run:
```bash
curl -s http://apt.armbian.com/mirrors | jq
```
You will see a result set similar to this (shortened), listing mirrors by region:
```json
{
"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
armbian-config --CON001
```
... or the fully featured one.
```bash
armbian-config --CON002
```
To test if Docker works correctly:
<!-- TODO: Will the above have added the current user to the docker group? -->
```bash
docker run hello-world
```
If you get that kind of output, then Docker install went fine:
```bash
Hello from Docker!
This message shows that your installation appears to be working correctly.
```

228
docs/User-Guide_Advanced-Features.md
View File

@@ -1,228 +0,0 @@
# Advanced Features
## How to switch kernels?
```bash
armbian-config --cmd SY015
```
## How to build a wireless driver?
Install kernel headers:
armbian-config --cmd SY004
Download driver sources:
git clone https://github.com/morrownr/8821au-20210708.git
cd 8821au-20210708
Build and install:
make
make install
??? "Build log"
```
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
CC [M] /root/8821au-20210708/core/rtw_mi.o
CC [M] /root/8821au-20210708/core/rtw_wlan_util.o
CC [M] /root/8821au-20210708/core/rtw_vht.o
CC [M] /root/8821au-20210708/core/rtw_pwrctrl.o
CC [M] /root/8821au-20210708/core/rtw_rf.o
CC [M] /root/8821au-20210708/core/rtw_chplan.o
CC [M] /root/8821au-20210708/core/monitor/rtw_radiotap.o
CC [M] /root/8821au-20210708/core/rtw_recv.o
CC [M] /root/8821au-20210708/core/rtw_sta_mgt.o
CC [M] /root/8821au-20210708/core/rtw_ap.o
CC [M] /root/8821au-20210708/core/wds/rtw_wds.o
CC [M] /root/8821au-20210708/core/mesh/rtw_mesh.o
CC [M] /root/8821au-20210708/core/mesh/rtw_mesh_pathtbl.o
CC [M] /root/8821au-20210708/core/mesh/rtw_mesh_hwmp.o
CC [M] /root/8821au-20210708/core/rtw_xmit.o
CC [M] /root/8821au-20210708/core/rtw_p2p.o
CC [M] /root/8821au-20210708/core/rtw_rson.o
CC [M] /root/8821au-20210708/core/rtw_tdls.o
CC [M] /root/8821au-20210708/core/rtw_br_ext.o
CC [M] /root/8821au-20210708/core/rtw_iol.o
CC [M] /root/8821au-20210708/core/rtw_sreset.o
CC [M] /root/8821au-20210708/core/rtw_btcoex_wifionly.o
CC [M] /root/8821au-20210708/core/rtw_btcoex.o
CC [M] /root/8821au-20210708/core/rtw_beamforming.o
CC [M] /root/8821au-20210708/core/rtw_odm.o
CC [M] /root/8821au-20210708/core/rtw_rm.o
CC [M] /root/8821au-20210708/core/rtw_rm_fsm.o
CC [M] /root/8821au-20210708/core/rtw_ft.o
CC [M] /root/8821au-20210708/core/rtw_wnm.o
CC [M] /root/8821au-20210708/core/rtw_mbo.o
CC [M] /root/8821au-20210708/core/rtw_rm_util.o
CC [M] /root/8821au-20210708/core/efuse/rtw_efuse.o
CC [M] /root/8821au-20210708/core/rtw_roch.o
CC [M] /root/8821au-20210708/core/crypto/aes-internal.o
CC [M] /root/8821au-20210708/core/crypto/aes-internal-enc.o
CC [M] /root/8821au-20210708/core/crypto/aes-gcm.o
CC [M] /root/8821au-20210708/core/crypto/aes-ccm.o
CC [M] /root/8821au-20210708/core/crypto/aes-omac1.o
CC [M] /root/8821au-20210708/core/crypto/ccmp.o
CC [M] /root/8821au-20210708/core/crypto/gcmp.o
CC [M] /root/8821au-20210708/core/crypto/aes-siv.o
CC [M] /root/8821au-20210708/core/crypto/aes-ctr.o
CC [M] /root/8821au-20210708/core/crypto/sha256-internal.o
CC [M] /root/8821au-20210708/core/crypto/sha256.o
CC [M] /root/8821au-20210708/core/crypto/sha256-prf.o
CC [M] /root/8821au-20210708/core/crypto/rtw_crypto_wrap.o
CC [M] /root/8821au-20210708/core/rtw_swcrypto.o
CC [M] /root/8821au-20210708/os_dep/osdep_service.o
CC [M] /root/8821au-20210708/os_dep/linux/os_intfs.o
CC [M] /root/8821au-20210708/os_dep/linux/usb_intf.o
CC [M] /root/8821au-20210708/os_dep/linux/usb_ops_linux.o
CC [M] /root/8821au-20210708/os_dep/linux/ioctl_linux.o
CC [M] /root/8821au-20210708/os_dep/linux/xmit_linux.o
CC [M] /root/8821au-20210708/os_dep/linux/mlme_linux.o
CC [M] /root/8821au-20210708/os_dep/linux/recv_linux.o
CC [M] /root/8821au-20210708/os_dep/linux/ioctl_cfg80211.o
CC [M] /root/8821au-20210708/os_dep/linux/rtw_cfgvendor.o
CC [M] /root/8821au-20210708/os_dep/linux/wifi_regd.o
CC [M] /root/8821au-20210708/os_dep/linux/rtw_android.o
CC [M] /root/8821au-20210708/os_dep/linux/rtw_proc.o
CC [M] /root/8821au-20210708/os_dep/linux/nlrtw.o
CC [M] /root/8821au-20210708/os_dep/linux/rtw_rhashtable.o
CC [M] /root/8821au-20210708/hal/hal_intf.o
CC [M] /root/8821au-20210708/hal/hal_com.o
CC [M] /root/8821au-20210708/hal/hal_com_phycfg.o
CC [M] /root/8821au-20210708/hal/hal_phy.o
CC [M] /root/8821au-20210708/hal/hal_dm.o
CC [M] /root/8821au-20210708/hal/hal_dm_acs.o
CC [M] /root/8821au-20210708/hal/hal_btcoex_wifionly.o
CC [M] /root/8821au-20210708/hal/hal_btcoex.o
CC [M] /root/8821au-20210708/hal/hal_mp.o
CC [M] /root/8821au-20210708/hal/hal_mcc.o
CC [M] /root/8821au-20210708/hal/hal_hci/hal_usb.o
CC [M] /root/8821au-20210708/hal/led/hal_led.o
CC [M] /root/8821au-20210708/hal/led/hal_usb_led.o
CC [M] /root/8821au-20210708/hal/HalPwrSeqCmd.o
CC [M] /root/8821au-20210708/hal/rtl8812a/Hal8812PwrSeq.o
CC [M] /root/8821au-20210708/hal/rtl8812a/Hal8821APwrSeq.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_xmit.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_sreset.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_hal_init.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_phycfg.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_rf6052.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_dm.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_rxdesc.o
CC [M] /root/8821au-20210708/hal/rtl8812a/rtl8812a_cmd.o
CC [M] /root/8821au-20210708/hal/rtl8812a/usb/usb_halinit.o
CC [M] /root/8821au-20210708/hal/rtl8812a/usb/rtl8812au_led.o
CC [M] /root/8821au-20210708/hal/rtl8812a/usb/rtl8812au_xmit.o
CC [M] /root/8821au-20210708/hal/rtl8812a/usb/rtl8812au_recv.o
CC [M] /root/8821au-20210708/hal/rtl8812a/usb/usb_ops_linux.o
CC [M] /root/8821au-20210708/hal/efuse/rtl8812a/HalEfuseMask8821A_USB.o
CC [M] /root/8821au-20210708/hal/rtl8812a/hal8821a_fw.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_debug.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_antdiv.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_soml.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_smt_ant.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_antdect.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_interface.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_phystatus.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_hwconfig.o
CC [M] /root/8821au-20210708/hal/phydm/phydm.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_dig.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_pathdiv.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_rainfo.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_dynamictxpower.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_adaptivity.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_cfotracking.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_noisemonitor.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_beamforming.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_direct_bf.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_dfs.o
CC [M] /root/8821au-20210708/hal/phydm/txbf/halcomtxbf.o
CC [M] /root/8821au-20210708/hal/phydm/txbf/haltxbfinterface.o
CC [M] /root/8821au-20210708/hal/phydm/txbf/phydm_hal_txbf_api.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_adc_sampling.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_ccx.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_psd.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_primary_cca.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_cck_pd.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_rssi_monitor.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_auto_dbg.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_math_lib.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_api.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_pow_train.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_lna_sat.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_pmac_tx_setting.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_mp.o
CC [M] /root/8821au-20210708/hal/phydm/phydm_cck_rx_pathdiv.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf_debug.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halphyrf_ce.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf_powertracking_ce.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf_powertracking.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf_kfree.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/halrf_psd.o
CC [M] /root/8821au-20210708/hal/phydm/rtl8821a/halhwimg8821a_mac.o
CC [M] /root/8821au-20210708/hal/phydm/rtl8821a/halhwimg8821a_bb.o
CC [M] /root/8821au-20210708/hal/phydm/rtl8821a/halhwimg8821a_rf.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/rtl8812a/halrf_8812a_ce.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/rtl8821a/halrf_8821a_ce.o
CC [M] /root/8821au-20210708/hal/phydm/rtl8821a/phydm_regconfig8821a.o
CC [M] /root/8821au-20210708/hal/phydm/rtl8821a/phydm_rtl8821a.o
CC [M] /root/8821au-20210708/hal/phydm/halrf/rtl8821a/halrf_iqk_8821a_ce.o
CC [M] /root/8821au-20210708/hal/phydm/txbf/haltxbfjaguar.o
CC [M] /root/8821au-20210708/hal/btc/halbtc8821a1ant.o
CC [M] /root/8821au-20210708/hal/btc/halbtc8821a2ant.o
CC [M] /root/8821au-20210708/platform/platform_ops.o
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'
```
Load driver for test
insmod 8821au.ko
Check `dmesg` and the last entry will be:
usbcore: registered new interface driver rtl8821au
Plug the USB wireless adaptor and proceed with [network configuration](/User-Guide_Networking/)
## How to install Docker?
Minimal:
```bash
armbian-config --CON01
```
Full featured:
```bash
armbian-config --CON02
```
Test if Docker works correctly:
```bash
docker run hello-world
```
If you get that kind of output, then Docker install went fine:
```bash
Hello from Docker!
This message shows that your installation appears to be working correctly.
```

236
docs/User-Guide_Configuration.md
View File

@@ -1,236 +0,0 @@
# How to customize keyboard, time zone?
<!-- TODO: Probably move stuff like sound or screen resolution to Advanced tasks?? Or at least some?? -->
- **Attention: The preferred method to change most of this stuff is by using the interactive _armbian-config_ tool which is shipped with all Armbian images.**
## Keyboard:
dpkg-reconfigure keyboard-configuration
In some cases, e.g. when your keyboard standard is not available in previous command, you may also need to set your keymap config:
# Check your actual keymap config
localectl status | grep -i keymap
# Set the desired keymap config. Example below to 'br-abnt2'
localectl set-keymap br-abnt2
## System language:
# Debian --> https://wiki.debian.org/ChangeLanguage
dpkg-reconfigure locales
# Ubuntu --> https://help.ubuntu.com/community/Locale
update-locale LANG=[options] && dpkg-reconfigure locales
## Console font, codepage:
dpkg-reconfigure console-setup
## Time zone:
dpkg-reconfigure tzdata
## Sound output:
# Check the available sound output options:
pacmd list-sinks | less
# The default will be marked with "*"
# Press "q" to close
# Define the new default sound output
pacmd set-default-sink <NAME-OF-DESIRED-OPTION>
The name of HDMI sound output may change accordingly to the device. If you don't wanna deal with different names you can:
pacmd set-default-sink $(pactl list short sinks | grep -i 'hdmi' | awk '{print $2}')
The command to define the default sound output is not persistent, to make it persistent add it to the file `~/.bashrc`
## Screen resolution on other boards:
nano /boot/boot.cmd
# example:
# change example from
# disp.screen0_output_mode=1920x1080p60
# to
# disp.screen0_output_mode=1280x720p60
mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr
## Screen resolution within Xorg
- Thanks to user @maxlinux2000 in [this](https://forum.armbian.com/topic/10403-add-undetected-hdmi-resolution-to-x11xorg/) forum post.
Find matching HDMI output:
xrandr --listmonitors
Calculate VESA CVT mode lines (example for 1440x900)
cvt 1440 900
Sample output:
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 )
Create new mode (example):
xrandr --newmode "1440x900_60.00" 106.50 1440 1528 1672 1904 900 903 909 934 -hsync +vsync
Add resolution (example):
xrandr --addmode HDMI-1 1440x900_60.00
Set current resolution (example):
xrandr --output HDMI-1 --mode 1440x900_60.00
If it works as expected add it to Xorg by editing `/etc/X11/xorg.conf.d/40-monitor.conf` and add (example):
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
Restart Xorg or reboot
## How to alter CPU frequency?
Some boards allow to adjust CPU speed
nano /etc/default/cpufrequtils
Alter **min_speed** or **max_speed** variable.
systemctl restart cpufrequtils
## Swap for experts
By default Armbian implements ZRAM (writing nothing to 'disk' but compressing memory pages in RAM) but in case you often run into out of memory 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 (`dmesg | grep zswap` should output something) and if so create a swapfile or swap partition the traditional way, edit/uncomment `/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.
## How to downgrade a package via apt?
This is useful when you need to fall back to previous kernel version.
apt install linux-image-sun8i=5.13
This example is for H3 legacy kernel. Check [this page](https://www.armbian.com/kernel/) for others.
## How to toggle boot output?
Edit and change [boot parameters](http://redsymbol.net/linux-kernel-boot-parameters/) in `/boot/boot.cmd` (not recommended) or variables in `/boot/armbianEnv.txt`:
- console=both
+ console=serial
To disable console entirely (not recommended) set console to `none`.
Recompile boot.cmd to boot.scr if it was changed:
mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr
Reboot.
Serial console on imx6 boards are ttymxc0 (Hummingboard, Cubox-i) or ttymxc1 (Udoo).
## How to toggle verbose boot?
Using Armbian 5.05 to 5.20 you would need to touch/rm `/boot/.force-verbose` to increase boot verbosity. With more recent Armbian builds you would have to alter the `verbosity=` line in `/boot/armbianEnv.txt` (defaults to 1 which means less verbose, maximum value is 7).
## How to provide boot logs for inspection?
When your SBC behaves strange first step is to check power supply and integrity of boot media (`armbianmonitor -c "$HOME"`). Then look into your kernel logs. We made a tool that grabs info and pastes it to an online pasteboard service. Please increase boot verbosity as shown above (`verbosity=7`), reboot and then run
sudo armbianmonitor -u
Copy and past URL of your log to the forum, mail, ...
## How to change network configuration?
To get Wi-Fi working simply use `nmtui`, a simple console based UI for network-manager (an example how to set up an AP with network-manager can be found [here](https://forum.odroid.com/viewtopic.php?f=52&t=25472&)). To deal with different Ethernet/Wi-Fi combinations there are six predefined configurations available, you can find them in those files:
/etc/network/interfaces.bonding
/etc/network/interfaces.default
/etc/network/interfaces.hostapd
/etc/network/interfaces.network-manager
/etc/network/interfaces.r1
/etc/network/interfaces.r1switch
By default **/etc/network/interfaces** is a copy of **/etc/network/interfaces.default**
1. BONDING: your network adapters are bonded in fail safe / "notebook" way.
2. DEFAULT: your network adapters are connected classical way.
3. HOSTAPD: your network adapters are bridged together and bridge is connected to the network. This allows you to have your AP connected directly to your router.
4. All interfaces are handled by network-manager (`nmtui`/`nmcli` or using the GUI)
4. Router configuration for Lamobo R1 / Banana R1.
5. Switch configuration for Lamobo R1 / Banana R1.
You can switch configuration with copying.
cd /etc/network
cp interfaces.x interfaces
(x = default,hostapd,bonding,r1)
Then check / alter your interfaces:
nano /etc/network/interfaces
## Choosing an apt mirror
Armbian has its own apt repository and mirrors for armbian-specific packages. The default of `http://apt.armbian.com` is a round-robin to all mirrors. If you are having trouble updating or slow speeds you may want to choose a specific mirror.
Do the following:
Assure `jq` is installed
`apt install -y jq`
Get a list of available mirrors from our `https://apt.armbian.com/mirrors` endpoint.
```bash
curl -s http://apt.armbian.com/mirrors | jq
```
You will see a result set similar to this, listing mirrors by region:
```json
{
"AS": [
"https://mirrors.tuna.tsinghua.edu.cn/armbian/",
"https://minio.k-space.ee/armbian/apt/"
],
"NA": [
"https://armbian.tnahosting.net/apt/",
"https://us.mirrors.fossho.st/armbian/apt/"
],
"EU": [
"https://minio.k-space.ee/armbian/apt/",
"https://armbian.systemonachip.net/apt/",
"https://mirrors.netix.net/armbian/apt/",
"https://mirrors.dotsrc.org/armbian-apt/",
"https://armbian.hosthatch.com/apt/"
],
"default": [
"https://armbian.tnahosting.net/apt/",
"https://us.mirrors.fossho.st/armbian/apt/",
"https://minio.k-space.ee/armbian/apt/",
"https://armbian.systemonachip.net/apt/",
"https://mirrors.netix.net/armbian/apt/",
"https://mirrors.dotsrc.org/armbian-apt/",
"https://armbian.hosthatch.com/apt/"
]
}
```
Edit `/etc/apt/sources.list.d/armbian.sources` and replace the URL `https://apt.armbian.com` with your preferred mirror.

117
docs/User-Guide_Getting-Started.md
View File

@@ -2,12 +2,33 @@
Before you start, please make sure you have:
- a proper power supply according to the board manufacturer requirements <!-- TODO: link to power issues -->
- a reliable SD card <!-- TODO: link to hints for SD-card -->
- a proper power supply according to the board manufacturer's requirements <!-- TODO: link to power issues -->
- a reliable SD card (at least 'Class 10' and 'A1'-rated is **highly** recommended)
You will also need an existing operating system and a SD card writer tool. We recommend using [USBImager](https://gitlab.com/bztsrc/usbimager) because it can validate written data **saving you from corrupted SD card contents**.
!!! tips "New users"
!!! warning
Make sure you use a **good, reliable and fast** SD card. If you encounter boot or stability issues, in over 95 percent of all cases these are either caused by an **insufficient** power supply, or they are related to the SD card. This can be due to a bad card, bad card reader, something went wrong when burning the image, the card turns out to be too slow to boot, etc. Armbian can simply not run on unreliable hardware.
Checking your SD card with either [F3](https://fight-flash-fraud.readthedocs.io/en/stable/) or [H2testw](https://www.heise.de/download/product/h2testw-50539) is mandatory if you run into problems. Since [counterfeit SD cards](https://www.happybison.com/reviews/how-to-check-and-spot-fake-micro-sd-card-8/) are still an issue, we also highly recommend checking your card with these tools directly after purchase.
Most SD cards are only optimised for sequential reads/writes as it is common with digital cameras. This is what the *speed class* is about. The SD Association defined [*Application Performance Class*](https://www.sdcard.org/developers/overview/application/index.html) as a standard for random IO performance.
|Application Performance Class|Pictograph|Minimum Random Read|Minimum Random Write|Minimum Sustained (Seq. Write)|
|---|---|---|---|---|
|Class 1 (A1)|![a1-logo](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/a1-logo.png)|1500 4k IOPS|500 4k IOPS|10MBytes/sec|
|Class 2 (A2)|![a2-logo](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/a2-logo.png)|4000 4k IOPS|2000 4k IOPS|10MBytes/sec|
We recommend SD cards that are rated at least A1 ([A2 rated cards are yet lacking driver support, and therefore show lower overall and especially random IO performance](https://github.com/ThomasKaiser/Knowledge/blob/master/articles/A1_and_A2_rated_SD_cards.md)) and fulfill at least speed class C10 or higher (U1/U3, etc.). For example:
![a1-16gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-ultra-a1.png) ![a1-32gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-extremepro-a1.png) ![a2-64gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-extreme-a2.png)
In case you chose an SD card that was already in use before, please consider resetting it back to 'factory default' performance with [SD Formatter](https://www.sdcard.org/downloads/formatter/) before burning Armbian to it ([explanation in the forum](https://forum.armbian.com/topic/3776-the-partition-is-not-resized-to-full-sd-card-size/&do=findComment&comment=27413)). Detailed information regarding ['factory default' SD card performance](https://forum.armbian.com/topic/954-sd-card-performance/page/3/&tab=comments#comment-49811).
!!! tip "New users"
Some users might find it easier to follow this video tutorial.
@@ -18,7 +39,7 @@ You will also need an existing operating system and a SD card writer tool. We re
## Download the image
If your hardware is [supported](index.md#hardware-support), you must download an image for your board. All of our system images can be found at <https://www.armbian.com/download/> or at one of our [many mirrors](/Mirrors/). You will find that there are different types of images, either using Debian GNU/Linux or Ubuntu as their base operating system.
If your hardware is [supported](index.md#which-hardware-is-supported), you must download an image for your board. All of our system images can be found at <https://www.armbian.com/download/> or at one of our [many mirrors](Mirrors.md). You will find that there are different types of images, either using Debian GNU/Linux or Ubuntu as their base operating system.
<!-- TODO: add some information about using the user interface on the site -->
@@ -51,7 +72,7 @@ Use the following images only if these are the only ones provided, or if you wan
- **edge** is, as the name implies, cutting-edge fresh / development / latest stable. It is only automatically tested, it can break at any time, and it is recommended only for experienced users.
- **legacy** is the old stable current kernel. Use it if _current_ is not available or if something does not work well with it.
The level of kernel support, however, always depends on the board family. If in your specific case something does not work well, you are always free to try an image with another kernel included, or change the kernel with [armbian-config](/User-Guide_Armbian-Config).
The level of kernel support, however, always depends on the board family. If in your specific case something does not work well, you are always free to try an image with another kernel included, or change the kernel with [armbian-config](User-Guide_Armbian-Config.md).
### Rolling releases
@@ -87,7 +108,7 @@ graph LR
**Do not use** rolling release or edge images in a productive environment. Their purpose is testing and providing constructive [feedback to developers](https://forum.armbian.com/forum/4-development/).
### Download and verfication
### Download and verification
After you have determined the image you want, the download for each image consists of three separate files:
@@ -153,28 +174,13 @@ After you have downloaded these files, we recommend checking the integrity and t
## Deploy the image
<!-- TODO: might be too much for novice users; needs to be shortened; maybe use admonitions -->
Write the **.xz compressed image** with a tool like [USBImager](https://gitlab.com/bztsrc/usbimager) onto your micro-SD card. Unlike other tools, it can validate written data **saving you from corrupted SD card contents**.
Before you start, there is an **important note:** Make sure you use a **good, reliable and fast** SD card. If you encounter boot or stability issues, in over 95 percent of the time it is either caused by an insufficient power supply or it is related to the SD card (due to a bad card, bad card reader, something went wrong when burning the image, card too slow to boot ... 'Class 10' is **highly** recommended!). Armbian can simply not run on unreliable hardware. So checking your SD card with either [F3](https://fight-flash-fraud.readthedocs.io/en/stable/) or [H2testw](https://www.heise.de/download/product/h2testw-50539) is mandatory if you run into problems. Since [counterfeit SD cards](https://www.happybison.com/reviews/how-to-check-and-spot-fake-micro-sd-card-8/) are still an issue, checking with F3/H2testw directly after purchase is also **highly recommended**.
!!! warning "Other tools"
Write the **.xz compressed image** with a tool like [USBImager](https://gitlab.com/bztsrc/usbimager) onto your microSD card. Unlike other tools, it can validate written data **saving you from corrupted SD card contents**. Due to known issues, [balenaEtcher](https://www.balena.io/etcher/) can no longer be recommended at this time.
We are aware that there are many programs that can be used for this step. **But**, they usually cannot validate the written data to catch a bad card, a faulty card reader, problems writing the image. etc. Issues like these have caused too many error reports. Thus, please follow our advice and don't use other tools, especially if you are a novice user.
!!! tip "Also important"
Most SD cards are only optimised for sequential reads/writes as it is common with digital cameras. This is what the *speed class* is about. The SD Association defined [*Application Performance Class*](https://www.sdcard.org/developers/overview/application/index.html) as a standard for random IO performance.
|Application Performance Class|Pictograph|Miniumum Random Read|Minimum Random Write|Minimum Sustained (Seq. Write)|
|---|---|---|---|---|
|Class 1 (A1)|![a1-logo](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/a1-logo.png)|1500 4k IOPS|500 4k IOPS|10MBytes/sec|
|Class 2 (A2)|![a2-logo](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/a2-logo.png)|4000 4k IOPS|2000 4k IOPS|10MBytes/sec|
<!-- TODO: Is that still correct?? -->
We recommend at least A1 rated SD-Cards ([A2 rated cards need yet lacking driver support and therefore show lower overall and especially random IO performance](https://github.com/ThomasKaiser/Knowledge/blob/master/articles/A1_and_A2_rated_SD_cards.md)). For example:
![a1-16gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-ultra-a1.png) ![a1-32gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-extremepro-a1.png) ![a2-64gb-card](https://raw.githubusercontent.com/armbian/documentation/master/docs/images/sandisk-extreme-a2.png)
In case you chose an SD card that was already in use before, please consider resetting it back to 'factory default' performance with [SD Formatter](https://www.sdcard.org/downloads/formatter/) before burning Armbian to it ([explanation in the forum](https://forum.armbian.com/topic/3776-the-partition-is-not-resized-to-full-sd-card-size/&do=findComment&comment=27413)). Detailed information regarding ['factory default' SD card performance](https://forum.armbian.com/topic/954-sd-card-performance/page/3/&tab=comments#comment-49811).
Due to known issues, [balenaEtcher](https://www.balena.io/etcher/) can no longer be recommended as an alternative at this time.
## First boot
@@ -186,9 +192,9 @@ Insert the SD card into a slot and power on the board. With the cheapest board,
The first boot will log you in automatically if you have connected a display via HDMI or if you are connected to the serial console. For SSH, you need to login as **root** and use the password **1234**. If you need to find your board's IP address, you can use [this tool](https://angryip.org/).
After logging in, you will be prompted to change the default password. You will then be asked to create a normal user account that will have sudo permissions. Beware, at this stage the keyboard is using the QWERTY layout. In case you have no wired network connection and there is a wireless adaptor detected, the system will prompt you to connect.
After logging in, you will be prompted to change the default password. You will then be asked to create a normal user account that will have sudo permissions. Beware, at this stage, the keyboard is using the QWERTY layout. In case you have no wired network connection and there is a wireless adaptor detected, the system will prompt you to connect.
Welcome to Armbian!
Welcome to Armbian!
Documentation: https://docs.armbian.com/ | Community support: https://forum.armbian.com/
@@ -225,7 +231,7 @@ After logging in, you will be prompted to change the default password. You will
1 NETWORK
2 MY-WIFI
3 Caatsanddogs
3 Caatsanddogs
Enter a number of SSID: 3
@@ -240,17 +246,41 @@ After logging in, you will be prompted to change the default password. You will
Generating locales: sl_SI.UTF-8
root@bananapim2pro:~#
???+ tips "Automated config"
These settings can be pre-loaded, see [Autoconfig](/User-Guide_Autoconfig)
???+ tip "Automated config"
These settings can be pre-loaded, see [Autoconfig](User-Guide_Autoconfig.md)
<!-- TODO: it must be made clear that this just preps the SD card -->
## First steps
You can customize your Armbian Linux before or after installing it onto your device's hard-drive. In many cases, you probably want to apply some basic customizations like adjusting the keyboard layout, the timezone, etc. before the installation, so you can use the same SD-card again if necesasary. Or you want to adjust your hardware configuration, or install software.
You can customize your Armbian Linux before or after installing it onto your device's hard-drive. In many cases, you probably want to apply some basic customizations like adjusting the keyboard layout, the timezone, etc., so you can use the same SD card again if necessary. Or you want to adjust your [system or hardware configuration](User-Guide_Armbian-Config.md) or [install preconfigured applications and advanced services](User-Guide_Armbian-Software.md).
Please note that the typical tool for all tasks is [_armbian-config_](User-Guide_Armbian-Config.md). The section [_Advanced Configuration_](User-Guide_Advanced-Configuration.md) contains a selection of tasks that require a deeper understanding of the operating system.
### Configuration
Typical tasks include for example:
- Set the default language and keyboard layout
- Disable or enable root logins and/or SSH
- Handle and configure system and firmware upgrades
- Configure the network
### Software titles
You can quickly and easily install popular software too! It is ready to run and optimized for Armbian. Here are few highlights:
- Desktops - install desktop environments
- Netconfig - network tools
- DevTools - development
- Benchy - system benchmaking and diagnostics
- Containers - containerization and virtual machines
- Media - media servers and editors
- Management - remote management tools
While the underlying operating system offers tools and processes to make these customizations, the **preferred method** to change most of these settings is using the interactive [_armbian-config_](User-Guide_Armbian-Config.md) tool which is shipped with all Armbian images.
<!-- TODO:
* first customize: armbian-config, install software -> show some examples
@@ -262,7 +292,7 @@ While the underlying operating system offers tools and processes to make these c
## Installation
At this stage, nothing has been installed onto the boards internal drive yet. Using the installer, you can now decide, where you want to install the boot loader and the rest of the system. The installer supports various combinations depending on the availability of onboard eMMC and/or attached SATA, NVME or USB storage.
At this stage, nothing has been installed onto the board's internal drive yet. Using the installer, one can now decide where to install the boot loader and the rest of the system. The installer supports various combinations depending on the availability of onboard eMMC and/or attached SATA, NVME, or USB storage.
!!! tip "Armbian Installer support those storage scenarios:"
@@ -277,7 +307,7 @@ At this stage, nothing has been installed onto the boards internal drive yet. Us
<!-- TODO: give the user a sensible default -->
Start the install script and follow the lead:
Start the install script, make your choice, and follow the instructions:
armbian-install
@@ -309,25 +339,28 @@ For the base operating system, use the APT package manager to keep the packages
Users with a desktop will find graphical tools that allow one to update the system packages without using the command line.
Armbian provides a firmware package freeze feature to provide you with the possibility to upgrade all packages **but** the firmware. This prevents unplesant surprises on functionality regressions that can come with kernel upgrades. To enable or disable this feature, look for
Armbian provides a firmware package freeze feature to provide you with the possibility to upgrade all packages **but** the firmware. This prevents unpleasant surprises on functionality regressions that can come with kernel upgrades. To enable or disable this feature, look for
Enable Armbian kernel/firmware upgrades / Disable Armbian kernel upgrades
within [armbian-config](/User-Guide_Armbian-Config).
within [armbian-config](User-Guide_Armbian-Config.md).
If the kernel was upgraded during this process, you will be prompted to reboot at the next login.
<!-- TODO: maybe move this to advanced? Definitely not for novice users -->
When a new major release of Debian or Ubuntu is out, we recommend to start with a fresh image. While it is possible to do what is called a _"dist-upgrade"_, the process is largerly in the domain of the underlaying Debian or Ubuntu user space. We provide an experimental `Distribution upgrades` feature for [armbian-config](/User-Guide_Armbian-Config).
!!! danger "Upgrade the Armbian OS"
When a new major release of Debian or Ubuntu is out, we recommend to start with a fresh image. While it is possible to do what is called a _"dist-upgrade"_, the process is largerly in the domain of the underlaying Debian or Ubuntu user space. We provide only an experimental `Distribution upgrades` feature for [armbian-config](User-Guide_Armbian-Config.md).
!!! danger
Userspaces distribution upgrades are neither tested nor supported. Therefore Armbian cannot provide any support if something goes wrong.
### Update the boot loader
First, you need to update all packages as described in the previous section. Then run:
The second part that can be updated is the boot loader.
First, update all packages as described in the previous section. Then run:
```bash
sudo armbian-install
@@ -340,7 +373,9 @@ and select:
## Troubleshooting
<!--
If you experience an issue during any of the steps mentioned in this section, please first check out our [_Troubleshooting and Recovery_](User-Guide_Troubleshooting.md) guide.
<!--
* armbianmonitor
* community / search forum || how to get help
* FAQ (maybe feature is not developed)
@@ -348,4 +383,4 @@ and select:
### How to report bugs
Follow our [bug reporting form](https://armbian.com/bugs/) and follow its instructions to collect the necessary information and how/where to provide them depending on the type of issue. Please understand that any reports lacking these fundamental diagnostics will be ignored.
If you are certain you have found a bug, fill out our [bug reporting form](https://armbian.com/bugs/) and follow its instructions to collect the necessary information and how/where to provide them depending on the type of issue. Please understand that any reports lacking these fundamental diagnostics might be ignored.

24
docs/index.md
View File

@@ -12,11 +12,9 @@ Welcome to the official documentation of Armbian Linux, a highly optimized base
The table of contents in the sidebar and the links at the top of the page should let you easily access the documentation for your topic of interest.
If you are **new to Armbian**, the [_Introduction_](index.md) and the [_Getting Started_](User-Guide_Getting-Started.md) sections provide everything you need to know about the project, where to find the resources for your board, and a tutorial for everything you need to get Armbian running.
If you are **new to Armbian**, the [_Introduction_](index.md) and the [_Getting Started_](User-Guide_Getting-Started.md) sections provide everything you need to know about the project, where to find the resources for your board, and a tutorial for everything you need to get Armbian running and configured.
It then continues on to [_Configuration_](User-Guide_Configuration.md) tasks and tools to customize your installation, e.g. change the network address, start or stop services like SSH, or install one of the many prepared software stacks. This section and the links contained in it are useful to **all user levels**.
**Advanced users** will find more complex topics in the [_Advanced_](User-Guide_Advanced-Features.md) section, including how to customize your initial installation.
It then continues on to [_Advanced Configuration_](User-Guide_Advanced-Configuration.md) tasks and tools for **advanced users**. The topics in this section cover a wide range of tasks: configuring the system or the network without using [`armbian-config`](User-Guide_Armbian-Config.md), configuring your device automatically at first boot, and creating a custom image using the [`Armbian Build Framework`](Developer-Guide_Overview.md).
If you have read through the documentation and still **need help**, check out our [_Troubleshooting_](User-Guide_Troubleshooting.md) advice.
@@ -62,7 +60,7 @@ In any case, you will get these key advantages:
- you get a lean and standard **Debian** or **Ubuntu** based user space with the well known APT package manager
- we provide independent kernel development and maintenance with **long term support**
- we provide an extensive [build framework](https://github.com/armbian/build) with fast **hybrid assembly** of the whole operating system and **endless capabilities**
- we provide advanced **hardware and OS configuration** and **software installation** with the built-in [armbian-config](/User-Guide_Armbian-Config/) tool
- we provide advanced **hardware and OS configuration** and **software installation** with the built-in [armbian-config](User-Guide_Armbian-Config.md) tool
- we provide exclusive support for **exotic hardware** that nobody else supports
- we provide **stabilized point** and **rolling** distribution of upgrades and OS images
- we provide a global download infrastructure with **perfect coverage, also in China mainland**
@@ -115,7 +113,7 @@ Armbian distributes stable images for many different single board computers (SBC
[Platinum Support](https://www.armbian.com/download/?device_support=Platinum%20support){ .md-button .md-button--primary }
At least one person is providing constant maintainance and support.
At least one person is providing constant maintenance and support.
[Standard Support](https://www.armbian.com/download/?device_support=Standard%20support){ .md-button }
@@ -139,21 +137,9 @@ The project sources are hosted on [GitHub](https://github.com/armbian) and are o
## How can you contribute?
<!-- tbw -->
If you want to contribute to our project, please read the [collaboration notes](Process_Contribute.md).
## Software titles
You can quickly and easily install popular software! They are ready to run and optimized for Armbian. Here are few highlights:
- Desktops - install desktop environments
- Netconfig - network tools
- DevTools - development
- Benchy - system benchmaking and diagnostics
- Containers - containerization and virtual machines
- Media - media servers and editors
- Management - remote management tools
???+ success "Unit testing"

3
mkdocs.yml
View File

@@ -114,9 +114,8 @@ nav:
- 'ARMBIAN OS':
- 'Introduction': 'index.md'
- 'Getting Started' : 'User-Guide_Getting-Started.md'
- 'Configuration' : 'User-Guide_Configuration.md'
- 'Advanced Usage' :
- 'Advanced Features': 'User-Guide_Advanced-Features.md'
- 'Advanced Configuration': 'User-Guide_Advanced-Configuration.md'
- 'Networking' : 'User-Guide_Networking.md'
- 'Firstboot config': 'User-Guide_Autoconfig.md'
#- 'Device tree overlays' : 'User-Guide_Armbian_overlays.md'