Jump to content

# F2FS

From ArchWiki

Related articles

- File systems

F2FS (Flash-Friendly File System) is a file system intended for NAND-based flash memory equipped with Flash Translation Layer. Unlike JFFS or UBIFS it relies on a flash-transition layer (FTL) to handle write distribution. It is supported from kernel 3.8 onwards.

An FTL is found in all flash memory with a SCSI/SATA/PCIe/NVMe interface [1], opposed to bare NAND Flash and SmartMediaCards [2].

Warning The data contained on F2FS partitions can become unusable if the kernel version on the running machine is older than the kernel version used to create the partition. For example, this limitation can manifest if the F2FS partition was created on a mainline kernel provided by linux yet the system has a need to downgrade to an older series of kernels provided by linux-lts. See the minimum version required for each feature table in this article and FS#69363.

This article or section needs expansion.

Reason: What advantages f2fs has over other fs, such as ext4? Is it recommended for being used inside lvm? (Discuss in Talk:F2FS)

## Known issues

### fsck failures

F2FS has a weak fsck that can lead to data loss in case of a sudden power loss [3][4].

If power losses are frequent, consider an alternative file system.

### Long running fsck delays boot

This article or section is out of date.

Reason: The commit is in f2fs-tools 1.14.0. What is the status of the issue now? (Discuss in Talk:F2FS)

If the kernel version has changed between boots, the fsck.f2fs utility will perform a full file system check which will take longer to finish[5].

This may be mitigated in the future thanks to a recent commit [6].

### GRUB support

While GRUB supports F2FS since version 2.0.4, it cannot correctly read its boot files from an F2FS partition that was created with the `extra_attr` flag enabled (for more details, see GRUB#Unsupported file systems).

### Cannot set file attributes for '/var/log/journal'

If the error:

    Cannot set file attributes for '/var/log/journal', maybe due to incompatibility in specified attributes, previous=0x10001000, current=0x10001000, expected=0x10801000, ignoring.

is present in your journal, it can be safely ignored: it is due to systemd-tmpfiles trying to use a file system feature that is not supported by F2FS.

## Creating a F2FS file system

This article assumes the device has partitions already setup. Install f2fs-tools. Use `mkfs.f2fs` to format the target partition referred to as `/dev/sdxY`:

    # mkfs.f2fs -l mylabel -i -O extra_attr,inode_checksum,sb_checksum /dev/sdxY

Note

- The `-i` option is included to allow more space for inodes.
- `extra_attr`, `inode_checksum`, and `sb_checksum` are options which help fsck.f2fs to detect and to fix some types of filesystem corruption. See mkfs.f2fs(8) for all available options.

### Compression

Note Unlike other filesystems with inline compression, f2fs compression does not expose additional freespace by default and instead reserves the same number of blocks regardless of whether compression is enabled or not. The primary goal is reducing writes to extend flash lifetime, and potentially, a small increase in performance. See Compression Implementation in the kernel docs. `F2FS_IOC_RELEASE_COMPRESS_BLOCKS` can be used to expose unused space on a per-file basis, but it makes the file immutable in the process.

To use compression, include the `compression` option. Example:

    # mkfs.f2fs -l mylabel -O extra_attr,inode_checksum,sb_checksum,compression /dev/sdxY

When mounting the filesystem, specify `compress_algorithm=(lzo|lz4|zstd|lzo-rle)`. Using `compress_extension=txt` will cause all txt files to be compressed by default.

In order to tell F2FS to compress a file or a directory, use :

    $ chattr -R +c [FOLDER]

### File-based encryption support

Since Linux 4.2, F2FS natively supports file encryption. Encryption is applied at the directory level, and different directories can use different encryption keys. This is different from both dm-crypt, which is block-device level encryption, and from eCryptfs, which is a stacked cryptographic filesystem. To use F2FS's native encryption support, see the fscrypt article. Create the file system with

     # mkfs.f2fs -l mylabel -O extra_attr,inode_checksum,sb_checksum,encrypt /dev/sdxY

or add encryption capability at a later time with `fsck.f2fs -O encrypt /dev/sdxY`.

## Mounting a F2FS file system

The file system can then be mounted manually or via other mechanisms:

    # mount /dev/sdxY /mnt/foo

### Recommended mount options

Since F2FS is designed to be used on flash devices, compression is a good idea. You have to enable it at `mkfs.f2fs` time. A few mount options can be used to improve things slightly.

    # mount -o compress_algorithm=zstd:6,compress_chksum,atgc,gc_merge,lazytime /dev/sdxY /mnt/mountpoint

- `compress_algorithm=zstd:6` tells F2FS to use zstd for compression at level 6, which should give pretty good compression ratio.
- `compress_chksum` tells the filesystem to verify compressed blocks with a checksum (to avoid corruption)
- `atgc,gc_merge` Enable better garbage collector, and enable some foreground garbage collections to be asynchronous.

  Note See #Remounting impossible with some options.

- `lazytime` Do not synchronously update access or modification times. Improves IO performance and flash durability.

### Implementation of discard

By default, F2FS is mounted using a hybrid TRIM mode which behaves as continuous TRIM. This implementation creates asynchronous discard threads to alleviate long discarding latency among RW IOs. It keeps candidates in memory, and the thread issues them in idle time [7]. As a result of this, users wanting periodic TRIM will need to implicitly set the `nodiscard` mount option in `/etc/fstab` or pass it to mount if mounting manually.

## Checking and repair

Checking and repairs to F2FS file systems are accomplished with `fsck.f2fs` provided by f2fs-tools. To check a file system, execute

    # fsck.f2fs /dev/sdxY

Depending on the result, see fsck.f2fs(8) for available switches to repair inconsistencies. For example:

    # fsck.f2fs -f /dev/sdxY

## Grow an F2FS file system

When the filesystem is unmounted, it can be grown if the partition is expanded. Shrinking is not currently supported.

First use a partition tool to resize the partition: for example, suppose the output of the `print` command in the `parted` console is the following:

    Number  Start   End     Size        File system     Name                  Flag
     1      1049kB  106MB   105MB       fat32           EFI system partition  boot, esp
     2      106MB   11,0GB  10,9GB      ext4
     3      11,0GB  12,3GB  1322MB      f2fs
     4      31,0GB  31,3GB  261MB       ext4

To resize the `f2fs` partition to occupy all the space up to the fourth one, just give `resizepart 3 31GB` and `exit`. Now expand the filesystem to fill the new partition using:

    # resize.f2fs /dev/sdxY

where `/dev/sdxY` is the target F2FS volume to grow. See resize.f2fs(8) for supported options.

Note If using GPT, the partition's GUID (seen in `/dev/disk/by-partuuid/`) might change, but the filesystem UUID (seen in `/dev/disk/by-uuid/`) should stay the same.

## Troubleshooting

### Remounting impossible with some options

As alluded to in Fsck#Boot time checking, the kernel keeps file systems in a read-only state by default, and it is either explicitly needed to pass the `rw` kernel parameter or have systemd remounting the filesystems as read-write with the `systemd-remount-fs.service`.

When remounting the file system from a read-only state to a read-write state, the `mount -o remount,... /` steps can fail for multiple reasons, which will either leave the root file system read-only or make the system unable to boot with the error message:

    Failed to start Remount Root and Kernel File Systems.

If the `atgc` option is specified in the fstab file but has not been passed as a kernel parameter, the F2FS kernel module will not permit re-mounting with an added or cleared `atgc` option[8][9], either:

- add the kernel parameter `rootflags=atgc` to your boot loader configuration,
- add the kernel parameter `rw` to your boot loader configuration,
- remove the `atgc` mount option from the fstab.

Since linux 6.2, a check is made in the kernel to disable `flush_merge` when the file system is read-only, but it is the state of the file system before remounting that is checked. As explained in FS#77596, either:

- add the kernel parameter `rw` to your boot loader configuration,
- remove the `flush_merge` mount option from the fstab.

## Minimum version required for each feature

Feature name | Description | Kernel version | F2FS tools version | Kernel commit | F2FS tools commit
--- | --- | --- | --- | --- | ---
Lost parent inode number (pino) bit | If a file is linked, F2FS may loose its parent inode number so that fsync calls for the linked file need to perform the checkpoint every time. But, if the pino can be recovered after the checkpoint, roll-forward mechanism for the further fsync calls can be adjusted, which improves the fsync performance significantly. | 3.11 | N/A | 354a3399dc6f ("f2fs: recover wrong pino after checkpoint during fsync") | N/A
Inline extended attributes | Add a mount option inline_xattr, which is enabled when xattr is set, if the mount option is enabled, all the files are marked with the inline_xattrs flag. | 3.12 | 1.2.0 | 444c580f7e9a ("f2fs: add flags for inline xattrs") | cd1e470 ("fsck, lib: support inline xattr")
Inline data | Support inline data in regular/symlink inode via inline_data mount option. | 3.14 | 1.3.0 | 1001b3479ce9 ("f2fs: add flags and helpers to support inline data") | 061ee67 ("f2fs-tools: add inline data check")
Large directory | Add a parameter to adjust structure of large directory for lookup performance tuning. | 3.15 | 1.4.0 | 3843154598a0 ("f2fs: introduce large directory support") | 99250ec ("mkfs: support large directory")
Large volume | Support for large volumes over around 3TB. | 3.16 | 1.4.0 | 1dbe4152168d ("f2fs: large volume support") | 092e3d9 ("mkfs.f2fs: large volume support")
Fsck flag | Adds "need fsck" flag to superblock to conduct fsck.f2fs later, this flag can only be removed by fsck.f2fs. | 3.18 | 1.4.0 | 2ae4c673e3cb ("f2fs: retain inconsistency information to initiate fsck.f2fs") | 7eb6c5a ("fsck.f2fs: add auto_fix feature")
Fastboot flag | Allow checkpoint write node summaries to speed up boot after a sudden poweroff. | 3.2 | 1.4.1 | 119ee9144534 ("f2fs: split UMOUNT and FASTBOOT flags") | b57708a ("dump.f2fs: show checkpoint flag")
Inline data (fix) | Enhance stability of inline_data feature (changes disk layout). | 3.19 | 1.4.1 | b3d208f96d6b ("f2fs: revisit inline_data to avoid data races and potential bugs") | 7279f03 ("fsck.f2fs: fix DATA_EXIST flag for old partition")
Inline dentry | Support storing of directory entries in the directory inode. | 3.19 | 1.4.1 | 34d67debe02b ("f2fs: add infra struct and helper for inline dir") | 6d88640 ("fsck.f2fs: support inline_dentry")
Version info | Stores current kernel version, updated on fsck. | 4.2 | 1.4.1 | 0040b933187b ("f2fs: add missing version info in superblock") | 6fa2547 ("fsck.f2fs: trigger fsck.f2fs when new change was made")
Initial version info | Identifies the Linux kernel version when the format was done. | 4.2 | 1.4.1 | 0040b933187b ("f2fs: add missing version info in superblock") | 762eedf ("mkfs.f2fs: give a kernel version for initial format")
Keep size bit | Ensures preallocated (with fallocate) file size does not change during roll-forward recovery. If a file needs to keep its i_size set by fallocate, autorecovery needs to be turned off during roll-forward recovery | 4.1 | N/A | 26787236b366 ("f2fs: do not activate auto_recovery for fallocated i_size") | N/A
Inline dots | Support to fix directory which has no '.' or '..' dentries, it changes disk layout | 4.1 | 1.5.0 | 510022a85839 ("f2fs: add F2FS_INLINE_DOTS to recover missing dot dentries") | f1e4f9c ("fsck.f2fs: fix missing dentries")
Encryption | Enables support for filesystem level encryption. | 4.2 | 1.5.0 | cde4de120577 ("f2fs crypto: declare some definitions for f2fs encryption feature") | 6e6c713 ("mkfs.f2fs: set encryption feature")
Block zoned | Specify F2FS filesystem to support the block zoned feature. It depends on multiple devices feature. | 4.8 | 1.7.0 | 52763a4b7a21 ("f2fs: detect host-managed SMR by feature flag") | 70a8fc3 ("mkfs/fsck: add host-managed smr feature")
Multiple devices | Enable support for multiple physical storage devices to be treated as a single logical volume | 4.1 | 1.8.0 | 3c62be17d4f5 ("f2fs: support multiple devices") | de7e07e ("f2fs-tools: support multiple devices")
Trimmed flag | Optimizes the handling of discarded blocks. This flag (CP_TRIMMED_FLAG) allows the F2FS kernel module to record that all invalid blocks were trimmed before umount, so on the next mount these operations can be skipped. | 4.12 | 1.9.0 | 1f43e2ad7bff ("f2fs: introduce CP_TRIMMED_FLAG to avoid unneeded discard") | f642b24 ("f2fs-tools: support to set and recognize CP_TRIMMED_FLAG")
NAT bits | Adds bitmaps to represent empty/full NAT blocks containing all used/free nid entries to optimize the management of NAT blocks. | 4.11 | 1.9.0 | 22ad0b6ab466 ("f2fs: add bitmaps for empty or full NAT blocks") | 191573e ("mkfs.f2fs: support nat_bits feature")
CRC recovery | Use CRC in addition to checkpoint version during roll-forward recovery. This allows for a more robust and reliable way to determine which version of the file to recover. Introduces new flag (CP_CRC_RECOVERY_FLAG) to indicate when the new mechanism is used. | 4.9 | 1.9.0 | a468f0ef516f ("f2fs: use crc and cp version to determine roll-forward recovery") | a0bd5b9 ("f2fs-tools: catch up up-to-date checkpoint flag")
Atomic write | Atomic write feature, this feature does not change disk layout. | 4.14 | 1.9.0 | e65ef20781cb ("f2fs: add ioctl to expose current features") | 8721519 ("f2fs-tools: add atomic_write feature flag")
Extra attributes | Enable extra attributes feature, required for some of the other features (see below). | 4.14 | 1.9.0 | 7a2af766af15 ("f2fs: enhance on-disk inode structure scalability") | dad33a1 ("f2fs-tools: enhance on-disk inode structure scalability")
Project quota | Enable project ID tracking for projet quota accounting. Uses extra attributes. | 4.14 | 1.9.0 | 5c57132eaf52 ("f2fs: support project quota") | a3d9db1 ("f2fs-tools: support project quota")
Inode checksum | Enable inode checksum. Uses extra attributes. | 4.14 | 1.9.0 | 704956ecf5bc ("f2fs: support inode checksum") | 7457726 ("f2fs-tools: support inode checksum")
Nocrc recovery | Disables the use of CRC during the checkpoint recovery process relying solely on the checkpoint version. | 4.16 | 1.10.0 | f236792311f4 ("f2fs: allow to recover node blocks given updated checkpoint") | f789444 ("fsck.f2fs: allow roll-forward for small checkpoint fix")
Flexible inline xattr | Enable flexible inline xattr size. Uses extra attributes. | 4.15 | 1.10.0 | 6afc662e68b5 ("f2fs: support flexible inline xattr size") | 8d46072 ("f2fs-tools: support flexible inline xattr size")
Quota sysfile | Enable quota feature (it allows F2FS to maintain an inner sysfile for disk quota data recording). | 4.15 | 1.10.0 | 234a96896142 ("f2fs: add quota_ino feature infra") | 23a872f ("mkfs.f2fs: support quota option in mkfs")
Pinfile | Support pinfile to avoid migration of its physical data blocks. | 4.16 | 1.12.0 | 1ad71a27124c ("f2fs: add an ioctl to disable GC for specific file") | "91bb7b2 (""f2fs-tools: fix to reset i_gc_failures offline"") 820b5e3 (""sload.f2fs: use F2FS_COMPRESS_RELEASED instead of IMMUTABLE bit"") added the F2FS_PIN_FILE flag w/o any use."
Inode creation time | Enable inode creation time feature. Requires extra attributes. | 4.16 | 1.10.0 | 1c1d35df7110 ("f2fs: support inode creation time") | 4862080 ("f2fs-tools: support inode creation time")
Extended node bitmap | Enable extended node bitmap to increase upper boundary limitation of node block count. | 4.17 | 1.11.0 | 199bc3fef29c ("f2fs: support large nat bitmap") | baaa076 ("mkfs.f2fs: expand scalability of nat bitmap")
Hot file extensions | Allows specifying a list of file extensions that F2FS will treat as hot files. The data of files with those extensions will be stored in the hot log. | 4.17 | 1.11.0 | b6a06cbbb5f7 ("f2fs: support hot file extension") | 6fdc37f ("mkfs.f2fs: support hot file extension")
lost+found | Enable lost+found feature. | 4.17 | 1.11.0 | b7c409deda6b ("f2fs: introduce F2FS_FEATURE_LOST_FOUND feature") | ff37829 ("mkfs.f2fs: create lost+found directory")
fs-verity | Enable support for verity protected files (a.k.a. fs-verity). | 5.4 | 1.11.0 | 95ae251fe828 ("f2fs: add fs-verity support") | 76cd377 ("mkfs.f2fs: support fsverity feature")
Checkpoint disable flag | Indicate checkpoint is disabled. | 4.2 | 1.12.0 | 4354994f097d ("f2fs: checkpoint disabling") | a48bda0 ("fsck.f2fs: support checkpoint=disable")
Quota needs fsck | Add a global state SBI_QUOTA_NEED_REPAIR to indicate that quota operation failed due to -EIO or -ENOSPC, so later, a) checkpoint will skip syncing dquot metadata. b) CP_QUOTA_NEED_FSCK_FLAG will be set in last cp pack to give a hint for fsck repairing. | 4.2 | 1.12.0 | af033b2aa8a8 ("f2fs: guarantee journalled quota data by checkpoint") | dfede78 ("fsck.f2fs: detect and recover corrupted quota file")
Superblock checksum | Enable superblock checksum. | 4.2 | 1.12.0 | d440c52d3151 ("f2fs: support superblock checksum") | 886a924 ("f2fs-tools: introduce sb checksum")
Checkpoint disable quick | Add a quick method of checkpoint disabling. | 5.1 | N/A | db610a640eee ("f2fs: add quick mode of checkpoint=disable for QA") | N/A
Casefolding | Enable casefolding support in the filesystem. Optional flags can be passed with -C. | 5.4 | 1.13.0 | 5aba54302a46 ("f2fs: include charset encoding information in the superblock") | ce64ea0 ("f2fs-tools: Add support for Casefolding")
Compression | Enable support for filesystem level compression. Requires extra attributes. | 5.6 | 1.14.0 | 4c8ff7095bef ("f2fs: support data compression") | fdd47b2 ("f2fs-tools: support data compression")
Resize FS flag | Introduces a new checkpoint flag, CP_RESIZEFS_FLAG, to help fsck fix issues related to online resizing. | 5.7 | 1.14.0 | c84ef3c5e65c ("f2fs: Add a new CP flag to help fsck fix resize SPO issues") | 9a31cef ("fsck.f2fs: allow fsck to fix issues with online resize due to SPO")
Compression (fix) | This change introduces a new flag (F2FS_COMPRESS_RELEASED) to represent the status of the released compressed blocks. Previously used IMMUTABLE bit prevented all operations on the released block. | 5.14 | 1.15.0 | c61404153eb6 ("f2fs: introduce FI_COMPRESS_RELEASED instead of using IMMUTABLE bit") | 820b5e3 ("sload.f2fs: use F2FS_COMPRESS_RELEASED instead of IMMUTABLE bit")
Readonly image | Enable readonly feature to eliminate OVP/SSA on-disk layout for small readonly partition. | 5.14 | 1.15.0 | a7d9fe3c3388 ("f2fs: support RO feature") | 1d2683f ("f2fs-tools: support small RO partition")
Trunc bit | "Direct IO (DIO) preallocates physical blocks before writing actual data, but if an error occurrs or a power-cut happens, the unwritten blocks' contents can be accessed by the user. This patch fixes it by: 1) turning to buffered writes for DIO into holes 2) truncating unwritten blocks from error or power-cut." | 5.17 | N/A | d4dd19ec1ea0 ("f2fs: do not expose unwritten blocks to user by DIO") | N/A
CP error recording | Supports recording the detailed stop checkpoint error into f2fs_super_block.s_stop_reason[]. | 6.1 | 1.16.0 | a9cfee0ef98e ("f2fs: support recording stop_checkpoint reason into super_block") | 2f1dde2 ("fsck.f2fs: trigger repairing if filesystem was forced to stop")
FS error recording | Supports recording the detailed reason of FSCORRUPTED error into f2fs_super_block.s_errors[]. | 6.1 | 1.16.0 | 95fa90c9e5a7 ("f2fs: support recording errors into superblock") | 8cbe34e ("fsck.f2fs: trigger repairing if filesystem has inconsistent errors")
16KB block support | Supports for 16K block size, mkfs can choose block size via the -b option, with other tools getting the blocksize from the superblock. | 6.7 | Not released yet | d7e9a9037de2 ("f2fs: Support Block Size == Page Size") | 50fd00b ("f2fs-tools: Support different block sizes") c404632 ("f2fs-tools: Refactor f2fs_dentry_block struct") ef47782 ("f2fs-tools: Refactor Summary block struct and friends") bb051c7 ("f2fs-tools: Refactor SIT/NAT block structs") 32f5a37 ("f2fs-tools: Refactor f2fs_node struct and friends") b1aeb99 ("f2fs-tools: Refactor Orphan Block struct") 30825b3 ("f2fs-tools: Define constants in terms of BLKSIZE")
Device alias | Enables device aliasing feature. | 6.13 | Not released yet | 128d333f0dff ("f2fs: introduce device aliasing file") | 8cc4e25 ("mkfs.f2fs: add device aliasing feature")

Category:

- File systems

Hidden categories:

- Pages or sections flagged with Template:Expansion
- Pages or sections flagged with Template:Out of date

F2FS
Add topic