F2FS

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.

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

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