SD card
This page provides an overview for OpenWrt installation via an SD card. Common devices that use this procedure include Raspberry Pi and NanoPi.
Graphical Utilities
Install Balena Etcher, a free open source program to flash SD cards on Windows, Linux, or macOS.
- Download the correct image for your device which will be named similar to
openwrt-*-sysupgrade.img.gz
. - Select the image.
- Select your SD card.
- Flash the image.
Command Line
- Download the image for your device which will be named similar to
openwrt-*-sysupgrade.img.gz
. - Decompress it:
gzip -d openwrt-*-sysupgrade.img.gz
- Connect SD card to your computer and look at
lsblk
ordmesg
to identify it. In most cases, it would be something like/dev/sdX
. 1) - Double check that you have identified your sd card correctly. If the
/dev/sdX
you have chosen, corresponds to your harddrive, the next step would destroy your system - Copy the image to the SD card with:
dd if=openwrt-*-sysupgrade.img of=/dev/sdX
Which image to chose?
Often a device has multiple images available which differ in the filesystem used.
ext4-sdcard.img.gz
- not optimized for flash memory (journaling increases flash wear)
- SD card can be easily mounted externally for modification
- updates and changes can be made directly to the partition
- Linux desktop standard
squashfs-sdcard.img.gz
- compressed
- newer images include a hidden f2fs filesystem, which is optimized for flash memory
- needs special mount procedure to externally modify
- all changes are done in an overlay partition
- due to overlay partition it is simple to reset system to defaults
other images
- ubifs-sdcard.img.gz
Mounting a squashfs filesystem locally
If you insert your newly flashed SD card into a Linux machine, it will be easy to mount the read only squashfs partition but it won't know about the overlay, which is not even in the partition table but instead located immediately after the squashfs filesystem in the same partition. You therefore need to mount the overlay as a loopback device. You can discover the offset by running losetup on the device, or calculate the offset yourself by inspecting the filesystem.
# Setup the loop back device.
# See libfstools/rootdisk.c for source of partition offset logic.
DEVICE= ### Set this appropriately - e.g. /dev/sda
PARTITION="$DEVICE"2
FS_SIZE="$(sudo unsquashfs -s "$PARTITION" | grep -o 'Filesystem size [0-9]* bytes' | grep -o '[0-9][0-9]*')"
FS_OFFSET="$(expr '(' "$FS_SIZE" + 65535 ')' / 65536 '*' 65536)"
LOOP_DEVICE="$(sudo losetup -f --show -o "$FS_OFFSET" "$PARTITION")"
# Now mount both partitions (remember, you may need to unmount any automatic mounts)
mkdir -p /mnt/base /mnt/overlay /mnt/combined
sudo mount "$PARTITION" /mnt/base
sudo mount "$LOOP_DEVICE" /mnt/overlay
sudo mount -o noatime,lowerdir=/mnt/base,upperdir=/mnt/overlay/upper,workdir=/mnt/overlay/work -t overlay overlayfs /mnt/combined
This should leave you with a writable filesystem in /mnt/combined which will work as it does on OpenWRT.
Expanding the filesystem
To use the whole available space of your sdcard, you probably have to resize your partition.
squashfs image
As with mounting the overlay above, to resize it you'll need the offset of the hidden f2fs or ext4 filesystem (depending on the size of your image, one or the other will be used).
First, make sure the partition is not mounted, then do something like:
DEVICE= ### Set this appropriately - e.g. /dev/sda PARTITION="$DEVICE"2 sudo cfdisk "$DEVICE" # select resize, then write # Create a loop device pointing to the FS # See libfstools/rootdisk.c for source of partition offset logic. FS_SIZE="$(sudo unsquashfs -s "$PARTITION" | grep -o 'Filesystem size [0-9]* bytes' | grep -o '[0-9][0-9]*')" FS_OFFSET="$(expr '(' "$FS_SIZE" + 65535 ')' / 65536 '*' 65536)" LOOP_DEVICE="$(sudo losetup -f --show -o "$FS_OFFSET" "$PARTITION")" # Now, resize... you may need to fsck first, though. sudo fsck "$LOOP_DEVICE" sudo resize2fs "$LOOP_DEVICE"
ext4 image
You can use gparted to resize and extend the partitions. To do it online, follow the procedure in link or link.
Example, to resize /dev/mmcblk0p2
mounted on /
, install parted
, tune2fs
and resize2fs
then:
parted p resizepart 2 32GB q
Next, you may need to repair your device (perhaps say yes to all interactive queries):
mount -o remount,ro / #Remount root as Read Only tune2fs -O^resize_inode /dev/mmcblk0p2 #Remove reserved GDT blocks fsck.ext4 /dev/mmcblk0p2 #Fix part, answer yes to remove GDT blocks remnants
Now, reboot
and then resize the partition:
resize2fs /dev/mmcblk0p2
Manual disk image assembly
Examples:
Howto:
- Partition and format the SD card. Details devicespecific? → Devicepage
- Copy bootloader, kernel, rootfs (and if necessary other data) to SD card. Details devicespecific? → Devicepage
- Possibly resize filesystem in order to use the complete available space on the SD card
/dev/sdX
and not /dev/sdX1