Manjaro - User contributions [en]

File Systems

2025-11-18T16:10:30Z

Andreas85: changed default filesystem for manjaro

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 was previously the default file system in Manjaro. It is the successor to the most widely used Linux file systems (Ext3, Ext2) and promises improved design, higher performance, reliability, and more features compared to its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


[[Btrfs]] is now the default file system in Manjaro. Because [[Btrfs]] works differently, some things may seem unfamiliar and strange. The [[Btrfs]] page is therefore a good starting point for finding answers and gaining a better understanding of [[Btrfs]].


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

{{BoxWarning|Maintenance|When using snapshots, you must be particularly careful not to use up all the space on the file system -> [[Btrfs#Out_of_space]]}}

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.

{{BoxWarning|As of kernel 6.13|reiserFS will no longer be supported.}}


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|-
|F2FS||?||?||?||
|-
|JFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties ||btrfs||ext4||ext3||ext2||XFS||ZFS||F2FS||JFS
|-
|journaling ||● full||● ordered||● ordered||-||●
|-
|barriers ||●||●||?||-
|-
|checksum ||● full||◎ metadata||-||-
|-
|kompression||●,<br><small>zstd ▶ 4.14/5.1</small>||-||-||-||
|-
|encryption||-||▶ 4.13||-||-
|-
|snapshots||●||-||-||-||
|-
|TRIM possible||▶ 4.3||▶ 2.6.33||-||-
|-
|xattr, ACL||ACL||ACL||?||◎||ACL
|-
|small repair||● auto||● fsck||● fsck||● fsck
|-
|journal repair||● auto 3.2||● fsck||● fsck||● fsck||
|-
|repair after power loss||● auto, scrub||● tune2fs, fsck||?||-||
|-
|RAID||0, 1, 10||-||-||-||
|-
|since||2009||2008||2001||1993||
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

File Systems

2025-11-18T15:33:21Z

Andreas85: changed default filesystem for manjaro

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 was previously the default file system in Manjaro. It is the successor to the most widely used Linux file systems (Ext3, Ext2) and promises improved design, higher performance, reliability, and more features compared to its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


[[Btrfs]] is now the default file system in Manjaro. Because [[Btrfs]] works differently, some things may seem unfamiliar and strange. The [[Btrfs]] page is therefore a good starting point for finding answers and gaining a better understanding of [[Btrfs]].


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

{{BoxWarning|Maintenance|When using snapshots, you must be particularly careful not to use up all the space on the file system -> [[Btrfs#Out_of_space]]}}

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.

{{BoxWarning|As of kernel 6.13|reiserFS will no longer be supported.}}


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

File Systems

2025-11-18T15:31:02Z

Andreas85: changed default filesystem for manjaro

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 is the default filesystem in Manjaro at the moment. It is the evolution of the most used Linux filesystems (Ext3, Ext2) and promises improved design, better performance, reliability, and features over its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


[[Btrfs]] is now the default file system in Manjaro. Because [[Btrfs]] works differently, some things may seem unfamiliar and strange. The [[Btrfs]] page is therefore a good starting point for finding answers and gaining a better understanding of [[Btrfs]].


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

{{BoxWarning|Maintenance|When using snapshots, you must be particularly careful not to use up all the space on the file system -> [[Btrfs#Out_of_space]]}}

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.

{{BoxWarning|As of kernel 6.13|reiserFS will no longer be supported.}}


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

Pamac

2025-10-02T15:06:54Z

Andreas85: added "only"

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{BoxWarning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state.| It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>

==== AUR (Arch User Repository) ==== 


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


{{BoxWarning| Any use of the AUR is at your own risk.|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted.}}


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights only if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|update / upgrade|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T12:17:23Z

Andreas85: warning shortend

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{BoxWarning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state.| It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>

==== AUR (Arch User Repository) ====


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


{{BoxWarning| Any use of the AUR is at your own risk.|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted.}}


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|update / upgrade|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T12:15:17Z

Andreas85: info changed

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{BoxWarning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state.| It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>

==== AUR (Arch User Repository) ====


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


{{BoxWarning| Any use of the AUR is at your own risk.|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted.}}


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|update / upgrade|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T12:07:25Z

Andreas85: Überschrift für AUR hinzugefügt

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{BoxWarning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state.| It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>

==== AUR (Arch User Repository) ====


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


{{BoxWarning| Any use of the AUR is at your own risk.|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted.}}


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|tip|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T12:02:22Z

Andreas85: moved warning for AUR, changed wording

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{BoxWarning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state.| It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


{{BoxWarning| Any use of the AUR is at your own risk.|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted.}}


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|tip|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T11:51:33Z

Andreas85: Warning shortened

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{BoxWarning|Carefully review the Transaction Summary before accepting the package removal.| Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{warning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state. It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>


{{warning|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted. Any use of the provided files is at your own risk.}}


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|tip|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T11:49:35Z

Andreas85: added another reason to the warning

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{warning|It is extremely important to carefully review the Transaction Summary before accepting the package removal. Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{warning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state. It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>


{{warning|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted. Any use of the provided files is at your own risk.}}


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. It also can lead to Permission issues with the database. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|tip|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Pamac

2025-10-01T11:37:00Z

Andreas85: wording für sudo angepasst

<languages/>
__TOC__

<translate>
=Overview= 


Pamac (Add/Remove Software) is Manjaro's Package Manager. It is based on libalpm with AUR and Appstream support. It focuses on providing an easy to use interface while still providing a powerful set of features.


[[File:Pamac-gtk-main.png|center|800px]]

=Installing Pamac= 


Pamac is pre-installed on many Manjaro Editions but if your system does not have it it can be easily installed. Pamac comes in several different packages:
* {{ic|pamac-gtk}} - The GTK version of pamac. Includes a tray icon for many desktops.
* {{ic|pamac-cli}} - The command line version of pamac.
* {{ic|pamac-tray-icon-plasma}} - A tray icon for KDE plasma


These packages can be installed using pacman. For example, to install the GTK version, you can use the command:
{{UserCmd|command=sudo pacman -Syu pamac-gtk}}


{{BoxSuccess|tip|Both the GTK and Qt pamac packages will automatically install the CLI version as well}}

=Using the Pamac GUI= 

==Installing Software== 


[[File:Pamac-gtk-optional-deps.png|left|thumb|400px]]


To install packages, simply check the box next to the packages. Once you have selected all the packages you want to install, click the Apply button at the bottom of the page.


If any of the packages have optional dependencies (packages that enable additional functionality) you will see a window like the one to the left which allows to select the ones you would like to install.
<div style="clear: both"></div>
[[File:Pamac-gtk-transaction-summary.png|left|thumb|400px]]


After you have selected optional dependencies, you should see a window similar to the one pictured on the left. This lists all the packages that will be installed, upgraded or removed by the action. Once you have reviewed the list, press the Apply button to install the packages.


You may notice this list has more packages than you selected in the GUI. This is because many packages also have dependencies which are packages that must be installed in order for the software you selected to function properly. You may also notice that packages are being removed even though you didn't select any packages to remove. This is happening in the example to the left where you can see {{ic|clutter}} and {{ic|cogl}} are being removed. They are being removed because they conflict with {{ic|deepin-clutter}} and {{ic|deepin-cogl}} which provide the same functionality.
<div style="clear: both"></div>

==Removing Software== 


[[File:Pamac-gtk-remove-summary.png|left|thumb|400px]]


Removing software is as simple as unchecking the packages you want to remove and clicking the Apply button at the bottom of the page.


Once you do, you should see a screen similar to the one on the left which lists all the packages that are about to be removed. You may notice this list contains more packages than you selected. This is because when you remove a package that other packages depend on, those packages are also removed.


{{warning|It is extremely important to carefully review the Transaction Summary before accepting the package removal. Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}
<div style="clear: both"></div>

==Preferences== 


You can access the preferences by clicking on the three dots in the upper right corner and selecting preferences.


[[File:Pamac-gtk-preferences-general.png|left|thumb|400px]]


The General tab of preferences contains several settings, most of which are self-explanatory.


* Remove unrequired dependencies - This removes dependencies which are no longer required by any package
* Check available disk space - Checks to ensure you have sufficient disk space available before downloading and installing packages
* Maximum parallel downloads - The number of concurrent downloads allowed
* Enable downgrade - This allows packages to be downgraded as well as upgraded. This is important when [[Switching_Branches|switching branches]].
* Check for updates - Disabling this will stop pamac from looking for updates. In most cases, turning this off on a [[The Rolling Release Development Model|rolling release]] distro like Manjaro is a bad idea.
* Ignore updates for - This is a list of packages that you don't want to be upgraded. This is inherently dangerous practice and should only be used by advanced users.


{{warning|Ignoring updates for individual packages will leave you in an unsupported "partial upgrade" state. It is common for innocuous looking ignored packages to leave your system unbootable}}
<div style="clear: both"></div>


{{warning|'''DISCLAIMER:''' AUR scripts are created for Arch Linux by Arch Linux Users. AUR packages are user-produced content. These PKGBUILDs are completely unofficial and have not been thoroughly vetted. Any use of the provided files is at your own risk.}}


[[File:Pamac-gtk-preferences-aur.png|left|thumb|400px]]


Pamac is also capable of using scripts from the [[Arch User Repository|Arch User Repository(AUR)]] to install or update packages. Please carefully read the considerations in the [[Arch User Repository|linked page]] prior to enabling support for AUR.


If you enable AUR support, you may also select, "Check for updates from AUR" so software you install from AUR won't become outdated. An alternative is creating an account on AURweb and subscribe to notifications for the scripts you are using on a permanent basis.


Checking for "development package" updates will allow updates on *-git packages which are built from the latest source code to also be updated.


The "Build directory" is where AUR packages will be built. Using "tmp" usually will provide the best performance but very large packages may fail to build. In this case, select a location with more available space.
<div style="clear: both"></div>
[[File:Pamac-gtk-preferences-cache.png|left|thumb|400px]]


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time. These preferences allow your cache to be automatically managed based on your preferences.


The first option allows you to set a number for how many copies of each package are retained. In other words, if you have downloaded 25 versions of Firefox over the life of your install and you set this number to "3", only the most recent 3 versions will be retained. Unless you are very short on disk space, it is recommended to set this to at least 2.


By selecting "Remove only the versions of uninstalled packages", pamac will retain all versions of packages you still have installed.
<div style="clear: both"></div>

=Using the Pamac CLI= 


Pamac also includes a fully functional CLI for when you don't have a working GUI or for those that prefer to manage packages that way.


{{BoxWarning|Do not use sudo with pamac.|Using sudo with pamac can have undesirable effects, especially when building packages. Pamac will ask for escalated rights if needed.}}

==Locating and Installing Packages== 


To search for available packages you can use the command {{ic|pamac search}}. For example, to search the repos for packages containing the word smplayer:
<pre>pamac search smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer</pre>


As you can see, this will also show you which packages are already installed. If you would like to search both the repos and [[Arch_User_Repository|AUR]] you add {{ic|-a}} like this:
<pre>pamac search -a smplayer
smplayer
[Installed] 19.5.0-1 community
Media player with built-in codecs that can play virtually all video and audio formats
smplayer-skins
[Installed] 1:15.2.0-2 community
Skins for SMPlayer
smplayer-themes
[Installed] 1:18.6.0-1 community
Themes for SMPlayer
papirus-smplayer-theme-git
20181024-2 AUR
Papirus theme for SMPlayer (git version)
smplayer-svn
17.12.0.r8852-1 AUR
Advanced front-end for MPlayer/MPV
smplayer-svn-notitlebar
18.3.0.r8982M-1 AUR
Advanced front-end for MPlayer/MPV + Patch to disable titlebar in compact mode
smplayer-skins-svn
15.2.0.r8852-1 AUR
Skins for SMPlayer
smplayer-themes-svn
17.3.0.r8852-1 AUR
Themes for SMPlayer
smplayer-qt4
18.5.0-1 AUR
Complete front-end for MPlayer/MPV (Qt4)
rosa-media-player-plugin
1.0-2 AUR
The new multimedia player(based on SMPlayer) with clean and elegant UI (mozilla plugin only).
smplayer-theme-faenza (Out of Date: 09/15/2017)
2-2 AUR
Normal, dark and silver faenza theme for smplayer.
umplayer
0.98.2-2 AUR
An alternative to SMPlayer</pre>


Once you have identified the packages you wish to install, you can install them with command {{ic|pamac install}}. For example, if we wanted to install {{ic|smplayer}} and {{ic|smplayer-themes}} we could use the command:
{{UserCmd|command=pamac install smplayer smplayer-themes}}


{{BoxInfo|tip|When using install, pamac will check to see if packages are installed and only install the ones not already installed}}


If you want to install packages from [[Arch_User_Repository|AUR]] you use the command {{ic|pamac build}}. Sticking with the above example, if you decided you wanted to install {{ic|umplayer}} instead you could use the command:
{{UserCmd|command=pamac build umplayer}}

==Removing Packages== 


The command {{ic|pamac remove}} can be used to uninstall packages installed from the repos or [[Arch_User_Repository|AUR]]. For example, if you wanted to remove all the packages installed above, you could use the command:
{{UserCmd|command=pamac remove smplayer smplayer-themes umplayer}}


{{BoxWarning|Carefully review the list of packages pamac presents before confirming.|Some packages have many packages which depend on them and you don't want to inadvertently remove your whole desktop environment}}

==Identifying Installed Packages== 


To display a list of all installed packages, you can use the command:
{{UserCmd|command=pamac list -i}}

==Displaying Detailed Package Information== 


To display detailed information on a package that is in the repos or installed on your system, use the command {{ic|pamac info}}. Keeping with our example of SMPlayer :
{{UserCmd|command=pamac info smplayer}}


If you also would like to check packages in [[Arch_User_Repository|AUR]], you could use:
{{UserCmd|command=pamac info -a smplayer}}

==Updating the System== 


To check if updates are available, you can use the command:
{{UserCmd|command=pamac checkupdates -a}}


To update all installed packages installed from the repos or [[Arch_User_Repository|AUR]], you can use the command:
{{UserCmd|command=pamac upgrade -a}}


{{BoxInfo|tip|pamac update and pamac upgrade are exactly the same. You can use them interchangeably.}}

==Dealing with Orphaned Packages== 


To check to see if there any orphaned packages (packages which are no longer needed) installed, you can use:
{{UserCmd|command=pamac list -o}}


To remove all orphans use the command:
{{UserCmd|command=pamac remove -o}}

==Cleaning the Cache== 


When pamac installs packages, it keeps a copy of all the old packages you have downloaded. This cache can be very useful if you have to install older packages in an emergency. However, left unchecked, this cache will grow very large over time.


Otherwise, to clear the cache completely, enter the following command (and use with care):
{{UserCmd|command=pamac clean}}


A safer way to remove old package cache files is to remove all packages except for the latest three package versions using:
{{UserCmd|command=pamac clean --keep 3}}

==Other Useful Pamac Functions== 


To see which package owns a certain file on your system, use the command {{ic|pamac search -f}}. For example:
{{UserCmd|command=pamac search -f /usr/bin/smplayer}}


To force a package to be installed even if it is already installed, use {{ic|pamac reinstall}}. For example:
{{UserCmd|command=pamac reinstall smplayer}}

</translate>
[[Category:Contents Page{{#translation:}}]]

Build Manjaro ISOs with buildiso

2025-09-30T12:39:41Z

Andreas85: Link korrigiert

<languages/>
__TOC__

<translate>
=Prerequisites= 


This is a detailed walkthrough of installation and configuration of the tools and build process.


It is a requirement to either download and install the latest version of [https://manjaro.org/products/download/x86 Manjaro] or be running a well maintained Manjaro system. '''It is vital your system is updated''' with the latest available kernel and packages.

==Install Manjaro Tools== 


To get started you need to the following packages


{{UserCmd|command=pamac install manjaro-tools-iso-git git}}


We will be working with the official XFCE to help you understand what you need to do.

=ISO profile= 
==Download the latest ISO profiles==


The latest profiles can be found in the Manjaro gitlab. You can download them directly using the command:
{{UserCmd|command=git clone <nowiki>https://gitlab.manjaro.org/profiles-and-settings/iso-profiles.git</nowiki> ~/iso-profiles}}

==ISO profile overview== 
The ISO profile for xfce can now be found at


{{UserCmd|command=ls -l ~/iso-profiles/manjaro/xfce}}


Let's take a closer look at the XFCE profile folder (marked above):


'''desktop-overlay'''
live-overlay -> ../../shared/manjaro/live-overlay
'''Packages-Desktop'''
Packages-Live -> ../../shared/Packages-Live
Packages-Mhwd -> ../../shared/Packages-Mhwd
Packages-Root -> ../../shared/Packages-Root
'''profile.conf'''


* '''desktop-overlay''': After every successful installation of your ISO the files and folders in here will get copied over.
* ''live-overlay'': Similar to ''desktop-overlay''. Files and folders in here will only get copied over to the LiveCD of your ISO.
* '''Packages-Desktop''': This file contains packages for the ISO installation. All packages will also get installed on LiveCDs.
* ''Packages-Live'': This file contains packages, which will only get installed on the LiveCD.
* ''Packages-Mhwd'': This file contains Mhwd packages important to all Manjaro installations and LiveCDs.
* ''Packages-Root'': This file contains base packages important to all Manjaro installations and LiveCDs.
* '''profile.conf''' contains basic settings for your ISO installation and LiveCD.


As you have probably noticed, several are only symlinks to the <code>shared</code> ISO profile. It is good practice to never change files or folders in the <code>shared</code> ISO profile. If you ever want to change them, first copy them to your ISO profile folder and delete the symlink.


All folders and files specific to your ISO are '''in bold'''. You can change them to your liking.

==Modifying an ISO profile== 


The most common places to tweak and customize an ISO profile are the 3 folders marked above: ''desktop-overlay'', ''profile.conf'', ''Packages-Desktop'':

===desktop-overlay=== 


The ''desktop-overlay'' folder looks like this:


{{UserCmdOutput|command=tree ~/iso-profiles/manjaro/xfce/desktop-overlay/etc|result=
<pre>
../iso-profiles/manjaro/xfce/desktop-overlay/
├── etc
│   ├── fonts
│   │   └── conf.d
│   │   └── 70-no-bitmaps.conf
│   └── lightdm
│   ├── lightdm.conf
│   └── lightdm-gtk-greeter.conf
└── usr
└── share
└── icons
└── default
└── index.theme
</pre>
}}


Go to this directory.


{{UserCmd|command=cd ~/iso-profiles/manjaro/xfce/desktop-overlay/etc/}}


Then create '''skel''' folder. This is where you can clone everything you see on your Desktop Screen to ISO.
{{UserCmd|command=mkdir skel}}


After the ISO has been successfully installed all files and folder in ''desktop-overlay'' folder get copied over to the installed system. This includes settings/config files but also themes and backgrounds/pictures.


All files and folder in here will get copied to the home folder. Most hidden files and their structure in <code>~/iso-profiles/manjaro/xfce/desktop-overlay/etc/skel/</code> should be already familiar to you, because your home folder looks very similar.

===Clone Custom Wallpaper Desktop=== 


To clone your Custom Wallpaper Desktop. Open a New File Manager and go to this file.


~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml


Change all image directories to where your Custom Wallpaper was located at. For example:


/usr/share/backgrounds/<YOUR IMAGE HERE>

===Example=== 
<div class="toccolours mw-collapsible mw-collapsed">
<span style="color:green">A sample `xfce4-desktop.xml` can be viewed by unfolding this block</span>
<div class="mw-collapsible-content">


<pre>
<?xml version="1.0" encoding="UTF-8"?>

<channel name="xfce4-desktop" version="1.0">
<property name="backdrop" type="empty">
<property name="screen0" type="empty">
<property name="monitor0" type="empty">
<property name="image-path" type="string" value="'''/usr/share/backgrounds/<YOUR IMAGE HERE>'''"/>
<property name="last-image" type="string" value="'''/usr/share/backgrounds/<YOUR IMAGE HERE>'''"/>
<property name="last-single-image" type="string" value="'''/usr/share/backgrounds/<YOUR IMAGE HERE>'''"/>
<property name="image-style" type="int" value="5"/>
</property>
<property name="monitorVGA-0" type="empty">
<property name="workspace0" type="empty">
<property name="color-style" type="int" value="0"/>
<property name="image-style" type="int" value="5"/>
<property name="last-image" type="string" value="'''/usr/share/backgrounds/<YOUR IMAGE HERE>'''"/>
</property>
<property name="workspace1" type="empty">
<property name="color-style" type="int" value="0"/>
<property name="image-style" type="int" value="5"/>
<property name="last-image" type="string" value="'''/usr/share/backgrounds/<YOUR IMAGE HERE>'''"/>
</property>
</property>
</property>
</property>
<property name="desktop-icons" type="empty">
<property name="style" type="int" value="2"/>
<property name="file-icons" type="empty">
<property name="show-removable" type="bool" value="true"/>
</property>
<property name="icon-size" type="uint" value="32"/>
</property>
</channel>
</pre>
</div>
</div>


Go to this directory:


{{UserCmd|command=cd ~/iso-profiles/manjaro/xfce/desktop-overlay/}}


Then create <code>usr/share/backgrounds</code> and place your Custom Wallpaper at this directory.
{{UserCmd|command=mkdir ./usr/share/backgrounds}}


{{UserCmd|command=cp ~/Pictures/Wallpapers/your-wallpaper.png ~/iso-profiles/manjaro/xfce/desktop-overlay/usr/share/backgrounds}}

===profile.conf=== 
<div class="toccolours mw-collapsible mw-collapsed">
<span style="color:green">The full content of an example profile.conf can be viewed by unfolding this block. It is always best to use the latest version instead of copying this one.</span>
<div class="mw-collapsible-content">
<pre>
##########################################
###### use this file in the profile ######
##########################################

# use multilib packages; x86_64 only
# multilib="true"

displaymanager="lightdm"

# Set to false to disable autologin in the livecd
# autologin="true"

# nonfree mhwd drivers
# nonfree_mhwd="true"

# use extra packages as defined in pkglist to activate a full profile
#extra="true"

################ install ################

# unset defaults to given value
# efi_boot_loader="grub"

# configure calamares for netinstall
# netinstall="false"

# configure calamares to use chrootcfg instead of unpackfs
# chrootcfg="false"

# use geoip for localization
# geoip='true'

# unset defaults to given values
# names must match systemd service names
enable_systemd=('avahi-daemon' 'bluetooth' 'cronie' 'ModemManager' 'NetworkManager' 'cups' 'haveged' 'ufw' 'apparmor' 'snapd.apparmor' 'snapd' 'systemd-timesyncd')
enable_systemd_timers=('fstrim' 'pacman-filesdb-refresh')
disable_systemd=('pacman-init')

# add strict snaps: strict_snaps="snapd core core18 gnome-3-28-1804 gtk-common-themes snap-store"
# strict_snaps=""
# add classic snaps: classic_snaps="code"
# classic_snaps=""
# choose the snap channel. Possible options are: stable, candidate, beta, edge
# snap_channel="candidate"

# the same workgroup name if samba is used
# smb_workgroup=""

################# livecd #################

# unset defaults to given value
# hostname="manjaro"

# unset defaults to given value
# username="manjaro"

# unset defaults to given value
# password="manjaro"

# the login shell
# defaults to bash
# login_shell=/bin/bash

# unset defaults to given values
# addgroups="lp,network,power,wheel"

# unset defaults to given values
# names must match systemd service names
# services in enable_systemd array don't need to be listed here
# enable_systemd_live=('manjaro-live' 'mhwd-live' 'pacman-init' 'mirrors-live')
disable_systemd_live=('tlp' 'tlp-sleep')

custom_boot_args=('splash')
</pre>
</div>
</div>


This config file contains setting options. All default settings are commented. If you want to change them, uncomment them (remove the <code>#</code> symbol in front) and change it.


The following settings are noteworthy:


* <code>multilib=</code> setting belongs to the <code>>multilib</code> flag in your package lists. multilib will install basic 32bit libraries on 64bit systems. This increases compatibility for 32bit applications on 64bit systems.
* <code>displaymanager=</code> sets the display / login manager your system uses. You need to list your display manager in your package list, too.
* <code>kernel=</code> lets you set the installed kernel. Do '''not''' include any kernels in your package list! This setting is all you need.
* <code>enable_systemd=</code> let's you set systemd services, which get started on the installed system (and with a similar setting on the livecd).

===Packages-Desktop=== 
<div class="toccolours mw-collapsible mw-collapsed">
<span style="color:green">An example `Packages-Desktop` file can be viewed by unfolding this block. It is always best to use the latest version instead of copying this one.</span>
<div class="mw-collapsible-content">
<pre>
## Network
avahi
networkmanager
networkmanager-openconnect
networkmanager-openvpn
networkmanager-pptp
networkmanager-vpnc
nss-mdns # NSS support for mDNS (optdepend for avahi)
ntp
mobile-broadband-provider-info
modemmanager
openresolv
openssh
samba
usb_modeswitch


## Libraries for Sound/Audio/Video
alsa-firmware
alsa-utils
ffmpeg
gst-libav
gst-plugins-bad
gst-plugins-base
gst-plugins-good
gst-plugins-ugly
libdvdcss
>multilib manjaro-alsa
manjaro-pulse
pulseaudio-bluetooth
pulseaudio-ctl
pulseaudio-zeroconf


## Connect Packages
android-tools
android-udev
gvfs
gvfs-afc
gvfs-gphoto2
gvfs-mtp
gvfs-nfs
gvfs-smb
mtpfs
udiskie
udisks2


## AUR Support/Development
# Missing base-devel packages
autoconf
automake
binutils
bison
fakeroot
flex
gcc
>multilib gcc-libs-multilib
>multilib gcc-multilib
libtool
m4
make
patch
pkg-config
>multilib lib32-flex
# Extra packages for AUR support
>extra git
>extra patchutils
>extra subversion


## Fonts
cantarell-fonts
# noto-fonts # default font
# noto-fonts-cjk # big package, ~76 mb compressed
# >extra noto-fonts-emoji
terminus-font
ttf-bitstream-vera # xfce4-terminal default Monospace
# ttf-dejavu # Installed as gnome-themes-standard dependency
>extra ttf-inconsolata
>extra ttf-indic-otf
>extra ttf-liberation
>extra ttf-droid


## Games
>extra steam-manjaro


## Package management
pamac
flatpak


## Java
>extra jdk8-openjdk
>extra jre8-openjdk-headless
>extra jre8-openjdk


## Printing
>extra cups
>extra cups-pdf
>extra cups-pk-helper
>extra ghostscript
>extra gsfonts
>extra gtk3-print-backends
>extra hplip
>extra splix
>extra system-config-printer


## Optional dependencies for hplip
>extra pyqt5-common # For hplip
>extra python-pillow # For hplip
>extra python-pip # For hplip
>extra python-pyqt5 # For hplip gui
>extra python-reportlab # For hplip


## Display manager
lightdm
lightdm-gtk-greeter
lightdm-gtk-greeter-settings
accountsservice # Enhanced user accounts handling


## GTK3
gtk3-classic
>multilib lib32-gtk3-classic


## XFCE Group
exo-gtk3
garcon-gtk3
thunar-gtk3
thunar-volman
tumbler
xfce4-appfinder-gtk3
xfce4-panel-gtk3
xfce4-power-manager-gtk3
xfce4-session-gtk3
xfce4-settings-gtk3
xfce4-terminal
xfconf-gtk3
xfdesktop-gtk3
xfwm4-gtk3


## XFCE Extras
blueman
ffmpegthumbnailer # tumbler - for video thumbnails
freetype2 # tumbler - for font thumbnails
gksu
gnome-keyring # fix wlan segfault
libgsf # tumbler - for ODF thumbnails
libopenraw # tumbler - for RAW thumbnails
light-locker
network-manager-applet
menulibre
orage
poppler-glib # tumbler - for PDF thumbnails
thunar-archive-plugin
file-roller
thunar-media-tags-plugin
# >extra xfce4-artwork
xfce4-battery-plugin
xfce4-clipman-plugin
>extra xfce4-cpufreq-plugin
>extra xfce4-cpugraph-plugin
# xfce4-datetime-plugin
>extra xfce4-dict
>extra xfce4-diskperf-plugin
>extra xfce4-fsguard-plugin
>extra xfce4-genmon-plugin
>extra xfce4-mailwatch-plugin
>extra xfce4-mount-plugin
>extra xfce4-mpc-plugin
>extra xfce4-netload-plugin
>extra xfce4-notes-plugin
xfce4-notifyd-gtk3
xfce4-screenshooter
>extra xfce4-sensors-plugin
>extra xfce4-smartbookmark-plugin
>extra xfce4-systemload-plugin
xfce4-taskmanager
>extra xfce4-time-out-plugin
>extra xfce4-timer-plugin
>extra xfce4-verve-plugin
>extra xfce4-wavelan-plugin
>extra xfce4-weather-plugin
xfce4-whiskermenu-plugin-gtk3
xfce4-xkb-plugin
xfce4-pulseaudio-plugin
pavucontrol


## Themes
>extra manjaro-wallpapers-18.0
>extra wallpapers-2018
gnome-icon-theme
gnome-themes-standard
grub-theme-manjaro
matcha-gtk-theme
xcursor-simpleandsoft
xcursor-vanilla-dmz-aa


## Applications
>extra catfish
dmidecode # optional dependency inxi
engrampa
>extra firefox
# >extra flashplugin
>extra galculator-gtk2
gcolor2
>extra gimp
gparted
gufw
>extra audacious
>extra hexchat
htop
qpdfview
inxi
>extra libreoffice-still
ms-office-online
manjaro-hello
manjaro-application-utility
manjaro-settings-manager
manjaro-settings-manager-notifier
>basic midori
>extra mlocate
mousepad
mugshot
>basic parole # media player
>extra pidgin
powertop
screenfetch
>extra poppler-data # CKJ support for pdf
>basic sylpheed # mail client
>extra thunderbird
>extra vlc
>extra viewnior
>extra xfburn
>extra yelp


# Optional dependencies engrampa
p7zip # 7Z and ARJ archive support
unace # ACE archive support
unrar # RAR archive support


## Documentation
manjaro-documentation-en


## Settings packages
>extra manjaro-xfce-gtk3-settings
>basic manjaro-xfce-gtk3-minimal-settings
manjaro-browser-settings


## Xorg Input Drivers
xf86-input-elographics
xf86-input-evdev
xf86-input-keyboard
xf86-input-libinput
xf86-input-mouse
xf86-input-void


## Xorg Server and Graphics
>multilib lib32-libva-intel-driver
>multilib lib32-libva-mesa-driver
>multilib lib32-libva-vdpau-driver
libva-intel-driver
libva-mesa-driver
libva-vdpau-driver
mesa-demos
>multilib lib32-mesa-demos
numlockx
xdg-user-dirs
xorg-server
xorg-twm
xorg-xinit
xorg-xkill


## Desktop Utils
perl-file-mimeinfo
xdg-utils
xdg-su


## Misc
manjaro-hotfixes


</pre>
</div>
</div>
This file contains a list of packages, which will get installed on your installed ISO (XFCE) '''and''' the LiveCD (the packages in Packages-Live file only get installled on the live ISO). This is a package list with Xfce specific packages (and packages you like to add to your custom Manjaro ISO) of multiple package lists in your ISO profile. The other package lists are more generic.


You can add or remove package names from this list as you like. You do not need to worry about dependencies when adding package names, just make sure the package name is spelled correctly and the package is available in the Manjaro repositories.


<code>#</code> marks a comment. The rest of the line after the <code>#</code> symbol gets ignored.

===Adding AUR packages=== 


If you want to add AUR packages to your ISO, you need to create a online repository and add it to a file '''user-repos.conf''' beside your '''profile.conf'''.


'''Only use your own http enabled repo.'''


[your-repo-name]
SigLevel = Optional TrustAll
Server = http://repo.server.tld/your-repo-name


The article [[Buildiso with AUR packages: Using buildpkg]] contains more detailed information on this process.

=manjaro-tools.conf= 


<code>manjaro-tools.conf</code> is the central configuration file for all tools part of ''manjaro-tools''. Only edit the general and the "buildiso" part to not exceed the scope of this tutorial. If you are not sure what and how to edit it, do '''not''' edit it. You can always use arguments with the <code>buildiso</code> command later.


By default, the systemwide config file is installed in


/etc/manjaro-tools/manjaro-tools.conf


Best practice is to leave the systemwide file untouched and copy the system wide config to your home directory here:


~/.config/manjaro-tools


If the userconfig is present, ''manjaro-tools''/''buildiso'' will load the userconfig values. Best practice is to leave the systemwide file untouched. By default it is commented and shows just initialization values done in code.

=Build your ISO= 
Build your ISO with the following command:
{{UserCmd|command=buildiso -p xfce}}
You need to specify the name of your ISO profile after the <code>-p</code> argument. In this case, it is <code>xfce</code>.


If the build process fails with an error, start it again.


'''Attention:''' The build process needs at least 10 minutes to complete or much longer when you are using HDDs, slow CPUs, or large ISOs.

When the build process finishes successfully, the ISO file and the package list will appear in this folder:
/var/cache/manjaro-tools/iso/
===Example:=== 
You can use arguments with the <code>buildiso</code> command for more build options:
{{UserCmd|command=buildiso -f -p xfce -b stable}}
* <code>-f</code> let's you specify if you want the full ISO. If omitted a minimal ISO will be build.
* <code>-b</code> let's you specify the branch. You can also set this in your <code>manjaro-tools.conf</code> file.
You can find other examples of builds using different arguments for ''buildiso'' [https://wiki.manjaro.org/index.php?title=Manjaro-tools#buildiso here].

=Cleaning your hard drive= 


After a successful or failed build, you can get rid of most data (the "raw" ISO with all downloaded packages) by deleting this folder:


{{UserCmd|command=sudo rm -r /var/lib/manjaro-tools/buildiso/}}


To clean your system of packages files of packages not installed on your system (this includes all the package files downloaded for your custom ISO):


{{UserCmd|command=sudo paccache -ruk0}}


You can also manually look into


/var/cache/manjaro-tools/


and delete folders or files to your liking. If you want to delete all ISO images, package lists, and cached Xorg packages do:


{{UserCmd|command=sudo rm -r /var/cache/manjaro-tools/}}


Please remember that all these packages and files are saved for your convenience. If you clean your system like suggested above, you have to download '''all''' packages and build '''all''' images again the next time you want to build your own Manjaro ISO.


By default, your <code>manjaro-tools.conf</code> file is saved. If you want to delete it, use


{{UserCmd|command=rm -r ~/.config/manjaro-tools}}

=Tips & Tricks= 

==Building a minimal ISO== 
A minimal ISO is easy to create by modifying an entry in the profile.conf file. Find the section
<pre>
# use extra packages as defined in pkglist to activate a full profile
# extra="false"
extra="true"
</pre>
and remove the '''#''' mark in front of '''extra = "false"''' and add a '''#''' in front of '''extra = "true"'''.


If you prefer not to change this you can always use the '''-f''' with buildiso to build a full profile.

=See also= 
* Source: [https://gitlab.manjaro.org/profiles-and-settings/iso-profiles Manjaro Gitlab ISO Profiles] (master branch may be unstable - select the branch for latest release)
* Video: [https://youtu.be/B--je--m0VI Building Manjaro ISO by Philip Müller](Tutorial Video)
* Wiki: [[Buildiso with AUR packages: Using buildpkg]]
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:ISO{{#translation:}}]]

CheatSheet/

2025-09-05T17:19:46Z

Andreas85: df and btrfs fi us

<languages/>

= Commands CheatSheet for Manjaro =


__TOC__

=== Locating and Installing Packages ===
==== Using Pamac CLI ====
Install packages {{UserCmd|command=pamac install [PackageName]}}
Uninstall packages {{UserCmd|command=pamac remove [PackageName]}}
Search for a package {{UserCmd|command=pamac search [PackageName]}}
Update installed packages {{UserCmd|command=pamac upgrade}}
Check for updates {{UserCmd|command=pamac checkupdates}}

==== Using native pacman ====
Install packages {{UserCmd|command=sudo pacman -Syu [PackageName]}}
Uninstall packages {{UserCmd|command=sudo pacman -Rns [PackageName]}}
Search for a package {{UserCmd|command=pacman -Ss [PackageName]}}
Update installed packages {{UserCmd|command=sudo pacman -Syu}}
Check for updates {{UserCmd|command=sudo pacman -Syu}}

=== Maintenance ===

Generates a random mirrorlist for the users and sort them by their current access time. {{UserCmd|command=sudo pacman-mirrors --fasttrack}}
Generate cache list {{UserCmd|command=du -sh ~/.cache/*}}
Purge files not accessed in 100 days {{UserCmd|command=find ~/.cache/ -type f -atime +100 -delete}}
Report journal current size {{UserCmd|command=journalctl --disk-usage}}
Remove but recent entries by size or time {{UserCmd|command=journalctl --vacuum-size=50M}} {{UserCmd|command=journalctl --vacuum-time=2weeks}}
Check for orphaned packages {{UserCmd|command=pamac list -o }}
Remove all orphans {{UserCmd|command=pamac remove -o }}
Remove all packages except the latest 3 versions {{UserCmd|command=pamac clean --keep 3}}

=== AUR ===

Search for package {{UserCmd|command=pamac search -a [PackageName]}}
Build the package {{UserCmd|command=pamac build [PackageName]}}

=== Access rights ===

Execute command as root {{UserCmd|command=sudo [command]}}
Empty password cache {{UserCmd|command=sudo -k}}
Change user password {{UserCmd|command=passwd username}}
Change owner and group of file {{UserCmd|command=chown [owner]:[group] -c [file]}}
Change file permissions {{UserCmd|command=chmod [permissions] -c [file]}}
Set permissions in octal mode: 4(read) 2(write) 1(execute)

Example: 755 read-write-execute for owner and read-execute for group and others

Display files and permissions [of directory]{{UserCmd|command=ls -lh [dir]}}

=== Files and Directories ===

Change the working directory {{UserCmd|command=cd [dir]}}
Change to parent directory {{UserCmd|command=cd ..}}
List directory contents {{UserCmd|command=ls -l}}
List also hidden files {{UserCmd|command=ls -la}}
Copy file {{UserCmd|command=cp [file] [target]}}
Copy directory '''recursively''' {{UserCmd|command=cp -r [directory] [target]}}
Move or rename file/directory {{UserCmd|command=mv [source] [target]}}
Remove directory '''recursively''' {{UserCmd|command=rm -r [dir]}}
Create symbolic link {{UserCmd|command=ln -s [target] [link]}}
Mount filesystem {{UserCmd|command=mount -t [type] [/dev/sdx9] [mountpoint]}}
Mount ISO image {{UserCmd|command=mount -o loop [iso] [mountpoint]}}
Home directory of user {{UserCmd|command=cd /home/$USER}} {{UserCmd|command=cd ~}}
Directory with global configurations {{UserCmd|command=cd /etc}}

=== Network ===

Display network information {{UserCmd|command=nmcli}}
List wireless access points {{UserCmd|command=nmcli c}}
Enable firewall [package Community: ufw] {{UserCmd|command=ufw enable}}
Allow/deny all incoming traffic {{UserCmd|command=ufw default [allow/deny]}}
Displays firewall status and rules {{UserCmd|command=ufw status}}
Allows/deny incoming traffic on the specified port {{UserCmd|command=ufw [allow/deny] [port]}}
Allows/deny incoming traffic from specified IP address {{UserCmd|command=ufw [allow/deny] from [ip]}}

=== System and Screen ===

Display kernel version {{UserCmd|command=uname -r}}
Display long kernel version {{UserCmd|command=uname -a}}
Report free disk space (non btrfs){{UserCmd|command=df [/] [/home]}}
Report free disk space (btrfs){{UserCmd|command=sudo btrfs filesystem usage -h [/]}}
Display system tasks {{UserCmd|command=top}} {{UserCmd|command=htop}}
Display system information {{UserCmd|command=inxi --filter --verbosity=8}}
Display system information (from chroot){{UserCmd|command=inxi --filter --verbosity=8 --color}}
Display a tree of processes {{UserCmd|command=pstree}}

Switch to tty
* {{key press|Ctrl|Alt|F1}}
* {{key press|Ctrl|Alt|F2}}
* {{key press|Ctrl|Alt|F3}}
* {{key press|Ctrl|Alt|F4}}
* {{key press|Ctrl|Alt|F5}}
* {{key press|Ctrl|Alt|F6}}

Switch to the X session
* {{key press|Ctrl|Alt|F7}}

Start a unit {{UserCmd|command=systemctl start unit}}
Stop a unit {{UserCmd|command=systemctl stop unit}}
Check status of a unit {{UserCmd|command=systemctl status unit}}
Enable a unit {{UserCmd|command=systemctl enable unit}}
Disable a unit {{UserCmd|command=systemctl disable unit}}
Restart a unit {{UserCmd|command=systemctl restart unit}}
Shut down the system {{UserCmd|command=poweroff}}
Restart the system {{UserCmd|command=reboot}}





=See Also=

[https://forum.manjaro.org/t/manjaro-cli-cheat-sheet/101305 Original forum post]

[[Category:Boilerplate{{#translation:}}]]

CheatSheet/

2025-09-05T17:12:20Z

Andreas85: added another inxi for chroot

<languages/>

= Commands CheatSheet for Manjaro =


__TOC__

=== Locating and Installing Packages ===
==== Using Pamac CLI ====
Install packages {{UserCmd|command=pamac install [PackageName]}}
Uninstall packages {{UserCmd|command=pamac remove [PackageName]}}
Search for a package {{UserCmd|command=pamac search [PackageName]}}
Update installed packages {{UserCmd|command=pamac upgrade}}
Check for updates {{UserCmd|command=pamac checkupdates}}

==== Using native pacman ====
Install packages {{UserCmd|command=sudo pacman -Syu [PackageName]}}
Uninstall packages {{UserCmd|command=sudo pacman -Rns [PackageName]}}
Search for a package {{UserCmd|command=pacman -Ss [PackageName]}}
Update installed packages {{UserCmd|command=sudo pacman -Syu}}
Check for updates {{UserCmd|command=sudo pacman -Syu}}

=== Maintenance ===

Generates a random mirrorlist for the users and sort them by their current access time. {{UserCmd|command=sudo pacman-mirrors --fasttrack}}
Generate cache list {{UserCmd|command=du -sh ~/.cache/*}}
Purge files not accessed in 100 days {{UserCmd|command=find ~/.cache/ -type f -atime +100 -delete}}
Report journal current size {{UserCmd|command=journalctl --disk-usage}}
Remove but recent entries by size or time {{UserCmd|command=journalctl --vacuum-size=50M}} {{UserCmd|command=journalctl --vacuum-time=2weeks}}
Check for orphaned packages {{UserCmd|command=pamac list -o }}
Remove all orphans {{UserCmd|command=pamac remove -o }}
Remove all packages except the latest 3 versions {{UserCmd|command=pamac clean --keep 3}}

=== AUR ===

Search for package {{UserCmd|command=pamac search -a [PackageName]}}
Build the package {{UserCmd|command=pamac build [PackageName]}}

=== Access rights ===

Execute command as root {{UserCmd|command=sudo [command]}}
Empty password cache {{UserCmd|command=sudo -k}}
Change user password {{UserCmd|command=passwd username}}
Change owner and group of file {{UserCmd|command=chown [owner]:[group] -c [file]}}
Change file permissions {{UserCmd|command=chmod [permissions] -c [file]}}
Set permissions in octal mode: 4(read) 2(write) 1(execute)

Example: 755 read-write-execute for owner and read-execute for group and others

Display files and permissions [of directory]{{UserCmd|command=ls -lh [dir]}}

=== Files and Directories ===

Change the working directory {{UserCmd|command=cd [dir]}}
Change to parent directory {{UserCmd|command=cd ..}}
List directory contents {{UserCmd|command=ls -l}}
List also hidden files {{UserCmd|command=ls -la}}
Copy file {{UserCmd|command=cp [file] [target]}}
Copy directory '''recursively''' {{UserCmd|command=cp -r [directory] [target]}}
Move or rename file/directory {{UserCmd|command=mv [source] [target]}}
Remove directory '''recursively''' {{UserCmd|command=rm -r [dir]}}
Create symbolic link {{UserCmd|command=ln -s [target] [link]}}
Mount filesystem {{UserCmd|command=mount -t [type] [/dev/sdx9] [mountpoint]}}
Mount ISO image {{UserCmd|command=mount -o loop [iso] [mountpoint]}}
Home directory of user {{UserCmd|command=cd /home/$USER}} {{UserCmd|command=cd ~}}
Directory with global configurations {{UserCmd|command=cd /etc}}

=== Network ===

Display network information {{UserCmd|command=nmcli}}
List wireless access points {{UserCmd|command=nmcli c}}
Enable firewall [package Community: ufw] {{UserCmd|command=ufw enable}}
Allow/deny all incoming traffic {{UserCmd|command=ufw default [allow/deny]}}
Displays firewall status and rules {{UserCmd|command=ufw status}}
Allows/deny incoming traffic on the specified port {{UserCmd|command=ufw [allow/deny] [port]}}
Allows/deny incoming traffic from specified IP address {{UserCmd|command=ufw [allow/deny] from [ip]}}

=== System and Screen ===

Display kernel version {{UserCmd|command=uname -r}}
Display long kernel version {{UserCmd|command=uname -a}}
Report file system disk space usage {{UserCmd|command=df [/] [/home]}} {{UserCmd|command=sudo btrfs filesystem usage -h [/]}}
Display system tasks {{UserCmd|command=top}} {{UserCmd|command=htop}}
Display system information {{UserCmd|command=inxi --filter --verbosity=8}}
Display system information (from chroot){{UserCmd|command=inxi --filter --verbosity=8 --color}}
Display a tree of processes {{UserCmd|command=pstree}}

Switch to tty
* {{key press|Ctrl|Alt|F1}}
* {{key press|Ctrl|Alt|F2}}
* {{key press|Ctrl|Alt|F3}}
* {{key press|Ctrl|Alt|F4}}
* {{key press|Ctrl|Alt|F5}}
* {{key press|Ctrl|Alt|F6}}

Switch to the X session
* {{key press|Ctrl|Alt|F7}}

Start a unit {{UserCmd|command=systemctl start unit}}
Stop a unit {{UserCmd|command=systemctl stop unit}}
Check status of a unit {{UserCmd|command=systemctl status unit}}
Enable a unit {{UserCmd|command=systemctl enable unit}}
Disable a unit {{UserCmd|command=systemctl disable unit}}
Restart a unit {{UserCmd|command=systemctl restart unit}}
Shut down the system {{UserCmd|command=poweroff}}
Restart the system {{UserCmd|command=reboot}}





=See Also=

[https://forum.manjaro.org/t/manjaro-cli-cheat-sheet/101305 Original forum post]

[[Category:Boilerplate{{#translation:}}]]

CheatSheet

2025-09-03T15:49:28Z

Andreas85: inxi angepasst und btrfs disk free

<languages/>
<translate>

= Commands CheatSheet for Manjaro = 



__TOC__

=== Locating and Installing Packages === 
==== Using Pamac CLI ====
Install packages {{UserCmd|command=pamac install [PackageName]}}
Uninstall packages {{UserCmd|command=pamac remove [PackageName]}}
Search for a package {{UserCmd|command=pamac search [PackageName]}}
Update installed packages {{UserCmd|command=pamac upgrade}}
Check for updates {{UserCmd|command=pamac checkupdates}}

==== Using native pacman ==== 
Install packages {{UserCmd|command=sudo pacman -Syu [PackageName]}}
Uninstall packages {{UserCmd|command=sudo pacman -Rns [PackageName]}}
Search for a package {{UserCmd|command=pacman -Ss [PackageName]}}
Update installed packages {{UserCmd|command=sudo pacman -Syu}}
Check for updates {{UserCmd|command=sudo pacman -Syu}}

=== Maintenance === 


Generates a random mirrorlist for the users and sort them by their current access time. {{UserCmd|command=sudo pacman-mirrors --fasttrack}}
Generate cache list {{UserCmd|command=du -sh ~/.cache/*}}
Purge files not accessed in 100 days {{UserCmd|command=find ~/.cache/ -type f -atime +100 -delete}}
Report journal current size {{UserCmd|command=journalctl --disk-usage}}
Remove but recent entries by size or time {{UserCmd|command=journalctl --vacuum-size=50M}} {{UserCmd|command=journalctl --vacuum-time=2weeks}}
Check for orphaned packages {{UserCmd|command=pamac list -o }}
Remove all orphans {{UserCmd|command=pamac remove -o }}
Remove all packages except the latest 3 versions {{UserCmd|command=pamac clean --keep 3}}

=== AUR === 


Search for package {{UserCmd|command=pamac search -a [PackageName]}}
Build the package {{UserCmd|command=pamac build [PackageName]}}

=== Access rights === 


Execute command as root {{UserCmd|command=sudo [command]}}
Empty password cache {{UserCmd|command=sudo -k}}
Change user password {{UserCmd|command=passwd username}}
Change owner and group of file {{UserCmd|command=chown [owner]:[group] -c [file]}}
Change file permissions {{UserCmd|command=chmod [permissions] -c [file]}}
Set permissions in octal mode: 4(read) 2(write) 1(execute)


Example: 755 read-write-execute for owner and read-execute for group and others


Display files and permissions [of directory]{{UserCmd|command=ls -lh [dir]}}

=== Files and Directories === 


Change the working directory {{UserCmd|command=cd [dir]}}
Change to parent directory {{UserCmd|command=cd ..}}
List directory contents {{UserCmd|command=ls -l}}
List also hidden files {{UserCmd|command=ls -la}}
Copy file {{UserCmd|command=cp [file] [target]}}
Copy directory '''recursively''' {{UserCmd|command=cp -r [directory] [target]}}
Move or rename file/directory {{UserCmd|command=mv [source] [target]}}
Remove directory '''recursively''' {{UserCmd|command=rm -r [dir]}}
Create symbolic link {{UserCmd|command=ln -s [target] [link]}}
Mount filesystem {{UserCmd|command=mount -t [type] [/dev/sdx9] [mountpoint]}}
Mount ISO image {{UserCmd|command=mount -o loop [iso] [mountpoint]}}
Home directory of user {{UserCmd|command=cd /home/$USER}} {{UserCmd|command=cd ~}}
Directory with global configurations {{UserCmd|command=cd /etc}}

=== Network === 


Display network information {{UserCmd|command=nmcli}}
List wireless access points {{UserCmd|command=nmcli c}}
Enable firewall [package Community: ufw] {{UserCmd|command=ufw enable}}
Allow/deny all incoming traffic {{UserCmd|command=ufw default [allow/deny]}}
Displays firewall status and rules {{UserCmd|command=ufw status}}
Allows/deny incoming traffic on the specified port {{UserCmd|command=ufw [allow/deny] [port]}}
Allows/deny incoming traffic from specified IP address {{UserCmd|command=ufw [allow/deny] from [ip]}}

=== System and Screen === 


Display kernel version {{UserCmd|command=uname -r}}
Display long kernel version {{UserCmd|command=uname -a}}

Report file system free space (non btrfs) {{UserCmd|command=df [/] [/home]}}
Report file system free space (btrfs) {{UserCmd|command=sudo btrfs filesystem usage -h [/]}}
Display system tasks {{UserCmd|command=top}} {{UserCmd|command=htop}}
Display system information {{UserCmd|command=sudo inxi --verbosity=8 --filter}}
Display system information (from chroot) {{UserCmd|command=inxi --verbosity=8 --filter --color}}
Display a tree of processes {{UserCmd|command=pstree}}


Switch to tty
* {{key press|Ctrl|Alt|F1}}
* {{key press|Ctrl|Alt|F2}}
* {{key press|Ctrl|Alt|F3}}
* {{key press|Ctrl|Alt|F4}}
* {{key press|Ctrl|Alt|F5}}
* {{key press|Ctrl|Alt|F6}}


Switch to the X session
* {{key press|Ctrl|Alt|F7}}


Start a unit {{UserCmd|command=systemctl start unit}}
Stop a unit {{UserCmd|command=systemctl stop unit}}
Check status of a unit {{UserCmd|command=systemctl status unit}}
Enable a unit {{UserCmd|command=systemctl enable unit}}
Disable a unit {{UserCmd|command=systemctl disable unit}}
Restart a unit {{UserCmd|command=systemctl restart unit}}
Shut down the system {{UserCmd|command=poweroff}}
Restart the system {{UserCmd|command=reboot}}







=See Also= 


[https://forum.manjaro.org/t/manjaro-cli-cheat-sheet/101305 Original forum post]
</translate>

[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T14:27:32Z

Andreas85: How to balance metadata

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need (starting with the oldest one!)
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 95%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:

=== Metadata ===
It is rarely recommended to include blocks with metadata in a balance. It is advantageous, in exceptional cases, if the following conditions are currently met:
You can check with:
{{RootCmd|command=sudo btrfs fi us /|grep 'Meta.*Size'}}
{{ic|Metadata,RAID1: Size:9.00GiB, Used:6.58GiB (73.09%)}}
* Several GB of metadata are present in your filesystem (''6.6 GB present, 9 GB used'')
* This metadata is poorly distributed (''73%'')
* Significantly more than one full GB could become free (9 GB - 6.6 GB ==> ''2.4 GB could become free'')
The command is then:
{{RootCmd|command=btrfs balance start -musage=95 /}}
Btrfs had to move 9 GB of metadata to free up 1 GB !
{{ic|Metadata,RAID1: Size:8.00GiB, Used:6.58GiB (82.20%)}}


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now''' (starting with the oldest one)
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full (plus 5 GB free space)


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90-95 %) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T13:38:29Z

Andreas85: /* Get out of jail */ beginn with oldest snapshot

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need (starting with the oldest one!)
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 95%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now''' (starting with the oldest one)
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full (plus 5 GB free space)


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90-95 %) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T13:35:14Z

Andreas85: delete oldest snapshot first

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need (starting with the oldest one!)
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 95%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full (plus 5 GB free space)


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90-95 %) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:55:35Z

Andreas85: 90 -> 95 %

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 95%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full (plus 5 GB free space)


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90-95 %) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:54:30Z

Andreas85: /* Get out of jail */ 95% plus 5 GB

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full (plus 5 GB free space)


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90-95 %) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:50:06Z

Andreas85: Grenze neu definiert 95% +5 GB

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't skimp on storage space when creating a Btrfs volume. A Btrfs volume should normally be less than 90% full. Then it's recommended to adjust the volume. In an emergency, 95% (plus at least 5 GB free) is fine. However, this isn't beneficial for neither the Btrfs volume nor an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}

=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:43:26Z

Andreas85: set limit to 85%

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 85% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:40:46Z

Andreas85: change limit to 95% + 5GB

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to delete snapshots before you run out of space|Each time you create a snapshot, you only use the '''rest of the volume''' to save all changes. Eventually, you'll need to free the snapshot. Don't overuse the space. Btrfs needs '''breathing room.''' Don't use more than '''95%''' and leave at least '''5 GB free''', or you'll be in big trouble.}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-07-13T05:33:33Z

Andreas85: Increased limits to 90%, 5 GB, 10 GB

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don't forget to delete snapshots, or you'll soon run into '''[[Btrfs#Out_of_space|out of space]] problems'''. Btrfs needs free space (at least 5 GB) to do its work. If your volume is more than 90% full, you'll need to figure out what to do (quickly). Even a Manjaro update can be more than 10 GB in size, so you'll always need some free space.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.


With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-06-17T16:24:38Z

Andreas85: scrub

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog.

With btrfs scrub, you can force btrfs to repair all corrupted blocks. This can take a long time because all blocks containing data must be read to verify the checksums.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-06-17T16:17:18Z

Andreas85: or

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one or more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This repair can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2025-04-27T14:40:31Z

Andreas85: how to delet them

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.

It's best to delete snapshots using the tool that created them.
* If you used Snapper to create them, delete them using Snapper.
* If you used Timeshift to create them, delete them using Timeshift.
* If you created them manually, delete them manually.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This repair can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs Maintenance

2025-04-26T18:03:54Z

Andreas85: -musage is not recommended because it rotates metadata

__TOC__


= Btrfs Maintenance =

== Btrfs needs no maintenance ==

This can even be true when:
* You always keep 10% of your volume '''unallocated'''
{{BoxWarning|free or unallocated|I'm not saying "free" because with btrfs, free means nothing. The value you need to pay most attention to is '''unallocated''' ! }}

==== Every filesystem needs some maintenance ====

Some filesystems do an automatic chkfs at every XX. mount.
Others need the user to do a chkfs manually. On most you have to watch not to fill them to 100%. Others reserve 5% for root.
Some filesystems need to be defragmented. Others do not.

'''Every filesystem has its own needs and tools !'''

== Automatic maintenance ==
Btrfs does some maintenance automatically.

=== Is the Volume in a clean state ===
At mount btrfs tests wehter the volume is in a clean state.

==== power down ====
Most file systems are not prepared for a sudden loss of power. If the computer suddenly loses power, transactions may not be written or only partially written to the volume. File systems that use journaling can often recover after a power failure.

Btrfs attempts to clean the volume by removing the last (uncompleted) action. This can result in losing the last changes you made before turning off. But you get a clean file system that doesn't need to be repaired.

==== error ====
If btrfs encounters an unrecoverable error, such as a checksum mismatch, the filesystem will be mounted '''read-only'''. (When using RAID2, such errors are auto-repaired)

==== clean ====
btrfs will mount the subvolume read-write.

== Manual Maintenance ==
From time to time it may be advisable to check the health of a btrfs volume.
{{BoxInfo|Note| Btrfs is used to perform all maintenance on '''a normally running system'''. The volume can be fully used. Shutting down during such an action is also unproblematic. Btrfs will keep running the action after the next launch until it completes.}}

=== Usage ===
Check if the '''unallocated''' space on your volume is ok.

==== check unallocated space ====

{{RootCmd|command=btrfs filesystem usage -h /}}

{{BoxWarning|Pay special attention to '''unallocated''' !|The commonly used term "free" is meaningless to btrfs users. Even if you have 50% of your volume "free", you can run out of storage space. }}

Try to leave '''at least 10%''' of your volume unallocated. If this got below 10%:
* Expand the volume to double size (see: [[Btrfs]])
* Delete some unused data
* Delete some old snapshots
* Balance ([[Btrfs]])

==== Clean up unused snapshots ====
From time to time it is necessary to check if you have snapshots that you no longer need but that are taking up valuable space on your volume.

=== Balance your free disk space ===
If you have some "free" space on your volume, but the unallocated space is below 10% (or close to 10%), you can help btrfs to rebalance some parts.

{{RootCmd|command=btrfs balance start -dusage=50 /}}
Btrfs looks for chunks that contain more than 50% free space. It will take 2 of them and then move everything into a new chunk. After that, a chunk is released. This continues until each chunk is at least 50% full.

This will give you some unallocated (free) chunks that help btrfs **not** to get out of space.

If you have less than 20% unallocated space, please do the following:
{{RootCmd|command=btrfs balance start -dusage=75 /}}
Btrfs looks for chunks that are less than 75% full.
It will take 4 of them and then move everything into 3 new chunks. After that, a chunk can be released. This continues until each chunk is at least 75% full.

If you still have less than 20% unallocated space, please do the following:
{{RootCmd|command=btrfs balance start -dusage=90 /}}

=== scrub ===
Check if everything is ok with the checksums and the readability of your data. '''Only do this when in doubt'''. This may take a long time as btrfs has to read ALL the data. Btrfs only scans the portion of your volume that actually contains data.

{{RootCmd|command=btrfs scrub start -Bd /}}

{{BoxSuccess|Want to watch how btrfs works ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a separate terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}

== special cases ==
There seem to be some cases where additional maintenance is needed.
==== SSD ====
Btrfs is optimal for SSDs due to its CoW nature

===== Read rate degradation (unconfirmed) =====
This isn't a problem with SSDs in general, it just seems to happen in a few rare cases. Updating the firmware should then solve the problem.
One way to test the read speed with btrfs is to read out all the data (scrub). If your SSD seems to have this RRD issue, '''balancing''' will help so that all data is written to a new location. This can be done while the system is running! But please only '''once''' a year!

{{RootCmd|command=btrfs balance start --full-balance /}}
This will take a long time. You can shut down your PC at any time. Do not be surprised. The "balance" will restart after booting until done!

If you want your data to rotate:

{{RootCmd|command=btrfs balance start -dlimit=10 /}}
This rewrites 10 chunks at a time. This can be used weekly if you find it necessary.

==== Rotating disks ====
On spinning disks, fragmentation can become an issue in some rare use cases. Then you can defragment your Btrfs volume.

===== Defragmentation (not recommended) =====
This is NOT the same as defragmentation in older Windows file systems. Btrfs does NOT require defragmentation as normal maintenance. Only do this if you can measure a huge read performance loss because a specific file/database is fragmented!
{{BoxDanger|Defragment only these specific files|Defragmenting an entire Btrfs volume does not increase its speed, it just wears out the device}}

=See Also=
[[Btrfs]] Learn basics about btrfs


[[Category:Boilerplate{{#translation:}}]]

Set all Qt app's to use GTK+ font & theme settings

2025-02-09T16:32:19Z

Andreas85: https://forum.manjaro.org/t/layout-of-qt5-programs-are-broken-after-stable-update-2025-02-04/173985/3

<languages/>
__TOC__

{{SectionTemplate|<translate> Overview</translate>|
<translate>

When using a [[Desktop_Environments|Desktop Environment]] or Window Manager that doesn't allow for the settings of QT themes, you can set QT to use your GTK themes instead.
</translate>}}

{{SectionTemplate|
<translate>

Using qt5ct
</translate>
|2=
<translate>

{{BoxInfo|note|In some Manjaro editions, this is already done for you by default}}


Install {{ic|qt5ct}} using your favorite package manager or the command:
{{UserCmd|command=pamac install qt5ct}}


Set environment variables in {{ic|~/.profile}} by adding or updating the following lines:
{{File|file=~/.profile|content=<pre>export QT_QPA_PLATFORMTHEME="qt5ct"</pre>}}

Add the following line to {{ic|~/.bash_profile}} if it does not already exist:
{{File|file=~/.bash_profile|content=<pre>[[ -f ~/.profile ]] && . ~/.profile</pre>}}

Reboot the computer (or logout and re-login)


Run the application '''QT5 Configuration Manager''' from the menu or run the command {{ic|qt5ct}}.


Logout and login again to make the change effective
</translate>}}

{{SectionTemplate|
<translate> [[File:Chmsee-icon.png|left|36px]]</translate>
<translate> See Also</translate>|
<translate>

* [https://wiki.archlinux.org/index.php/Uniform_Look_for_Qt_and_GTK_Applications Arch Wiki]
</translate>
}}

[[Category:Contents Page{{#translation:}}]]

Btrfs

2024-12-30T16:07:21Z

Andreas85: BoxWarning

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This repair can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a (unformatted) partition''' (for example a fast extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
{{BoxDanger|Do NOT remove this USB-Stick|From now on this partition belongs to your volume! '''Do not boot without it'''. If possible do not reboot at all in this stage! This USB-stick has to stay until '''btrfs device remove''' has '''completed'''.}}
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess||After that inside a terminal: {{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* If neccesary '''balance''' your volume with a filter(90%) This '''will''' take some more time !{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* After "btrfs remove" has finished successfully, you can remove the USB stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:38:44Z

Andreas85: Bulletproof

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using RAID 1 btrfs mirrors '''data and metadata'''. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This repair can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.
{{BoxInfo|Bulletproof your system|If you have enough storage space and it is spread across 2 devices, it is really advisable to use btrfs RAID1/10. This will cover a whole range of risks that would be impossible to manage without RAID. At the same time, RAID in BTRFS is as straightforward as it gets.
}}

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:24:51Z

Andreas85: deep

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to '''replace''' the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get deep into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:21:58Z

Andreas85: link zu out of space und add

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''[[Btrfs#Out_of_space|out of space]]-trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 85% full you have to think(fast) what to do.
* ++++ '''[[Btrfs#Extend_a_volume|Add]]''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (This does only help if they are not part of '''any''' snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:16:18Z

Andreas85: link zu out of space

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run [[Btrfs#Out_of_space|out of space]]''' soon.

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:10:37Z

Andreas85: ls -lA

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -lA /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:07:56Z

Andreas85: BoxInfo

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


{{BoxInfo|In order to make a rollback possible|The snapshot has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)
}}

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T15:04:17Z

Andreas85: backup of snapshot

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, (or to restore one of the external backups of a snapshot) '''without changing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-6.xx-x86_64.img)
* '''kernel''' (/boot/vmlinuz-6.xx-x86_64)
* '''kernel-modules''' (/usr/lib/modules/6.xx.xx-x-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-30T14:54:44Z

Andreas85: btrfs sen linked

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make a full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use '''one''' volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work. It is also possible to send a ro-snapshot to another btrfs volume as '''[[Btrfs#Send_.2B_receive_.3D_backup_.E2.87.92|backup]]'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0


{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}


Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

File Systems

2024-12-30T14:38:43Z

Andreas85: Btrfs out of space

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 is the default filesystem in Manjaro at the moment. It is the evolution of the most used Linux filesystems (Ext3, Ext2) and promises improved design, better performance, reliability, and features over its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because [[Btrfs]] is different, some things seem unfamiliar and strange. Then the page [[Btrfs]] is a good starting point to search for answers.


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

{{BoxWarning|Maintenance|When using snapshots, you must be particularly careful not to use up all the space on the file system -> [[Btrfs#Out_of_space]]}}

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.

{{BoxWarning|As of kernel 6.13|reiserFS will no longer be supported.}}


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

File Systems

2024-12-30T14:26:53Z

Andreas85: kernel 6.14

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 is the default filesystem in Manjaro at the moment. It is the evolution of the most used Linux filesystems (Ext3, Ext2) and promises improved design, better performance, reliability, and features over its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because [[Btrfs]] is different, some things seem unfamiliar and strange. Then [[Btrfs]] is a good starting point to search for answers.


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.

{{BoxWarning|As of kernel 6.13|reiserFS will no longer be supported.}}


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

File Systems

2024-12-30T06:05:40Z

Andreas85: readonly if damaged

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 is the default filesystem in Manjaro at the moment. It is the evolution of the most used Linux filesystems (Ext3, Ext2) and promises improved design, better performance, reliability, and features over its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because [[Btrfs]] is different, some things seem unfamiliar and strange. Then [[Btrfs]] is a good starting point to search for answers.


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side. The same thing may happen, when NTFS becomes damaged.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

File Systems

2024-12-30T06:02:05Z

Andreas85: Repair NTFS only in windows

<languages/>

__TOC__
<translate>

This page provides information on some of the filesystems commonly used in Manjaro. It also shows where and how they are used. Further information on these and other filesystems can be found in the ARCH Wiki.


A filesystem manages the space on a storage medium (hard disk, SSD ...). It makes this memory available to the operating system so that files can be saved and read again. Each of the following filesystems has advantages and disadvantages. They are mostly developed for a special purpose and are therefore used in a certain environment.

== Linux == 


filesystems that are mostly used under Linux.


Note that many filesystem drivers are already included in the Linux kernel. You may not need anything else to mount, read, or write these filesystems. But there are packages with additional tools. You may need them to format, check, repair, modify, or optimize such filesystems. So if you regularly use a filesystem, it is a good idea to install the appropriate tools.

=== Ext2 → Ext3 → Ext4 === 


Ext4 is the default filesystem in Manjaro at the moment. It is the evolution of the most used Linux filesystems (Ext3, Ext2) and promises improved design, better performance, reliability, and features over its predecessors.


If you are using Ext2 or Ext3, you can convert the partition to Ext4. Ext4 uses journaling, checksums and write barriers and is therefore more robust against damage.


Currently Ext4 is fully supported in Win10 and OsX. Support for ext4 has been built in since WSL is included in Win10 (2016).


see [https://ext4.wiki.kernel.org/ Ext4@kernel.org], [https://wiki.archlinux.org/title/Ext4 Ext4@ARCH-wiki], [https://de.wikipedia.org/wiki/Ext4 Ext4@wikipedia]
<br>For advanced optimizations see [https://wiki.archlinux.org/index.php/Ext4#Improving_performance Improving Ext4 performance@Archwiki].

====Install==== 


In Manjaro, e2fsprogs is already installed

===[[Btrfs]]=== 


A modern '''C'''opy '''o'''n '''W'''rite filesystem for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. [[Btrfs]] not only is a filesystem, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because [[Btrfs]] is different, some things seem unfamiliar and strange. Then [[Btrfs]] is a good starting point to search for answers.


Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
* '''Snapshots''' which do not make a full copy of files
* '''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
* '''Self-healing''' - checksums for data and metadata, automatic detection of silent data corruptions


see [[Btrfs]], [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs@kernel.org], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARCH-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia]

====Install==== 


<tvar|usercmd0>{{UserCmd|command=pamac install btrfs-progs}}</>

=== ReiserFS → reiser4 === 


ReiserFS was the first journaling filesystem to be included in the standard kernel. It was actively used by some distros some time ago, but is not currently widely used. Reiser4 is the successor to ReiserFS(3). However, Reiser4 seems not to be integrated in the kernel yet.


see [https://wiki.archlinux.org/title/Reiser4 Reiser4@ARCH-wiki], [https://en.wikipedia.org/wiki/ReiserFS ReiserFS@wikipedia], [https://en.wikipedia.org/wiki/Reiser4 Reiser4@wikipedia], [https://reiser4.wiki.kernel.org/ Reiser4@kernel.org]

====Install==== 


<tvar|usercmd2>{{UserCmd|command=pamac install reiserfsprogs reiser4progs}}</>

== Windows == 


filesystems mostly used in windows

=== NTFS === 


It is the most widely used filesystem on windows these days. It does exist in different versions, but unlike FAT32, all of them offer the following points:
* Large files> 4GB
* Long file names with UTF16 up to 255 characters
* Rights management, ACL
* Journaling of metadata
* Compression, encryption, ...


Currently there are some restrictions when using NTFS with Linux. If windows is suddenly switched off or goes into hibernating, the NTFS filesystem is left in a "dirty-state". When Windows starts again, NTFS is the first to be cleaned. This operation is currently not supported by the Linux driver. Then Linux shows the NTFS filesystem as read-only to be on the safe side.


see [https://wiki.archlinux.org/title/NTFS NTFS@ARCH-wiki], [https://en.wikipedia.org/wiki/NTFS NTFS@wikipedia]


{{BoxWarning|If you regularly switch between Windows and Linux|You should switch off "hibernation", "Hybrid Boot", "Fast Boot" in Windows. Then Linux has always full (read / write) access to NTFS drives.
* [https://forum.manjaro.org/t/all-of-my-files-are-in-read-only-mode/83777/7 all-of-my-files-are-in-read-only-mode@forum]
}}

{{BoxDanger|If your NTFS file system becomes corrupted|It is strongly recommended that you only repair the file system using the original Windows tools. Anything else is highly risky.
}}

====Install==== 


<tvar|usercmd3>{{UserCmd|command=pamac install ntfs-3g}}</>

== DOS == 


filesystems under DOS and early windows on a lot of floppydisks and USB-sticks

=== FAT16 → FAT32 (+VFAT) === 


This is a traditional filesystem under DOS and early Windows versions. Even today it can be found on many floppy disks, USB sticks and hard drives. It is supported by all types of operating systems and is therefore often used to exchange files, to pass them on, or to keep them accessible to both operating systems in the case of dualboot.


Even with FAT32, this comes not without its disadvantages.
* no support for user rights or xattr
* severely restricted file names (8.3 or LFN for VFAT, no distinction between lowercase and uppercase)
* no files over 2GB (FAT16) 4GB (FAT32)
* no journaling
* not robust


{{warning | FAT Filesystems do not use journaling. Data on such filesystems is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://wiki.archlinux.org/title/FAT FAT@ARCH-wiki], [https://en.wikipedia.org/wiki/File_Allocation_Table FAT@wikipedia]

====Install==== 


<tvar|usercmd4>{{UserCmd|command=pamac install dosfstools}}</>

=== exFAT === 


Microsoft developed the exFAT (Extended File Allocation Table) in 2006 and optimized it for flash memories such as USB sticks and SD cards. It can store large files and large numbers of files, and it can manage very large partitions. It is supported by Linux, Windows, macOS and many other devices and is one of the most compatible filesystems. ExFAT is included in Linux 5.4 and higher.


* Flash friendly
* No support for user rights or xattr
* Files over 4 GB
* Checksums for metadata
* No journal
* Not robust


{{warning | exFAT FS does not use journaling. Data on such a filesystem is vulnerable to irreparable corruption due to ''improper ejection or power outage''.}}


see [https://en.wikipedia.org/wiki/ExFAT ExFAT@wikipedia]

====Install==== 


<tvar|usercmd5>{{UserCmd|command=pamac install exfatprogs}}</>

== macOS == 


Filesystems mostly used in macOS

=== HFS → HFS+ === 


see [https://en.wikipedia.org/wiki/HFS_Plus HFSPlus@wikipedia]

====Install from AUR==== 


<tvar|usercmd6>{{UserCmd|command=pamac install hfsprogs}}</>

== Others == 

=== XFS === 


see [https://wiki.archlinux.org/title/XFS XFS@ARCH-wiki]

===ZFS=== 


see [https://wiki.archlinux.org/title/ZFS ZFS@ARCH-wiki]

==Comparisions== 
</translate>
{| class="wikitable sortable"
|+<translate> Possible usage of Filesystems</translate>
|-
!Filesystem!!Manjaro!!Win10!!OSX!!Win9x, DOS
|-
|ext2||●||▷ ExtFS||●||
|-
|ext3/4||●||▷ ExtFS||?||
|-
|btrfs||● btrfs-progs||▷ ExtFS, WinBtrfs||-||-
|-
|reiser3||● reiser4progs||▷ RFSTool||?||-
|-
|reiser4||○ reiserfs||?||?||-
|-
|NTFS||○ ntfs-3g<br>▶ 5.15?? ntfs3||●||?||
|-
|FAT32||● dosfstools||●||●||●
|-
|exFAT||▶ 5.4 exfatprogs||●||?||?
|-
|HFS||○ hfsprogs (AUR)||?||●||
|-
|XFS||?||▷ ExtFS||?||
|-
|ZFS||?||?||?||
|}
<translate>


● = fully supported, additional tools to install
▶ = included since kernel x.x.x
○ = partially supported
▷ = possible via external tools
? = feel free to extend ;-)


{| class="wikitable sortable"
|+ Some important properties
|-
! Properties !!ext2!!ext3!!ext4!!btrfs||reiserfs(3)||XFS
|-
|journaling ||-||● ordered||● ordered||● full||▶ 2.6||●
|-
|barriers ||-||||●||●
|-
|checksum ||-||-||◎ metadata||● full||●
|-
|kompression||-||-||-||●,<br><small>zstd ▶ 4.14/5.1</small>||
|-
|encryption||-||-||▶ 4.13||-
|-
|snapshots||-||-||-||●||-
|-
|TRIM possible||-||-||▶ 2.6.33||▶ 4.3
|-
|xattr, ACL||◎||?||ACL||ACL||ACL
|-
|small repair||● fsck||● fsck||● fsck||● auto||reiserfsck
|-
|journal repair||● fsck||● fsck||● fsck||● auto 3.2||
|-
|repair after power loss||-||?||● tune2fs, fsck||● auto, scrub||
|-
|since||1993||2001||2008||2009||2001
|}

=See also= 


[https://en.wikipedia.org/wiki/ExFAT Wikipedia:exFAT]<br />
[https://en.wikipedia.org/wiki/Comparison_of_file_systems Wikipedia:Comparison of filesystems]<br />
[https://wiki.archlinux.org/index.php/Filesystems Archwiki:filesystems]<br />
</translate>
[[Category:Contents Page{{#translation:}}]]
[[Category:filesystems{{#translation:}}]]

Btrfs

2024-12-06T16:52:12Z

Andreas85: Vorschlag compress volume

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)
* [[Btrfs#Compression_.E2.87.92|use compression]] on this volume

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0

{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}

Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-06T16:48:53Z

Andreas85: Tabelle mit vorschlägen eingefügt

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
You can turn on compression at any time by changing the mount options in the fstab. After the next reboot, all newly written data from then on will be automatically compressed. Compression factors of 2:1 on average are not uncommon.
[[Btrfs#Mount_options|@see mount-options]]
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / btrfs rw,noatime,compress=zstd,subvol=@ 0 0

{| class="wikitable"
|+ Which compression suits me best?
|-
! CPU !! rotating disk !! SSD
|-
| slow || zstd:1 ... 4 || zstd:1 ... 3
|-
| medium || zstd:4 ... 7 || zstd:3 ... 5
|-
| fast || zstd:7 ... 10 || zstd:5 ... 10
|}

Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-06T16:09:16Z

Andreas85: Vorschlag kompression einschalten

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* ++ [[Btrfs#Compression_.E2.87.92|Compress]] your volume
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-12-06T16:01:23Z

Andreas85: 80% -> 90 %

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then '''90%''' or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-08-04T11:48:16Z

Andreas85: remove musage

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then 80% or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]

Btrfs

2024-08-04T11:46:42Z

Andreas85: musage removed

<languages/>
__TOC__
<translate>
=Btrfs is a modern CoW [[File_Systems|file system]]= 
A modern '''C'''opy '''o'''n '''W'''rite file system for Linux aimed at implementing advanced features while also focusing on '''fault tolerance''', '''repair''' and '''easy administration'''. Btrfs not only is a file system, but also is partly a volume manager, software-raid, backup-tool, and it is flash-friendly.


Because Btrfs is different, some things seem unfamiliar and strange. If you want to learn the details and the newest stuff, then [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs.wiki.kernel.org] is the place to go or [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io].
Development of Btrfs started in 2007. Since that time, Btrfs is a part of the Linux kernel and is under active development. The Btrfs code base and filesystem-layout is '''[https://btrfs.wiki.kernel.org/index.php/Status stable] .''' However, new features are still under development. Its main features and benefits are:
*'''Snapshots''' which do not make the full copy of files
*'''Volume Manager''' join partitions, split into subvolumes
*'''RAID''' - support for software-based RAID 0, RAID 1, RAID 10
*'''Auto-repair''' - checksums for data and metadata, automatic detection of silent data corruption


(see [https://btrfs.wiki.kernel.org/index.php/Main_Page btrfs@kernel.org],
[https://btrfs.readthedocs.io/en/latest/ btrfs.readthedocs.io], [https://wiki.archlinux.org/title/Btrfs Btrfs@ARC-wiki], [https://de.wikipedia.org/wiki/Btrfs Btrfs@wikipedia])


__TOC__

=== Familiar with btrfs-slang ? === 
Because Btrfs is different, you will find some words that do have a special meaning when used for btrfs. This may be a source of confusion.


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume'''</div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' is a pool of raw storage and consists of one or more '''device'''s. The size of the volume will be the addition of all devices that are part of this volume. In most cases you will only use one volume. You are able to add/remove devices at any time. ''Usually you do '''not''' mount a Btrfs volume.''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''chunk'''</div><div class="mw-collapsible-content">A '''chunk''' is simply a piece of storage that Btrfs can use to put data on. Think of a chunk (usually 1GiB) as of a page in a book. The book is the '''[[Btrfs#Btrfs_Volume|volume]]''', and the chunk is one page of it. When you start, all pages are empty. When you write data to the volume, one page (="chunk") after the other is written to.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''device'''</div><div class="mw-collapsible-content">A '''device''' is some linux device. It may be '''a partition''' like '''/dev/sdz1''' or /dev/sdz2. Or it may be a raw disk device like /dev/sdz without any partitioning. A Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' consists of '''at least one device'''.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''subvolume'''</div><div class="mw-collapsible-content">A Btrfs '''[[Btrfs#subvolume|subvolume]]''' is an independently mountable POSIX file-tree and '''not a block device'''. It is the part of a '''[[Btrfs#Btrfs_Volume|volume]]''' that will be '''mounted writeable''' into your Linux system. By convention the names of subvolumes start with @ ('''@''', '''@home''', '''@snapshots''' ...). All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes ''as sort of "dynamic partitions" inside a Btrfs volume'')
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''default subvolume''' </div><div class="mw-collapsible-content">The default subvolume of a Btrfs '''[[Btrfs#Btrfs_Volume|volume]]''' is special. When you mount, you normally have to name a '''[[Btrfs#subvolume|subvolume]]''' to mount. When you don't name a subvolume, the default subvolume will be used. The default subvolume can be changed to any subvolume. It is advisable to set that subvolume as default, that is used for mounting linux '''"/"''' this is often the subvolume with the name '''"@"'''
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Btrfs '''volume-root''' "/", Btrfs '''layout''' </div><div class="mw-collapsible-content">A '''[[Btrfs#Btrfs_Volume|volume]]''' contains one ore more '''[[Btrfs#subvolume|subvolumes]]'''. But they are not stored in form of a simple list. These subvolumes are stored in a tree-like structure like in a filesystem. Sometimes called the "top-level subvolume" or "root of the volume". But be careful this is '''not linux-root "/"''', but Btrfs '''volume-root "/"'''. There are several basic schemas to '''layout''' subvolumes in a volume
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''snapshot'''</div><div class="mw-collapsible-content">A '''[[Btrfs#snapshot|snapshot]]''' looks nearly the same as a '''[[Btrfs#subvolume|subvolumes]]'''. But don´t get confused. When we talk about snapshots we usually mean a "'''Read-Only (ro) photograph''' of a subvolume". While the subvolume changes with time. A snapshot stays in the state of the subvolume at the time we made it. You can mount snapshots into your linux system, but you only can read the content. And the content will never change while this snapshot exists. When creating '''snapshots''' you have to watch out for the Btrfs-'''layout''' in use.
It is possible to make a writeable(rw) subvolume out of a ro-snapshot. This is the way '''[[Btrfs#Rollback_to_a_snapshot|roll back]]''' does work.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ Self-healing</div><div class="mw-collapsible-content">'''This is no magic.''' Because of the nature of Btrfs as '''[[Btrfs#What.27s_this_.22Copy_on_Write.22|CopyOnWrite]]''' filesystem and because of the checksums, it is possible to check the filesystem and repair some errors. This does happen silently.


* [[Btrfs#RAID_0_.28not_Just_a_Bunch_of_Disks.29|Without RAID]] it is possible to correct some small faults that happen because of power outage. (This is done when the filesystem is mounted again)
* [[Btrfs#RAID_1_.28mirrored.29.2C_1C3.2C_1C4|With RAID1]] it is possible to repair some parts of files that where damaged by faults on one device. (This is done when the file is read the next time)
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''scrub'''</div><div class="mw-collapsible-content">A '''[[Btrfs#scrub|scrub]]''' is like an inspection of your car. The mechanic will look at all parts, and will tell you if something is amiss. If he finds very small problems, he will repair this automatically without asking for permission, and with minimal extra cost.
</div></div>


<div class="mw-collapsible mw-collapsed"><div class="mw-collapsible-toggle" style="float:none;">▶ '''balance'''</div><div class="mw-collapsible-content">A '''[[Btrfs#balance|balance]]''' is like renovating your home. Sometimes it is necessary to renovate a room, sometimes you will renovate your home completely. But you don't do it once in every week ;-) With balance, the furniture will be transported around and rearranged. '''You need to do this when changing RAID-levels.'''
</div></div>


You may also have a look at [https://btrfs.readthedocs.io/en/latest/Glossary.html Btrfs Glossary]

= Volume management [https://btrfs.readthedocs.io/en/latest/Volume-management.html ⇒] = 
A volume is a pool of raw storage. Consists of one or more devices. The size of the volume will be the addition of all included devices, unless you use RAID.


If you do use more then one device, please also read the section about RAID. You are able to add/remove devices at any time to increase/decrease the size of the volume. With adding/removing devices it is also possible to move a volume from one device to another (without changing the UUID).


Usually you do not mount the Btrfs volume itself, but you mount subvolumes. There may be times when it is practical to mount the Btrfs volume-root itself. Then you are able to change the volume layout. All (writeable) subvolumes inside a volume are movable inside the volume with mv. Moving subvolumes will not touch the data, but change the volume layout in an instant.


When not otherwise specified, additional devices are handled as '''J'''ust a '''B'''unch '''o'''f '''D'''isks (JBOD)
{{BoxInfo|Tip|In most cases it is advisable to use '''only one volume'''}}

=== Extend a volume === 
This is very easy because btrfs incorporates a volume manager. You only have to look for a free device. You may use a partition like ''/dev/sdz4'' or you may use a raw device like ''/dev/sdz''. Then add this device to your existing volume with '''btrfs device add'''. You may need to do a '''balance''' afterwards to redistribute some chunks.
{{RootCmd|command=btrfs device add [/dev/sdz4] /}}
{{BoxWarning|Dont´t format the partition!|To add a device it should have '''NO filesystem''' on it. The btrfs volume manager will include the free storage of the device '''into the existing filesystem'''.}}

=== Move a volume (to another disk) === 
There are a lot of ways you can move a "normal" filesystem from one disk to another. But there are dangers with moving btrfs volumes that do not exist with other filesystems! '''Don´t ever move a btrfs volume with a tool that does not say it is 100% btrfs-proof.'''
When at any time there are 2 partitions in one computer that have the same filesystem UUID, one ore both filesystems '''may be destroyed'''. Under the topic '''tips''' you will find an easy way to do move a volume without any danger
{{BoxDanger|Do NOT|
* make a block-level copy of a Btrfs filesystem to another block device
* use LVM snapshots, or any other kind of block level snapshots
* turn a copy of a filesystem that is stored in a file into a block device with the loopback driver
* try to mount either the original or the copy while both are visible to the same kernel
See why at [https://btrfs.wiki.kernel.org/index.php/Gotchas Block-level copies of devices@btrfs.wiki.kernel.org]}}
{{BoxSuccess|Tip: move a volume|There is an easy and secure way to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this while the volume is in use. [[Btrfs#move_a_volume|See how to in "tips"]]}}

== Subvolume [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] == 
A subvolume is an independent mountable POSIX file-tree and '''not a block device'''. It is the part of a volume that will be '''mounted writeable''' into your Linux system. If you dont´t care about snapshots, and you don´t care about backups, it would be possible to use only one subvolume for everything. But then you would not be able to use the powers of Btrfs. ''Lets assume you do care.''


All subvolumes share the space of the Btrfs volume. You may create subvolumes at will. (You may think of subvolumes as sort of "dynamic partitions" inside a Btrfs volume)


When making snapshots (or send/receive) every subvolume will be handled separately. For example when you have 2 subvolumes(@, @home), and make a snapshot of one of them(@), this snapshot will contain every bit of data of all files in this subvolume(@), but none of the data from the other subvolume(@home). So if you make a few subvolumes, you are able to '''follow different strategies for snapshots''' of them. And you can '''restore''' each of them '''separately'''.


By convention the names of subvolumes start with '''@ (@home, @snapshots''' ...).

=== Subvolume '''@''' === 
This is the subvolume where your '''complete manjaro system''' will reside. It is mounted at "/" in your filesystem. You may take snapshots of this subvolume (or backups with send/receive) to secure a running manjaro system. When something bad happens, you are able to rollback to one of the snapshots, or to restore one of the backups of this subvolume '''without loosing your data''' at /home.


In order to make a rollback possible, this has to contain all and every data that is needed for your manjaro to work properly! This includes:
* '''config''' of your bootloader (/boot/brub/grub.cfg)
* '''initramdisk''' (/boot/initramfs-5.10-x86_64.img)
* '''kernel''' (/boot/vmlinuz-5.10-x86_64)
* '''kernel-modules''' (/usr/lib/modules/5.10.59-1-MANJARO/*)
* programs (/usr/bin/*)
* configs (/etc/*)
* libraries (/usr/lib/*)
* your root account (/root/*)
* rest of system files (/usr/*)

=== Subvolume '''@home''' === 
This is the subvolume where all '''user data''' ist stored. When you rollback your "@", this will not change at all. You may take snapshots of /home at a different rate and for different reasons. While snapshots of "@" are good for rollback, snapshots of @home are good for '''undeleting''' accidentally by users deleted (or overwritten) files.

=== Subvolume '''@snapshots''', '''@home.snapshots''' === 
It is wise to "store" snapshots '''NOT inside''' the subvolume they where taken from. So this may be the right place to store your snapshots of '''@''' or '''@home'''.

=== Subvolume '''@...''' === 
Sometimes it is desired to have other '''special snapshot strategies''' (or no snapshots at all) for some parts of the filesystem. If you need this, make another subvolume.


To have access to the root(/) of your volume, you need to mount this separately. (Please do not confuse this with "/" of the file system)
{{RootCmd|command=mount -t btrfs -o subvol=/,defaults [/dev/sdz2] /mnt}}
Now you are able to create a new subvolume in a flat layout.
{{RootCmd|command=btrfs subvolume create [/mnt/@tests]}}
This will be shown by
{{RootCmd|command=ls -l /mnt}}
{{RootCmd|command=btrfs subvolume list /mnt}}
This subvolume '''tests''' is empty. And it is not mounted by default. So if you want to use it, you have to mount it by ''fstab'' or other means. '''Now lets delete it again.'''
{{RootCmd|command=btrfs subvolume delete [/mnt/@tests]}}
{{RootCmd|command=umount /mnt}}

== Snapshot == 


A snapshot looks nearly the same as a subvolume. But snapshots really are "read-only photographs of a subvolume". While the subvolume changes with time. The snapshot is frozen in the state of the subvolume at the time you made it.
A snapshot is '''read-only'''. Therefore it is guaranteed not to change. In a snapshot you will find all files of the subvolume frozen in time. A snapshot is not a substitute for a backup! {{BoxWarning|Where to place snapshots|When creating snapshots you have to watch out for the volume layout in use. [https://github.com/jrabinow/snapper-rollback see@wiki.archlinux]}}


Snapshots (if regularly made) may be used for:
* Comparing config files from different "times"
* Merging config files
* Recovering accidentally deleted/overwritten files
* Rollback your system
* Anchor for a backup with send/receive
* Basis for a seed
* ''What do you use snapshots for ?''


Making and deleting snapshots is best done automatically:
* snapper [https://wiki.archlinux.org/title/snapper snapper@wiki.archlinux] [https://github.com/openSUSE/snapper snapper@github] [http://snapper.io/ snapper.io]
* timeshift [https://wiki.archlinux.org/title/Synchronization_and_backup_programs timeshift@wiki.archlinux] [https://github.com/teejee2008/timeshift timeshift@github]

=== Taking snapshots === 


Taking a snapshot is '''very fast''', and '''nearly priceless'''. After the snapshot is taken, all future writes will go as in CoW usual. But none of the space occupied by files in the snapshot will be reusable. As you write more and more new files, the filesystem will grow because it can not reuse the files in the snapshot. A new snapshot will freeze additionally all created or modified files since the last snapshot and so on. '''If you don´t release'''(delete) any snapshot '''you will''' eventually '''run out of space''' soon(disk full)

=== Releasing snapshots === 


Deleting a snapshot does not delete any files that are actually in use by other snapshots or the subvolume they where taken from. To free some space, Btrfs has to test for every file in the snapshot, whether it is in use, or it is not. If it is not, the space of this file/version will become free.(This is greatly simplified) Therefore it is '''costly to remove snapshots'''. And Btrfs will do this work in the background. You may notice this, because when you delete a snapshot there will be '''no immediate gain in free space'''. After a while you will notice that some space has become free.


Don´t forget to remove snapshots, or you will get in '''"out of space" -trouble soon'''. Btrfs needs some free space to manage its work. If your volume is more then 80% full you have to think(fast) what to do.
* ++++ '''Add''' some partition/device to the volume
* +++ '''Remove''' some snapshots you don't need
* + '''Delete''' some files (this does only help if they are not part of any snapshot)

=== Rollback to a snapshot === 


If you need to roll back into a snapshot you have to replace the actual subvolume by the chosen snapshot.
# '''Make a snapshot(ro)''' of the actual subvolume (for later reference)
# '''Delete the subvolume''' out of its actual place
# '''Create a new subvolume(rw)''' out of the snapshot chosen for rollback
# Make this new subvolume the default (optional)
# '''Don't forget''' to remove the snapshot you made in a few days
see in forum: [https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 manual Rollback with btrfs]


Please also have a look at [https://github.com/jrabinow/snapper-rollback snapper-rollback@github] and at [https://wiki.archlinux.org/title/Snapper#Suggested_filesystem_layout snapshot-layout@wiki.archlinux] for the suggested flat layout and the reasoning. ([https://forum.manjaro.org/t/how-to-manual-rollback-with-btrfs/80230 Rollback example ])
{{BoxWarning|Don't forget to remove snapshots before you run out of space|Every time you take a snapshot you only use the "rest of the volume" for storing everything you change from this time on. At some point in time you have to release the snapshot. Don´t use your space up. Btrfs needs '''space to breath.''' Don't use more then 80% or you will get into trouble."}}
{{BoxDanger|NO Snapshots together with quotas|There are reports about massive problems when using '''quotas''' together with snapshots (snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}

= Btrfs RAID = 
With Btrfs you no longer need to use ''mdadm'' to create mirrored volumes or to create RAIDs. This is already included in btrfs, and very easy to use. There are even advanced features bult in:
* Add devices to the volume This will integrate a device into the mounted volume {{RootCmd|command=btrfs device add [/dev/sdz7] /}}
* Remove devices from the volume. This will not delete any data, but remove the device from the volume. Bevorehand all data will be copied to the remaining devices of the volume.{{RootCmd|command=btrfs device delete [/dev/sdz8] /}}
* Use devices with different sizes in one volume
* Switch the volume between RAID levels
* Convert data to different RAID levels
* Do this while the volume is mounted and being used
{{BoxInfo|Raid Levels|There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation (of btrfs). See [https://en.wikipedia.org/wiki/RAID RAID@wikipedia],[https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#profiles RAID profiles@btrfs.readthedocs]
}}

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid0 RAID 0] (not Just a Bunch of Disks)== 
Using one ore more devices to build a volume. This volume has the '''capacity of all the used devices together(1+2+3+4...)'''. This is an very easy way to expand your volume when you need more space. You even can add 2 or 3 devices at a time. When you want to replace a device, you can add the new device, then remove the old device. Btrfs will move all data as necessary. ''To distribute all data to all devices you may want to '''balance''' the volume.'' Btrfs will stripe the data to all devices.
{{BoxWarning|If one device fails, everything is lost|Be aware that when one of the devices fails your complete volume may be lost if you use RAID 0}}

=== 1 device === 
In most setups you will start a volume with 1 device. If only one device is present, '''metadata will be duplicated''' on that device. Even with this simple setup you benefit from most features of Btrfs.

=== 2 or more devices === 
By default, '''metadata will be mirrored''' across two devices and '''data will be striped''' across all of the devices present. But if you have 2 or more devices in your volume you should consider using RAID 1.

== [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1 RAID 1] (mirrored), [https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#raid1c3 1C3], [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles 1C4] == 


When using Raid 1 btrfs mirrors data and metadata. This way it is possible to repair data when one copy gets damaged. This could happen when one device fails, when power was lost while writing, ... '''After enabling RAID1''' all new data and metadata is automatically mirrored. To mirror your existing data and metadata, '''you have to balance your complete volume'''.

=== Automatic repair === 
In order to preserve the integrity of the volume, Btrfs does separate CRC-checksums of metadata blocks and of data blocks. Every time a data block is read, the checksum is verified. When the checksum shows that the data is not good, Btrfs tries to get a good copy from the mirrored block. Then the bad block is written again with the good data from the mirrored block. This happens in background. The filesystem has been repaired, and this is logged into syslog. This can be forced by using btrfs scrub.

=== [https://btrfs.readthedocs.io/en/stable/mkfs.btrfs.html#man-mkfs-profiles RAID 10] (automatic) === 
When using enough devices(4...) with RAID 1, Btrfs will distribute all data, so that it not only is mirrored but also striped.

== RAID 5 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

== RAID 6 == 
{{BoxDanger|Not save yet|This is not recommended [https://btrfs.wiki.kernel.org/index.php/Gotchas see Parity RAID@btrfs.wiki.kernel.org]}}

= Btrfs maintenance = 
Btrfs needs maintenace like every filesystem. The more you use advanced features of btrfs, the more you have to watch for the right maintenance. Please also have a look at [[Btrfs Maintenance|Btrfs_Maintenance]]
=== Fragmentation ===
Files on btrfs tend to get somewhat fragmented, when they are appended or changed often. If you use a mechanical disk with slow seeks, it may be advisable to defragment some heavy used files from time to time (like once in a month).

When the files are only written to, or are only read seldom, '''don't worry'''.
==== Databases ==== 
It may be good to defragment a database if there is a ''noticeable'' slowdown when using it.
==== Logfiles ====
It may be good to defragment a logfile, if there is a ''noticeable'' slowdown when booting your system.

== Balance [https://btrfs.readthedocs.io/en/latest/Balance.html ⇒] == 
When adding devices or changing the RAID-level of your volume, it may be necessary to balance your volume. While balancing, btrfs will read ALL (or a subset of all) '''chunks''' in, and write them out again using the actual RAID-level. It will stripe these files over all available devices equally. While this happens, the volume will keep being usable, but you may see some '''heavy load''' on it. Also '''this may take a very long time''' because '''ALL data must be''' read AND '''written''' again.
Don´t worry about shutdown. When you shutdown your computer while the balance is running, the balance will pause. After you restart the computer the balance will restart and continue until it is finished.
{{BoxDanger|Possible bug when using a swap file:| Never use a full-balance on a machine with a swapfile, since it will ignore +C Attributes. You may also have a look at [https://forum.manjaro.org/t/howto-enable-and-configure-hibernation-with-btrfs/51253/36] }}

=== Filters === 
Because a complete balance may take '''a long time''', there is the possibility of filters in balance. When using a filter only those chunks will be balanced, that are named by the filter.
* '''balance''' all chunks that are less than 50% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=50 /}}
* '''balance''' all chunks that are less than 90% full. This '''will''' take some time !
{{RootCmd|command=btrfs balance start -dusage=90 /}}
{{BoxWarning|Don't use filters higher than 90%|This is unnecessary on an SSD drive. On a hard drive, this will put a lot of strain on the disk. Even with today's hard drives (>2TB), it may take a very long time. (e.g. 24 hours or more)}}

=== Merging chunks === 
As you use your volume, you will be creating some files, deleting some, modifying some. Then some parts of the chunks are empty. But this is not a coherent space that can be easily reused. Usually this is not a problem for btrfs and will be cleaned up automatically over time. However, if space is scarce (> 80% full), it is advisable to merge free areas together. This can be done by using balance with a filter.

=== After removing a device === 
When you remove a device from a volume, btrfs will automatically balance all "chunks" that where on the removed device. These chunks are placed on another device of the volume. So you don't need to balance by yourself after removing a device.

=== After adding a device === 
When you add a device there will be no automatic balance. Only when further using the volume, btrfs will use the additional free space according to the actual RAID-level.

=== After changing RAID-level === 
When you changed RAID-levels (for example from RAID 0 to RAID 1) there is no automatic duplication of the chunks. Only when writing further, btrfs will respect the changed RAID-level. This may not be what you intended. To complete the conversion to another RAID-level you need to tell btrfs to rewrite chunks where needed. You do this with a manual balance:


see: [https://btrfs.readthedocs.io/en/latest/Balance.html btrfs filesystem balance]

== Scrub [https://btrfs.readthedocs.io/en/latest/Scrub.html ⇒] == 
A scrub of a btrfs volume is like inspecting your home. Does the light work in every room? Is the battery of a smoke alarm empty? Does the fire extinguisher need to be replaced? Is any faucet dripping?
Every now and then it is advisable to look for such things. And fix it right away!

==== Check & repair on the fly ==== 
Every time btrfs reads a file, it checks the corresponding checksums. When btrfs is in RAID 0 and detects a 'damaged' file, it only can tell you that the file is damaged. You may delete it, or replace it from your backup.
When running in RAID 1 btrfs has 2 copies of every file. So if one file seems to be damaged, btrfs will read the other copy. If this other copy is ok, btrfs will automatically create another good copy of the file, and then afterwards delete the defect copy. You won't even notice this ''''automatic' repair.'''

==== Full check ==== 
Sometimes you may want to check ALL files, and to get a report of defects, because:
* Some files are read very seldom, and you don't want "bitrott"
* You want to check your data completely for any faults
* Once in a while you want to make sure all is well
* You want to force your disk/device to verify all data
* ...
This is when you use btrfs scrub. Scrub will read ALL data of your complete volume. While this is done, all files and metadata will be checked by the checksums and all problems will be reportet. Because this will read and verify your complete volume (eventually a few Terra-byte), it may take some time. Scrub will not waste time in checking unused chunks.
While checking you can enable automatic repair for RAID 1 or disable it. If you disable automatic repair, scrub will work completely readonly, and will change nothing on your volume.


Scrub can be done automatically (for example every month), or manually.


{{BoxInfo|Notice| Be aware, that Scrub does not structurally check the filesystem, but only checksums data and tree blocks. You may also have a look at [https://btrfs.readthedocs.io/en/latest/Tree-checker.html tree checker] }}


A manual scrub is done by:


{{RootCmd|command=btrfs scrub start -Bd /}}

= Solving Problems = 

== Out of space == 

==== Avoid to get out of space with btrfs! ==== 
Don't be stingy on storage space when creating a btrfs volume. A btrfs volume should normally only be 80% full. Then it is advisable to adjust the volume. In an emergency, 90% are okay too. But that is neither advantageous for the Btrfs volume nor for an SSD.
{{BoxWarning|Don't forget to include the snapshots in the bill|Manjaro is a rolling release distribution. There will be a lot of changes over time.}}
{{BoxInfo|Tip: Check how close you are to "out of space".| Look at '''Device unallocated:''' (not at ''Free (estimated):'') [https://forum.manjaro.org/t/could-not-boot-due-to-brfs-no-space-condition-how-should-i-keep-using-btrfs/92922/7 1]
{{RootCmd|command=btrfs filesystem usage /}}
}}
=== Get out of jail ===
This said, there is an '''easy way out''': Give btrfs more space ;-)
* '''add a partition''' (for example a extern USB-Stick with 8GB) to the btrfs-volume with{{RootCmd|command=btrfs device add /dev/[sdz4] /}}
* From now on this usb-partition belongs to your volume! Do not boot without it. '''Do not reboot''' at all in this stage! This stick has to stay until btrfs device remove has completed.
* look for old snapshots you don´t need, remove them '''now'''
* '''or delete some files''' you do not need
* Do this until your disk will be not more then 95% full


Do not get confused if btrfs does not immediately display the vacant space. After the next step (balance) it will become visible.


* '''balance''' your volume with a filter(50%) This '''will''' take some time !
{{RootCmd|command=btrfs balance start -musage=50 -dusage=50 /}}
{{BoxSuccess|Tip: Want to watch the volume clean up ?|
{{UserCmd|command=pamac install procps-ng}}}}
{{BoxSuccess|After that inside a terminal:|
{{RootCmd|command=watch -n 60 btrfs filesystem usage -h / }}}}
* '''balance''' your volume with a filter(95%) This '''will''' take some more time !
{{RootCmd|command=btrfs balance start -musage=95 -dusage=95 /}}


* '''remove the added partition''' from the volume with {{RootCmd|command=btrfs device remove /dev/[sdz4] /}}
* This '''will''' take some time ! '''Do not reboot until this step is complete'''.
* Now you may remove the USB-Stick.

=== Stay out of jail === 
* Think about how to extend the btrfs volume to '''double size'''
* seek if there is a program filling your disk
* look for snapshots !
* don’t forget to remove old snapshots (best done automatically)

== Corrupted checksums == 
[ 9364.354241] BTRFS error (device nvme0n1p3): block=58469742080 write time tree block corruption detected
This ERROR or similar may lead to Messages like:
Configuration file "/home/user/.config/dolphinrc" not writable. Please contact your system administrator.
because btrfs does mount this partition '''readonly''' when it detects corrupted blocks.


Now you have to investigate WHY a checksum of a btrfs block says it is corrupted.


* In some cases the underlying device may beginn to fail ! => replace it (consider using RAID10)
* In other cases a corruption may have happened even before the block had been written to disk
** corruption in RAM
** some software-bug ???
** ssd gone bad ??? [https://forum.manjaro.org/t/update-ended-in-readonly-filesystem/154442/34 example]
[https://btrfs.readthedocs.io/en/latest/Hardware.html What the Btrfs developers say:] If you use unreliable hardware and don’t know about that, don’t blame the filesystem when it tells you.


Also see: [https://btrfs.readthedocs.io/en/latest/Tree-checker.html Tree-ckecker]

== Tips == 

=== Move a volume === 


There is an '''easy and secure way''' to move a volume to another disk/device. If you use Btrfs itself to move the volume, there will be no danger. You even can do this '''while the volume is in use'''.
* Create the partition you want to use as ''destination'' '''without formatting''' it. Or remove the filesystem when one is present
* Add the ''destination'' device to your volume by {{RootCmd|command=btrfs device add /dev/[destination] [path to filesystem]}}
* Remove the ''source'' device from your volume by {{RootCmd|command=btrfs device remove /dev/[source] [path to filesystem]}}
Btrfs will notice, that it is necessary for this setup to move all data from the source device to the destination device. And it will start immediately to move data in the background. Meanwhile you can use your PC as you want.
* Empty Blocks will not be moved
* Compressed data will remain compressed
* All Snapshots will remain
* '''The UUID of the filesystem will remain the same''', but btrfs will be aware of this
* If you used the UUID to identify your volume, you even wont´t need to edit '''/boot/grub/grub.cfg''' and '''/etc/fstab'''
* Only, '''don't shutdown while the move of the volume is not complete'''.
If you want to watch the volume move, inside a terminal:
{{UserCmd|command=pamac install procps-ng}}
{{RootCmd|command=watch -n 60 btrfs filesystem show /}}

=== Resize a btrfs filesystem/device === 


When you resize a file system, you also need to resize the partition (device) it resides on. You cannot resize a mounted partition using '''gparted'''! So you need to unmount it beforehand or use a live manjaro from USB to resize the partition and file system.


When resizing existing file systems, it is strongly advisable to have current backups. However, resizing is possible without any problems when using '''gparted'''.

==== shrink ==== 


What you need to understand is that you can only safely shrink a file system if it is ''not too full''. Shrinking a file system can take a '''long time''' because BTRFS may need to move data that was in the area to be freed to the remaining area.


Using '''gparted''' you can safely shrink a BTRFS file system. All necessary steps are taken such as:
* Mount file system
* Shrink file system
* Unmount file system
* Shrink partition


see@ https://forum.manjaro.org/t/howto-resize-a-btrfs-filesystem/152999

==== expand ==== 


A BTRFS file system can also be safely expanded with '''gparted'''. All necessary steps are taken such as:
* Extend partition
* Mount file system
* Expand file system
* Unmount file system

=== Mount options === 
The default mount settings chosen by btrfs are really optimal in most cases! There are only a few options to think about. Current and accurate information can also be found at: https://btrfs.readthedocs.io/en/latest/Administration.html
{{BoxInfo|,noatime|Under read intensive work-loads, specifying noatime significantly improves performance because no new access time information needs to be written. Default is ''relatime''. ( ''''',lazytime ''[https://github.com/kdave/btrfs-progs/issues/377 may not help, however]''')}}
{{BoxInfo|,compress=zstd:7| Enables automatic and transparent compression. If compression is enabled, ''nodatacow'' and ''nodatasum'' are disabled. The compression level is adjustable, with higher levels trading off speed and memory for higher compression rates. ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. '''Default is 3''' each}}
* '',ssd'' ('''automatic !)'''
* '',discard'' ('''automatic !)'''
* '',space_cache'' ('''automatic !)'''
You can always test what btrfs uses with: {{UserCmd|command=mount -t btrfs}}

= Btrfs options = 

== Compression [https://btrfs.readthedocs.io/en/latest/Compression.html ⇒] == 
Compression can only be set '''per volume'''. So if you set different "levels" of compression for different mounts in the fstab, only the first "level" will be applied. [https://btrfs.readthedocs.io/en/latest/Compression.html#how-to-enable-compression see@btrfs.readthedocs.io]
{{BoxWarning|Grub needs to load the kernel and initrd|When you use compression on kernel, initrd, or grub config files, '''grub''' needs to decompress these files. Otherwise you will '''not be able to boot'''. GRUB introduced '''zstd''' support in '''2.04.''' Maybe you need to update grub '''and''' reinstall it}}

== Encryption == 
May be in the future.

== Send + receive = backup [https://btrfs.readthedocs.io/en/latest/Send-receive.html ⇒] == 
Some wiki-posts in the forum:
* [https://forum.manjaro.org/t/howto-copy-move-a-subvolume-from-one-partition-to-another/135166 move a subvolume to another volume]
* [https://forum.manjaro.org/t/howto-use-btrfs-send-receive/135808 backup snapshots]

== Quota groups [https://btrfs.readthedocs.io/en/latest/Qgroups.html ⇒] == 
Quota support in Btrfs is implemented at the subvolume level.


For more info see [https://btrfs.wiki.kernel.org/index.php/Quota_support Quota_support@btrfs.kernel.org]
{{BoxDanger|Reports about problems|There are reports about massive problems when using quotas (especially together with snapshots, snapper, timeshift). Please have a look at: [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues Known_issues@btrfs.kernel.org]}}
* [https://forum.manjaro.org/t/freeze-issues-with-btrfs-and-timeshift/22005/10 freeze-issues-with-btrfs-and-timeshift 2021]
* [https://forum.manjaro.org/t/cannot-clone-btrfs-boot-drive-with-clonezilla/78836/10 cannot-clone-btrfs-boot-drive-with-clonezilla 2021]
* [https://forum.manjaro.org/t/btrfs-qgroups-warning-error/64029 btrfs-qgroups-warning-error 2021]
* [https://forum.manjaro.org/t/files-disappearing-in-btrfs-and-ssd/28991 files-disappearing-in-btrfs-and-ssd 2020]

== Zoned mode [https://btrfs.readthedocs.io/en/latest/Zoned-mode.html ⇒] == 
Beginning with version 5.12

= Btrfs Tools = 
For complete info an all tools for btrfs please do an actual search at the arch wiki and at the manjaro forum for "btrfs". In the following section only a few commands are described. Especially those commands that are often misinterpreted. Commands described earlier are omitted.

== btrfs (the command) [https://btrfs.readthedocs.io/en/latest/man-index.html ⇒] == 
Be aware that some sub-commands of btrfs will not work as normal user. Other sub-commands do work but will give only partial info. So best use them as ''root'' or with ''sudo''.

==== help, version ==== 
'''help''' together with '''man btrfs''' or '''info btrfs''' will get you an overview over the usable options on your install. {{UserCmd|command=btrfs help}}


With the '''version''' of btrfs given here you can look at [https://btrfs.wiki.kernel.org/index.php/Changelog changelog].{{UserCmd|command=btrfs version}}

==== device ==== 
'''scan''' will give no visible results 😜
{{RootCmd|command=btrfs device scan}}


'''stats''' will give a list of errors detected in the past. This all should be 0, or you may be in trouble.
{{RootCmd|command=btrfs device stats /}}


What to look for in device '''usage''':
* RAID-level of Data, Metadata and System
* Unalocated:
Don't ever let ''Unalocated:'' get below 5% of your volume (or double the size you need for your next update)! If this goes too low, you will get into "out of space" trouble
{{RootCmd|command=btrfs device usage /}}
Without sudo this will give very wrong results for everything displayed. '''Dont´t use this without sudo !'''

=== btrfs filesystem df / === 

=== btrfs filesystem du === 
Here the full scope of btrfs' difference becomes visible. When btrfs takes snapshots, many files are contained unchanged in several snapshots, but only take up space in the file system once. At the same time, there can be the same(!) file with different content and size in different snapshots.


It is therefore not enough to simply add up the size of all files in a path to determine the '''space consumption''' in the file system.


For each file, it must be determined how large it is and whether all or part of it is shared with other subvolumes. Since btrfs has to read a lot of metadata for this, it can take a '''long time''' to display the results:


{{RootCmd|command=btrfs filesystem du -s /home}}
Total Exclusive Set shared Filename
8.11TiB 6.23GiB 215.76GiB /home
{{BoxInfo|Total|The sum of all files, as "du" would display them in a conventional file system. This is how much space a conventional file system would use to store these files (and all the necessary copies).}}
{{BoxInfo|Exclusive|The sum of the files that "only" occur in one of the subvolumes and are not shared with other subvolumes}}
{{BoxInfo|Set shared|The sum of files shared with other subvolumes}}
{{BoxInfo|Exclusive + Set shared|This is the actual space used in the file system}}

=== btrfs filesystem show === 
=== btrfs filesystem usage ===
=== btrfs scrub status ===

==btrfsck== 
This is not what you may think it is 😜

== Recomendations == 


{| class="wikitable"
|+ We recommend using Btrfs with UEFI and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 || Fat32 || 1GiB || EFI system partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}


{| class="wikitable"
|+ IF you don't have UEFI, you may use Btrfs with BIOS and GPT
|-
! Partition !! Filesystem !! Size !! Partition type
|-
| /dev/sda1 ||(bootloader)|| 4MiB || BIOS boot partition
|-
| /dev/sda2 || Btrfs || 1Gib - 8EiB || Btrfs Volume
|-
| /dev/sda3 || swap [https://btrfs.readthedocs.io/en/latest/Subvolumes.html ⇒] || 4GiB, at least your RAM-size || Swap partition (optional)
|}





<small>Please be aware that the information on this page is a simplified version of the reality. Is is written to make the reader understand a little of these complex things. To get an in depth understanding it will be neccesary to read further at btrfs.wiki.kernel.org or other places.</small>

= Additional Information = 
=== Why not btrfs ? ===
A lot of people say: "'''I don't use btrfs because''' it is experimental and is '''not stable'''. You can´t use it in production. It is not safe!".

==== Not stable ? ==== 
The status of btrfs was experimental for a long time, but the core functionality is considered '''good enough for daily use'''. <small>(from kernel.org)</small>


If you see statements declaring Btrfs as not stable, please look for the date of them. Some seem to date from 10 years ago. So if you want to give Btrfs a chance, you have to look for newer statements. Maybe even look at [https://btrfs.wiki.kernel.org Btrfs Kernel Wiki] as that sure is the best information regarding Btrfs

==== Experimental ? ==== 
Btrfs is feature-rich! There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.<small>(from kernel.org)</small>


Some features are '''not implemented yet'''. Others are only '''partly implemented'''. Some are '''experimental''' and not suggested for production use. As is always the case in Linux-land ''you'' decide what to use, and so you are responsible for your own decisions.

==== Not usable for production ? ==== 
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Distro_support Distro support] for Btrfs as main filesystem
* Some companies do use Btrfs in production@wiki.btrfs.kernel.org
* Some manufacturers do deploy devices where Btrfs is installed by default.

==== Difficult to repair ? ==== 
Indeed, when you search for the usual ways to repair a file system like FAT or Ext4 then you don't find good information about repairing btrfs. This is not because it is difficult to repair Btrfs, but because repairing Btrfs '''does work very differently'''.

== What's this "Copy on Write" == 
When you want to get the most out of using Btrfs you do need to know some things about this file system. Then you are able to use it properly and to your advantage. Btrfs is not difficult, but different to some extend.

=== Write in place (FAT32) === 
Most older file systems do write "in place". This means that some data or metadata will be written "over" the previous data at the same place.


For example this is the case for FAT32 file systems. The '''F'''ile '''A'''llocation '''T'''able is at a fixed place on this file system. When the "FAT" changes (because a file got bigger and needs more blocks), this new FAT must be written with the new data to the same place as before. When the disk is ejected before (or while) this data is written, the file system will be corrupted. And the FAT does change a lot.


The danger of corruption is especially big while metadata (like filename, permission, usage of disk space ...) is being written.

=== Write to a metadata-log (Ext4) === 
There is a solution to this with newer file systems like Ext4. Instead of writing metadata "in place", metadata is written into an "endless" log. Then it is not possible to be corrupted while overwritten. This is possible because metadata is only a very small part of the data in a file system.


There has to be an additional mechanism to make this safe. Sometimes this is called "barriers", and there have to be checksums that tell when a part of the log is corrupted.


This does protect the file system itself, but not the files in it. Because a file may be overwritten in place, and then the old file is lost, and the new one may not have been written completely.

=== Copy on Write! (Btrfs)=== 
Copy on Write is a "new" concept. It means the file system will try to '''never''' write over existing data. '''How is this even possible?'''
* Files are appended at the end of a "data page"
* Metadata is appended at a "metadata page"
* Inside a page '''nothing is ever overwritten'''
* When a page is full the file system will use the next free page
* Deleting a file does not write/clean its data, but writes metadata, that marks this file as deleted
* Overwriting a file does first append the new file to the actual "data page", then appends the metadata for this file to the "metadata page".
* Changing small parts of a file will write only the new parts, then ''link'' the rest to the old file
* there are checksums for data and metadata

==== Downsides ==== 
* Management of space is complex
* There are 2 sorts of pages (data / metadata)
* There has to be a clean-up-process who makes the space of deleted files reusable, so that the disk does not run out of free pages
* It must be avoided to write data unnecessarily, because then the clean-up would also be very expensive

==== Advantages ==== 
* It is possible to '''detect''' nearly any '''corruption''' because of the checksums
* When the power is lost, or the disk is disconnected, all old data is save. WHY?
** Every bit of "old" data from before the power loss or the disconnection is present because it is '''NOT overwritten'''
** Only the newly written data may be partly damaged
** The metadata may also be partly damaged
** When mounting the volume it is possible by analyzing checksums and metadata to find the point in the filesystem where all was good
** Btrfs will '''automatically roll back''' to this point, then it can mount the file system writable


* CoW is a sound foundation to build upon
** Snapshots
** RAID
** Volume management
** Compression
** Encryption (maybe some time in the future)


{{BoxWarning|Don´t disable CoW in Btrfs|It is possible to disable CoW in Btrfs. But then you '''loose all benefits''' of Btrfs. It won´t even make checksums. If you don't like CoW, then you better use another filesystem}}

= Use the Forum! = 
It is a good Idea to [https://forum.manjaro.org/search?q=btrfs search the forum] for posts related to btrfs.

= Btrfs is fast moving! See Also:= 
<big>
* [https://btrfs.readthedocs.io/en/latest/index.html btrfs.readthedocs.io]
* [https://wiki.archlinux.org/title/btrfs btrfs@ARCH-wiki]
</big>



</translate>
[[Category:Boilerplate{{#translation:}}]]