== Slint with BTRFS

In this article we outline the unique characteristics of the BTRFS file system and how a Slint system is configured at installation to take advantage of them.

In order not to overload this document with definitions, we refer the reader to the https://slint.fr/en/HandBook.html#_glossary[glossary] included in the Slint Manual and more specifically for btrfs "jargon" to the https://btrfs.readthedocs.io/en/latest/Glossary.html[glossary] included in its documentation.

A BTRFS file system consists of a logical volume that can span multiple block devices (partitions or disks). Initially Slint is installed on a single partition.

A subvolume is a subtree of files inside the volume, the root of which can be mounted as if it were an independent filesystem. However, the space allocated to a volume is also allocated to each of its sub-volumes: it is therefore not necessary to distribute it between the sub-volumes, as if they were in distinct partitions. 

Subvolumes can be created at the same time as the volume (by the mkfs.btrfs command), but also added or deleted later using the btrfs tools.

As an example the commands below create the Slint "system" volume and its subvolumes, in case BTRFS is used. In the following $ROOTNAME is the name of the partition in which Slint will be installed and $SLINT the mount point of the system volume during installation.
----
mkdir /SLINT
SLINT="/SLINT"
mkfs.btrfs -L root $ROOTNAME
mount -o compress=zstd:3,noatime $ROOTNAME $SLINT
btrfs subvolume create $SLINT/@
btrfs subvolume create $SLINT/@home
btrfs subvolume create $SLINT/@swap
umount $SLINT
mount -o subvol=/@,compress=zstd:3,noatime $ROOTNAME $SLINT
mkdir $SLINT/home
mkdir $SLINT/swap 
----
The $ROOTNAME partition (denoted by its UUID which we will call <uuid>) will then be mounted three times (once per subvolume) each time Slint is started, as indicated in the /etc/fstab file:
----
UUID=<uuid> / btrfs subvol=/@,compress=zstd:3,noatime 0 0
UUID=<uuid> /home btrfs subvol=/@home,compress=zstd:3,noatime 0 0
UUID=<uuid> /swap btrfs subvol=/@swap,compress=zstd:3,noatime 0 0 
----
Which gives for example (taken from the output of lsblk /dev/sda5):
----
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda5        50G   22G   28G  44% /
/dev/sda5        50G   22G   28G  44% /home
/dev/sda5        50G   22G   28G  44% /swap
----
We see that the space available for the volume (28G) is also available for each of the sub-volumes. On the other hand, the "compress_zstd:3" mount option means that all the files that will be stored will be compressed by the zstd utility with compression level 3. Thus the size of the system is approximately half that with the ext4 file system.

If we mount the device at the root of the volume (without mention of a subvolume), like this:
----
mount /dev/sda5 /mnt
----
we see the subvolumes appear as subdirectories of /mnt:
----
ls /mnt
@ @home @swap
ls /mnt/@home/didier
Desktop Documents GNUstep Images Templates Music Audience Downloads Videos 
----
Another remarkable feature of BTRFS is "copy-on-write". When editing a file, modified parts are written to another location, the metadata (which record the location of all parts of the file) being updated. As long as the previous data are still referenced, they will stay untouched.

This makes it very easy to create snapshots of BTRFS subvolume: taking a new snapshot is "free", as it uses very few disk space: only the metadata of the snapshot are written, which stores the physical location of all parts of files in the subvolume, and this is done almost instantly. The space used by the snapshot will only grow when the original subvolume and the snapshot differ, as then the snapshot will retrieves data removed from the original. On the other hand data added to the original will not be included in he snapshot: in other words a modification of the original subvolume does not modify the snapshot.

Slint includes the utility `absm`, which takes snapshots of the subvolume @, allowing to return to a previous state of the system if an update goes wrong, by booting the system on this snapshot, selected in the GRUB boot menu. To know its usage, just type `absm` as root or using sudo.

BTRFS also verifies the integrity of each file when it is opened using a checksum, making it unnecessary to check the file system at system startup. In addition, the "btrfs scrub" command verifies the integrity of all files, including those that are rarely read. By default, the utility `btrfsmaintenance` included in Slint runs "btrtfs scrub" once a week.

`btrfsmaintenance` also triggers "btrfs balance" once a week by default. This command allows you to distribute the data between the devices if the file system extends over several, but also to reorganize the space used, in particular to free the unallocated space of the file system, which improves in particular the performance of BTRFS in the case of a hard disk. To know more about `btrfsmaintenance` read /usr/doc/btrfsmaintenance*/README.html

Other useful and BTRFS-compatible tools are included in Slint, all have a --help option and a man page:

* `jdupes` detects duplicate files and allows you to take action accordingly, regardless of the file system used
* `btdu` allows to know with precision the place occupied by the BTRFS sub-volumes and directories
* `restic` is a very versatile backup software that can be used for any file system.

Recommendations.

* BTRFS needs room to breathe and reorganize. Always keep 10-20% free space.
* Some tool options included in the btrfs-tools package can be dangerous or counterproductive. Use only those whose effect you know perfectly well and if in doubt seek advice first, on the Slint mailing list or by IRC on irc.libera.chat, channel #btrfs.
* In particular, avoid using "btrfs filesystem defrag" and especially not "btrfs check --repair".
* Before using a command, carefully read the corresponding man page (starting with "man btrtfs" which lists the others).
* As with any file system: make regular backups! This is usually the only way to recover your data in the event of hardware failure.

For further:

* The Forza wiki: https://wiki.tnonline.net/w/Category:Btrfs
* The official documentation: https://btrfs.readthedocs.io/en/latest/
* Questions, problems: on irc.libera.chat channel #btrfs

