Skip to content
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions docs/boot_multiple_kernel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Using Multiple Kernels on SBC with Armbian via SD Cards

A common and effective way to use multiple kernels on a single-board computer (SBC) running Armbian is to use separate SD cards. This method is especially useful for testing new kernels, different versions of a kernel, or different Linux distributions without risking your primary, stable system. It also simplifies the process by leveraging the standard SBC boot sequence, which typically checks for a bootable SD card first.

This tutorial will walk you through the process of setting up multiple SD cards with different Armbian kernels.

---

## Prerequisites

Before you begin, you'll need a few things:

- **Your SBC**: A compatible single-board computer (e.g., Orange Pi, Rock Pi, Odroid).
- **Multiple SD cards**: One for each kernel or system you want to run. Use reliable, high-speed cards from a reputable brand.
- **A computer** to write the images to the SD cards.
- **A reliable power supply** for your SBC.
- **Armbian images**: The specific Armbian images for your board, each with the desired kernel version (`current`, `edge`, or `legacy`). You can download these from the [official Armbian website](https://www.armbian.com/download/).

---

## Step 1: Prepare the SD Cards 💾

Each SD card must be flashed with a different Armbian image.

1. **Download the Images**
Go to the official Armbian download page and find the images for your specific SBC model.
Example: one with the `current` kernel and another with the `edge` kernel.

2. **Flash the SD Cards**
Use a flashing tool like **BalenaEtcher** or the `dd` command-line utility.

### Using BalenaEtcher
- Insert an SD card into your computer.
- Open Etcher, select the downloaded Armbian image file.
- Select your SD card from the list of drives.
- Click **Flash!** to start the process.
- Repeat for each SD card and image.

### Using `dd` (Linux/macOS users)
- Unzip the Armbian image file (`.xz`).
- Identify your SD card's device name with `lsblk` or `diskutil list`.
- Run:
```bash
sudo dd if=/path/to/armbian-image.img of=/dev/sdX bs=1M status=progress && sync
```
Replace `/path/to/armbian-image.img` and `/dev/sdX` with the correct path and device name.
- **Be extremely careful** to select the right device to avoid data loss.
Comment on lines +39 to +47
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix dd instructions for macOS compatibility; split Linux/macOS with correct flags and steps

The current dd example won’t work on macOS (BSD dd doesn’t support status=progress and typically uses bs=1m; device is /dev/rdiskN). Also, “Unzip” is inaccurate for .xz images—use “decompress”. Propose a precise, safe rewrite.

-   ### Using `dd` (Linux/macOS users)
-   - Unzip the Armbian image file (`.xz`).  
-   - Identify your SD card's device name with `lsblk` or `diskutil list`.  
-   - Run:  
-     ```bash
-     sudo dd if=/path/to/armbian-image.img of=/dev/sdX bs=1M status=progress && sync
-     ```  
-     Replace `/path/to/armbian-image.img` and `/dev/sdX` with the correct path and device name.  
-   - **Be extremely careful** to select the right device to avoid data loss.  
+   ### Using `dd` (advanced)
+   - Decompress the image first if using `dd` (Etcher can flash `.xz` directly):
+     ```bash
+     unxz /path/to/armbian-image.img.xz
+     ```
+   - Identify your SD card device:
+     - Linux: `lsblk` (device looks like `/dev/sdX` or `/dev/mmcblkX`)
+     - macOS: `diskutil list` (device looks like `/dev/diskN` and raw `/dev/rdiskN`)
+   - Linux (GNU dd):
+     ```bash
+     sudo dd if=/path/to/armbian-image.img of=/dev/sdX bs=4M conv=fsync status=progress
+     ```
+   - macOS (BSD dd):
+     ```bash
+     diskutil unmountDisk /dev/diskN
+     sudo dd if=/path/to/armbian-image.img of=/dev/rdiskN bs=1m ; sync
+     # Tip: press Ctrl+T to see progress on macOS, or install coreutils and use `gdd ... status=progress`
+     ```
+     Replace `/path/to/armbian-image.img`, `/dev/sdX`, `/dev/diskN`, and `/dev/rdiskN` with your actual paths/devices.
+   - Double-check the device path to avoid data loss.
🧰 Tools
🪛 LanguageTool

[style] ~47-~47: As an alternative to the over-used intensifier ‘extremely’, consider replacing this phrase.
Context: ...rrect path and device name. - Be extremely careful to select the right device to avoid d...

(EN_WEAK_ADJECTIVE)

🪛 markdownlint-cli2 (0.17.2)

39-39: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


43-43: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)


45-45: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents
In docs/boot_multiple_kernel.md around lines 39-47, the dd instructions are
inaccurate for macOS and the .xz step is mislabeled as "Unzip"; update the
section to (1) say "decompress .xz" (or recommend Etcher) rather than "unzip",
(2) split Linux and macOS commands with correct device names and flags: for
Linux recommend GNU dd with bs=4M conv=fsync status=progress, and for macOS
instruct to unmount the disk with diskutil, target the raw device (/dev/rdiskN),
use BSD dd with bs=1m and run sync afterwards (or suggest installing
coreutils/gdd to get status=progress), and (3) keep a clear warning to
double-check the target device to avoid data loss.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good to me

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@leggewie Thank you for confirming! The suggested changes will help make the dd instructions much more accurate and usable for both Linux and macOS users. The split approach with platform-specific commands, proper device naming conventions, and the correction about decompressing .xz files (rather than "unzipping") will definitely improve the documentation quality.

  /|   /|  
 ( :v:  )
  |(_)|
 /     \
/       \

/_________\


If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!


---

## Step 2: Initial Boot and Configuration ⚙️

After flashing, each SD card is a self-contained, bootable system.

1. **Insert and Boot**
Insert one SD card into your SBC and connect power. The SBC’s bootloader (usually U-Boot) will detect and boot from it.

2. **Initial Setup**
On first boot, Armbian will:
- Resize the filesystem
- Prompt for a root password
- Prompt to create a new user

Complete these steps for each SD card.

3. **Shut Down and Swap**
- Power down the SBC.
- Remove the first SD card.
- Insert the second SD card.
- Repeat the boot and setup process.

---

## Step 3: Managing and Using Different Kernels 🧑💻

Now you have multiple independent systems on separate SD cards.

- **Swapping SD Cards**
To switch kernels, power down, swap SD cards, and power back up. The bootloader handles everything automatically.

- **Testing and Development**
- Use one SD card for a stable, “production” kernel.
- Use another for experimental or development kernels.
- If something fails, swap back to your stable card instantly.

- **Kernel Version Management**
While Armbian’s `armbian-config` tool allows kernel management inside a single installation, using separate SD cards gives **full isolation**.
This prevents conflicts between kernel versions and ensures a clean test environment.

---