diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..c72e22c7 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,7 @@ +{ + "MD013": false, + "MD046": false, + "MD033": { + "allowed_elements": ["br", "iframe"] +} +} \ No newline at end of file diff --git a/docs/User-Guide_Autoconfig.md b/docs/User-Guide_Autoconfig.md index fad55ac3..e76a24a2 100644 --- a/docs/User-Guide_Autoconfig.md +++ b/docs/User-Guide_Autoconfig.md @@ -2,7 +2,7 @@ ## 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. +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` @@ -12,48 +12,48 @@ After flashing an image to boot media, mount it and add a file containing your c ## 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: -```bash + +```bash title="/root/.not_logged_in_yet" PRESET_CONFIGURATION="http://path/to/config/file" ``` ## Configuration directives - - The directives in this file are specified using `key="value"` format. - To ask for a value interactively, leave it unset or comment out the directive. - For fully-unattended setup, specify all values -| Configuration directive | `[default] | option` | Description: | +| Configuration directive | `[default]` \| `option` | Description: | | :---------------------- | :--------------: | -----------: | -| `PRESET_CONFIGURATION` | `http://path/to/config/file` | See [Loading a remote config](#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_CONFIGURATION` | `http://path/to/config/file` | See [Loading a remote config](#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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | -| `PRESET_NET_USE_STATIC` | `[0] 1` | Use the static IP provided, DHCP is the default; leaving **any** value unset will result in a broken config | +| `PRESET_NET_WIFI_COUNTRYCODE` | `CC` | Country code, **required** for WiFi
e.g. `GB`, `US`, `DE`; see [Wikipedia/ISO_3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | +| `PRESET_CONNECT_WIRELESS` | `Y` \| `n` | Set to `Y` for interactive mode, `n` uses values from file | +| `PRESET_NET_USE_STATIC` | `[0]` \| `1` | Use the static IP provided, DHCP is the default
Leaving **any** value unset will result in a broken config | | `PRESET_NET_STATIC_IP` | `xxx.xxx.xxx.xxx` | Static IPv4 address, dotted decimal notation | | `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 -| `PRESET_NET_STATIC_DNS` | `x.x.x.x x.x.x.x` | DNS Servers to use, separated by a space. If unsure, CloudFlare is `1.1.1.1 1.0.0.1`, Google is `8.8.8.8 8.8.4.4` | -| `PRESET_USER_SHELL` | `shell` | Currently only `bash` (default) or `zsh` (`armbian-zsh`) supported | -| `PRESET_CONNECT_WIRELESS` | `Y | n` | Set to `Y` for interactive mode, `n` for automatic | -| `SET_LANG_BASED_ON_LOCATION` | `Y | n` | "Set user language based on your location?" | +| `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 a space. 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?" | | `PRESET_LOCALE` | `locale` | Locale e.g. `en_GB.UTF-8`, `de_DE.UTF-8`, `zh_TW.UTF-8` | | `PRESET_TIMEZONE` | `timezone` | Timezone e.g. `Etc/UTC`, | -| `PRESET_ROOT_PASSWORD` | `[1234] | password` | Preset `root` password, **stored in plaintext**, *SSH keys are safer!* | +| `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_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 | ## Sample config file The following is an example configuration, it may be used as a template -```bash + +```bash title="/root/.not_logged_in_yet" #/root/.not_logged_in_yet # Network Settings PRESET_NET_CHANGE_DEFAULTS="1" @@ -87,10 +87,8 @@ 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](https://github.com/armbian/build/pull/6194). diff --git a/docs/User-Guide_Getting-Started.md b/docs/User-Guide_Getting-Started.md index 8f59c0c8..067182f4 100644 --- a/docs/User-Guide_Getting-Started.md +++ b/docs/User-Guide_Getting-Started.md @@ -9,7 +9,7 @@ - a proper power supply according to the board manufacturer requirements - a reliable SD card (see below "How to prepare a SD card?") -### What to download? +## What to download? The download for each image consists of three separate files: @@ -25,15 +25,15 @@ The download for each image consists of three separate files: # download public key from the database gpg --keyserver hkp://keyserver.ubuntu.com --recv-key DF00FAF1C577104B50BF1D0093D6889F9F0E78D5 # perform verification - gpg --verify Armbian_5.18_Armada_Debian_jessie_3.10.94.img.xz.asc + gpg --verify Armbian_5.18_Armada_Debian_jessie_3.10.94.img.xz.asc # proper response gpg: Signature made sob 09 jan 2016 15:01:03 CET using RSA key ID 9F0E78D5 gpg: Good signature from "Igor Pecovnik (Ljubljana, Slovenia) " - # wrong reponse. Not genuine Armbian image! - gpg: Signature made Sun 03 Jan 2016 11:46:25 AM CET using RSA key ID 9F0E78D5 - gpg: BAD signature from "Igor Pecovnik (Ljubljana, Slovenia) " + # wrong reponse. Not genuine Armbian image! + gpg: Signature made Sun 03 Jan 2016 11:46:25 AM CET using RSA key ID 9F0E78D5 + gpg: BAD signature from "Igor Pecovnik (Ljubljana, Slovenia) " ``` It is safe to ignore the message `WARNING: This key is not certified with a trusted signature!`. @@ -46,10 +46,10 @@ The download for each image consists of three separate files: while on Linux/macOS, in the directory in which you have downloaded the files ,you would do this ```sh - shasum -a 256 -c Armbian_*.img.sha + shasum -a 256 -c Armbian_*.img.sha - #good response - Armbian_5.35_Clearfogpro_Debian_stretch_next_4.13.16.img: OK + #good response + Armbian_5.35_Clearfogpro_Debian_stretch_next_4.13.16.img: OK ``` For each board we usually provide various image types: @@ -114,7 +114,6 @@ graph LR Write the **.xz compressed image** with a tool [USBImager](https://gitlab.com/bztsrc/usbimager) or [balenaEtcher](https://www.balena.io/etcher/) on all platforms since, unlike other tools, either can validate written data **saving you from corrupted SD card contents**. - !!! 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. @@ -138,6 +137,9 @@ Insert SD card into a slot and power the board. (First) boot (with DHCP) takes u First boot will log you automatically on HDMI or serial console while for SSH login you need to login as **root** and use password **1234**. You will be prompted to change this password. You will then be asked to create a normal user account that is sudo enabled (beware of default QWERTY keyboard settings at this stage). Please use [this tool](https://angryip.org/), to find your board IP address. +???+ tips "Automated config" + These settings can be pre-loaded, see [Autoconfig](/User-Guide_Autoconfig) + In case you have no wired network connection and there is a wireless adaptor detected, it will prompt you to connect. Welcome to Armbian! @@ -203,7 +205,7 @@ In case you have no wired network connection and there is a wireless adaptor det Start the install script and follow the lead: - armbian-install + armbian-install !!! tip "Armbian installer provides those scenarios:" @@ -225,8 +227,8 @@ Start the install script and follow the lead: ### Armbian OS? - apt update - apt upgrade + apt update + apt upgrade **Update process can take some time in case of using old & cheap SD card and/or under heavy load.** @@ -252,7 +254,6 @@ Armbian provides firmware package freeze to give you an option to upgrade all pa When a new userspace is out, we recommend to start with a fresh image. However, it is possible to upgrade, but the process is largerly in the domain of underlaying Debian or Ubuntu user space. However we provide experimental `Distribution upgrades` within [armbian-config](/User-Guide_Armbian-Config) - !!! danger Userspaces distribution upgrades are neither tested nor supported. Therefore Armbian cannot provide support if something goes wrong.