| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:techref:filesystems [2018/02/20 20:37] – ↷ Links adapted because of a move operation | docs:techref:filesystems [2024/03/09 03:22] (current) – [Filesystems] add link to intro palebloodsky |
|---|
| ====== Filesystems ====== | ====== Filesystems ====== |
| |
| This article is about file systems in the OpenWrt installation on built-in flash. | This article is about file systems used by OpenWrt for device built-in flash. |
| For general external support for installing file systems on other devices, including partitioning and mounting see [[docs:user-guide:storage:start|this page about general storage]]. | |
| |
| Please read about the -> [[flash.layout]] as well. Also, note that there are two types of flash memory: [[wp>Flash_memory#NOR_flash|NOR flash]] and [[wp>Flash_memory#NAND_flash|NAND flash]]. Also, you should read up on ''[[docs:techref:mtd]]''. | For installing additional file systems, including partitioning and mounting, see this page for [[docs:guide-user:storage:start|general storage]] as well as this page to other common [[:docs:guide-user:storage:filesystems-and-partitions|filesystems]]. |
| | |
| | Please read about the [[flash.layout]] as well. Also, note that there are two types of flash memory: [[wp>Flash_memory#NOR_flash|NOR flash]] and [[wp>Flash_memory#NAND_flash|NAND flash]]. See also [[docs:techref:mtd]]. |
| |
| ===== Common File System ===== | ===== Common File System ===== |
| |
| ==== OverlayFS ==== | ==== OverlayFS ==== |
| Used to merge two filesystems, one read-only and the other writable. [[flash.layout]] explains how this is used in OpenWRT. | Used to merge two filesystems, one read-only and the other writable. [[flash.layout]] explains how this is used in OpenWrt. |
| | * [[wp>OverlayFS]] |
| | * [[https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html|Overlayfs documentation]] |
| * [[https://dev.openwrt.org/browser/trunk/target/linux/generic/patches-2.6.38/209-overlayfs.patch?rev=26213]] | * [[https://dev.openwrt.org/browser/trunk/target/linux/generic/patches-2.6.38/209-overlayfs.patch?rev=26213]] |
| * http://lwn.net/Articles/447650/ | * [[http://lwn.net/Articles/447650/|Debating overlayfs]] on LWN.net |
| * was mainlined in Linux kernel 3.18, see [[https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/Documentation/filesystems/overlayfs.txt|/Documentation/filesystems/overlayfs.txt]] | * Was mainlined in Linux kernel 3.18 |
| * [[https://git.kernel.org/cgit/linux/kernel/git/mszeredi/vfs.git/tree/Documentation/filesystems/overlayfs.txt?h=overlayfs.current | Overlayfs documentation]] in the official development tree | |
| * Overlayfs's support for inotify mechanisms is not complete yet. Events like IN_CLOSE_WRITE cannot be notified to listening process. | * Overlayfs's support for inotify mechanisms is not complete yet. Events like IN_CLOSE_WRITE cannot be notified to listening process. |
| | |
| |
| ==== tmpfs ==== | ==== tmpfs ==== |
| * [[wp>tmpfs]] | [[wp>tmpfs]] is implemented on many Unix-like operating systems (including OpenWrt). It operates similar to a RAM-Disk, without writing files to disk. In OpenWrt, ''/tmp'' resides on a tmpfs-partition and ''/var'' is a symlink to it; ''/dev'' resides on a little tmpfs partition of its own. |
| * ''/tmp'' resides on a tmpfs-partition and ''/var'' is a symlink to it; ''/dev'' resides on a little tmpfs partition of its own | |
| * (+) no wear leveling | * [[https://www.kernel.org/doc/html/latest/filesystems/tmpfs.html|Kernel documentation on tmpfs]] |
| | |
| | * (+) doesn't directly use space on non-volatile storage |
| | * (-) no wear leveling |
| * (-) volatile (doesn't survive a reboot) | * (-) volatile (doesn't survive a reboot) |
| * [[http://lxr.free-electrons.com/source/Documentation/filesystems/tmpfs.txt|Kernel documentation on tmpfs]] | |
| |
| ==== SquashFS ==== | ==== SquashFS ==== |
| |
| * (+) taking up as little space as possible | * (+) taking up as little space as possible |
| * (+) allowing the implementation of an idiot proof [[docs:user-guide:troubleshooting:failsafe_and_factory_reset|FailSafe]] for recovery, since it is not possible to write to it | * (+) allowing the implementation of an idiot proof [[docs:guide-user:troubleshooting:failsafe_and_factory_reset|FailSafe]] for recovery, since it is not possible to write to it |
| * (-) read only | * (-) read only |
| * (-) waste space, since each time a file contained on it is modified, actually a copy of it is being copied to the second (JFFS2) partition | * (-) waste space, since each time a file contained on it is modified, actually a copy of it is being copied to the second (JFFS2) partition |
| * [[http://lxr.free-electrons.com/source/Documentation/filesystems/squashfs.txt|Kernel documentation on SquashFS]] | * [[https://www.kernel.org/doc/html/latest/filesystems/squashfs.html|Kernel documentation on SquashFS]] |
| * [[http://tree.celinuxforum.org/CelfPubWiki/SquashFsComparisons|SquashFs Performance Comparisons]] | * [[https://elinux.org/Squash_Fs_Comparisons|SquashFs Performance Comparisons]] |
| | |
| There is a generic problem when running SquashFS on NAND: The issue is that SquashFS has no bad block management at all and requires all blocks on order; but for proper NAND bad block management you also need to be able to skip bad blocks and occasionally relocate blocks (see [[http://www.infradead.org/pipermail/linux-mtd/2006-April/015386.html|squashfs and NAND flash]]). That's why raw SquashFS is a bad idea on NAND (it works if you use a FTL like UBIFS). | |
| |
| | There is a generic problem when running SquashFS on NAND: The issue is that SquashFS has no bad block management at all and requires all blocks on order; but for proper NAND bad block management you also need to be able to skip bad blocks and occasionally relocate blocks (see [[https://www.infradead.org/pipermail/linux-mtd/2006-April/015386.html|squashfs and NAND flash]]). That's why raw SquashFS is a bad idea on NAND (it works if you use a FTL like UBIFS). |
| |
| ==== JFFS2 ==== | ==== JFFS2 ==== |
| * (+) is writable, has journaling and wear leveling | * (+) is writable, has journaling and wear leveling |
| * (+) is cool | * (+) is cool |
| * (-) is compressed, so a program (''[[docs:user-guide:additional-software:opkg]]'' in particular) cannot know in advance how much space a package will occupy | * (-) is compressed, so a program (''[[docs:guide-user:additional-software:opkg]]'' in particular) cannot know in advance how much space a package will occupy |
| * (+) is compressed, so a program (which is preinstalled) takes much less space, so effectively you have more space | * (+) is compressed, so a program (which is preinstalled) takes much less space, so effectively you have more space |
| | |
| | For NAND-flash targets, it was replaced with UBIFS. |
| |
| ==== UBIFS ==== | ==== UBIFS ==== |
| * [[wp>UBIFS]] is a file system for [[docs:techref:flash.layout|raw flash]]. It is used in OpenWrt NAND targets since :FIXME: around r40364 | * [[wp>UBIFS]] is a file system for [[docs:techref:flash.layout|raw flash]]. It is used in OpenWrt NAND targets since :FIXME: around r40364 |
| * [[http://lxr.free-electrons.com/source/Documentation/filesystems/ubifs.txt|Kernel documentation on UBIFS]] | * [[https://www.kernel.org/doc/html/latest/filesystems/ubifs.html|Kernel documentation on UBIFS]] |
| * https://lwn.net/Articles/704261/ how does UBIFS understand what a "file" is? Isn't a file | * [[https://lwn.net/Articles/704261/|UBIFS File Encryption]] how does UBIFS understand what a "file" is? Isn't a file |
| * https://lwn.net/Articles/706338/ | * [[https://lwn.net/Articles/706338/|UBIFS File Encryption v1]] on LWN.net |
| * https://lwn.net/Articles/707900/ | * [[https://lwn.net/Articles/707900/|UBIFS File Encryption v2]] on LWN.net |
| * [[https://www.phoronix.com/scan.php?page=news_item&px=UBI-UBIFS-Linux-4.9|UBIFS Supports OverlayFS In Linux 4.9, Readying UBI For MLC Support]] | * [[https://www.phoronix.com/scan.php?page=news_item&px=UBI-UBIFS-Linux-4.9|UBIFS Supports OverlayFS In Linux 4.9, Readying UBI For MLC Support]] |
| | |
| ==== ext2 ===== | ==== ext2 ===== |
| * [[wp>ext2]] | * [[wp>ext2]] |
| * Ext2/3/4 is used on x86, x86-64 and for some arch with SD-card rootfs | * Ext2/3/4 is used on x86, x86-64 and for some arch with SD-card rootfs |
| * [[http://lxr.free-electrons.com/source/Documentation/filesystems/ext2.txt|Kernel documentation on ext2]] | * [[https://www.kernel.org/doc/html/latest/filesystems/ext2.html|Kernel documentation on ext2]] |
| * (+) a program (''[[docs:user-guide:additional-software:opkg]]'' in particularly) knows how much space is left! | * (+) a program (''[[docs:guide-user:additional-software:opkg]]'' in particularly) knows how much space is left! |
| * (+) good ol' veteran FOSS file system | * (+) good ol' veteran FOSS file system |
| * (-) no journaling | * (-) no journaling (ext3, ext4 support journaling) |
| * (-) no wear leveling | * (-) no wear leveling |
| * (-) no transparent compression | * (-) no transparent compression |
| ===== Other filesystems ===== | ===== Other filesystems ===== |
| |
| OpenWrt does not use other filesystems as rootfs. It supports several filesystem attached to via various mechanisms like USB, SATA or network. For a list see [[docs:user-guide:storage:start]]. | OpenWrt does not use other filesystems as rootfs. It supports several filesystems attached to via various mechanisms like USB, SATA or network. For a list see [[docs:guide-user:storage:start]]. |
| |
| ==== mini_fo ==== | ==== mini_fo ==== |
| * was used by older OpenWrt version and thus there are still references to this in the Wiki | * was used by older OpenWrt version and thus there are still references to this in the Wiki |
| * replaced by [[#OverlayFS]] now. | * replaced by [[#OverlayFS]] now. |
| * [[https://lwn.net/Articles/135283]] | * [[https://lwn.net/Articles/135283|The mini_fo filesystem]] on LWN.net |
| * [[http://www.denx.de/wiki/bin/view/Know/MiniFOHome]] | * [[https://www.denx.de/wiki/bin/view/Know/MiniFOHome|mini_fo: The mini fanout overlay file system]] official site |
| |
| |
| ===== Implementation in OpenWrt ===== | ===== Implementation in OpenWrt ===== |
| The [[docs:techref:flash.layout]] article documents how OpenWrt uses both SquashFS and JFFS2 filesystems combined into one filesystem by overlayfs. The kernel is also stored separately from these partitions in raw flash. When the kernel is built, it is also compressed with [[wp>Lempel–Ziv–Markov chain algorithm|LZMA]] and [[wp>gzip]], as documented in [[doc:howto:obtain.firmware.generate]]. | The [[docs:techref:flash.layout]] article documents how OpenWrt uses both SquashFS and JFFS2 filesystems combined into one filesystem by overlayfs. The kernel is also stored separately from these partitions in raw flash. When the kernel is built, it is also compressed with [[wp>Lempel–Ziv–Markov chain algorithm|LZMA]] and [[wp>gzip]], as documented in [[docs:guide-user:additional-software:imagebuilder]]. |
| |
| ==== Boot process ==== | ==== Boot process ==== |
| System bootup is as follows: ->[[process.boot]] | System bootup is as follows: ->[[process.boot]] |
| - kernel boots from a known raw partition (without a FS), scans mtd partition //rootfs// for a valid superblock and mounts the SquashFS partition (containing ''/etc'') then runs ''[[docs:user-guide:notuci.config#etcpreinit|/etc/preinit]]''. (More info at [[docs:techref:filesystems#technical.details]]) | - kernel boots from a known raw partition (without a FS), scans mtd partition //rootfs// for a valid superblock and mounts the SquashFS partition (containing ''/etc'') then runs ''[[docs:guide-user:base-system:notuci.config#etcpreinit|/etc/preinit]]''. (More info at [[docs:techref:filesystems#technical.details]]) |
| - ''/etc/preinit'' runs ''[[https://dev.openwrt.org/browser/trunk/package/base-files/files/sbin/mount_root|/sbin/mount_root]]'' | - ''/etc/preinit'' runs ''[[https://dev.openwrt.org/browser/trunk/package/base-files/files/sbin/mount_root|/sbin/mount_root]]'' |
| - ''mount_root'' mounts the JFFS2 partition (''/overlay'') and **combines** it with the SquashFS partition (''/rom'') to create a new //virtual root filesystem// (''/'') | - ''mount_root'' mounts the JFFS2 partition (''/overlay'') and **combines** it with the SquashFS partition (''/rom'') to create a new //virtual root filesystem// (''/'') |
| The fact that we pack things so tightly in flash means that if the firmware ever changes, the size and location of the JFFS2 partition also changes, potentially wiping out a large chunk of JFFS2 data and corrupting the filesystem. To deal with this, we've implemented a policy that after each reflash the JFFS2 data is reformatted. The trick to doing that is a special value, ''0xdeadc0de''; when this value appears in a JFFS2 partition, everything from that point to the end of the partition is wiped. So, hidden at the end of the firmware images, is the value 0xdeadcode, positioned such that it becomes the start of the JFFS2 partition.\\ | The fact that we pack things so tightly in flash means that if the firmware ever changes, the size and location of the JFFS2 partition also changes, potentially wiping out a large chunk of JFFS2 data and corrupting the filesystem. To deal with this, we've implemented a policy that after each reflash the JFFS2 data is reformatted. The trick to doing that is a special value, ''0xdeadc0de''; when this value appears in a JFFS2 partition, everything from that point to the end of the partition is wiped. So, hidden at the end of the firmware images, is the value 0xdeadcode, positioned such that it becomes the start of the JFFS2 partition.\\ |
| The fact that we use a combination of compressed and partially read only filesystems also has an interesting effect on package management:\\ | The fact that we use a combination of compressed and partially read only filesystems also has an interesting effect on package management:\\ |
| In particular, you need to be careful what packages you update. While ''[[docs:user-guide:additional-software:opkg]]'' is more than happy to install an updated package on JFFS2, it's unable to remove the original package from SquashFS; the end result is that you slowly start using more and more space until the JFFS2 partition is filled. The opkg util really has no idea how much space is available on the JFFS2 partition since it's compressed, and so it will blindly keep going until the opkg system crashes -- at that point you have so little space you probably can't even use opkg to remove anything. | In particular, you need to be careful what packages you update. While ''[[docs:guide-user:additional-software:opkg]]'' is more than happy to install an updated package on JFFS2, it's unable to remove the original package from SquashFS; the end result is that you slowly start using more and more space until the JFFS2 partition is filled. The opkg util really has no idea how much space is available on the JFFS2 partition since it's compressed, and so it will blindly keep going until the opkg system crashes -- at that point you have so little space you probably can't even use opkg to remove anything. |
| |
| === Explanation 2 === | === Explanation 2 === |
| |
| ===== Notes ===== | ===== Notes ===== |
| Example pictures: on formated partition / how data is stored (and addressed on ext3) | Example pictures: on formatted partition / how data is stored (and addressed on ext3) |
| * how data is stored and addressed by ext2: | * how data is stored and addressed by ext2: |
| * how data is stored and addressed by ext3: | * how data is stored and addressed by ext3: |
| * how data is stored and addressed by JFFS2: | * how data is stored and addressed by JFFS2: |
| |
| ===== Archive ===== | |
| |
| * see [[docs:techref:filesystems.old]] | |