[NILFS] FAQ

FAQ

How can I manually perform Garbage Collection (GC)?
If nilfs-clean command is provided by the nilfs-utils package installed in your PC, execute it:
```
# nilfs-clean [device]
```
This command will start one-pass GC.
The disk got full. I deleted files, but disk space is not freed.
Execute nilfs-clean command along with -p option:
```
# nilfs-clean -p 0 device
```
If the nilfs-clean command is not available for some reason, try remounting the filesystem with the ``pp'' option:
```
# mount -t nilfs2 -o remount,pp=0 device mount-point
```
nilfs_cleanerd never deletes recent checkpoints whose elapsed time from its creation is smaller than ``protection period''. The above option shortens the protection period to one second and allows nilfs_cleanerd to reclaim checkpoints preserving the deleted files. (Note that snapshots are protected independently of the protection period).
The protection period is defined in /etc/nilfs_cleanerd.conf, in which the default value is set to one hour.
How can I turn off the garbage collector?
Use ``nogc'' mount option:
```
# mount -t nilfs2 -o nogc device mount-point
```
You can also disable it during use by remount:
```
# mount -t nilfs2 -o remount,nogc device mount-point
```
This kills nilfs_cleanerd process. To restart the GC process, you have only to remount the partition without the nogc option:
```
# mount -t nilfs2 -o remount device mount-point
```
Disk space usage using df command seems to count past data. How can I get the used amount of ``the current filesystem''?
lscp command of nilfs-utils version 2.2.0 and later, outputs block count of each checkpoint. For prior versions, this command needs '-b' option to show the block count. (the option is available only for 2.0.22 and later)
In the following example, the block count of the latest checkpoint is displayed in the ``BLKCNT'' column:
```
$ lscp -r -n 1
         CNO        DATE     TIME  MODE  FLG      BLKCNT       ICNT
     1863279  2014-03-18 17:07:34   cp    -      5902745     669595
```
However, this feature is not available on some old NILFS kernel modules. To make matters worse, these legacy modules break the block count data itself. We therefore recommend you to specify block_count feature at mkfs time:
```
$ mkfs -t nilfs2 -O block_count device
```
This feature prevents the partition from being mounted by such legacy modules.
Can I resize NILFS volumes ?
Yes, you can both enlarge and shrink NILFS volumes with nilfs-resize command. This feature is available on Linux 3.0 and later. Resizing for unmounted file systems are not supported at present.
For details, please see the man page of nilfs-resize(8).
How can I get/set/change label or UUID of NILFS volumes ?
Use nilfs-tune command. Please see the man page of nilfs-tune(8) for details.
What is the role of ".nilfs" file ? Is it deletable ?
The .nilfs file was used for locking between cleanerd and other NILFS utilities. This file is now obsolete, and you can delete it if you are using nilfs-utils 2.1 or later.
The .nilfs is a regular file, and the kernel module of NILFS2 does not depend on this file.
cleanerd (or chcp/mkcp command) fails to start with error: ``cannot open nilfs on /dev/xxx: Function not implemented''.
Confirm whether tmpfs (former shm fs) is mounted on /dev/shm. POSIX semaphores do not work if the filesystem on /dev/shm is wrong, which causes the above failure.
Some systems are using ramfs instead of tmpfs. You may need to change kernel configuration and rebuild kernel to enable tmpfs. Check on two configurations CONFIG_SHMEM and CONFIG_TMPFS:
```
 # cd linux
 # make menuconfig
     General setup --->
        [*] Use full shmem filesystem
     File systems --->
        Pseudo filesystems --->
            [*] Tmpfs virtual memory file system support (former shm fs)
```
cleanerd or other NILFS tools fail with error: ``cannot open nilfs on /dev/xxx: No such file or directory''.
Confirm if the target device node in /proc/mounts really exists. NILFS library will fail if the given device does not appear in /proc/mounts. Here, two device nodes are regarded as equivalent only if their canonical path names equal.
Some systems replace the root device node with /dev/root. In that case, the above error arises if /dev/root is not a valid alias nor a valid symlink to the device.
cleanerd fails to start with error: ``cannot create mqueue on /dev/xxx: Function not implemented''.
Confirm whether mqueue is enabled in your kernel. Check on CONFIG_POSIX_MQUEUE configuration:
```
 # cd linux
 # make menuconfig
     General setup --->
        [*] POSIX Message Queues
```
lscp or cleanerd fails with error: ``inappropriate ioctl for device''.
Note: This entry applies only to extremely old Linux environments (pre-2009). Before NILFS2 was merged into the mainline kernel, the ioctl interface was changed to resolve 32-bit vs 64-bit compatibility issues. Some legacy tool packages, such as those included in Debian 5.0 (lenny) or Ubuntu 9.04/8.10, are older than this change and will cause this error when used with a newer kernel.
This issue is resolved in all currently supported distributions. If you encounter this error in a legacy environment, please build and install the latest nilfs-utils from source code provided on this site.
mount fails with error: ``mount.nilfs2: cannot find or load nilfs2 filesystem''.
This error typically occurs if the nilfs2 filesystem module is not registered or loaded in your system. In modern Linux distributions, the filesystem module should be automatically loaded by the mount command, but this message appears if the auto-loading fails.
First, try to load the module manually using the modprobe command to check if it is recognized:
```
# modprobe nilfs2
```
If you see an error like "modprobe: FATAL: Module nilfs2 not found in directory …", consider the following causes:
- The module is separated into a different package:
  In some distributions, certain filesystem modules are moved from the main kernel package to an "extra" package (e.g., kernel-modules-extra). Please ensure that all necessary kernel module packages are installed.
- You are using a RHEL-based OS (AlmaLinux, Rocky Linux, etc.):
  The standard kernels of Red Hat Enterprise Linux and its compatible distributions do not include the nilfs2 module. To use NILFS2 in these environments, you need to obtain, build, and install the standalone kernel module (nilfs2-kmod). For more details, please refer to the Standalone Kernel Module section on the Download page.
mount fails with 'Please remount the partition with -f option …' error:
```
# mount -t nilfs2 /dev/sdb1 /nilfs
Please remount the partition with -f option after making /etc/mtab writable.
nilfs_cleanerd not started
# ls -la /etc/mtab
lrwxrwxrwx 1 root root 19 Nov 4  2018 /etc/mtab -> ../proc/self/mounts
```
This error typically occurs when nilfs-utils is built without libmount support on a system where /etc/mtab is a symbolic link (the standard setup for modern Linux).
To resolve this, ensure the libmount development package (libmount-devel or libmount-dev) is installed, then rebuild nilfs-utils:
```
$ cd nilfs-utils
$ ./configure
$ make
$ sudo make install
```
If your system is very old and uses /etc/mtab as a regular file, you must use the --without-libmount option instead:
```
$ ./configure --without-libmount
```
File creation fails with ``Permission denied'' error.
Confirm whether SELinux is enabled or not. Since NILFS does not fully support SELinux, you may get this error on SELinux-enabled systems. Try context mount (context=, fscontext=, defcontext=, or rootcontext=) if this matters. These options allow you to specify SELinux policy on a per-volume basis:
```
# mount -t nilfs2 -o context=system_u:object_r:public_content_t:s0 /dev/sdb1 /nilfs
```
This feature is available on nilfs-utils 2.1 or later. (nilfs-utils 2.1.4 is required if you configure tools without libmount library).
When installing nilfs-utils from source package (by make install), warning ``libtool: install: warning: relinking 'libnilfsgc.la' '' is output.
This message is innocuous and can be ignored. The libnilfsgc shared library depends on libnilfs shared library, where both are built from the same nilfs-utils source package. Libtool tries to relink libnilfsgc to ensure it uses the installed libnilfs rather than the binary in the build directory.
NILFS got stuck.
We appreciate if you get stack dump of suspended tasks by using the magic sysrq feature of kernel and send it to us.
```
# echo t > /proc/sysrq-trigger
# dmesg
```
This feature may be turned off in your kernel. Please check CONFIG_MAGIC_SYSRQ kernel configuration if /proc/sysrq-trigger is missing.

How can I build NILFS ?

Check on the following kernel configurations.

 # cd linux-6.x
 # make menuconfig
     File systems --->
        <M> NILFS2 file system support
     Library routines --->
        -*- CRC32/CRC32c functions

Note that nilfs2 does not appear in the menu for old kernels (kernel 3.8 and earlier) unless you enable EXPERIMENTAL code/drivers:

 # cd linux-2.6.x
 # make menuconfig
     General setup --->
        [*] Prompt for development and/or incomplete code/drives
     File systems --->
        <M> NILFS2 file system support (EXPERIMENTAL)
     Library routines --->
        -*- CRC32 functions

diff command does not report any difference between a file on the current file system and its past version on snapshot.
The diff program regards two directories (or files) as identical if both their block devices and inode numbers equal.
This optimization causes undesirable results like the above since the current state and snapshots of NILFS are mounted on the same block device. This is unavoidable under the current NILFS implementation.
For reference, here is a workaround for the diff program. The patch modifies the diff program so that it regards two files (directories) as identical only if they have the same inode number and the same ctime.