User Tools

Site Tools


doc:howto:extroot.old

Extroot with Legacy OpenWrt Versions

Back to current versions: extroot

Barrier Breaker

  • For Barrier Breaker, a new block-mount package is introduced, refer to block_mount and fstab.
  • Decide whether you want to pivot /overlay (recommended) or to pivot / (entire root)

Required Packages

  • block-mount

This is the only required extroot package for OpenWrt 12.09, see block_mount. Note that from r36988 the new block utility can be used, which is the new runnable that is responsible for all mounting procedures. See fstab Configuration for more details. The extroot fstab configuration is unchanged from the new external overlay/root variants in OpenWrt 12.09.

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

opkg update
opkg install block-mount
Also opkg install any filesystem or usb packages you need

Duplicate data

Copy necessary files from flash to the new root partition:

  1. 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):
    tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -
  2. For pivot-root (only possible as of 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
    mkdir -p /tmp/cproot
    mount --bind / /tmp/cproot
    tar -C /tmp/cproot -cvf - . | tar -C /mnt/sda1 -xf -
    umount /tmp/cproot

Configuration

The configuration of extroot is very simple and is done entirely in /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 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 block 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.

There exists an issue where option target '/overlay' does not mount as the overlay, and the issue appears to be the "/". Eliminating the forward slash eliminates the issue; therefor, the command should be option target 'overlay'

Pivot Root

After 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 r26311 it will appear mounted to /tmp/rom-disabled, while after 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,

mkfs.ext4 /dev/sda1  
mount /dev/sda1 /mnt/sda1
tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -
Note: mkfs.ext4 is provided by the package e2fsprogs.

Next, edit your fstab, for example with vi:

vi /etc/config/fstab

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):

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'

You can also use UCI CLI commands to change the fstab file:

uci set fstab.@mount[0].target=overlay
uci set fstab.@mount[0].enabled=1
uci commit fstab
/etc/init.d/fstab restart

Reboot your system.

To check if extroot is working run df and it should give an output like this:

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

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.

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)

Required Packages

  • block-mount

This is the only required extroot package for OpenWrt 12.09, see block_mount.

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

opkg update
opkg install block-mount
Also opkg install any filesystem or usb packages you need

Duplicate data

Copy necessary files from flash to the new root partition:

  1. 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):
    tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -
  2. For pivot-root (only possible as of 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
    mkdir -p /tmp/cproot
    mount --bind / /tmp/cproot
    tar -C /tmp/cproot -cvf - . | tar -C /mnt/sda1 -x
    umount /tmp/cproot

Configuration

The configuration of extroot is very simple and is done entirely in /etc/config/fstab.

Old external overlay variant (pivot-overlay)

Before 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.

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 fstab.

config mount option target /mnt # This is ignored once is_rootfs is set to 1 option device /dev/sda1 option fstype ext3 option options rw,sync option enabled 1 option enabled_fsck 0 option is_rootfs 1

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.

option is_rootfs is deprecated after 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)

While option is_rootfs will still work after r25787, the preferred method of configuring the extroot is option target /overlay in the config mount section for the rootfs device in the /etc/config/fstab file.

For trunk versions newer than and including r25787 use this variant. This is the entry in the /etc/config/fstab configuration file.

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 .

Whole external root (pivot-root)

After 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 new to OpenWrt 12. Backfire releases do not support this.

In order to set up such a whole root overlay, use the following fstab mount entry in the file /etc/config/fstab

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 r26311 it will appear mounted to /tmp/rom-disabled, while after 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:

cp /.extroot.md5sum /tmp/whole_root-disabled/etc/extroot.md5sum
or
cp /.extroot.md5sum /tmp/overlay-disabled/etc/extroot.md5sum

Example

The following steps were made on the hg553 using OpenWrt trunk@r28057: openwrt-HW553-jffs2-64k-cfe.bin after correctly setting up usb.essentials to obtain basic support for USB and usb.storage for USB storage.

The HG553 has two USB ports, I've used the one on the top. The USB drive was recognized as /dev/sda.

mkfs.ext4 /dev/sda1
mount /dev/sda1 /mnt
mkdir /tmp/cproot
mount --bind / /tmp/cproot
tar -C /tmp/cproot -cvf - . | tar -C /mnt -xvf -
sync ; umount /mnt
umount /tmp/cproot
Note: mkfs.ext4 is provided by package e2fsprogs.

After that, /etc/config/fstab should be edited to reflect the desired mount point:

config mount option target / option device /dev/sda1 option fstype ext4 option options rw,sync option enabled 1 option enabled_fsck 0

Note the fstype, options and enable_fchk options are optional, see fstab.

After reboot you should check your mounts and get something like:

/dev/root on /rom type jffs2 (ro,noatime)
proc on /proc type proc (rw,noatime)
sysfs on /sys type sysfs (rw,noatime)
tmpfs on /tmp type tmpfs (rw,nosuid,nodev,noatime,size=31020k)
tmpfs on /dev type tmpfs (rw,noatime,size=512k,mode=755)
devpts on /dev/pts type devpts (rw,noatime,mode=600)
/dev/sda1 on / type ext4 (rw,sync,relatime,user_xattr,barrier=1,data=ordered)
debugfs on /sys/kernel/debug type debugfs (rw,relatime)
none on /proc/bus/usb type usbfs (rw,relatime)

OpenWrt 10.03+ 'Backfire'

In OpenWrt 10.03 extroot was first introduced. Initially, only the pivot overlay variant was available.

Required Packages

You need the folowing packages:

  • block-extroot
  • block-hotplug
  • block-mount

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

opkg update
opkg install block-extroot block-hotplug block-mount 

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):

tar -C /overlay -cvf - . | tar -C /mnt/sda1 -xf -

Configuration

The configuration of extroot is very simple and is done entirely in /etc/config/fstab.

The external overlay variant (pivot overlay) is the only extroot variant available in Backfire.

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. The following is an example for an extroot fstab mount entry.

config mount option target /mnt # This is ignored once is_rootfs is set to 1 option device /dev/sda1 option fstype ext3 option options rw,sync option enabled 1 option enabled_fsck 0 option is_rootfs 1

A target option is not mandatory as it will be the overlay file system. However, using the directory /mnt for example 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.

For Backfire the option is_rootfs is required for extroot mounts. Later releases activate extroot dependent on the target being /overlay or /.
There is still a 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
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.
As of r26314 block-extroot and block-hotplug have been merged with block-mount.
doc/howto/extroot.old.txt · Last modified: 2016/04/01 17:26 by booBot