-
-
Notifications
You must be signed in to change notification settings - Fork 192
Update documentation to last discussed state #760
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
48 commits
Select commit
Hold shift + click to select a range
83ed7e5
Typo fix
dleidert fcfbb8a
Typo fix
dleidert 28cf52e
Add link to collaboration guidelines
dleidert 57c3dc4
Reorder the SD cards hints
dleidert f6d8458
Use the same form in the whole document
dleidert fed823e
Comma fixes
dleidert 7ab5af2
Rephrase
dleidert 764b571
Some minor updates to the Upates section
dleidert 7adc376
Minor update to the Troubleshotting section
dleidert 2cbc84c
Minor rephrase to the report bugs section
dleidert 066a97a
Rephrase link to Configuration page
dleidert 1a6b139
Use admonition for dist-upgrade instructions
dleidert 794b5a6
Change title
dleidert 6830765
Rephrase intro into page
dleidert 6bce542
Update standard customizations
dleidert 3750cd2
Update sound section
dleidert 77c4ceb
Update sections about screen resolutions
dleidert 0f25104
Update CPU freq section
dleidert 31ab46d
Update swap section
dleidert 67beb18
Update package downgrade section
dleidert 5fdb03e
Update toogle boot output section
dleidert c178b85
Update other boot related sections
dleidert cb654e4
Disable the network configuration section
dleidert 42c6a4d
Update the APT mirror config section
dleidert cbfdac1
Move all configuration tasks into the Advanced section
dleidert b79a527
Whitespace fix
dleidert c08b537
Move kernel section and fix command
dleidert 5ffde6a
Move the example for building a driver
dleidert fad30d4
Move the docker example
dleidert ee090ce
Drop the User-Guide_Advanced-Features.md file
dleidert 471cacb
Fix links to armbian-config
dleidert 25e5c1b
Fix a bunch of links
dleidert 0082138
Drop redundant sub-section
dleidert 9852ca5
Fix a bunch of typos
dleidert 4ffe5d4
Update docs/User-Guide_Getting-Started.md
EvilOlaf e9d0646
Typo and grammatical fixes pointed out by coderabbitai
dleidert 37cc8eb
Fix markdown related issues pointed out by coderabbitai
dleidert 99231a4
Drop old section about network configuration
dleidert aa6f0b1
Move legacy info into admonition
dleidert 59abde5
Add nore about pipewire replacing pulseaudio
dleidert 0d8e84d
Add minor detail that xrandr requires a graphical session
dleidert 8539b4d
Add a bit more content to building out-of-tree modules
dleidert e6cbb34
The cpufreq workaround is for legacy versions only
dleidert 83ccb74
Clarify the situation when this workaround is necessary
dleidert 9daa1d4
Add link to armbian-config
dleidert b53de38
Merge kernel switch and downgrade and update example
dleidert 5b9d6bb
Rephrase according to coderabbitai
dleidert d97b3d7
Fix two typos discovered by the coderabbitai
dleidert File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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"` | ||
igorpecovnik marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
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. | ||
``` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.