Summary

Btrfs is a feature-rich copy-on-write file system that has been around since 2007, it is the default file system for some popular Linux distributions such as Fedora and is used by many large companies such as Meta in their datacenters. Over the years it has proven itself to be stable and more flexible than other popular file systems. Most significant features are the following:

  • Bitrot protection (when used in Btrfs-RAID mode)
  • Subvolumes
  • Snapshots
  • Transfer

Features described in this page are only available starting from RouterOS v7.18beta2!

Btrfs features require the ROSE-storage package.

Examples

Two disk Btrfs-RAID (RAID1)

In case you want to create a reliable data storage solution with just two disks (for example, NAS), then you can follow this these steps to successfully create a RAID1 array with Btrfs:

  1. Find the names of the disks you want to use for setting up a Btrfs-RAID:
    /disk print

    In this example, the disks used are going to be called <disk-name-1>  and <disk-name-2> , make sure you replace these placeholders with your actual disk names!

  2. Format one of your disks to Btrfs, in this case <disk-name-1> :
    /disk format-drive <disk-name-1> file-system=btrfs
  3. You can check the current status of Btrfs disks using the following command:
    /disk/btrfs/filesystem print

    In case there was an existing RAID on your disks and you want to remove any obsolete configuration for simplicity, then you can wipe the disks with /disk format-drive <disk-name-x> file-system=wipe-quick . This is useful when you have unwanted entries under /disk/btrfs/filesystem print 
  4. Add a label for the Btrfs drive for simplicity:
    /disk/btrfs/filesystem set [find where present-devs=<disk-name-1>] label=BtrfsRAID
  5. Add a disk to an existing Btrfs disk:
    /disk/btrfs/filesystem/add-device [find where present-devs=<disk-name-1>] device=<disk-name-2>
  6. Start Btrfs balance process to create a Btrfs-RAID with RAID1 configuration:
    /disk/btrfs/filesystem balance-start [find where label=BtrfsRAID] data-profile=raid1 metadata-profile=raid1 system-profile=raid1
  7. Set mount-filesystem=no for second disk to prevent the files showing up twice:
    /disk set <disk-name-2> mount-filesystem=no

    Btrfs has feature that allows you to mount any of the Btrfs-RAID members and you will still be able to access the whole Btrfs-RAID array. A downside of this feature is that if you have mounted the same array twice, then your files will appear twice as well. To prevent this, you can simply disable mounting one of the Btrfs-RAID members automatically.

  8. You can also change the mount point's name for simplicity:
    /disk set <disk-name-1> mount-point-template=BtrfsRAID
  9. Your newly created Btrfs-RAID array is now accessible through /BtrsRAID/ folder.

With a reliable storage solution such as Btrfs-RAID consider adding useful features to your RouterOS device by following the suggested guides below:

When regular RAID is used with Btrfs filesystem, then your RAID array will not be able to heal itself from Bitrot, your RAID array can only detect Bitrot with regular RAID. It is recommended to use Btrfs-RAID (the configuration described in this section) when possible.

Creating Btrfs-RAID check

It is extremely important for you to monitor the Btrfs-RAID array's health. One way you can do this is by using the script below as a working example:

/system scheduler
add interval=30s name=test_braid on-event=braidcheck policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon start-time=startup
/system script
add dont-require-permissions=no name=braidcheck owner=admin policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon source=":global CheckBRAID;\
    \n:local temp [/disk btrfs filesystem/find where about~\"has errors\"];\
    \n:if (!([:len \$temp] = 0)) do={\
    \n        :if ( \$CheckBRAID < 1 ) do={\
    \n               /log info message=\"ERROR: BRAID has failed!\";\
    \n               /tool e-mail send to=sysadmin@domain.com subject=([/system identity get name].\" BRAID failed\") body=(\"Go check it! Value: \".\$temp);\
    \n:set \$CheckBRAID 7;\
    \n:delay 5s;\
    \n}\
    \n}\
    \n:if ( \$CheckBRAID > 0 ) do={\
    \n     :set \$CheckBRAID ( \$CheckBRAID -1 );\
    \n}\
    \n\
    \n"

You also need to adjust e-mail server settings on your RouterOS device:

/tool e-mail
set from=<raidcheck@domain.com> port=587 server=smtp.domain.com tls=starttls

Make sure you adjust the e-mail settings with the required settings on your e-mail server. Remember to adjust the e-mail address in the script above.


Creating subvolumes

The main benefit of creating subvolumes is to organize data on your Btrfs main (root) subvolume. Consider subvolumes as folders with features of a partition, while still sharing the total disk space between all subvolumes. You can later use these subvolumes for much more advanced tasks and it is recommended to create subvolumes when you have large amounts of different types of data, especially that requires frequent backups. Follow the guide to setup a few example subvolumes:

Subvolumes are most useful when used together with snapshots. Be sure to check out the snapshot feature as well.


  1. Find the disk name of your disk that you want to use as your Btrfs disk:
    /disk print

    In this example, the disk used is going to be called <disk-name-1> , make sure you replace the placeholder with your actual disk name!

  2. Format the disk to Btrfs, in this case <disk-name-1> :
    /disk format-drive <disk-name-1> file-system=btrfs
  3. Add a label for the Btrfs disk for simplicity:
    /disk/btrfs/filesystem set [find where present-devs=<disk-name-1>] label=BtrfsDisk
  4. You can also change the Btrfs disk mount point for simplicity:
    /disk set <disk-name-1> mount-point-template=BtrfsDisk
  5. Create a new subvolume called Documents to BtrfsDisk :
    /disk/btrfs/subvolume/add name=Documents fs=BtrfsDisk

    Subvolumes are also snapshots. You might encounter both of these names in various menus. In simple terms, snapshots are subvolumes created at a specific time and contains data from that time point.

  6. Create another subvolume called Photos to BtrfsDisk :
    /disk/btrfs/subvolume/add name=Photos fs=BtrfsDisk
  7. You can view the currently available subvolumes:
    /disk/btrfs/subvolume/print
  8. You can now access these subvolumes as /BtrfsDisk/Documents and /BtrfsDisk/Photos 

Creating snapshots

Snapshots are space efficient way to create backups for your data. By creating a snapshot you save the current state of your data which you can later access.

Snapshots don't create a copy of your data, they save the current state of your data while allowing to make changes to your current data. Snapshots contain the information on how to revert the current data to a state that was present at the time when the snapshot was created. Snapshots don't create multiple copies of your data like, for example, a full backup does.

While you can create snapshots of a root subvolume, it is recommended to create a new subvolume for your data and then use the snapshot feature. This is only a preference when managing many snapshots.

  1. Create subvolumes (or use the root subvolume, see above) and put data inside these subvolumes, for example:
    [admin@MikroTik] > /file print 
 # NAME   
 0 BtrfsDisk
 1 BtrfsDisk/Documents
 2 BtrfsDisk/Photos 
 3 BtrfsDisk/Documents/document1.txt
 4 BtrfsDisk/Photos/photo1.jpg
  2. In this example, we have created /Btrfs/Documents and /Btrfs/Photos/ subvolumes and you can view them with:
    /disk/btrfs/subvolume/print
  3. In order to make snapshots more organized, create a new subvolume called Snapshots :
    /disk/btrfs/subvolume/add name=Snapshots fs=BtrfsDisk
  4. Create a snapshot for Documents and Photos :
    /disk/btrfs/subvolume/add read-only=yes parent=Documents fs=BtrfsDisk  name=Snapshots/Documents-22012025
/disk/btrfs/subvolume/add read-only=yes parent=Photos fs=BtrfsDisk  name=Snapshots/Photos-22012025
  5. You should now have new subvolumes that are read-only and contain your files:
    [admin@MikroTik] > /file print 
 # NAME      
 0 BtrfsDisk
 1 BtrfsDisk/Documents
 2 BtrfsDisk/Photos
 3 BtrfsDisk/Snapshots
 4 BtrfsDisk/Documents/document1.txt
 5 BtrfsDisk/Photos/photo1.jpg
 6 BtrfsDisk/Snapshots/Documents-22012025
 7 BtrfsDisk/Snapshots/Photos-22012025
 8 BtrfsDisk/Snapshots/Documents-22012025/document1.txt
 9 BtrfsDisk/Snapshots/Photos-22012025/photo1.jpg
  6. For testing purposes, you can add more data to your subvolumes and you should notice that newly added files do not appear in the snapshots, but only in the subvolumes:
    [admin@infra1.mikrotikls.lv] > /file print 
 # NAME   
 0 BtrfsDisk
 1 BtrfsDisk/Documents
 2 BtrfsDisk/Photos
 3 BtrfsDisk/Snapshots
 4 BtrfsDisk/Documents/document1.txt
 5 BtrfsDisk/Documents/document2.txt
 6 BtrfsDisk/Photos/photo1.jpg
 7 BtrfsDisk/Photos/photo2.jpg 
 8 BtrfsDisk/Snapshots/Photos-22012025
 9 BtrfsDisk/Snapshots/Documents-22012025
10 BtrfsDisk/Snapshots/Documents-22012025/document1.txt
11 BtrfsDisk/Snapshots/Photos-22012025/photo1.jpg
  7. You can now create a new snapshot:
    /disk/btrfs/subvolume/add read-only=yes parent=Documents fs=BtrfsDisk  name=Snapshots/Documents-23012025 
/disk/btrfs/subvolume/add read-only=yes parent=Photos fs=BtrfsDisk  name=Snapshots/Photos-23012025
  8. After a new snapshot, you will have 2 snapshots for each subvolume. One contains older files and another one contains older and newer files:
    [admin@MikroTik] > /file print 
 # NAME   
 0 BtrfsDisk
 1 BtrfsDisk/Documents
 2 BtrfsDisk/Photos
 3 BtrfsDisk/Snapshots
 4 BtrfsDisk/Documents/document1.txt
 5 BtrfsDisk/Documents/document2.txt
 6 BtrfsDisk/Photos/photo1.jpg
 7 BtrfsDisk/Photos/photo2.jpg
 8 BtrfsDisk/Snapshots/Photos-22012025
 9 BtrfsDisk/Snapshots/Documents-22012025
10 BtrfsDisk/Snapshots/Documents-23012025
11 BtrfsDisk/Snapshots/Photos-23012025
12 BtrfsDisk/Snapshots/Documents-22012025/document1.txt 
13 BtrfsDisk/Snapshots/Documents-23012025/document1.txt
14 BtrfsDisk/Snapshots/Documents-23012025/document2.txt
15 BtrfsDisk/Snapshots/Photos-22012025/photo1.jpg
16 BtrfsDisk/Snapshots/Photos-23012025/photo1.jpg
17 BtrfsDisk/Snapshots/Photos-23012025/photo2.jpg

    Multiple snapshots do not create multiple copies of each file, but if a file has been deleted and it still exists in a snapshot, then the deleted file will take up space. If a file exists in multiple snapshots, then it will take up space for only 1 file.

  9. In case you don't need an older snapshot, you can delete it:
    /disk/btrfs/subvolume/remove [find where name=Documents-22012025]
/disk/btrfs/subvolume/remove [find where name=Photos-22012025]

Transfer your snapshots

Btrfs allows to easily send a snapshot between two devices that is using Btrfs. In this example we will use two RouterOS devices running ROSE-storage package. The RouterOS device containing snapshots that need to be backed up is going to be called RouterA and the RouterOS device that is going to receive backups is going to be called RouterB .

This guide only shows an example how to use Btrfs transfer between RouterOS devices, but you can transfer snapshots between RouterOS and Linux devices as well. If you require such functionality, then make sure to check the documentation of your Linux distribution on how to use Btrfs transfer on it.

This guide will use the SSH host key for a SSH user key on the same RouterOS device. If you wish to use your own key for the SSH user, then you can use these commands on a Linux computer and later import the key pair under /user/ssh-keys :
openssl genpkey -outform PEM -out btrfstransfer_key.pem -algorithm ED25519
openssl pkey -in btrfstransfer_key.pem -pubout -out btrfstransfer_key_pub.pem
  1. OPTIONAL: Increase the security level of your SSH server, run the following commands on RouterA and RouterB :
    /ip ssh/set host-key-type=ed25519 strong-crypto=yes
/ip/ssh/regenerate-host-key

    Regenerating the host key will create a error message next time you try to connect to the RouterOS device using SSH. You will need to adjust your SSH client's configuration (usually in ~/.ssh/known_hosts ) to trust the new host key.

  2. On RouterA exports the SSH private and public key:
    /ip/ssh/export-host-key key-file-prefix=admin
  3. On RouterA import the SSH private key for user admin :
    /user/ssh-keys/private/import private-key-file=admin_ed25519.pem user=admin
  4. Upload the SSH public key from RouterA to RouterB :
    /file/sync/add local-path=admin_ed25519_pub.pem remote-address=RouterB user=admin mode=upload
/file/sync/remove [find where local-path=admin_ed25519_pub.pem]
  5. On RouterB create a new user, for example btrsfstransfer  and set a secure password for it:
    /user/add name=btrfstransfer group=write

    While the password is not going to be used for the Btrfs transfer feature, you still need to use a secure password to prevent unauthorized access to your device.

  6. On RouterB import the uploaded SSH public key and set it for user btrfstransfer :
    /user/ssh-keys/import public-key-file=admin_ed25519_pub.pem user=btrfstransfer
  7. On RouterA setup type send :
    /disk/btrfs/transfer add type=send fs=BtrfsDisk ssh-address=RouterB send-subvolumes=Documents-23012025 ssh-user=btrfstransfer ssh-receive-mount=BackupBtrfsDisk/Snapshots
    Where:
    - BtrfsDisk is the Btrfs disk label found under /disk/btrfs/filesystem print on RouterA 
    - Documents-23012025 is the snapshots name (not the path)
    - btrsfstransfer is the SSH user on RouterB 
    - BackupBtrfsDisk is the Btrfs disk label found under /disk/btrfs/filesystem print on RouterB 
    - Snapshots is the subvolumes under for your snapshots under BackupBtrfsDisk 
  8. On RouterB  setup type receive :
    /disk/btrfs/transfer/add fs=BackupBtrfsDisk type=receive file=BackupBtrfsDisk/Snapshots
    Where:
    - BackupBtrfsDisk is the Btrfs disk label found under /disk/btrfs/filesystem print on RouterB 
    - BackupBtrfsDisk/Snapshots is the mount path for Snapshots subvolume
  • No labels