why i started use btrfs

I used Ubiquity Unify controller installed on my home Ubuntu server with Ext4 file system by default.

Unify uses MongoDB which is very sensitive for an unexpected reboot. As a result, it was completely destroyed in 50% cases with power failure and I couldn’t repair it with any instructions. So, I spent a lot of time for re-instalation Unify controller and restoring the configuration from a backup.

After several months with such exercises, I performed research and found that CoW (Copy-on-Write) filesystem solves such problems.

The most popular CoW filesystems are ZFS and BtrFS. Only BtrFS was included to Linux kernel at that moment due to ZFS licensing. So, I decided to play with it.

Hopefully, I never was faced with MongoDB failure again after switching to it.

advantages and disadvantages of btrfs


The biggest advantage in comparing with Ext4 is faile-tolerance for unexpected reboots due to a completely another approach for writing on a disk.

BtrFS provides an easy way to clone your disk on-flight. You don’t need to boot with another system and use dd utility. With BtrFS you can create RAID1, mirror your disk, destroy RAID1, and get two drives with the same data on them.



BtrFS consumes more resources of your desktop or server, but I didn’t see any problem even with Raspberry PI 4.

BtrFS has own data occupancy limitation approach applicable for sub-volumes but not for a user. BtrFS quota are not supported with Linux kernel quota and other softwares don’t recognize it. For en example, Samba can see a size and remaining space for the whole disk but not for sub-folder and you see just an unexpected error if the quota is exceeded.

Advantages of subvolume based limits

BTW, this approach has an advantage for the home server.

As the usual home server has one or a couple of disks that are used for a home media library, documents, and backup laptops or desktops. At the same time, incremental backups consume as much space as possible up to the whole shared disk (especially Mac Time Machine – please see the article “Configure your Linux based NAS as a TimeCapsule”).

So, you can limit usage for all users’ space for media, documents, and backup with Linux standard user quota. It’s not suitable because a user needs different limitations for these types of files.

Of cause, you can slice your drive on volumes and apply user quota for a particular one. But, is it suitable to make sizes of partitions if you need another proportion between patitions?

In another hand, BtrFs applies limits to subvolume. An operation system works with BtrFS like usual folders. So, by default, subvolume can occupate a whole disk, and you have the ability dynamically change limits for subvolumes without any exercises with partitioning your disk.

What should I do if I use folder but not a subvolume for samba share

host:# ls -l
drwxr-xr-x  1 backup backup    0 May 18 10:02 test

Just rename your folder and create a subvolume with a full path (/BACKUP/test in my case).

My BtrFS disk mounted to /BACKUP mount point.

Please pay attention to the current permissions and the owner of your folder.

host:# mv test test1
host:# ls -la
drwxr-xr-x  1 backup backup    0 May 18 10:02 test1
host:# btrfs subvolume create /BACKUP/test
Create subvolume '/BACKUP/test'
host:# ls -la
drwxr-xr-x  1 root   root      0 May 18 10:11 test
drwxr-xr-x  1 backup backup    0 May 18 10:02 test1
host:# chown backup:backup test
host:# ls -la
drwxr-xr-x  1 backup backup    0 May 18 10:11 test
drwxr-xr-x  1 backup backup    0 May 18 10:02 test1
host:# mv -f test1/* test/
host:# rmdir test1

As the result, you “converted” your folder into BtrFS subvolume. As can you see, Linux handles BtrFS subvolumes as a common folder. You can see your subvolumes with following command:

host:# btrfs subvolume list /BACKUP
ID 1085 gen 290993 top level 5 path test

Enable and set btrfs quota

Now you should add limit for your subfolder (more information you can find on wiki.

First of you have to enable quota for your drive an it depends on whether it a fresh BtrFS disk or an exists and used one.

So, you can enable quota with one command for fresh file system:

host:# btrfs quota enable /BACKUP

And use following commands for used one:

host:# btrfs quota enable /BACKUP
host:# btrfs subvolume list /BACKUP | cut -d' ' -f2 | xargs -I{} -n1 btrfs qgroup create 0/{} /BACKUP
host:# btrfs quota rescan /BACKUP

Don’t forget to replace /BACKUP with your actual mount point.

Set and check your quota:

host:# btrfs qgroup limit 100G /BACKUP/test
host:# btrfs qgroup show -reF /BACKUP/test/
qgroupid         rfer         excl     max_rfer     max_excl 
--------         ----         ----     --------     -------- 
0/1085       16.00KiB     16.00KiB    100.00GiB         none 

Configure SAMBA to work with btrfs limits

Hopefully, Samba is developed for a huge amount of OS and not all of them have a standard Linux quota, also some OS provide disk size in non-standard for samba way and samba can’t recognize disk size on such OSes. So, samba provides an ability to use a custom application or script to get actual disk size.

Hence, you have to configure samba to use a script to get a size of a BtrFS subvolume and it solves the problem.

More information about dfree command you can find in Samba documentation.

I don’t provide complete samba setup in this article, but the update of configuration for  “Configure your Linux based NAS as a TimeCapsule”.

Prepare dfree script

Following script provides remaining space in subvolume  in required for samba format (I call it as

host:# touch /BACKUP/
host:# chmod +x /BACKUP/
host:# vi /BACKUP/

STR=$(/usr/bin/sudo /bin/btrfs qgroup show -rF --raw $1 | /usr/bin/tail -1)

SIZE=$(/usr/bin/expr `/bin/echo $STR | /usr/bin/cut -d \  -f 4` / 1024)
USED=$(/usr/bin/expr `/bin/echo $STR | /usr/bin/cut -d \  -f 2` / 1024)
AVAIL=$(/usr/bin/expr $SIZE - $USED)

/bin/echo $SIZE $AVAIL

Biggest problem that btrfs tool must be run a root but samba service doesn’t have root permissions.

So, you have to grant necessary permissions with sudo.

Please add following rows to /etc/sudoers.

ALL ALL=(ALL) NOPASSWD: /bin/btrfs

Moreover you have to add SUID bit to the script

host:# chmod +s /BACKUP/

Add following row to your samba sare configuration:

dfree command = /BACKUP/ 

So, your configuration for Time Capsule will look like this:

[TimeMachine Home]
        path = /BACKUP/%U
        writable = yes
        durable handles = yes
        kernel oplocks = no
        kernel share modes = no
        posix locking = no
        vfs objects = catia fruit streams_xattr
        ea support = yes
        browseable = yes
        read only = No
        inherit acls = yes
        fruit:time machine = yes
        fruit:aapl = yes
        spotlight = yes
        create mask = 0600
        directory mask = 0700
        comment = Time Machine
        dfree command = /BACKUP/ 

Now you have to add samba user accordingly to the article “Configure your Linux based NAS as a TimeCapsule”.

Please remember that in this configuration your subvolume must have the same name as samba user for backup.


Please ask any question in the comments for the article.

Leave a Reply

Your email address will not be published. Required fields are marked *