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)
    /etc/init.d/fstab start

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

/etc/init.d/fstab restart

FIXME As of, or before 2014-04-14, running:

/etc/init.d/fstab start|restart
results in the following error message:
this file has been obseleted. please call "/sbin/block mount" directly
. Need to document the [b]new[b] proper way of doing things for Barrier Breaker.

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

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.

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

Back to top

doc/uci/fstab.txt · Last modified: 2014/10/22 23:38 by spy00a35