Btrfs (B-tree file system) is a copy-on-write (CoW) file system that is included in the Linux kernel and is known for its advanced features and capabilities, such as snapshotting, incremental backups, and more. Btrfs is designed to be scalable and flexible, and it supports features such as online file system resizing, online file system balancing, and online file system recovery.
Btrfs is a modern file system that is designed to handle large file systems with a high degree of data integrity and performance. Btrfs is well-suited for use in storage servers, cloud storage systems, and other environments where data integrity and scalability are important.
Btrfs is a powerful and flexible file system that offers many advanced features and capabilities. Some of the key features of Btrfs include:
- Snapshotting: Btrfs supports the creation of snapshots, which are point-in-time copies of the file system that can be used for backup and recovery purposes.
- Incremental backups: Btrfs supports incremental backups, which means that you can create backups that only include the changes made since the last backup.
- Online file system resizing: Btrfs supports online file system resizing, which means that you can resize a Btrfs file system while it is mounted and in use.
- Online file system balancing: Btrfs supports online file system balancing, which means that you can redistribute data across devices and disks in a Btrfs file system while it is mounted and in use.
btrfs Utility
Use the btrfs command to manage and display information about a Btrfs file system. The command requires a subcommand. Enter btrfs without any arguments to list the subcommands:
# btrfs usage: btrfs [--help] [--version] [group] [[group]...] [command] [args] Command groups: subvolume manage subvolumes: create, delete, list, etc filesystem overall filesystem tasks and information balance balance data across devices, or change block groups using filters device manage and query devices in the filesystem scrub verify checksums of data and metadata rescue toolbox for specific rescue operations inspect-internal query various internal information property modify properties of filesystem objects quota manage filesystem quota settings qgroup manage quota groups replace replace a device in the filesystem Commands: check Check structural integrity of a filesystem (unmounted). restore Try to restore files from a damaged filesystem (unmounted) send Send the subvolume(s) to stdout. receive Receive subvolumes from a stream help Display help information version Display btrfs-progs version For an overview of a given command use 'btrfs command --help' or 'btrfs [command...] --help --full' to print all available options. Any command name can be shortened as far as it stays unambiguous, however it is recommended to use full command names in scripts. All command groups have their manual page named 'btrfs-[group]'.
btrfs subvolume Command Examples
1. Create a new empty subvolume:
# btrfs subvolume create /path/to/new_subvolume
2. List all subvolumes and snapshots in the specified filesystem:
# btrfs subvolume list /path/to/btrfs_filesystem
3. Delete a subvolume:
# btrfs subvolume delete /path/to/subvolume
4. Create a read-only snapshot of an existing subvolume:
# btrfs subvolume snapshot -r /path/to/source_subvolume /path/to/target
5. Create a read-write snapshot of an existing subvolume:
# btrfs subvolume snapshot /path/to/source_subvolume /path/to/target
6. Show detailed information about a subvolume:
# btrfs subvolume show /path/to/subvolume
btrfs device Command Examples
1. Add one or more devices to a btrfs filesystem:
# btrfs device add /path/to/block_device1 /path/to/block_device2 /path/to/btrfs_filesystem
2. Remove a device from a btrfs filesystem:
# btrfs device remove /path/to/device|device_id [...]
3. Display error statistics:
# btrfs device stats /path/to/btrfs_filesystem
4. Scan all disks and inform the kernel of all detected btrfs filesystems:
# btrfs device scan --all-devices
5. Display detailed per-disk allocation statistics:
# btrfs device usage /path/to/btrfs_filesystem
btrfs filesystem Command Examples
1. Show filesystem usage (optionally run as root to show detailed information):
# btrfs filesystem usage /path/to/btrfs_mount
2. Show usage by individual devices:
# btrfs filesystem show /path/to/btrfs_mount
3. Defragment a single file on a btrfs filesystem (avoid while a deduplication agent is running):
# btrfs filesystem defragment -v /path/to/file
4. Defragment a directory recursively (does not cross subvolume boundaries):
# btrfs filesystem defragment -v -r /path/to/directory
5. Force syncing unwritten data blocks to disk(s):
# btrfs filesystem sync /path/to/btrfs_mount
6. Summarize disk usage for the files in a directory recursively:
# btrfs filesystem du --summarize /path/to/directory
btrfs check Command Examples
1. Check a btrfs filesystem:
# btrfs check /path/to/partition
2. Check and repair a btrfs filesystem (dangerous):
# btrfs check --repair /path/to/partition
3. Show the progress of the check:
# btrfs check --progress /path/to/partition
4. Verify the checksum of each data block (if the filesystem is good):
# btrfs check --check-data-csum /path/to/partition/
5. Use the n-th superblock (n can be 0, 1 or 2):
# btrfs check --super n /path/to/partition
6. Rebuild the checksum tree:
# btrfs check --repair --init-csum-tree /path/to/partition
7. Rebuild the extent tree:
# btrfs check --repair --init-extent-tree /path/to/partition
btrfs balance Command Examples
1. Show the status of a running or paused balance operation:
# btrfs balance status /path/to/btrfs_filesystem
2. Balance all block groups (slow; rewrites all blocks in filesystem):
# btrfs balance start /path/to/btrfs_filesystem
3. Balance data block groups which are less than 15% utilized, running the operation in the background:
# btrfs balance start --bg -dusage=15 /path/to/btrfs_filesystem
4. Balance a max of 10 metadata chunks with less than 20% utilization and at least 1 chunk on a given device devid (see btrfs filesystem show):
# btrfs balance start -musage=20,limit=10,devid=devid /path/to/btrfs_filesystem
5. Convert data blocks to the raid6 and metadata to raid1c3 (see mkfs.btrfs(8) for profiles):
# btrfs balance start -dconvert=raid6 -mconvert=raid1c3 /path/to/btrfs_filesystem
6. Convert data blocks to raid1, skipping already converted chunks (e.g. after a previous cancelled conversion operation):
# sudo btrfs balance start -dconvert=raid1,soft path/to/btrfs_filesystem
7. Cancel, pause, or resume a running or paused balance operation:
# btrfs balance [cancel|pause|resume] /path/to/btrfs_filesystem
btrfs inspect-internal Command Examples
1. Print superblock’s information:
# btrfs inspect-internal dump-super /path/to/partition
2. Print superblock’s and all of its copies’ information:
# btrfs inspect-internal dump-super --all /path/to/partition
3. Print filesystem’s metadata information:
# btrfs inspect-internal dump-tree /path/to/partition
4. Print list of files in inode n-th:
# btrfs inspect-internal inode-resolve n /path/to/btrfs_mount
5. Print list of files at a given logical address:
# btrfs inspect-internal logical-resolve logical_address /path/to/btrfs_mount
6. Print stats of root, extent, csum and fs trees:
# btrfs inspect-internal tree-stats /path/to/partition
btrfs property Command Examples
1. List available properties (and descriptions) for the given btrfs object:
# btrfs property list /path/to/btrfs_object
2. Get all properties for the given btrfs object:
# btrfs property get /path/to/btrfs_object
3. Get the label property for the given btrfs filesystem or device:
# btrfs property get /path/to/btrfs_filesystem label
4. Get all object type-specific properties for the given btrfs filesystem or device:
# btrfs property get -t [subvol|filesystem|inode|device] /path/to/btrfs_filesystem
5. Set the compression property for a given btrfs inode (either a file or directory):
# btrfs property set /path/to/btrfs_inode compression [zstd|zlib|lzo|none]
btrfs rescue Command Examples
1. Rebuild the filesystem metadata tree (very slow):
# btrfs rescue chunk-recover /path/to/partition
2. Fix device size alignment related problems (e.g. unable to mount the filesystem with super total bytes mismatch):
# btrfs rescue fix-device-size /path/to/partition
3. Recover a corrupted superblock from correct copies (recover the root of filesystem tree):
# btrfs rescue super-recover /path/to/partition
4. Recover from an interrupted transactions (fixes log replay problems):
# btrfs rescue zero-log /path/to/partition
5. Create a /dev/btrfs-control control device when mknod is not installed:
# btrfs rescue create-control-device
btrfs restore Command Examples
1. Restore all files from a btrfs filesystem to a given directory:
# btrfs restore /path/to/btrfs_device /path/to/target_directory
2. List (don’t write) files to be restored from a btrfs filesystem:
# btrfs restore --dry-run /path/to/btrfs_device /path/to/target_directory
3. Restore files matching a given regex ([c]ase-insensitive) files to be restored from a btrfs filesystem (all parent directories of target file(s) must match as well):
# btrfs restore --path-regex regex -c /path/to/btrfs_device /path/to/target_directory
4. Restore files from a btrfs filesystem using a specific root tree bytenr (see btrfs- find-root):
# btrfs restore -t bytenr /path/to/btrfs_device /path/to/target_directory
5. Restore files from a btrfs filesystem (along with metadata, extended attributes, and Symlinks), overwriting files in the target:
# btrfs restore --metadata --xattr --symlinks --overwrite /path/to/btrfs_device /path/to/target_directory
btrfs scrub Command Examples
1. Start a scrub:
# btrfs scrub start /path/to/btrfs_mount
2. Show the status of an ongoing or last completed scrub:
# btrfs scrub status /path/to/btrfs_mount
3. Cancel an ongoing scrub:
# btrfs scrub cancel /path/to/btrfs_mount
4. Resume a previously cancelled scrub:
# btrfs scrub resume /path/to/btrfs_mount
5. Start a scrub, but wait until the scrub finishes before exiting:
# btrfs scrub start -B /path/to/btrfs_mount
6. Start a scrub in quiet mode (does not print errors or statistics):
# btrfs scrub start -q /path/to/btrfs_mount
btrfs version Command Examples
1. Display btrfs-progs version:
# btrfs version
2. Display help:
# btrfs version --help