Getting started

From btrfs Wiki

Contents 1 Download 2 Compiling the Kernel Module 3 Compiling Btrfs Utilities 4 Basic Filesystem Commands 5 Mount Options

Download

Download the latest utility programs and modules from:

http://www.kernel.org/pub/linux/kernel/people/mason/btrfs/

Example: btrfs-0.16.tar.bz2, btrfs-progs-0.16.tar.bz2

See also Btrfs source repositories for SCM access, and Hot Fixes for links to the latest updates.

Compiling the Kernel Module

Btrfs uses libcrc32c in the kernel for file and metadata checksums. You need to compile the kernel with: CONFIG_LIBCRC32C=m or CONFIG_LIBCRC32C=y

If you are running the latest Btrfs code from the unstable repository, you'll need to also configure zlib compression into your kernel:

CONFIG_ZLIB_INFLATE and CONFIG_ZLIB_DEFLATE for btrfs newer than v0.16

Once your kernel is setup, typing make in the btrfs module sources will build against the running kernel. When the build is complete:

modprobe libcrc32c ; modprobe zlib_inflate zlib_deflate ; insmod btrfs.ko

Compiling Btrfs Utilities

The Btrfs utility programs require libuuid to build. This can be found in the e2fsprogs sources, and is usually available as libuuid, uuid-dev or e2fsprogs-devel from various distros. You also need the zlib development headers, usually available in a package called zlib-devel or zlib1g-dev.

Building the ext3 conversion tools requires libe2fs (usually available in e2fsprogs-devel or e2fslibs-dev) and libacl (may be available in libacl1-dev).

Building the utilities is just make. If you would also like the ext3 conversion program, type make convert.

make install will copy the programs into /usr/local/bin

Basic Filesystem Commands

Creating a filesystem of at least 1Go is recommanded. Be aware that for that size, it will report full when reaching about 75%.

• mkfs.btrfs: create a filesystem
• btrfsctl: control program to create snapshots and subvolumes and scan devices
  • Scan all devices looking for btrfs filesystems, or scan just one partition
    • btrfsctl -a
    • btrfsctl -A /dev/sda2
• Snapshots and subvolumes
  • mount -t btrfs /dev/sda2 /mnt/btrfs
  • btrfsctl -S new_subvol_name /mnt/btrfs
  • btrfsctl -s /mnt/btrfs/snapshot_of_root /mnt/btrfs
    • mount -t btrfs -o subvol=new_subvol /dev/sda2 /mnt/new_subvol
    • mount -t btrfs -o subvol=snapshot_of_root /dev/sda2 /mnt/snap
• btrfsck: do a limited check of the FS extent trees.
• btrfs-debug-tree: print all of the FS metadata in text form
  • debug-tree /dev/sda2 >& big_output_file
• If a problem occures you can create an image of the fs with btrfs-image and send it to the devs. (All data will be zeroed, but metadata and the like is preserved.)
  • btrfs-image -c 9 /dev/sda2 /tmp/btrfs_dump.z

More Informations on the commands.

Mount Options

Here is a list of the current mount options in btrfs and an explanation of what they do

• degraded - This is used when you have multiple devices in your btrfs volume and one of them is failing. This will allow you to still mount the filesystem even if the failing device is throwing errors.
• subvol=<volume name> - Mount this subvolume instead of the root subvolume.
• device=<device name> - Tells btrfs to scan this device for a btrfs volume.
• nodatasum - Do not checksum data.
• nodatacow - Do not copy-on-write data.
• nobarrier - Do not use device barriers. NOTE: Using this option greatly increases the chances of you experiencing data corruption during a power failure situation.
• max_extent=<number> - Set the maximum extent size used for allocation during delayed allocation. By default this is set to the largest number possible, since we use other calculations to figure out the optimal extent size to try and allocate.
• max_inline=<number> - Set this maximum amount of space that can be used to inline data within a btree leaf.
• alloc_start=<number> - Set where in the disk we start allocations.
• thread_pool=<number> - The number of worker threads to allocate.
• compress - Enable compression
• ssd - Turn on some of the SSD optimized behaviour within btrfs.
• noacl - Do not enable ACL's.
• notreelog - This disables the tree logging used for fsync.
• flushoncommit - Turns on ext3 like behaviour, where all outstanding delayed allocations are flushed to disk when we commit the transaction.
• metadata_ratio=<number> - Sets the number of data chunks that need to be allocated to force a metadata chunk allocation. By default this is set to 8.