NILFS2

NILFS2 (New Implementation of a Log-structured File System) is a log-structured file system supporting versioning of the entire file system and continuous snapshotting, which allows users to even restore files mistakenly overwritten or destroyed just a few seconds ago.

It was developed by Nippon Telegraph and Telephone Corporation (NTT) CyberSpace Laboratories and a community from all over the world. NILFS was released under the terms of the GNU General Public License (GPL).

NILFS2 is continously snapshoted, as such it can be considered versioning file system where file system automatically keeps past versions of every file.

Note: NILFS2 might not be best choice for mechanical hard drives due to its log structured design causing fragmentation.

Note: As of 22/4/2025 NILFS2 does not implement atime (access time), extended atributes and Posix ACLs (Posix Access Control Lists). If your workflow is dependent on these, do not use NILFS2. It also currently lacks proper fsck so in the case of severe error it might not be recoverable. See Current status to see what is and is not implemented.

Tip: While most of NILFS2 tools allow omiting device file argument, it is recomended to always use it in setups with multiple NILFS2 file systems to prevent accidentaly modifying wrong file system.

Creating a NILFS2 file system

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

# mkfs.nilfs2 -L mylabel /dev/sdxY

See mkfs.nilfs2(8) for all available options.

Changing label

Nilfs-tune command should be used only for unmounted file systems.

# nilfs-tune -L newlabel /dev/sdxY

Mounting

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

# mount /dev/sdxY /mnt/foo

Mount options

Error handling

errors=continue / remount-ro / panic Specifies what NILFS2 should do on file system error. Continue Ignores error, remount-ro remounts file system read-only and panic halts the system.

Discard

discard / nodiscard Enable/disable TRIM

See mount.nilfs2(8) for all available options.

Snapshots

NILFS2 has two types of snapshots, checkpoints and snapshots. They are often written as cp and ss respectivelly.

NILFS2 creates checkpoints on every write automatically. Checkpoint is snapshot that can be automatically deleted by NILFS2 garbage collector to free up space when file system is filled up or when user manually prompts it for cleaning.

Snapshots have to be manually converted from checkpoints and are never deleted automatically. They can be mounted to recover data from them.

Listing snapshots

Checkpoints and snapshots can be listed with:

lscp /dev/sdxY

CNO        DATE     TIME  MODE  FLG      BLKCNT       ICNT
     1  2025-04-14 21:35:06   cp    -     10181423     554012
     2  2025-04-14 22:17:38   cp    -     10181423     554012
     3  2025-04-14 22:18:22   cp    -     10181423     554012
     4  2025-04-14 22:28:56   cp    -     10181423     554012
     5  2025-04-14 22:39:59   cp    -     10181423     554012
 ...

To list only snapshots(ss) use -s flag with lscp. See lscp(1) for all available options.

Converting checkpoints to snapshots

In order to recover data from checkpoint it first has to be converted into snapshot. To do that use chcp utility:

# chcp ss /dev/sdxY checkpoint-number

checkpoint-number is number of the checkpoint listed in lscp in the CNO column.

lscp will now show line like:

    4  2025-04-14 22:28:56   ss    -     10181423     554012

To convert snapshot back to checkpoint use:

# chcp cp /dev/sdxY checkpoint-number

Creating snapshots

Use following to create a checkpoint:

# mkcp /dev/sdxY

Or to create a snapshot directly:

# mkcp --snapshot /dev/sdxY

Mounting snapshots

Following command will mount snapshot checkpoint-number read-only into /mnt/snapshot:

# mount -t nilfs2 -r -o cp=checkpoint-number /dev/sdxY /mnt/snapshot

Deleting snapshots

To delete a singular checkpoint use:

# rmcp /dev/sdxY checkpoint-number

To delete a range of checkpoints you can use:

# rmcp /dev/sdxY start..end

Where start is number of starting checkpoint and end the number of ending checkpoint.

To delete all checkpoints older than a checkpoint use:

# rmcp /dev/sdxY ..checkpoint-number

To delete all checkpoints newer than a checkpoint use:

# rmcp /dev/sdxY checkpoint-number..

Tip: Add -i flag to the rmcp for interactive use to double check inputed values

See rmcp(8) for further details.

Cleaning file system

To clear obsolete checkpoints from a mounted NILFS2 file system run:

# nilfs-clean /dev/sdxY

See nilfs-clean(8) and nilfs_cleanerd(8) for further details on garbage collector.

Resizing file system

nilfs-resize tool resizes online NILFS2 file system.

Mounted NILFS2 filesystem can be resized with following command:

# nilfs-resize /dev/sdxY desired-size

Where desired-size can be suffixed by unit letter s, K, M, G, or T, for 512 byte sectors, kilobytes, megabytes, gigabytes, or terabytes, respectively. If desired-size is not specified, it will default to the size of partition.

nilfs-resize does not change size of paritions themselves, they either have to be shrink afterwards when shrinking the filesystem or grown beforehand when enlarging it. This can be done with fdisk for example.

See nilfs-resize(8) for further details.