Differences

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

doc:howto:extroot [2013/05/09 18:24]
nill14
doc:howto:extroot [2014/10/19 18:08] (current)
cejny
Line 1: Line 1:
====== Rootfs on External Storage (extroot) ====== ====== Rootfs on External Storage (extroot) ======
-To understand the concept of OpenWrt extroot, please read [[doc:howto:extroot:extroot.theory]].+More often then not, there is a limited amount of storage space available on embedded devices. While the available flash memory will usually accomodate a bare OpenWrt installation, more room for applications and data can tremendously expand a device's potential. Luckily, many of these devices have these expansion capabilities built-in, for example in the form of USB ports, SATA ports, PCIexpress slots, or even storage in a network location. However, many of the applications you want to install are developed with the idea that they should be installed in the root file system (rootfs). By employing OpenWrt's extroot, you can expand the storage capacity of your root file system using the additional space of an added storage device. At a certain point in the boot process the external storage space is mounted as the root file system or in an overlay configuration over the original file system. To understand the technical details of OpenWrt extroot, please read [[doc:howto:extroot:extroot.theory]]. This article explains how to get it to work.
===== Alternatives to extroot ===== ===== Alternatives to extroot =====
-  - configure your [[doc:techref:bootloader]] to boot from the external USB device directly. Most bootloaders can't...! +To see if extroot is a good option for increasing the amount of storage for new application packages, look at the following alternatives to achieve this goal: 
-  - configure your bootloader to boot over the network ->[[inbox:netboot]] Many bootloaders can't...! +  - Configure your [[doc:techref:bootloader]] to boot from the external USB device directly. However, most bootloaders can't...!  
-  - make ''opkg'' install new packages somewhere else: ->[[doc:techref:opkg#Installation destinations]] +    * Popular bootloaders (e.g. U-Boot or RedBoot) [[wp>Comparison_of_boot_loaders|support different file systems]], but they lack the necessary hardware drivers. 
-  - use [[kexec]]+  - Configure your bootloader to boot over the network ->[[inbox:netboot]]. However, many bootloaders can't...! 
 +  - Make ''opkg'' install new packages somewhere else ->[[doc:techref:opkg#Installation destinations]]. However, installing OPKG packages in root is much more convenient, as its files are installed in locations that the rest of the OS expects them to reside. 
 +  - Use [[kexec]]. However, this may require custom configurations on different devices.
-==== Preparations ==== +===== Preparations ===== 
-  - Please read the article [[doc:howto:extroot:extroot.theory]] for better understanding. +  - Please read the article [[doc:howto:extroot:extroot.theory]] for better understanding of extroot. In particular, understand the difference between the two extroot variants: pivot overlay and pivot root
-  - This entire extroot functionality is **<color red>Work-in-Progress</color>**, so is this article, so please make sure to check [[#Troubleshooting]] and the [[#Notes]] as a preparation and also later on from time to time!+  - For different OpenWrt versions extroot configuration and features differ. The sections below provide separate instructions for OpenWrt 10 and higher. Notably, in OpenWrt 10 (Backfire) you can only use the pivot overlay variant, not pivot root. 
 +  - The entire extroot functionality is **<color red>Work-in-Progress</color>**, so is this article, so please make sure to check [[#Troubleshooting]] and the [[#Notes]] as a preparation and also later on from time to time! 
 + 
 +| {{:meta:icons:tango:48px-emblem-important.svg.png?nolink}} | If for some reason extroot fails at boot, the normal configuration is loaded that is still in the JFFS2 partition on the main flash, which is the old configuration that you copied to the external root device and have since changed from there. This configuration may pose a security risk (for example if its configuration of SSH gives unprotected access from the internet). You should therefore make sure the system is safe and protected before installing extroot. Also, any changes you make to your network environment should be compatible with the security in the original JFFS2 configuration. |
-===== OpenWrt Backfire 10.03+ ===== 
==== Prerequisites ==== ==== Prerequisites ====
-  - you need to **mount** a **file system**, on which the overlay will be copied to. You could +You need to **mount** a **file system**, on which the overlay will be copied to. 
-    - follow [[doc:howto:usb.essentials]] and additionally [[doc:howto:usb.storage]] for USB storage +    * For USB, follow [[doc:howto:usb.essentials]] and additionally [[doc:howto:usb.storage]] for USB storage.  
-    - alternatively follow [[doc:howto:sata.essentials]], [[doc:howto:ide.essentials]] or [[doc:howto:cf.essentials]] for other storage +    * Alternatively, follow [[doc:howto:sata.essentials]], [[doc:howto:ide.essentials]] or [[doc:howto:cf.essentials]] for other storage 
-    - alternatively follow [[doc:howto:client.overview#Mounting Filesystems]] to mount a remote network file system+    * Alternatively, follow [[doc:howto:client.overview#Mounting Filesystems]] to mount a remote network file system 
 + * See [[Storage]] for general information on configuring storage devices.
-==== Required Packages ==== +Make sure that you can mount and have read/write access to your external storage device. For example, check if you can read/write from a manually mounted file system on your partitioned USB drive at ''/dev/sda'':
-  ***''block-extroot''** +
-  ***''block-hotplug''** +
-  ***''block-mount''** +
- +
-Depending on your medium (USB-Device, IDE-Device, SATA-Device or SD/MMC device) you need: +
-  ***''kmod-usb-core''** Kernel support for USB +
-  ***''kmod-usb2''** Kernel support for USB2 (EHCI) controllers +
-  ***''kmod-usb-ohci''**  Kernel support for USB OHCI controllers +
-  ***''kmod-usb-storage''**  Kernel support for USB Mass Storage devices +
-or +
-  ***''kmod-ata-ahci''** Support for AHCI Serial ATA controllers +
-  * and any other required SATA drivers +
-or +
-  ***''kmod-ide-core''** Kernel support for IDE, useful for usb mass storage devices +
-  * and any other required IDE drivers +
-or +
-  ***''kmod-mmc''**  Kernel support for MMC/SD cards +
-  * and any required required drivers +
-You also need the kernel module for the filesystem with which you formated the partition you want to mount+
-  ***''kmod-fs-ext4''** +
-or +
-  ***''kmod-fs-ext3''** +
-or +
-  ***''kmod-fs-ext2''** +
- +
-Optionally: +
-  ***''e2fsprogs''** contains essential ext2, ext3 and ext4 file system utilities (''e2fsck'', ''mke2fs'', ''debugfs'', ''dumpe2fs'', ''tune2fs'', ..) considerably smaller than ->[[http://packages.debian.org/squeeze/e2fsprogs|e2fsprogs in Debian repos]] +
-      ***''e2fsck''** contained in ''e2fsprogs''. Cannot be installed alone. :!: Please regard RAM requirements to check big file systems.((Roughly 1 MB of RAM for every 1 GB of disk to successfully fsck the disk. [[http://www.openbsd.org/faq/faq14.html#LargeDrive|Source]].)) +
- +
-==== Installation ==== +
- +
-<code> +
-opkg update +
-opkg install block-mount block-hotplug block-extroot +
-</code> +
-Also opkg install any filesystem or usb packages you need +
- +
-=== Duplicate data === +
-  - **Copy** necessary files from flash to the new root partition: +
-    - For //pivot overlay// you can either use an empty new rootfs OR copy the contents of the current overlay (JFFS2) to the new rootfs (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1''): +
-<code>tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -</code> +
- +
-=== Configuration === +
-The configuration of extroot is very simple and is done entirely in ''[[doc:uci:fstab|/etc/config/fstab]]''.+
-| {{:meta:icons:tango:48px-outdated.svg.png?nolink}}| For backfire the option ''is_rootfs'' is required for block-extroot mounts! |+    mount /dev/sda1 /mnt/sda1
-=== External overlay variant (pivot overlay) ===+You should check if the mount was succesful by running ''mount'' or ''df''. Now check if you can write to ''/mnt/sda1'' by writing a file to it and reading it back.
-This is the only variant available in Backfire. +===== OpenWrt 12.09 'Attitude Adjustment' ===== 
- +For OpenWrt 12.09, the second extroot variant pivot root is added. Decide whether you want to pivot ''/overlay'' (recommended) or to pivot ''/'' (entire root)
-Configure by setting the option **is_rootfs** in your ''/etc/config/fstab''.  Besides that, there is really nothing to be configured regarding //ExtRoot// that is different from any other mount. +
- +
-For Backfire 10.03, and 10.03.1-rc1 to 10.03.1-rc5 use the example given below. +
- +
-|''config mount +
-        option device        /dev/sda1 +
-        option fstype        ext3 +
-        option options      rw,sync +
-        option enabled      1 +
-        option enabled_fsck  0 +
-        option is_rootfs    1''| +
- +
-**''Note:''**  +
-Using the directory ''/mnt'' as target will make testing possible, first set is_rootfs to 0, reboot and check if all mounts well and than set it to 1 and reboot again. +
-Make sure the target it is **NOT** manually set to ''/overlay.''  ''/overlay'' is automatically used on a successful ''is_rootfs''-mount, but if for some reason this file system could not be made the rootfs it will be mounted on the target listed here.  Using ''/overlay'' will result in an double ''/overlay'' mount and screw thing up. +
- +
-===== OpenWrt Attitude Adjustment (Trunk) ===== +
-==== Prerequisites ==== +
-  - you need to **mount** a **file system**, on which the overlay will be copied to. You could +
-    - follow [[doc:howto:usb.essentials]] and additionally [[doc:howto:usb.storage]] for USB storage +
-    - alternatively follow [[doc:howto:sata.essentials]], [[doc:howto:ide.essentials]] or [[doc:howto:cf.essentials]] for other storage +
-    - alternatively follow [[doc:howto:client.overview#Mounting Filesystems]] to mount a remote network file system +
-  - decide whether you want to pivot ''/overlay'' (recommended) or to pivot ''/'' (entire root)+
==== Required Packages ==== ==== Required Packages ====
  ***''block-mount''**   ***''block-mount''**
-Depending on your medium (USB-Device, IDE-Device, SATA-Device or SD/MMC device) you need: +This is the only required extroot package for OpenWrt 12.09, see [[doc/techref/block_mount]].  
- ***''kmod-usb-core''** Kernel support for USB +   
-  ***''kmod-usb2''** Kernel support for USB2 (EHCI) controllers +==== Installation ==== 
- ***''kmod-usb-ohci''**  Kernel support for USB OHCI controllers +After preparing your storage device and its file system, installation proceeds as follows. First the required packages are installed. Then the existing files from the current JFFS2 overlay partition on flash are copied to the new storage device. Then the system is configured using fstab for activating extroot at boot.
- ***''kmod-usb-storage''**  Kernel support for USB Mass Storage devices +
-or +
-  ***''kmod-ata-ahci''** Support for AHCI Serial ATA controllers +
-  * and any other required SATA drivers +
-or +
-  ***''kmod-ide-core''** Kernel support for IDE, useful for usb mass storage devices +
-  * and any other required IDE drivers +
-or +
-  ***''kmod-mmc''**  Kernel support for MMC/SD cards +
-  * and any required required drivers +
-You also need the kernel module for the filesystem with which you formated the partition you want to mount: +
-  ***''kmod-fs-ext4''** (recommended, this also supports ext2 and ext3)+
-Optionally: +=== Install packages ===
-  ***''e2fsprogs''** contains essential ext2, ext3 and ext4 file system utilities (''e2fsck'', ''mke2fs'', ''debugfs'', ''dumpe2fs'', ''tune2fs'', ..) considerably smaller than ->[[http://packages.debian.org/squeeze/e2fsprogs|e2fsprogs in Debian repos]] +
-      ***''e2fsck''** contained in ''e2fsprogs''. Cannot be installed alone. :!: Please regard RAM requirements to check big file systems. +
- +
-Also **required**: +
-  ***''kmod-scsi-generic''**  Linux kernel (2.6.30 and later) uses the SCSI devices to link any storage media. +
- +
-==== Installation ====+
<code> <code>
opkg update opkg update
Line 130: Line 49:
=== Duplicate data === === Duplicate data ===
-  - **Copy** necessary files from flash to the new root partition:+Copy necessary files from flash to the new root partition:
    - For //pivot overlay// you can either use an empty new rootfs OR copy the contents of the current overlay (JFFS2) to the new rootfs (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1''):<code>tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -</code>     - For //pivot overlay// you can either use an empty new rootfs OR copy the contents of the current overlay (JFFS2) to the new rootfs (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1''):<code>tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -</code>
    - For //pivot root// (only possible as of [[https://dev.openwrt.org/changeset/26109/trunk|r26109]]!) you must make sure to have a complete root filesystem on the external rootfs device. One possible way to get such a system (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1'') is to issue  <code>mkdir -p /tmp/cproot     - For //pivot root// (only possible as of [[https://dev.openwrt.org/changeset/26109/trunk|r26109]]!) you must make sure to have a complete root filesystem on the external rootfs device. One possible way to get such a system (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1'') is to issue  <code>mkdir -p /tmp/cproot
mount --bind / /tmp/cproot mount --bind / /tmp/cproot
-tar -C /tmp/cproot -cvf - . | tar -C /mnt/sda1 -xf -+tar -C /tmp/cproot -cvf - . | tar -C /mnt/sda1 -x
umount /tmp/cproot</code> umount /tmp/cproot</code>
=== Configuration === === Configuration ===
- 
The configuration of extroot is very simple and is done entirely in ''[[doc:uci:fstab|/etc/config/fstab]]''. The configuration of extroot is very simple and is done entirely in ''[[doc:uci:fstab|/etc/config/fstab]]''.
-//But// because this is such a **<color red>WiP</color>**, you really need to read on before just switching extroot on!+== Old external overlay variant (pivot overlay) == 
 +Before [[https://dev.openwrt.org/changeset/25787/trunk|r25787]] configure by setting the option **is_rootfs** in your ''/etc/config/fstab''.  Besides that, there is nothing to be configured regarding extroot that is different from any other mount.
-| {{:meta:icons:tango:48px-outdated.svg.png?nolink}}| ''option is_rootfs'' is deprecated **after** [[https://dev.openwrt.org/changeset/25787/trunk|r25787]]! **Before** Trunk r25787 the option ''is_rootfs'' is required for block-extroot mounts! | +For trunk versions up to, but not including r25787 the following is an example for an extroot mount entry in the file /etc/config/fstab. Note the fstype, options and enable_fchk options are optional, see [[doc:uci:fstab|fstab]].
- +
-=== Old external overlay variant (pivot overlay) === +
-Before [[https://dev.openwrt.org/changeset/25787/trunk|r25787]] configure by setting the option **is_rootfs** in your ''/etc/config/fstab''. Besides that, there is really nothing to be configured regarding //ExtRoot// that is different from any other mount. +
- +
-For trunk versions up to, but not including r25787 and the releases +
-Backfire 10.03, and 10.03.1-rc1 to 10.03.1-rc5 use the example given below.+
|''config mount |''config mount
        option target        /mnt  # This is ignored once is_rootfs is set to 1         option target        /mnt  # This is ignored once is_rootfs is set to 1
-        option device        /dev/sda2+        option device        /dev/sda1
        option fstype        ext3         option fstype        ext3
        option options      rw,sync         option options      rw,sync
Line 160: Line 73:
        option is_rootfs    1''|         option is_rootfs    1''|
-**''Note:''**  + A ''target'' option is not mandatory as it will be the overlay file system. However, using the directory ''/mnt'' as target will make testing possible: first set is_rootfs to 0, reboot and check if all mounts well and than set it to 1 and reboot again. Make sure the target it is **not** manually set to ''/overlay.''  ''/overlay'' is automatically used on a successful ''is_rootfs''-mount, but if for some reason this file system could not be made the rootfs will be mounted on the target listed here.  Using ''/overlay'' will result in an double ''/overlay'' mount and screw things up. In later releases, the target is used to determine if a mount entry is an extroot device and ''is_rootfs'' is not used anymore to circumvent this.
-Using the directory ''/mnt'' as target will make testing possible, first set is_rootfs to 0, reboot and check if all mounts well and than set it to 1 and reboot again. +
-Make sure the target it is **NOT** manually set to ''/overlay.''  ''/overlay'' is automatically used on a successful ''is_rootfs''-mount, but if for some reason this file system could not be made the rootfs it will be mounted on the target listed here.  Using ''/overlay'' will result in an double ''/overlay'' mount and screw thing up.+
 +| {{:meta:icons:tango:48px-outdated.svg.png?nolink}}| ''option is_rootfs'' is deprecated **after** [[https://dev.openwrt.org/changeset/25787/trunk|r25787]]. Use the new overlay variant where the target is used to determine if a mount entry is an extroot device. **Before** Trunk r25787 the option ''is_rootfs'' is required for block-extroot mounts! |
-=== New external overlay variant (pivot overlay) ===+ 
 +== New external overlay variant (pivot overlay) ==
While ''option is_rootfs'' will still work after [[https://dev.openwrt.org/changeset/25787/trunk|r25787]], the preferred method of configuring the extroot is ''option target /overlay'' in the ''config mount'' section for the rootfs device in the ''[[doc:uci:fstab|/etc/config/fstab]]'' file. While ''option is_rootfs'' will still work after [[https://dev.openwrt.org/changeset/25787/trunk|r25787]], the preferred method of configuring the extroot is ''option target /overlay'' in the ''config mount'' section for the rootfs device in the ''[[doc:uci:fstab|/etc/config/fstab]]'' file.
-For trunk versions newer than and including r25787 use this variant. <color red>Backfire releases do **not** support this</color>.+For trunk versions newer than and including r25787 use this variant. This is the entry in the /etc/config/fstab configuration file.
|''config mount |''config mount
        option target        /overlay         option target        /overlay
-        option device        /dev/sda2+        option device        /dev/sda1
        option fstype        ext3         option fstype        ext3
        option options      rw,sync         option options      rw,sync
Line 179: Line 92:
        option enabled_fsck  0''|         option enabled_fsck  0''|
-**Note**: If the overlay mount fails it will appear on ''/tmp/overlay-disabled'' instead of becoming the rootfs. No more double mounts even on failure. +If the overlay mount fails it will appear on ''/tmp/overlay-disabled'' instead of becoming the rootfs. This means that you will have no more double mounts, even on failure .
-=== Whole external root (pivot root) ===+== Whole external root (pivot root) ==
After [[https://dev.openwrt.org/changeset/26109/trunk|r26109]] you can configure a non-overlay rootfs (called a ''whole_root'' extroot because the entire filesystem must be present on device, not only the changes from the SquashFS) using ''option target /'' in the ''config mount'' section for the rootfs device. After [[https://dev.openwrt.org/changeset/26109/trunk|r26109]] you can configure a non-overlay rootfs (called a ''whole_root'' extroot because the entire filesystem must be present on device, not only the changes from the SquashFS) using ''option target /'' in the ''config mount'' section for the rootfs device.
-Note that this isn't required or preferred, it's just another option for those who want it. Backfire releases do **not** support this.+Note that this isn't required or preferred, it's just another option for those who want it. This is new to OpenWrt 12. Backfire releases do **not** support this.
-In order to set up such a whole root overlay, refer to the example below.+In order to set up such a whole root overlay, use the following fstab mount entry in the file /etc/config/fstab
| ''config mount | ''config mount
        option target        /         option target        /
-        option device        /dev/sda2+        option device        /dev/sda1
        option fstype        ext3         option fstype        ext3
        option options      rw,sync         option options      rw,sync
Line 198: Line 110:
        option enabled_fsck  0'' |         option enabled_fsck  0'' |
-**Note**: If the non-overlay extroot mount fails before [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/rom-disabled'', while after [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/whole_root-disabled''.+If the non-overlay extroot mount fails before [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/rom-disabled'', while after [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/whole_root-disabled''. 
 + 
 +If the system on the extroot is obtained from a prebuilt image the md5sums will not match and you need to copy the md5sum from the active system:  
 + 
 +<code>cp /.extroot.md5sum /tmp/whole_root-disabled/etc/extroot.md5sum</code>
 +or
 +<code>cp /.extroot.md5sum /tmp/overlay-disabled/etc/extroot.md5sum</code>
-== Examples ==+=== Example ===
The following steps were made on the [[toh:huawei:hg553]] using OpenWrt trunk@r28057: openwrt-HW553-jffs2-64k-cfe.bin after correctly setting up [[doc:howto:usb.essentials]] to obtain basic support for USB //and// [[doc:howto:usb.storage]] for USB storage. The following steps were made on the [[toh:huawei:hg553]] using OpenWrt trunk@r28057: openwrt-HW553-jffs2-64k-cfe.bin after correctly setting up [[doc:howto:usb.essentials]] to obtain basic support for USB //and// [[doc:howto:usb.storage]] for USB storage.
Line 214: Line 133:
sync ; umount /mnt sync ; umount /mnt
umount /tmp/cproot</code> umount /tmp/cproot</code>
-NOTE: mkfs.ext4 is provided by package e2fsprogs!+Note: mkfs.ext4 is provided by package e2fsprogs.
-After that, fstab should be edited to reflect the desired mount point:+After that, /etc/config/fstab should be edited to reflect the desired mount point:
| ''config mount | ''config mount
Line 225: Line 144:
option enabled 1 option enabled 1
option enabled_fsck 0'' | option enabled_fsck 0'' |
 +
 +Note the fstype, options and enable_fchk options are optional, see [[doc:uci:fstab|fstab]].
After reboot you should check your mounts and get something like: After reboot you should check your mounts and get something like:
Line 237: Line 158:
none on /proc/bus/usb type usbfs (rw,relatime)</code> none on /proc/bus/usb type usbfs (rw,relatime)</code>
-== Last attempt ==+===== OpenWrt 'Barrier Breaker' (trunk) =====
-If all previous don't work, try with a sysupgrade restoring configurations files (especially fstab with the desired configuration). Then be generated correctly a "whole_root-disabled", that is need to fix (and repeat this operation for each new sysupgrade). However, if the files contained in the extroot are already updated, you may not need to perform this operation and extroot starts correctly (check with a //df// before and after reboot again), although it is best to clean the partition before, especially if we can not it to work when trying to enable:+For the current trunk of OpenWrt, a new block-mount package is introduced, refer to [[doc/techref/block_mount]] and [[doc/uci/fstab]].
- mkdir -p /tmp/cproot +Decide whether you want to pivot ''/overlay'' (recommended) or to pivot ''/'' (entire root)
- mount --bind / /tmp/cproot +
- tar -C /tmp/cproot -cvf - . | tar -C /tmp/whole_root-disabled -xf - +
- sync +
- umount /tmp/cproot +
- /etc/init.d/fstab whole_root_enable +
- reboot+
-With any &quot;overlay-disabled&quot; is more easy (note that first we need clean overlay, check that it's ok before do any //rm//): +==== Required Packages ==== 
- rm -r /tmp/overlay-disabled/* +  ***''block-mount''** 
- tar -C /overlay -cvf - . | tar -C /tmp/overlay-disabled -xf +This is the only required extroot package for OpenWrt 12.09, see [[doc/techref/block_mount]]. Note that from [[https://dev.openwrt.org/changeset/36988|r36988]] the new ''block'' utility can be used, which is the new runnable that is responsible for all mounting procedures. See [[doc/uci/fstab|fstab Configuration]] for more details. The extroot fstab configuration is unchanged from the new external overlay/root variants in OpenWrt 12.09. 
- /etc/init.d/fstab overlay_enable +  
- reboot+Additional packages that may be needed are: 
 +  *''kmod-usb-storage'' 
 +  *''kmod-fs-ext4'' or other depending on the FS used for the external storage. 
 + 
 + 
 + 
 +==== Installation ==== 
 +After preparing your storage device and its file system, installation proceeds as follows. First the required packages are installed. Then the existing files from the current JFFS2 overlay partition on flash are copied to the new storage device. Then the system is configured using fstab for activating extroot at boot. 
 + 
 +=== Install packages === 
 +<code> 
 +opkg update 
 +opkg install block-mount 
 +</code> 
 +Also opkg install any filesystem or usb packages you need 
 + 
 +=== Duplicate data === 
 + 
 +Copy necessary files from flash to the new root partition: 
 +    - For //pivot overlay// you can either use an empty new rootfs OR copy the contents of the current overlay (JFFS2) to the new rootfs (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1''):&lt;code>tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -&lt;/code> 
 +    - For //pivot root// (only possible as of [[https://dev.openwrt.org/changeset/26109/trunk|r26109]]!) you must make sure to have a complete root filesystem on the external rootfs device. One possible way to get such a system (assuming the filesystem for the new external rootfs is mounted on ''/mnt/sda1'') is to issue  <code>mkdir -p /tmp/cproot 
 +mount --bind / /tmp/cproot 
 +tar -C /tmp/cproot -cvf - . | tar -C /mnt/sda1 -xf - 
 +umount /tmp/cproot</code> 
 + 
 + 
 +=== Configuration === 
 +The configuration of extroot is very simple and is done entirely in ''[[doc:uci:fstab|/etc/config/fstab]]''. 
 + 
 +== Pivot Overlay == 
 +The following is an example for an extroot /etc/config/fstab mount entry for pivot overlay. Note the fstype, options and enable_fchk options are optional, see [[doc:uci:fstab|fstab]]. 
 + 
 +|''config mount 
 +        option target        /overlay 
 +        option device        /dev/sda1 
 +        option fstype        ext3 
 +        option options      rw,sync 
 +        option enabled      1 
 +        option enabled_fsck  0''| 
 + 
 +If the overlay mount fails it will appear on ''/tmp/overlay-disabled'' instead of becoming the rootfs. This means that you will have no more double mounts, even on failure. 
 + 
 +Some users reported a problem with Barier Breaker 14.07 (and RC versions) on ar71xx devices, the problem was solved by user S-trace, thanks to him. The partition won't mount as /overlay, but still mount as /mnt/sdax. To get the right uuid run bloc detect. 
 +  
 +|''root@OpenWrt:/# cat /etc/config/fstab 
 +config global 
 +        option anon_swap '0' 
 +        option anon_mount '0' 
 +        option auto_swap '1' 
 +        option auto_mount '1' 
 +        option delay_root '5' 
 +        option check_fs '0' 
 + 
 +config mount 
 +        option target '/overlay' 
 +        option uuid '1902a323-79a6-4b1a-a511-a58655974ee9' 
 +        option enabled '1' 
 +        option fstype 'ext4' 
 + 
 +config mount 
 +        option target '/mnt/sda2' 
 +        option uuid 'dc64a6dd-de63-4363-b405-403cdced1649' 
 +        option enabled '1' 
 +        option fstype 'ext4' ''| 
 + 
 +This will work.  
 + 
 +== Pivot Root == 
 +After [[https://dev.openwrt.org/changeset/26109/trunk|r26109]] you can configure a non-overlay rootfs (called a ''whole_root'' extroot because the entire filesystem must be present on device, not only the changes from the SquashFS) using ''option target /'' in the ''config mount'' section for the rootfs device. 
 + 
 +Note that this isn't required or preferred, it's just another option for those who want it. This is introduced in OpenWrt 12. 
 + 
 +In order to set up such a whole root overlay, use the following /etc/config/fstab mount entry 
 + 
 +| ''config mount 
 +        option target       
 +       option device        /dev/sda1 
 +        option fstype        ext3 
 +        option options      rw,sync 
 +        option enabled      1 
 +        option enabled_fsck  0'' | 
 + 
 +If the non-overlay extroot mount fails before [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/rom-disabled'', while after [[https://dev.openwrt.org/changeset/26311/trunk|r26311]] it will appear mounted to ''/tmp/whole_root-disabled''. 
 + 
 + 
 + 
 + 
 +=== Example === 
 +This example assumes you have a device connected properly, at ''/dev/sda'' with a partition at ''/dev/sda1''. The following will format at to an ext4 partition, mount it at ''/mnt/sda1'',  
 +<code>mkfs.ext4 /dev/sda1   
 +mount /dev/sda1 /mnt/sda1 
 +tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf - 
 +</code> 
 +Note: mkfs.ext4 is provided by the package e2fsprogs. 
 + 
 +Next, edit your fstab, for example with vi: 
 +<code> 
 +vi /etc/config/fstab 
 +</code> 
 + 
 +You need to modify the //target// line and //option enabled// line so that it looks like this (Note: In this example we have referred to the partition by its UUID instead of its device file. The UUID will be different for you as this is just an example. Alternatively, you can point to the right partition using the ''device'' option set to the device file ''/dev/sda1'' as in the previous examples): 
 +<code> 
 +config 'global' 
 +        option  anon_swap      '0' 
 +        option  anon_mount      '0' 
 +        option  auto_swap      '1' 
 +        option  auto_mount      '1' 
 +        option  delay_root      '0' 
 +        option  check_fs        '0' 
 + 
 +config 'mount' 
 +        option  target  '/overlay
 +        option  uuid    '7d3abfaf-493a-46bb-9730-1d793ecb9783' 
 +        option  enabled '1' 
 +</code> 
 + 
 +You can also use UCI CLI commands to change the fstab file: 
 +<code> 
 +uci set fstab.@mount[0].target=/overlay 
 +uci set fstab.@mount[0].enabled=1 
 +uci commit fstab 
 +/etc/init.d/fstab restart 
 +</code> 
 + 
 +Reboot your system. 
 + 
 +To check if extroot is working run ''df'' and it should give an output like this: 
 +<code> 
 +root@OpenWrt:~# df 
 +Filesystem          1K-blocks      Used Available Use% Mounted on 
 +rootfs                2758072    118004  2501828  5% / 
 +/dev/root                2048      2048        0 100% /rom 
 +tmpfs                    63340        76    63264  0% /tmp 
 +/dev/sda1              2758072    118004  2501828  5% /overlay 
 +overlayfs:/overlay    2758072    118004  2501828  5% / 
 +tmpfs                      512        0      512  0% /dev 
 +</code> 
 + 
 +Notice ''rootfs'' and ''overlayfs:/overlay'' share the same space and both are mounted on the root (''/''). Further, ''/dev/sda1'' is mounted on ''/overlay'' and is the overlay file system. For pivot root configurations the ''overlayfs:/overlay'' entry in ''df'' will be absent.
===== Troubleshooting ===== ===== Troubleshooting =====
  * Add option force_space in ''/etc/opkg.conf'' to allow installation of packets bigger than your ''/rom'' partitions free space: <code>echo option force_space >> /etc/opkg.conf</code>   * Add option force_space in ''/etc/opkg.conf'' to allow installation of packets bigger than your ''/rom'' partitions free space: <code>echo option force_space >> /etc/opkg.conf</code>
-  * There is still a [[https://dev.openwrt.org/ticket/9454|bug]] in extroot that prevents it from working with 2.4 kernels: /backfire/10.03.1-rc4/brcm-2.4 and /backfire/10.03/brcm-2.4. Extroot does work with /backfire/10.03.1-rc4/brcm47xx +  * Do not use vfat (FAT/FAT32); it does not work. If you have a FAT preformatted USB drive, you cannot use it for extroot without reformatting. Use e.g. ext4 (install e2fsprogs, then format your FAT formatted USB drive using ''mkfs.ext4 /dev/sda1'' as per the example, also see [[storage]]). 
-  * If extroot does not work with 10.03.1 try the latest rc (currently 10.03.1-rc6). +  * On Barrier Breaker, ''block-mount'' will create a file ''/etc/.extroot-uuid'' on extroot filled with uuid of mtd partition ''rootfs''. At boot time when trying to do extroot, ''block-mount'' would try to check the actual uuid with the content of ''.extroot-uuid''. If they did not match, extroot would fail. So if you want to continue use extroot after flashing a new firmwre, ''/etc/.extroot-uuid'' needs to be deleted first. 
-  * Do not use vfat, it doesn't work! Use e.g. ext4 (install e2fsprogs, then format usb drive mkfs.ext4 /dev/sda1) +  * If the partition containing your extroot isn't mounted during boot, but you can mount it without problems from a shell, you should try to increase ''config 'global' / option delay_root''. On my system I had to set it to 15 to get extroot working.  Another hint to this being the culprit is having a working swap or other partitions mounted after booting, but not your extroot.
- +
-| {{:meta:icons:tango:48px-outdated.svg.png?nolink}} | **Note:** Before OpenWrt 'Backfire' 10.03.1-RC4 the ''block-extroot'' package is still existent and //cannot// be installed later on with opkg. It has to be included in the image.\\ There is a separate howto_build for this [[doc:howtobuild:extroot.howtobuild]]  | +
-| {{:meta:icons:tango:48px-outdated.svg.png?nolink}} | As of [[https://dev.openwrt.org/changeset/26314/trunk|r26314]] ''block-extroot'' and ''block-hotplug'' have been merged with **''block-mount''**. |+
===== Notes ===== ===== Notes =====
==== Remote File Systems ==== ==== Remote File Systems ====
-  * [[https://forum.openwrt.org/viewtopic.php?id=32812]]+  * Forum: [[https://forum.openwrt.org/viewtopic.php?id=32812|Fstab not mounting cifs at boot or through CLI]]
==== System Upgrade ==== ==== System Upgrade ====
Line 282: Line 332:
  - recreate the extroot   - recreate the extroot
  - copy back your data back to recreated extroot   - copy back your data back to recreated extroot
-  - remove the md5sums (''<extroot>/.extroot.md5sum'' and ''<extroot>/etc/extroot.md5sum''). As of trunk [[https://dev.openwrt.org/changeset/26312/|r26312]] you can achieve the md5sum removal with <code>/etc/init.d/fstab enable_overlay</code>+  - remove the md5sums (''<extroot>/.extroot.md5sum'' and ''<extroot>/etc/extroot.md5sum''). As of trunk [[https://dev.openwrt.org/changeset/26312/|r26312]] you can achieve the md5sum removal with <code>/etc/init.d/fstab overlay_enable</code>
  - make sure your ''/etc/config/fstab'' (located on the JFFS2) is correct   - make sure your ''/etc/config/fstab'' (located on the JFFS2) is correct
  - reboot.   - reboot.
In future I plan to have a script that removes all non-conffiles (except also preserving files preserved by sysupgrade) pointed to the opkg list on the extroot, and few other cleanups, which will hopefully sanitize extroot so it can be safely used again. In future I plan to have a script that removes all non-conffiles (except also preserving files preserved by sysupgrade) pointed to the opkg list on the extroot, and few other cleanups, which will hopefully sanitize extroot so it can be safely used again.
 +
 +==== Accessing original root ====
 +
 +Sometimes you may need to access the original root overlay, for example to change your extroot settings.  A convenient way of doing this is to configure /etc/config/fstab on your extroot partition to mount the original root overlay in another directory, like this:
 +
 +| ''config mount
 + option target /overlay-boot
 + option device /dev/mtdblock3
 + option fstype jffs2
 + option options rw,sync
 + option enabled 1
 + option enabled_fsck 0'' |
 +
 +This assumes the original overlay was on /dev/mtdblock3 - check your router's page on this wiki and look at the flash map to confirm what MTD block it is for you. Or run "$ cat /proc/mtd" and search the partition named rootfs_data to know where is your overlay.
 +
 +If you then create /overlay-boot on the extroot partition, this directory will contain the original root overlay, which is used as the main root overlay until the extroot is up and running.  So you can then for example edit /overlay-boot/etc/config/fstab to change your extroot configuration (or temporarily disable it) should you ever need to.
=== Old Notes === === Old Notes ===
Line 299: Line 365:
To upgrade kernel + kernel modules you need to first upgrade the kernel-modules (with opkg upgrade ... --force... ) and then immediately WITHOUT rebooting, reflash Kernel + SquashFS with ''sysupgrade''. Then reboot. To upgrade kernel + kernel modules you need to first upgrade the kernel-modules (with opkg upgrade ... --force... ) and then immediately WITHOUT rebooting, reflash Kernel + SquashFS with ''sysupgrade''. Then reboot.
 +===== Information on Legacy versions =====
 +
 +Backfire see: [[doc:howto:extroot.old]]
{{tag>USBrelated}} {{tag>USBrelated}}
 +

Back to top

doc/howto/extroot.1368116641.txt.bz2 · Last modified: 2013/05/09 18:24 by nill14