Difference between revisions of "Getting Started with Alpine-Linux"

From FriendlyELEC WiKi
Jump to: navigation, search
(updated by API)
 
(updated by API)
 
Line 1: Line 1:
 
[[Getting Started with Alpine-Linux/zh|查看中文]]
 
[[Getting Started with Alpine-Linux/zh|查看中文]]
−
==Alpine-Linux version==
+
==Introduction to Alpine Linux==
−
* OS: Debian 12<br />
+
Alpine Linux is a lightweight Linux distribution based on musl libc and busybox, designed for security, simplicity, and efficiency. Its core is very small, containing only the most basic features, making it ideal for embedded devices, containers (such as Docker), and other resource-constrained environments. Alpine’s package manager, apk, provides fast and simple package installation and updates, supporting a wide range of software packages.<br /><br >
−
* Alpine-Linux: 8.2.7<br />
+
FriendlyElec, based on the features of Alpine Linux, offers an Alpine Linux system image built with GitHub Actions. Users can directly download and test the image or fork the repository to customize the system according to their specific needs.
−
==First Look==
+
−
[[File:Alpine-Linux.png|600px]]
+
 
==Supported platforms==
 
==Supported platforms==
−
* RK3528 (Single core)<br />
+
* RK3328<br />
−
* RK3566 (Single core)<br />
+
* RK3399<br />
 +
* RK3528<br />
 +
* RK3566<br />
 
* RK3568<br />
 
* RK3568<br />
 
* RK3588<br />
 
* RK3588<br />
−
==IP Address==
+
==Downloading the System Image==
−
The default IP address of the system is 192.168.1.200. The method to change the IP address is as follows:
+
You can download the Alpine Linux image for FriendlyElec development boards, built online using GitHub Actions, from here: <br />
−
===Change the IP address after the system starts===
+
https://github.com/friendlyarm/Actions-Alpine-Linux <br /><br />
−
For example, if your network segment is 192.168.100 and you want to set the IP address to 192.168.100.200, you can use the following command:
+
Users should select the appropriate image file based on the CPU of their development board. <br />
 +
The image file names begin with the CPU model (e.g., rk3568, rk3588), and the terms “sd” and “eflasher” in the file names represent different purposes. Their meanings are as follows: <br />
 +
* '''sd''': Used for installing the system to a TF card
 +
* '''eflasher''': Used when writing the system to eMMC via TF card
 +
==Installing Alpine Linux==
 +
===Running the System from TF Card===
 +
Download the image file with “-sd-” in the name, use your preferred flashing tool to write the image file to the TF card, then insert the TF card into the development board. Power on the board, and the Alpine Linux system will start.
 +
===Flashing the System to eMMC===
 +
Download the image file with “-eflasher-” in the name, use your preferred flashing tool to write the image file to the TF card, then insert the TF card into the development board. Power on the board, and it will automatically flash the system to eMMC. After flashing is complete, removing the TF card will trigger an automatic reboot and boot into the Alpine Linux system on eMMC.<br />
 +
If an HDMI display is connected, you can observe the flashing progress through the graphical interface. Alternatively, you can monitor the flashing progress using the onboard LED lights. For example, on the NanoPi-R5S/NanoPi-R3S/NanoPi-R5C, the LED behavior is as follows: <br />
 +
<table style="border: 1px solid black; border-collapse: collapse;">
 +
<tr style="border: 1px solid black; border-collapse: collapse;" class="header">
 +
<th style="border: 1px solid black; border-collapse: collapse;"><p>Progress</p></th>
 +
<th style="border: 1px solid black; border-collapse: collapse;"><p>SYS LED(Red)</p></th>
 +
<th style="border: 1px solid black; border-collapse: collapse;"><p>LAN LED(Green)</p></th>
 +
<th style="border: 1px solid black; border-collapse: collapse;"><p>WAN LED(Green)</p></th>
 +
</tr>
 +
<tr style="border: 1px solid black; border-collapse: collapse;" class="odd">
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Power On</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Solid On</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
</tr>
 +
<tr style="border: 1px solid black; border-collapse: collapse;" class="even">
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>System Boot</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Slow Flashing</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
</tr>
 +
<tr style="border: 1px solid black; border-collapse: collapse;" class="odd">
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Installation in Progress</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Fast Flashing</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Off</p></td>
 +
</tr>
 +
<tr style="border: 1px solid black; border-collapse: collapse;" class="even">
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Installation Done</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Slow Flashing</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Solid On</p></td>
 +
<td style="border: 1px solid black; border-collapse: collapse;"><p>Solid On</p></td>
 +
</tr>
 +
</table>
 +
==Logging into Alpine Linux==
 +
Default account: <br />
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
rm -f /etc/firstuse
+
Username: root
−
sed -i 's/new_ip=.*/new_ip=192.168.100.200/' /etc/init.d/friendlyelec_firstuse.sh
+
−
reboot
+
−
</syntaxhighlight>
+
−
The following configuration file will be modified:<br/>
+
−
/etc/resolv.conf<br/>
+
−
/etc/network/interfaces<br/>
+
−
/etc/hosts<br/>
+
−
Alpine-Linux has strict requirements for hostname configuration. Incorrect settings can prevent services from starting, so please pay special attention.
+
−
===Change the IP address before installing the system===
+
−
Insert the SD card that has been flashed with the eflasher firmware into the computer, mount the first partition of the SD card (assuming the SD card device is /dev/sdX) to /mnt using the following command:
+
−
<syntaxhighlight lang="bash">
+
−
mount /dev/sdX1 /mnt
+
−
</syntaxhighlight>
+
−
Use vi or another text editor to open the file /mnt/Alpine-Linux-arm64/info.conf, append the following line, and then use this SD card to flash the Alpine-Linux system to eMMC:
+
−
<syntaxhighlight lang="bash">
+
−
bootargs-ext=Alpine-Linux_ip=192.168.100.200
+
−
</syntaxhighlight>
+
−
The above setting saves Alpine-Linux_ip=192.168.100.200 to the kernel boot parameters, which will be read by the /etc/init.d/friendlyelec_firstuse.sh script to initialize the network settings.
+
−
==Access the Alpine-Linux web page==
+
−
In the web browser, enter https://192.168.1.200:8006. The browser may display a privacy error message; click “Advanced” and select “Proceed to site” to continue.<br />
+
−
the default login account is: <br />
+
−
<syntaxhighlight lang="bash">
+
−
UserName: root
+
 
Password: fa
 
Password: fa
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Regular account:
+
There are three methods to log into Alpine Linux:
−
<syntaxhighlight lang="bash">
+
* Serial port: Connect to the serial terminal using the following settings:
−
UserName: pi
+
{| class="wikitable"  
−
Password: pi
+
−
</syntaxhighlight>
+
−
This article uses the root user for access during testing.
+
−
==Root Login via SSH==
+
−
<syntaxhighlight lang="bash">
+
−
ssh root@192.168.1.200
+
−
</syntaxhighlight>
+
−
The initial password for the root user is fa, and the initial password for the pi user is pi.
+
−
==Creating a VM==
+
−
Only virtual machines that support EFI ACPI are supported.
+
−
===Create a virtual machine using an ISO file===
+
−
This article uses the installation of Debian as an example.<br />
+
−
First, download the live ISO file from the official Debian website: [https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/debian-12.7.0-arm64-netinst.iso], then use the scp command to upload it to the corresponding directory on the development board, windows users can use WinSCP software to upload the file:
+
−
<syntaxhighlight lang="bash">
+
−
scp debian-12.7.0-arm64-netinst.iso root@192.168.1.200:/var/lib/vz/template/iso/
+
−
</syntaxhighlight>
+
−
Click '''Create VM''' at the top of the screen，then configure the virtual machine in the wizard interface. The important settings are as follows, and you can leave the rest at their default values:
+
−
{| class="wikitable"
+
−
! Section !! Content !! Description
+
−
|-
+
−
| General || '''Name''': Feel free to fill || Provide the name of the VM
+
−
|-
+
−
| OS || '''EFI Storage''': local<br />'''ISO image''': debian-12.7.0-arm64-netinst.iso || Operating system installation image
+
 
|-
 
|-
−
| System || '''Machine''': virt<br />'''BIOS''': OVMF (UEFI)<br />'''SCSI Controller''': VirtIO-SCSI ||  
+
| Baud rate
 +
| 1500000
 
|-
 
|-
−
| Disks || '''Storage''': local || Disk storage
+
| Data bit
 +
| 8
 
|-
 
|-
−
| CPU || '''Cores''': 1 || Number of CPU cores allocated to the VM
+
| Parity check
 +
| None
 
|-
 
|-
−
| Memory || '''Memory (MiB)''': 512<br />'''Minimum memory (MiB)''': 512 || Memory allocation for the VM
+
| Stop bit
 +
| 1
 
|-
 
|-
−
| Network || '''Bridge''': wan<br />'''Model''': VirtIO (paravirtualized) || Network bridge and adapter model
+
| Flow control
 +
| None
 
|}
 
|}
−
* It is recommended to first configure the system installation using a single-core CPU before attempting to change to a multi-core setup.
+
* HDMI: Connect a display to log directly into the Alpine system.
−
* Note that due to the lack of support for heterogeneous architectures, CPU big and little cores cannot be mixed. You should either use all big cores or all little cores. Specifically, you need to explicitly specify the cores used by the virtual machine, with numbering starting from 0. For example, if certain CPUs are numbered 0-3 as big cores and you want the virtual machine to use four cores, you would enter 0,1,2,3.
+
* SSH: After connecting to the device via the network, you can log in through SSH. By default, Alpine Linux is configured only for the eth0 interface. If the development board has multiple network interfaces, connect the Ethernet cable to the WAN port (on some development boards, this may be labeled with numbers; choose the one with the smallest number).
−
* By default, the system has already created two bridges: wan and br-lan. If the virtual machine is bound to wan, it will be on the same subnet as the development board and will receive an IP address from the upstream router (in this example, it will receive an address from the 192.168.1.0/24 subnet). If the virtual machine is bound to the lan network, it will receive an IP address from the local DHCP server in the 192.168.2 subnet.
+
==Initial Setup==
−
==== Start the Virtual Machine ====
+
On the first boot, use the setup-alpine command to perform basic system configuration, including setting up the network, time zone, hostname, and other details:
−
In the left navigation pane, select the newly created virtual machine, click on “Console”, and then click “Start Now”
+
−
=== Create a Virtual Machine Using QCOW2 Disk Image File ===
+
−
The following demonstrates how to create a virtual machine using the command line and import the QCOW2 disk image file into the virtual machine. Please replace example.qcow2 with the actual file name. When downloading QCOW2 files online, make sure to choose versions with file names that contain the terms armv8, aarch64 and efi:
+
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
# download 
+
setup-alpine
−
wget https://github.com/xxx/yyy/releases/download/armv8/example-armv8-efi.qcow2 -O example.qcow2
+
−
 
+
−
# create vm with id(200)
+
−
qm create 200 --name example --memory 1024 --net0 virtio,bridge=wan --bios ovmf --cores 1 --cpu host
+
−
 
+
−
# create EFI disk for id(200)
+
−
qm set 200 --bios ovmf
+
−
qm set 200 --efidisk0 local:1
+
−
qm set 200 --boot c --bootdisk scsi0
+
−
qm set 200 --scsihw virtio-scsi-pci
+
−
 
+
−
# import img file into vm
+
−
qm importdisk 200 example.qcow2 local
+
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Return to the interface, and you will see an additional virtual machine named “example”<br />
+
==Installing Packages==
−
Select it, click on “Hardware” and double-click “Unused Disk 0” In the pop-up dialog, change the following options:<br />
+
Alpine uses the apk package manager to install software packages. You can use the following command to install the desired packages:
−
Bus/Device: '''SCSI'''<br />
+
−
SCSI Controller: '''VirtIO SCSI'''<br />
+
−
Finally, click “Add”<br />
+
−
Return to the management interface, click “Console” and then click “Start Now” to start the virtual machine.<br />
+
−
If “Display output is not active” appears, please be patient and wait.<br />
+
−
==Other==
+
−
===Increase Swap Space===
+
−
It is recommended to perform this setting for machines with 2GB of memory or less.
+
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
dd if=/dev/zero of=/swapfile bs=1M count=4096
+
apk add <package_name>
−
chmod 600 /swapfile
+
−
mkswap /swapfile
+
−
swapon /swapfile
+
−
echo "/swapfile none swap sw 0 0" >> /etc/fstab
+
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Check the status
+
For example, to install the vim editor:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
swapon --show
+
apk update
−
free -h
+
apk add vim
 
</syntaxhighlight>
 
</syntaxhighlight>
−
===Check if KVM is Enabled in the Kernel===
+
You can configure the package source by modifying the /etc/apk/repositories file.
 +
==Customizing Your Own Alpine Linux System==
 +
===Method 1: Fork the GitHub Action Project===
 +
* Fork the project: Click the link below, and click the “Fork” button in the top right corner to copy the project to your GitHub account: https://github.com/friendlyarm/Actions-Alpine-Linux
 +
* Modify the script file scripts/setup-alpine.sh, which is used to initialize the Alpine Linux system. You can customize your Alpine system by modifying this file.
 +
* Change the repository permissions: Go to the repository’s Settings -> Actions -> General -> Workflow permissions, and change the option to “Read and write permissions.”
 +
* Trigger the GitHub Actions build: By default, clicking Star will trigger the build. You can track the build progress and results via the GitHub dashboard.
 +
===Method 2: Repackage Using the Original Materials===
 +
Visit https://github.com/friendlyarm/Actions-Alpine-Linux/releases to download the file image-assets-rkXXXX.tgz (where XXXX is replaced with the specific CPU model). This file contains the filesystem and partition image files, which users can modify and repackage into a flashable firmware. For example, to repackage the firmware for the rk3528 platform: <br />
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
root@prox4nanopi:~# ls -l /dev/kvm
+
git clone https://github.com/friendlyarm/sd-fuse_rk3528 -b kernel-6.1.y
−
crw-rw---- 1 root kvm 10, 232 Oct 11 04:23 /dev/kvm
+
tar xzf image-assets-rk3528.tgz -C sd-fuse_rk3528 --strip-components=1
−
root@prox4nanopi:~# dmesg | grep kvm
+
cd sd-fuse_rk3528
−
[    7.796613] kvm [1]: IPA Size Limit: 40 bits
+
# modify rootfs
−
[    7.796627] kvm [1]: GICv3: no GICV resource entry
+
./tools/extract-rootfs-tar.sh rootfs.tgz
−
[    7.796631] kvm [1]: disabling GICv2 emulation
+
echo "hello" > rootfs/root/welcome.txt
−
[    7.796642] kvm [1]: GIC system register CPU interface enabled
+
# re-package rootfs.img
−
[    7.796755] kvm [1]: vgic interrupt IRQ9
+
./build-rootfs-img.sh rootfs alpine-linux-arm64
−
[    7.796959] kvm [1]: VHE mode initialized successfully
+
# download kernel source code
 +
git clone https://github.com/friendlyarm/kernel-rockchip -b nanopi6-v6.1.y kernel --depth 1
 +
cat > kernel/arch/arm64/configs/custom.config<<EOL
 +
CONFIG_ANDROID_LOW_MEMORY_KILLER=n
 +
CONFIG_ANDROID_BINDER_IPC=y
 +
CONFIG_ANDROID_BINDERFS=y
 +
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder,anbox-binder,anbox-hwbinder,anbox-vndbinder"
 +
EOL
 +
# check default defconfig
 +
grep "KCFG:=" ./build-kernel.sh
 +
# re-build kernel with customize config
 +
KCFG="nanopi5_linux_defconfig kvm.config custom.config" kernel_src=kernel ./build-kernel.sh alpine-linux-arm64
 +
# re-package sdraw image
 +
./mk-sd-image.sh alpine-linux-arm64
 +
# re-package sd-to-emmc image (Select Y when asking whether to download the eflasher file.)
 +
./mk-emmc-image.sh alpine-linux-arm64
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
==Alpine Linux Official Documentation==
 +
For more Alpine Linux usage guides, please refer to the official documentation: <br />
 +
https://wiki.alpinelinux.org/

Latest revision as of 05:54, 14 March 2025

查看中文

1 Introduction to Alpine Linux

Alpine Linux is a lightweight Linux distribution based on musl libc and busybox, designed for security, simplicity, and efficiency. Its core is very small, containing only the most basic features, making it ideal for embedded devices, containers (such as Docker), and other resource-constrained environments. Alpine’s package manager, apk, provides fast and simple package installation and updates, supporting a wide range of software packages.

FriendlyElec, based on the features of Alpine Linux, offers an Alpine Linux system image built with GitHub Actions. Users can directly download and test the image or fork the repository to customize the system according to their specific needs.

2 Supported platforms

  • RK3328
  • RK3399
  • RK3528
  • RK3566
  • RK3568
  • RK3588

3 Downloading the System Image

You can download the Alpine Linux image for FriendlyElec development boards, built online using GitHub Actions, from here:
https://github.com/friendlyarm/Actions-Alpine-Linux

Users should select the appropriate image file based on the CPU of their development board.
The image file names begin with the CPU model (e.g., rk3568, rk3588), and the terms “sd” and “eflasher” in the file names represent different purposes. Their meanings are as follows:

  • sd: Used for installing the system to a TF card
  • eflasher: Used when writing the system to eMMC via TF card

4 Installing Alpine Linux

4.1 Running the System from TF Card

Download the image file with “-sd-” in the name, use your preferred flashing tool to write the image file to the TF card, then insert the TF card into the development board. Power on the board, and the Alpine Linux system will start.

4.2 Flashing the System to eMMC

Download the image file with “-eflasher-” in the name, use your preferred flashing tool to write the image file to the TF card, then insert the TF card into the development board. Power on the board, and it will automatically flash the system to eMMC. After flashing is complete, removing the TF card will trigger an automatic reboot and boot into the Alpine Linux system on eMMC.
If an HDMI display is connected, you can observe the flashing progress through the graphical interface. Alternatively, you can monitor the flashing progress using the onboard LED lights. For example, on the NanoPi-R5S/NanoPi-R3S/NanoPi-R5C, the LED behavior is as follows:

Progress

SYS LED(Red)

LAN LED(Green)

WAN LED(Green)

Power On

Solid On

Off

Off

System Boot

Slow Flashing

Off

Off

Installation in Progress

Fast Flashing

Off

Off

Installation Done

Slow Flashing

Solid On

Solid On

5 Logging into Alpine Linux

Default account: 

Username: root
Password: fa

There are three methods to log into Alpine Linux:

  • Serial port: Connect to the serial terminal using the following settings:
Baud rate 1500000
Data bit 8
Parity check None
Stop bit 1
Flow control None
  • HDMI: Connect a display to log directly into the Alpine system.
  • SSH: After connecting to the device via the network, you can log in through SSH. By default, Alpine Linux is configured only for the eth0 interface. If the development board has multiple network interfaces, connect the Ethernet cable to the WAN port (on some development boards, this may be labeled with numbers; choose the one with the smallest number).

6 Initial Setup

On the first boot, use the setup-alpine command to perform basic system configuration, including setting up the network, time zone, hostname, and other details: 

setup-alpine

7 Installing Packages

Alpine uses the apk package manager to install software packages. You can use the following command to install the desired packages: 

apk add <package_name>

For example, to install the vim editor: 

apk update
apk add vim

You can configure the package source by modifying the /etc/apk/repositories file.

8 Customizing Your Own Alpine Linux System

8.1 Method 1: Fork the GitHub Action Project

  • Fork the project: Click the link below, and click the “Fork” button in the top right corner to copy the project to your GitHub account: https://github.com/friendlyarm/Actions-Alpine-Linux
  • Modify the script file scripts/setup-alpine.sh, which is used to initialize the Alpine Linux system. You can customize your Alpine system by modifying this file.
  • Change the repository permissions: Go to the repository’s Settings -> Actions -> General -> Workflow permissions, and change the option to “Read and write permissions.”
  • Trigger the GitHub Actions build: By default, clicking Star will trigger the build. You can track the build progress and results via the GitHub dashboard.

8.2 Method 2: Repackage Using the Original Materials

Visit https://github.com/friendlyarm/Actions-Alpine-Linux/releases to download the file image-assets-rkXXXX.tgz (where XXXX is replaced with the specific CPU model). This file contains the filesystem and partition image files, which users can modify and repackage into a flashable firmware. For example, to repackage the firmware for the rk3528 platform: 

git clone https://github.com/friendlyarm/sd-fuse_rk3528 -b kernel-6.1.y
tar xzf image-assets-rk3528.tgz -C sd-fuse_rk3528 --strip-components=1
cd sd-fuse_rk3528
# modify rootfs
./tools/extract-rootfs-tar.sh rootfs.tgz
echo "hello" > rootfs/root/welcome.txt
# re-package rootfs.img
./build-rootfs-img.sh rootfs alpine-linux-arm64
# download kernel source code
git clone https://github.com/friendlyarm/kernel-rockchip -b nanopi6-v6.1.y kernel --depth 1
cat > kernel/arch/arm64/configs/custom.config<<EOL
CONFIG_ANDROID_LOW_MEMORY_KILLER=n
CONFIG_ANDROID_BINDER_IPC=y
CONFIG_ANDROID_BINDERFS=y
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder,anbox-binder,anbox-hwbinder,anbox-vndbinder"
EOL
# check default defconfig
grep "KCFG:=" ./build-kernel.sh
# re-build kernel with customize config
KCFG="nanopi5_linux_defconfig kvm.config custom.config" kernel_src=kernel ./build-kernel.sh alpine-linux-arm64
# re-package sdraw image
./mk-sd-image.sh alpine-linux-arm64
# re-package sd-to-emmc image (Select Y when asking whether to download the eflasher file.)
./mk-emmc-image.sh alpine-linux-arm64

9 Alpine Linux Official Documentation

For more Alpine Linux usage guides, please refer to the official documentation:
https://wiki.alpinelinux.org/

Retrieved from "https://wiki.friendlyelec.com/wiki/index.php?title=Getting_Started_with_Alpine-Linux&oldid=26746"