Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
docs:guide-user:installation:openwrt_x86 [2022/09/28 21:52] – [Download disk images] joshendersdocs:guide-user:installation:openwrt_x86 [2023/12/12 11:24] – [Expanding root partition] optimize code vgaetera
Line 38: Line 38:
  
 NVMe SSD support is available since OpenWrt 21.02. NVMe SSD support is available since OpenWrt 21.02.
 +
 +===== Packages to consider on x86 =====
 +OpenWrt has a minimalist philosophy regarding packaging strategy due to limited space on embedded devices.  For many x86 machines, disk space is likely not a limiting factor.  Users coming from desktop distros where thousand of modules are provided in the default image, might be surprised to see that on OpenWrt, the default number of drivers is also minimal.  Therefore, it may be necessary to identify and obtain the needed modules for things like: storage controllers (SATA/USB etc.), sound module, crypto modules, video modules, etc.
 +
 +One strategy to identify needed modules is to boot into a live Linux distro (for example [[https://archlinux.org/download|Arch Linux]]) and inspect the output of ''lsmod'' or ''lspci -vvv | grep driver'' and then search for corresponding OpenWrt kmod packages.
 +
 +Another option if building your own image is to build all modules ''ALL_KMODS=y'' and see what works.  Newer hardware may not be supported out-of-the-box.
 +
 +Beyond the kmods, some common packages to consider installing on x86 are listed below:
 +  * For CPU/APU microcode updates for AMD processors, [[:packages:pkgdata:amd64-microcode]] and for Intel processors, [[:packages:pkgdata:intel-microcode]].
 +  * For disk monitoring, [[:packages:pkgdata_owrt21_2:smartmontools]], see: [[:docs:guide-user:additional-software:smartmontools]]
 +  * For hardware monitoring, [[:packages:pkgdata:lm-sensors]]
 +  * For hardware watchdog support, see: [[:docs:guide-user:hardware:watchdog]]
 +  * For kernel entropy, [[:packages:pkgdata:rng-tools]], see: [[:docs:guide-user:services:rng]]
  
 ===== Installation ===== ===== Installation =====
Line 46: Line 60:
 Installation procedure differs depending from what OS you are using to write the raw disk image from, mostly because of different tools you have to use. Installation procedure differs depending from what OS you are using to write the raw disk image from, mostly because of different tools you have to use.
  
-<WRAP center round important 80%+<WRAP important> 
-**WARNING: writing raw image files DELETES the content of the drive you write them on,** be sure that you are not deleting anything important, and that you have selected the right drive.+Writing raw image files DELETES the content of the drive you write them on
 +Be sure to select the correct drive so you do not delete anything important.
 </WRAP> </WRAP>
  
Line 77: Line 92:
 </code> </code>
  
-===== Installing OpenWrt in an internal drive ===== +===== Installing OpenWrt on an internal drive ===== 
-If you want to write OpenWrt in Sata or IDE drives or CF Cards or SD cards, you can just remove them from the device and flash the image raw from your PC.+If you want to write OpenWrt in SATA or IDE drives or CF Cards or SD cards, you can just remove them from the device and flash the image raw from your PC.
 Also sometimes eMMC is removable or can be put in "usb write mode" in some devices. Also sometimes eMMC is removable or can be put in "usb write mode" in some devices.
  
Line 117: Line 132:
 Any additional space in the device is unallocated. Any additional space in the device is unallocated.
  
-===== Resizing partitions ===== +===== Expanding root partition and filesystem ===== 
-:!: Be sure to [[docs:guide-user:virtualization:qemu#preparation|resize the image]] before resizing partitions when installing in a VM.+See also: [[docs:guide-user:advanced:expand_root|Expanding root partition and filesystem: Automated]]
  
-  - Install [[packages:pkgdata:fdisk]]. +==== Expanding root partition ==== 
-  - Use fdisk to show the partitions. +<WRAP important> 
-  - Write down the starting sector address of /dev/sda2 (which is the root partition). +When installing OpenWrt on VMbe sure to [[docs:guide-user:virtualization:qemu#preparation|expand the underlying disk image]] before expanding the partition. 
-  - Use fdisk to delete the partition 2 (which is sda2), don't write the changes to disk yet. +</WRAP>
-  - Use fdisk to create new partition 2choose/type the starting sector address you wrote down earlier (as by default it will try to place it somewhere else), and leave the default end sector address (this will mean the partition will now use all available space). +
-  Write the partition table changes to disk. It may complain about partition signatures already present, write **n** to NOT remove the partition signature to proceed.+
  
-An example fdisk operation on 8GB flash drive:+Use [[man>parted]] to fix the partition table, identify and expand the root partition. 
 + 
 +<code bash> 
 +# Install packages 
 +opkg update 
 +opkg install parted 
 + 
 +# Identify disk name and partition number 
 +parted -l -s 
 + 
 +# Expand root partition 
 +parted -f -s /dev/sda resizepart 2 100% 
 + 
 +# Apply changes 
 +reboot 
 +</code> 
 + 
 +==== Expanding root filesystem ==== 
 +<WRAP important> 
 +Be sure to [[docs:guide-user:installation:openwrt_x86#expanding_root_partition|expand the underlying partition]] before expanding the filesystem. 
 + 
 +It is possible to expand the root filesystem online while OpenWrt is booted. 
 +You can also perform this operation offline to reduce the chance of filesystem corruption. 
 +</WRAP> 
 + 
 +Use [[man>losetup]] to map the root partition and [[man>resize2fs]] to expand the root filesystem. 
 + 
 +<code bash> 
 +# Install packages 
 +opkg update 
 +opkg install losetup resize2fs 
 + 
 +# Map loop device to root partition 
 +losetup /dev/loop0 /dev/sda2 2> /dev/null 
 + 
 +# Expand root filesystem 
 +resize2fs -f /dev/loop0 
 + 
 +# Apply changes 
 +reboot 
 +</code> 
 + 
 +==== Expanding root partition with fdisk ==== 
 +You can also use ''fdisk'' to expand the root partition if ''parted'' does not work for you. 
 +The easiest way to do this is from the machine booted with a "live CD" distro like [[https://www.finnix.org|Finnix]]. 
 + 
 +Here's an overview of the steps: 
 +  - Use fdisk to display the partition table. Notice the ~100MB root partition. 
 +  - Write down the starting sector address of the root partition (Usually ''/dev/sda2'' or ''/dev/nvme0n1p2''). 
 +  - Use fdisk to delete partition 2 but don't write the changes to disk yet. 
 +  - Use fdisk to create new partition 2. 
 +    - choose/type the starting sector address you wrote down earlier (as by default it will try to place it somewhere else). 
 +    - leave the default end sector address (this will mean the partition will now use all available space). 
 +  - Write the partition table changes to disk. 
 +    - When it warns about partition signatures being present, type **n** to NOT remove the partition signature to proceed. 
 +  - Proceed with updating ''/boot/grub/grub.cfg'' with the new partition UUID 
 + 
 +Example output:
  
 <code> <code>
Line 171: Line 241:
 </code> </code>
  
-Automated method:+Be aware that deleting and recreating the root partition can change its UUID. 
 +Make sure to update the root partition UUID in your GRUB configuration ''/boot/grub/grub.cfg'' in order for the system to be bootable.
  
 <code bash> <code bash>
-opkg update +# Update GRUB configuration 
-opkg install fdisk +ROOT_BLK="$(readlink -/sys/dev/block/"$(awk -e \ 
-BOOT="$(sed -n -e "/\s\/boot\s.*$/{s///p;q}" /etc/mtab)" +'$9=="/dev/root"{print $3}/proc/self/mountinfo)")" 
-DISK="${BOOT%%[0-9]*}" +ROOT_DISK="/dev/$(basename "${ROOT_BLK%/*}")" 
-PART="$((${BOOT##*[^0-9]}+1))" +ROOT_DEV="/dev/${ROOT_BLK##*/}" 
-ROOT="${DISK}${PART}" +ROOT_UUID="$(partx -g -o UUID "${ROOT_DEV}" "${ROOT_DISK}")" 
-OFFS="$(fdisk ${DISK} -l -o device,start | sed -n -e "\|^${ROOT}\s*|s///p")" +sed -i -r -e "s|(PARTUUID=)\S+|\1${ROOT_UUID}|g" /boot/grub/grub.cfg
-echo -e "p\nd\n${PART}\nn\np\n${PART}\n${OFFS}\n\nn\np\nw" | fdisk ${DISK} +
-</code> +
- +
-Be sure to update the GPT partition UUID in the GRUB configuration when using **efi.img.gz**: +
- +
-<code bash> +
-opkg update +
-opkg install lsblk +
-BOOT="$(sed -n -e "/\s\/boot\s.*$/{s///p;q}" /etc/mtab)" +
-DISK="${BOOT%%[0-9]*}" +
-PART="$((${BOOT##*[^0-9]}+1))" +
-ROOT="${DISK}${PART}" +
-UUID="$(lsblk -n -o PARTUUID ${ROOT})" +
-sed -i -r -e "s|(PARTUUID=)\S+|\1${UUID}|g" /boot/grub/grub.cfg +
-</code> +
- +
-===== Resizing filesystem ===== +
-:!: Be sure to [[docs:guide-user:installation:openwrt_x86#resizing_partitions|resize partitions]] before resizing filesystem. +
-Note that online resizing should work for both F2FS and Ext4 on OpenWrt 19.07, although F2FS requires rebooting to apply changes. +
- +
-==== Resizing F2FS overlay ==== +
-Resize F2FS overlay for **squashfs-combined.img.gz**: +
- +
-<code bash> +
-opkg update +
-opkg install losetup f2fs-tools +
-LOOP="$(losetup -n -O NAME | sort | sed -n -e "1p")" +
-ROOT="$(losetup -n -O BACK-FILE ${LOOP} | sed -e "s|^|/dev|")" +
-OFFS="$(losetup -n -O OFFSET ${LOOP})" +
-LOOP="$(losetup -f)" +
-losetup -o ${OFFS} ${LOOP} ${ROOT} +
-fsck.f2fs -f ${LOOP} +
-mount ${LOOP} /mnt +
-umount ${LOOP} +
-resize.f2fs ${LOOP} +
-reboot +
-</code> +
- +
-==== Resizing Ext4 rootfs ==== +
-Resize Ext4 rootfs for **ext4-combined.img.gz**: +
- +
-<code bash> +
-opkg update +
-opkg install losetup resize2fs +
-BOOT="$(sed -n -e "/\s\/boot\s.*$/{s///p;q}" /etc/mtab)" +
-DISK="${BOOT%%[0-9]*}" +
-PART="$((${BOOT##*[^0-9]}+1))" +
-ROOT="${DISK}${PART}" +
-LOOP="$(losetup -f)" +
-losetup ${LOOP} ${ROOT} +
-fsck.ext4 -y ${LOOP} +
-resize2fs ${LOOP} +
-reboot+
 </code> </code>
  
Line 240: Line 258:
 Any remaining space will be unallocated and the drive will have a normal MBR partition table. Any remaining space will be unallocated and the drive will have a normal MBR partition table.
  
-Any partition management tool that supports MBR and ext4 can be used to create extra partitions on the drive, in example fdiskGParted.+Any partition management tool that supports MBR and ext4 can be used to create extra partitions on the drive, e.g. [[packages:pkgdata:parted]][[packages:pkgdata:fdisk]].
  
 But attention must be taken for future upgrades. But attention must be taken for future upgrades.
Line 246: Line 264:
  
 ===== Upgrading ===== ===== Upgrading =====
-On most embedded devices, upgrading OpenWrt is much simpler than the first installation and consists of simply executing **sysupgrade**. +On most embedded devices that run OpenWrt, upgrading is much simpler than the first installation and consists of simply executing the ''sysupgrade'' commandUnfortunately, when upgrading x86 machines, the opposite is true and it is typically more involved than the first installation.
-On x86 machines, on the other hand, upgrading is more complex than the first installation.+
  
-One of the advantages of x86 is the easiness to backup and restore drives, using any normal backup tool that supports MBR and ext4. +Fortunately, one of the advantages of running OpenWrt on x86 machines is the simplicity of backup and restoration; you can backup an x86 machine using any normal backup program which supports either full disk imaging or object-based backups of the filesystem.
-Always make a proper backup of the whole drive and test its restore before any upgrade procedure. +
-It's also recommended to restore the backup on a virtual machine and execute the upgrade on it prior to upgrading the real router, to learn and experiment the procedures without risking the real thing.+
  
-On all procedures on this section, we must either connect the drive on a secondary PC running Linux, or boot the router with a Linux Live CD/USB.+<WRAP important> 
 +Always make a proper backup of the whole drive and test a restoration before any upgrade procedure. It's also recommended to restore the backup on a virtual machine and execute the upgrade on the virtual machine prior to upgrading the real router. This can be an effective strategy for learning and experimenting the process without risking the real thing. 
 +</WRAP> 
 + 
 +With most procedures in this section, we must either connect the drive on a secondary PC running Linux, or boot the router with a Linux Live CD/USB such as [[https://www.finnix.org|Finnix]]. 
 + 
 +If your installation used the ''ext4-combined.img.gz'' image to install, there are several options for upgrading:
  
-If you had used **ext4-combined.img.gz** type of image to installthere are 4 options for upgrading:+  - Write new ''ext4-combined.img.gz'' image: this is the simplest option and is identical to first installation: all dataconfigs, packages and extra partitions will be erased and you'll have a brand new OpenWrt system with default packages and configs. You will need to reinstall all packages, copy config files back, and create any additional partitions you require. 
 +  - Use ''sysupgrade'': this is default upgrading procedure but the least recommended option for x86 machines. Proceed to [[docs:guide-user:installation:installation_methods:sysupgrade|Sysupgrade]] for details. 
 +  - Extract the boot partition image from ''ext4-combined.img.gz'' and write it and the ''ext4-rootfs.img.gz'', leaving the Master Boot Record and partition table intact. 
 +  - Extract the boot partition image from ''ext4-combined.img.gz'' and write it and then uncompress the ''rootfs.tar.gz'' to the existing root filesystem.
  
-  - Write a new **ext4-combined.img.gz** image: this is the simplest option and is identical to first installation: all dataconfigspackages and extra partitions will be wiped and you'll have a brand new OpenWrt system with default packages and configsThen you can reinstall all packages and copy config files back and create extra partitions. +The last two options require more steps to execute but have the advantage of leaving the Master Boot Record and partition table intactThis preserves the bootrootfs, and any extra partitions you may have addedThis is considered the best practice for upgrading an x86 machine with the exception being when an OpenWrt release includes a newer version of GRUB2GRUB2 is installed to the Master Boot Record and therefore a full re-image of ''ext4-combined.img.gz'' is required to update it.
-  - Use **sysupgrade**: this is default upgrading procedure, but the least recommended option for x86 machinesProceed to [[docs:guide-user:installation:installation_methods:sysupgrade|Sysupgrade]] for details. +
-  - Extracting boot partition image from **ext4-combined.img.gz** and writing it and **ext4-rootfs.img.gz**, leaving MBR partition table intact. +
-  - Extracting boot partition image from **ext4-combined.img.gz** and writing it, then uncompressing **rootfs.tar.gz** to existing rootfs partition.+
  
-The 2 last options require more steps to execute, but have the advantage of leaving MBR partition intact, therefore keeping boot and rootfs partitions sizes (in case of having resized them) and any extra partitions. +FIXME Include instructions for EFI: ''ext4-combined-efi.img.gz''
-At this time they are the most recommended methods of upgrading. +
-The only exception is when new OpenWrt image brings a newer version of GRUB2. +
-Part of GRUB2 is stored close to MBR and outside of partitions area, so we need to write a full ext4-combined.img.gz to update it.+
  
 ==== Extracting boot partition image ==== ==== Extracting boot partition image ====
Line 283: Line 301:
  
 ==== Upgrading rootfs partition ==== ==== Upgrading rootfs partition ====
-As said above, there are 2 options for upgrading rootfs partition, when we are using the ext4 file system and not squashfs: writing **ext4-rootfs.img.gz** image or uncompressing **rootfs.tar.gz** into existing partition.+As said above, there are 2 options for upgrading rootfs partition, when we are using the ext4 filesystem and not squashfs: writing **ext4-rootfs.img.gz** image or uncompressing **rootfs.tar.gz** into existing partition.
  
 Writing **ext4-rootfs.img.gz** will delete any file on the partition. Writing **ext4-rootfs.img.gz** will delete any file on the partition.
Line 312: Line 330:
 rm openwrt-19.07.8-x86-64-generic-rootfs.tar.gz rm openwrt-19.07.8-x86-64-generic-rootfs.tar.gz
 </code> </code>
 +
 ===== Building your own image with larger partition size ===== ===== Building your own image with larger partition size =====
 Anyone can compile OpenWrt from source, but it's a complex procedure with many options which require some experience, specially for using it on a production router. Anyone can compile OpenWrt from source, but it's a complex procedure with many options which require some experience, specially for using it on a production router.
Line 324: Line 343:
 In many cases, OpenWrt will be back fully working on first boot after upgrading. In many cases, OpenWrt will be back fully working on first boot after upgrading.
  
-Another advantage for building a custom image is when the default rootfs partition size is too small to store all packages and we need to resize it. +Another advantage for building a custom image is when the default rootfs partition size is too small to store all packages and we need to expand it. 
-Note that, when following above procedures of installing then resizing partition and upgrading by writing partition image or extracting rootfs.tar.gz, we don't need to build the image with the final size of the partition.+Note that, when following above procedures of installing then expanding partition and upgrading by writing partition image or extracting rootfs.tar.gz, we don't need to build the image with the final size of the partition.
 Doing so would result in the too large image file and would require enough RAM to store the whole file during building. Doing so would result in the too large image file and would require enough RAM to store the whole file during building.
 It's recommended to use on the image just enough size to store all packages plus a small amount of free space. It's recommended to use on the image just enough size to store all packages plus a small amount of free space.
  • Last modified: 2024/12/11 21:31
  • by efahlgren