NILFS2 - ArchWiki

Jump to content

# NILFS2

From ArchWiki

Related articles

- File systems

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.
- As of 2025-04-22 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` respectively.

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 inputted 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.

## See also

- NILFS2 FAQ

Category:

- File systems

NILFS2
Add topic