diff --git a/docs/User-Guide_Getting-Started.md b/docs/User-Guide_Getting-Started.md index b4cd9d16..4dc87169 100644 --- a/docs/User-Guide_Getting-Started.md +++ b/docs/User-Guide_Getting-Started.md @@ -3,7 +3,7 @@ Before you start, please make sure you have: - a proper power supply according to the board manufacturer requirements -- a reliable SD card +- a reliable SD card You will also need an existing operating system and a SD card writer tool. We recommend using [balenaEtcher](https://www.balena.io/etcher/) or [USBImager](https://gitlab.com/bztsrc/usbimager) because these tools can validate written data **saving you from corrupted SD card contents**. @@ -16,48 +16,14 @@ You will also need an existing operating system and a SD card writer tool. We re Some word of advice, though. The video has been created a few years ago. You might therefore find differences between this video and our current site. So, in doubt, also follow the sections below while watching the video. -## What to download +## Download the Image -The download for each image consists of three separate files: +All our images can be found at . You will find, that there are different types of images, either using Debian GNU/Linux or Ubuntu as their base operating system. -- **.xz** compressed image file -- **.sha file** for download verification (optional) -- **.asc file** for image authentication (optional) + -!!! question "How to check download authenticity?" - All our images are digitally signed and therefore it is possible to check their authenticity. You need to issue these commands (Linux/macOS, you might need to install dependencies first, eg. `sudo apt-get install gnupg ` on Debian/Ubuntu or `brew install gnupg ` on macOS. on windows install the current simple gnupg [Gnupg](https://gnupg.org/download/): - - ```sh - # 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 - - # 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) " - ``` - It is safe to ignore the message `WARNING: This key is not certified with a trusted signature!`. - -!!! question "How to check download integrity?" - - Since it might happen that your download got somehow corrupted we integrate a checksum/hash for the image. You can compare the image's SHA-256 hash with the one contained in the `sha256sum.sha` file. - - On Windows, you can download and use the [QuickHash GUI](https://www.quickhash-gui.org/download/quickhash-v3-1-0-windows/) and follow the instructions in the gui. - - 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 - - #good response - Armbian_5.35_Clearfogpro_Debian_stretch_next_4.13.16.img: OK - ``` +### Minimal, Server, and Desktop? For each board we usually provide various image types: @@ -67,27 +33,32 @@ For each board we usually provide various image types: For some boards we provide only minimal images due to their hardware limitations. + ### Debian or Ubuntu? -If you have no special preferences that require specific versions, we recommend Ubuntu based Armbian. +If you have no special preferences or requirements, we recommend Ubuntu based Armbian. -### Vendor, current? -In some cases we provide images with different firmware. They differ in level of hardware support. Focus into: +### Vendor, Current, Edge, or Legacy? -- **vendor** contains vendor provided kernel which usually has best hardware support while version can be outdated, containin less general fixes -- **current** is following latest [mainline LTS kernel](https://www.kernel.org/category/releases.html) and is in most cases best choice +In some cases we provide images with different firmware. They differ in the level of hardware support. Focus into: -And use those if they are the only one / for testings: +- **vendor** contains a vendor-provided kernel which usually has the best hardware support while package version can be outdated, containing less general fixes +- **current** is following the latest [mainline LTS kernel](https://www.kernel.org/category/releases.html) and is in most cases the best choice. -- **edge** is as the name implies cutting-edge fresh / development / latest stable. It is only automatically tested and can break at any time. Recommended for experienced users. -- **legacy** is old stable current kernel. Use if either _current_ is not available or something does not work well with it. +Further, if the following images are the only ones provided, or if you want to participate in testing: + +- **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 an other kernel included or change kernel within [armbian-config](/User-Guide_Armbian-Config). ### Rolling releases? -Rolling releases are suitable for Linux enthusiasts who want cutting edge packages and have the skills to fix damage that a bad update might cause. If you want stability in a production environment or low headaches as a novice user, skip rolling releases. They are only at, build and ship, Debian testing / Arch / Manjaro / Suse Tumbleweed / Kali / Gentoo support quality level! + + +Rolling releases are suitable for Linux enthusiasts who want cutting edge packages and have the skills to fix the damage that a bad update might cause. If you want stability in a production environment or low headaches as a novice user, skip rolling releases. They are not at a suitable support quality level! ``` mermaid graph LR @@ -100,8 +71,8 @@ graph LR B -->|vendor| X["point release"]; B -->|current| X["point release"]; B -->|edge| X["point release"]; - - + + C ---->|minimal| E[Debian or Ubuntu]; C ---->|server| F[Debian or Ubuntu]; C ---->|desktop| G[Debian or Ubuntu]; @@ -113,9 +84,75 @@ graph LR !!! danger - **Do not use** rollling or edge images in a productive environment. Their purpose is testing and providing constructive [feedback to developers](https://forum.armbian.com/forum/4-development/). + **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 + +After you have determined the image you want, the download for each image consists of three separate files: + +- the **.xz** compressed image file +- the **.sha file** for download verification (optional) +- the **.asc file** for image authentication (optional) + +After you have downloaded these files, we recommend checking the integrity and the authenticity of the compressed image file. + +!!! question "How to check download integrity?" + + Since it might happen that your download got somehow corrupted, we publish a checksum/hash for each of our images. You can compare the image's SHA-256 hash with the one contained in the `.sha` file. + + On Windows, you can download and use the [QuickHash GUI](https://www.quickhash-gui.org/download/quickhash-v3-1-0-windows/) and follow the instructions in the gui. Linux and macOS users can simply do this in the directory with the compressed image and the checksum file: + + ```sh + sha256sum -c Armbian_25.2.1_Bananapicm4io_bookworm_current_6.12.13_minimal.img.xz.sha + ``` + + The integrity is verified if the output looks something like this: + + ```sh + Armbian_25.2.1_Bananapicm4io_bookworm_current_6.12.13_minimal.img.xz: OK + ``` + +!!! question "How to check download authenticity?" + + All our images are digitally signed. It is therefore possible to check their authenticity. Linux and macOS user might need to install the required tools first: for Debian/Ubuntu, this can be done via `sudo apt-get install gnupg `, and for macOS use `brew install gnupg ` on macOS. Windows users can install the [GnuPG from here](https://gnupg.org/download/). To check the authenticity, you will need the public key that was used to sign the images. This key can be retrieved from a keyserver or from the Debian/Ubuntu package repository (this step only needs to be done once): + + ```sh + # download the public key either from a keyserver + gpg --keyserver hkp://keyserver.ubuntu.com --recv-key DF00FAF1C577104B50BF1D0093D6889F9F0E78D5 + # or from the repository server + wget -O- https://apt.armbian.com/armbian.key | gpg --import - + ``` + + To perform the verfification, run the command shown below. + + ```sh + gpg --verify Armbian_25.2.1_Bananapicm4io_bookworm_current_6.12.13_minimal.img.xz.asc + ``` + + While the output can very depending on the GnuPG version, it should result in a response similar to the one below. It is safe to ignore the message `WARNING: This key is not certified with a trusted signature!`. + + ```sh + gpg: Signature made Thu Feb 13 11:53:18 2025 CET + gpg: using RSA key DF00FAF1C577104B50BF1D0093D6889F9F0E78D5 + gpg: Good signature from "Igor Pecovnik " [unknown] + gpg: aka "Igor Pecovnik (Ljubljana, Slovenia) " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: DF00 FAF1 C577 104B 50BF 1D00 93D6 889F 9F0E 78D5 + ``` + + If something is wrong, the output will look something like this: + + ```sh + gpg: Signature made Thu Feb 13 11:53:18 2025 CET + gpg: using RSA key DF00FAF1C577104B50BF1D0093D6889F9F0E78D5 + gpg: BAD signature from "Igor Pecovnik " [unknown] + ``` + + +## Deploy the Image -## Preparing SD card **Important note:** Make sure you use a **good, reliable and fast** SD card. If you encounter boot or stability troubles in over 95 percent of the time it is either insufficient power supply or related to SD card (bad card, bad card reader, something went wrong when burning the image, card too slow to boot -- 'Class 10' 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 in 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 **highly recommended**.