User Tools

Site Tools


doc:uci:fstab

Fstab Configuration

The Fstab, or file systems table, is a central configuration that defines how file systems (usually on block devices) should be mounted if requested (such as on booting the device or connecting it physically). This way, you don't have to manually mount your devices when you want to access them. The mounting configuration can consist of static file systems but also swap partitions. The fstab UCI configuration file is where all the options for all devices and file systems to be mounted are defined and is located at…

/etc/config/fstab

The package block-mount (see block_mount for details) contains several scripts necessary for mounting the entries in this configuration. For example, block-mount contains scripts that run the mounting process at boot or upon insertion of a USB hot-plug storage device, all according to the specified Fstab configuration. It also contains the Extroot load script. This article explains how the UCI Fstab configuration should be configured.

Please read the Notes before proceeding. Also read Storage for general information on partitioning devices, formatting and mounting file systems manually.

:!: BTRFS, JFS, UBI, XFS and potentially other (F2FS…) are not supported in /etc/config/fstab. Use manual scripting.

In r36988 the package block-mount was changed. For fstab functionality, the new block-mount package now contains the executable block which facilitates mounting. The new package ubox which is automatically installed as dependency of block-mount replaced its mounting functionality. You can run block <info|mount|umount|detect>.

Initial Configuration

Package Installation

The package block-mount is required for fstab functionality. Its functionality is now provided by ubox. It is set up as a standard init.d configuration:

  1. Install
    opkg update
    opkg install block-mount 

Creating Initial fstab Automatically

After r36988, when installing block-mount, you can use the new block utility. Call block detect to get a sample UCI configuration file. You can change this to your liking.

You can quickly install this standard configuration using:

block detect > /etc/config/fstab

Next, edit your fstab, as per the configuration below:

vi /etc/config/fstab

If the mount target is / then it will be used as external root upon boot. See Extroot for more information. Running block info is also valid to get the uuid of different file systems. Also see this guide: block_mount for technical details of the mounting process and scripts involved.

Enable fstab at Boot

  1. enable (make it start automatically on every boot up)
    /etc/init.d/fstab enable
  2. and start (right now)
    block mount

Whenever you change your configuration, restart this to make it take effect:

block umount;block mount

Configuration

The configuration file consists of mount sections defining file systems to be mounted and swap partitions to be activated.

Example Configuration

A sample configuration looks as follows:

#### Global options

config 'global'
        # mount swap devices that don't have their own config section
        option  anon_swap       '0'
        # mount block devices that don't have their own config section   
        option  anon_mount      '0'
        # automatically mount block devices when they appear
        option  auto_swap       '1'
        # automatically mount swap devices when they appear
        option  auto_mount      '1'
        # wait X seconds before trying to mount root devices on boot
        option  delay_root      '0'
        # run e2fsck on device prior to a mount
        option  check_fs        '0'

#### Mount sections. Note that partitions/devices can either be defined it by their device file,
#### mount point or UUID (or more at the same time).

# a swap partition
config 'swap'
        option  device  'sda1'
        option  uuid    'd3c87695-886f-4579-ae94-0a3bb3eb6046'

# a swap file
config 'swap'
        option  device  '/mnt/shared/swap'

# a swap device by label (mkswap -L swap /dev/sdb2)
config 'swap'
        option  label 'swap'

# a pivot overlay device (ext4) for extroot
config 'mount'
        option  target  '/overlay'
        option  uuid    '998d4bfc-81b5-469a-be2a-999ed2b81d88'

# and a data partition (vfat)
config 'mount'
        option  target  '/data'
        option  uuid    'e10e-6812'

:!: the sections below are often related to old versions before trunk r36988. FIXME

Automount

There is one global section named automount which defines the hotplug automounting behaviour.

This example is included by default:

config 'global' 'automount' option 'from_fstab' '1' option 'anon_mount' '1'

The automount section contains these settings:

Name Type Required Default Description
from_fstab boolean no 1 Whether to use mount sections when doing hotplug mounts
anon_mount boolean no 1 When using hotplug mounts, whether to automatically mount filesystems not defined in a mount section under /mnt/$device

Autoswap

There is one global section named autoswap which defines the hotplug auto swap behaviour.

This example is included by default:

config 'global' 'autoswap' option 'from_fstab' '1' option 'anon_swap' '0'

The autoswap section contains these settings:

Name Type Required Default Description
from_fstab boolean no 1 Whether to use swap sections when doing hotplug swap on
anon_swap boolean no 0 When using hotplug swapon, whether to automatically swapon devices not defined in a swap section

Mounting Filesystem

Each mount section defines a filesystem to be mounted at boot. Filesystems must be formatted before they can be used. :!: mount section can not be renamed by user (such as "storage" instead of "mount").

This example is included by default:

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

The mount section contains these settings:

Name Type Required Default Description
device string yes or uuid or label (none) Device (partition) to mount the filesystem from. If uuid or label are specified, they are used, rather than device.
uuid string yes or device or label (none) UUID of device (partition) to mount the filesystem from, as shown by blkid. If uuid is present in the mount section, it is used in preference to label or device.
label string yes or device or uuid (none) LABEL of device (partition) to mount the filesystem from, as shown by blkid. If uuid is present in the mount section, it takes precedence. label takes precedence over device.
enabled boolean no 1 Whether to mount this filesystem automatically at boot.
fstype string no auto Type of the filesystem (i.e. ext3). remote file systems
options string no rw Mount options for this filesystem.
target string yes (none) Target directory to mount the filesystem onto. After trunk r25787 specifying '/overlay' here means this filesystem will be mounted as the overlay-based rootfs, while after trunk r26109 specifying '/' here means the filesystem will be mounted as regular rootfs (that is not overlay-based) (see extroot). Neither '/' nor '/overlay' aplies to Backfire.
enabled_fsck boolean no 0 Whether to automatically check for/repair errors before mounting the filesystem.
is_rootfs boolean no 0 »Please read the particular article extroot for this functionality!«
deprecated after trunk r25787, still needed in Backfire.
Before r25787 it is required for block-extroot mounts

Adding Swap Partitions

Each swap section defines a swap partition to be activated at boot.
:!: Swap partitions must be formatted before they can be used and the swap-utils package needs to be installed!
:!: Swap partitions must be first defined (i.e. formatted and hex type 82 (LINUX_SWAP) selected as its partition type) using the mkswap /dev/device command!

This example is included by default:

config 'swap' option 'device' '/dev/sda2' option 'enabled' '0'

The swap section contains these settings:

Name Type Required Default Description
device string yes or uuid or label (none) Device (partition) to mount the swap from. uuid and label take precedence
uuid string yes or device or label (none) UUID of device (partition) to mount the swap from, as shown by blkid. If uuid is present in the mount section, it is used in preference to label or device.
label string yes or device or uuid (none) LABEL of device (partition) to mount the swap from, as shown by blkid. If uuid is present in the mount section, it takes precedence. label takes precedence over device.
enabled boolean no 1 Whether to activate this swap partition automatically at boot.

The right amount of SWAP

If you ask people or search the net, you will find as a general rule of thumb double RAM for machines with 512MiB of RAM or less than, and same amount as RAM for machines with more. But this very rough estimate does apply for your embedded device! Be aware that there are exactly two differences between RAM and SWAP, that matter: the access time and the price. A CUPS spooling server will run just fine, when only SWAP is available, whereas some applications may perform very poorly when their data it stored on the SWAP rather then being kept in the "real" RAM. The decision which data is kept in the RAM and which is stored on the SWAP is made by the system. As explained here Debian Forum (german) since Kernel 2.6 you can define the swapiness of your system:

root@OpenWrt:~# sysctl -w vm.swappiness=60
root@OpenWrt:~# echo 60 > /proc/sys/vm/swappiness

In contrast to other operating systems, Linux makes ample use of memory, so that your system runs smoother and more efficiently. If memory is then needed by an application, the system will unload stuff again, and make memory available. For OpenWrt, let us just say to use as much SWAP-Space as needed by your applications running. If this should not perform well, because of the poor access time, it would not help to decrease the amount of SWAP, but only to run fewer services at the same time or increase the amount of RAM with a soldering iron ;-)

OpenWrt vanilla will run just fine, with no SWAP at all. But after you installed a couple of applications, you could try to mount a SWAP-Partition and see what is does for you. Do not worry, you can not brake anything by doing that. The manual commands are swapon /dev/sdaX to mount respectivly swapoff /dev/sdaX to unmount. Type in free to see the usage of memory:

root@OpenWrt:~# free
              total         used         free       shared      buffers
  Mem:        29484        28540          944            0         1116
 Swap:       524280         2336       521944
Total:       553764        30876       522888

In this example there is 32MiB of RAM and 512MiB of SWAP. SWAP is a SWAP-formated 512MiB-Partition on a large USB-Harddisk. In this example, only 2MiB of swap are being used! And you do not see here, that actually a TMPFS-Directory is allowed to use as much as half the RAM. Use df to see that:

root@OpenWrt:~# df  
Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/root                 1280      1280         0 100% /rom
tmpfs                    14744       116     14628   1% /tmp       <= //Up to 14MiB of RAM may be used here, the//
tmpfs                      512         0       512   0% /dev         //tmpfs directories grow and shrink with usage!//
/dev/mtdblock3            5440      4988       452  92% /overlay
mini_fo:/overlay          1280      1280         0 100% /
/dev/sda2              2709204     86276   2485284   3% /mnt/sda2
/dev/sda3              7224600    147320   6710196   2% /mnt/sda3

In this example, it would probably perform better, to mount the /tmp-directory on the USB-Harddisk and not use TMPFS at all, rather than using a 512MiB-Swap Partition. But you can also see, that overlay has only 8% space left to install programs on. So in this example it would be even better to use the exroot option. See extroot for that.

Supersizing /tmp directory

If you want to store large amount of data in your /tmp folder you may hit size limit of tmpfs partitions, which is by default 50 % of your RAM. Because your RAM size is limited and probably better utilized by applications, you want the files in /tmp to be moved to swap as soon as applications need more RAM for themself.

  1. We will remove the limit of 50 % of RAM. You can set size parameter to the size of your swap.
    • temporarily:
      mount -t tmpfs -o remount,rw,nosuid,nodev,noatime,size=256M tmpfs /tmp
    • permanently in /etc/config/fstab:
      config 'mount'
        option 'target' '/tmp'
        option 'device' 'tmpfs'
        option 'fstype' 'tmpfs'
        option 'options' 'remount,rw,nosuid,nodev,noatime,size=256M'
        option 'enabled_fsck' '0'
        option 'enabled' '1'
  2. And we will set /tmp files to be more likely swapped than applications in RAM.
    • temporarily:
      echo 5 > /proc/sys/vm/swappiness
    • permanently:
      sysctl -w vm.swappiness=5

You can revert the changes by:

mount -t tmpfs -o remount,rw,nosuid,nodev,noatime,size=50% tmpfs /tmp
echo 60 > /proc/sys/vm/swappiness
sysctl -w vm.swappiness=60

Troubleshooting

Sleep before startup

I installed the packages, enabled the fstab, and changed my fstab config file. When I restart, the drive does NOT show up. I can issue an /etc/init.d/fstab start and I get an error that it can't find a file (/tmp/fstab) but the drive mounts. I took the advice from this posting https://forum.openwrt.org/viewtopic.php?id=27210 and put "sleep 15" in the start function of the /etc/init.d/fstab file. (I'm using a USB stick) That fixed the problem.

start() { sleep 15 config_load fstab mkdir -p /var/lock lock /var/lock/fstab.lck #echo '# WARNING: this is an auto generated file, please use uci to set defined filesystems' > /etc/fstab lock -u /var/lock/fstab.lck config_foreach do_mount mount config_foreach do_swapon swap }

https://forum.openwrt.org/viewtopic.php?id=28311

This may be obsolete for Barier Breaker since block-mount suports option delay_root (wait X seconds before trying to mount root devices on boot) FIXME

Fstab does not mount partition on boot

Symptoms: You can mount your partition with mount -t ext4 /dev/sda1 /mnt -o rw,sync, but fstab won't mount it automatically on reboot. You are using Backfire or older version.

Solution: Despite you have installed block-mount try to install block-hotplug separately:

opkg update
opkg install block-hotplug

Note: This may or may not apply also to block-extroot. This problem should not occur in Attitude Adjustment.

Wait for mount is done

Symptoms: When you use fstab to mount external drives that are used by transmission, samba or etc, you can face with issue of late mount. It means that transmission could start earlier when block-mount finishes mounting fstab. In this case transmission tries to look up for directories, can't find and create it in root fs under your mount point folder.

Solution: Usually is needed to postpone starting transmission, samba or other daemons on start. It could be done by following script:

#!/bin/sh /etc/rc.common

START=41
TIMEOUT=60

start()
{
        idx=0
        res=`uci -q get fstab.@mount[$idx].enabled`
        while [ $? -eq 0 ];
        do
                if [ $res -ne 0 ]
                then
                        res=`uci -q get fstab.@mount[$idx].wait4mounted`
                        if [ $? -ne 0 ] || [ $res -ne 0 ]
                        then
                                res=`uci -q get fstab.@mount[$idx].target`
                                mnt=$(printf '%s\n%s' $mnt $res)
                        fi
                fi

                idx=$(($idx+1))
                res=`uci -q get fstab.@mount[$idx].enabled`
        done

        notReady="all"
        timeout=$TIMEOUT

        while [ -n "$notReady" ] && [ $timeout -gt 0 ];
        do
                if [ "$notReady" != "all" ]
                then
                        sleep 5
                        timeout=$(($timeout-5))
                fi

                notReady=""

                for m in $mnt; do
                        res=`mount | grep -iw $m`
                        if [ -z "$res" ]
                        then
                                notReady=$(printf '%s %s' $notReady $m)
                        fi
                done
        done

        if [ -n "$notReady" ]
        then
                echo "Following mount points were not ready during $TIMEOUT seconds: $notReady"
                exit 1
        fi

        exit 0
}

Steps to make it works:

  1. goto /etc/init.d folder
  2. create file wait4mount and put script above
  3. run chmod 755 wait4mount to make it executable
  4. run /etc/init.d/wait2mount enable to enable it on start

How does it work? Script runs just after fstab script, reads from /etc/config/fstab entries config mount, checks if entry enabled and waits for mount points will be ready. If some of them will not be ready during 60 seconds, script exits with message what mount points were not ready.

In case you want to wait only for one mounting point, you can use option wait4mounted 1|0. By default, wait4mounted=1.

Example:

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'

# By default, script will wait for '/home'
config mount
        option target   /home
        option uuid     4b76ee08-eaa5-4288-8cb1-c2ca26c594bd
        option fstype   ext4
        option options  rw,sync
        option enabled  1

# Script doesn't care about '/home2' because of 'wait4mounted=0'
config mount
        option target   /home2
        option uuid     a09273df-0dd6-4526-b7ba-181283e45e5a
        option fstype   ext4
        option options  rw,sync
        option enabled  1
        option wait4mounted 0

# Script doesn't care about '/raid1' because of 'enabled=0' and 'wait4mounted' was ignored
config mount
       option target   /raid1
       option uuid     beb33a09-e6a9-40d4-891e-b09535104572
       option fstype   ext4
       option options  rw,sync
       option enabled  0

Notes

block-mount: Scripts used to mount and check block devices (file systems and swap), as well as hotplug scripts to automount and check block devices when hotplug event (e.g. from plugging in a device) occurs. Also includes preinit scripts for mounting a block device as the root filesystem. This allows one to have the root filesystem on devices other than the built in flash device.
As of trunk r26314 block-extroot and block-hotplug have been merged with block-mount, they're still separate in Backfire.
In the OpenWrt 'Backfire' 10.03 release there is a bug. Solution is: vi /etc/init.d/fstab and put a # in front of the line:
echo '# WARNING: this is an auto generated file, please use UCI to set defined filesystems' > /etc/fstab
This creates the file /etc/fstab and thus prevents creating a symlink to /tmp/fstab. In order for UCI to work, there need to be symlink! In case the bug has already taken place, delete /etc/fstab and then type this code to busybox.
ln -s /tmp/fstab /etc/fstab
It will create a symlink to the /tmp/fstab file, fixing the bug completely.
In the OpenWrt 'Backfire' 14.07 release, the tmpfs resize option via fstab config does not work

UUID or Label mount

  • remove mount, umount provided by BusyBox

rm /bin/mount
rm /bin/umount

  • install mount-utils

opkg update
opkg install mount-utils

  • find UUID or Label

blkid /dev/sda1

  • mount a disk

mount LABEL=xxx /mnt
mount UUID=xxx /mnt

doc/uci/fstab.txt · Last modified: 2015/01/30 18:05 by andreas85