HowTO: Btrfs Root Installation
Foreword
Btrfs is a new copy on write file system for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Initially developed by Oracle, Btrfs is licensed under the GPL and open for contribution from anyone.
Linux has a wealth of file systems to choose from, but we are facing a number of challenges with scaling to the large storage subsystems that are becoming common in today's data centers. File systems need to scale in their ability to address and manage large storage, and also in their ability to detect, repair and tolerate errors in the data stored on disk.
Source: http://btrfs.wiki.kernel.org
The steps and procedures in this guide have been tested on and work with Ubuntu 9.10 - Karmic Koala, and Ubuntu 10.04 - Lucid Lynx. Any other release is not guaranteed to work at all.
Please bear in mind that Btrfs is a development file system, as such, you will experience crashes, glitches, and possible loss of data. Do not use it for production use
OK, I think that has scared away most users. Now for those crazy people who remain. (You Lucid users know who you are). 
Updates for Maverick users:
- Booting into a Btrfs system no longer requires patching of GRUB. So long as you have a separate partition to boot (recommended format ext2), things are said to go smoothly.
- As of 2.6.34, Btrfs has a new and enhanced utility tool to control and show statistics of the Btrfs partition. It's usage is not covered in this guide.
Updates for Natty users:
- The Ubuntu installer seamlessly allows you to use Btrfs now, and GRUB has full support, meaning it is no longer necessary to have a separate /boot anymore.
Part 1: Installation
By and far, the most simplest method is to convert an already existing installation from Ext3/Ext4 to Btrfs. Although an installation from scratch probably produces better behaviour and will give you the option for choosing between how the file system is setup - options you cannot change after creation - ie: raid level.
Setting up the Base Install
So, what we do is go through the installation process as normal, and when we reach the Partition stage, select the "Advanced" option to specify manually.
Separate /boot
First, we create a /boot partition formatted as an ext2 - this is important if we want to boot the OS!
500MB in size should be sufficient enough.
How you go about your business after that doesn't really matter, but you may end up with something like this afterwards.
Ensure that you make a note of which file system will be mounted as /, as you will need that info when you convert it.
Post Installation
The rest is everything as usual, and once the installation is complete, congratulations, the easy bit is done! Select "Continue Testing" so we can now traverse onto the hard bit.
Firstly, edit the sources so that the universe is included in them. This can be done via "System -> Administration -> Software Sources"
Reload the sources after closing, and next, open a terminal. Now we can begin on the dirty work. 
Converting Ext4 to Btrfs
The Physical Conversion
As my system was installed on /dev/sda5, that is the one I'll be specifying in this guide. If yours is different, change the path as needed.
In order to convert the file system, we require btrfs-tools to be installed.
Code:
sudo apt-get install btrfs-tools
The conversion, thankfully, is elementary.
Code:
sudo btrfs-convert /dev/sda5
The not so elementary bit is reconfiguring the boot process to play nice with the file system.
First though, we re-mount all file systems as you would expect them to be as if you were booted into it.
Code:
sudo mount /dev/sda5 /mnt
sudo mount /dev/sda1 /mnt/boot
for fs in proc sys dev dev/pts; do sudo mount --bind /$fs /mnt/$fs; done
Now we chroot into the file system.
From here on - until we reboot - we will run all commands inside the chroot.
Update Fstab
The conversion process creates a new UUID for the partition, as such this requires updating.
To obtain the new UUID, run:
Make a note, then edit /etc/fstab
I've highlighted the areas of interest that require changing - don't forget to update the file system type too.
Before:
Code:
# / was on /dev/sda5 during installation
UUID=e03cb3cc-8470-4ee6-a18a-b49da45c6f21 / ext4 error=remount-ro 0 1
After:
Code:
# / was on /dev/sda5 during installation
UUID=4be84d08-94cb-4013-ae0b-ce1d72d96db1 / btrfs defaults 0 1
Hack GRUB2
At this current time of writing, Grub2's detection method of using stat() cannot detect a Btrfs file system - see here why - so we need to make it so Grub2 detects the it every time you run update-grub.
As it turns out Grub0.97 can detect it just fine, but if downgrading is out of the question, I've written a nice little patch that backports the old grub detection method.
All you need to do is install patch, download and setup the correct diversions - so they don't get overwritten if an upgrade were to occur.
Code:
apt-get install patch
wget http://launchpadlibrarian.net/36483885/legacy_detection.patch
dpkg-divert --local --add /usr/sbin/grub-mkconfig
dpkg-divert --local --add /usr/lib/grub/grub-mkconfig_lib
Then open the patch for editing
Code:
nano legacy_detection.patch
and search and replace the two lines specified below in the file as seen highlighted in red, ignoring the rest of the file.
Before:
Code:
+++ grub2-1.97~beta4/util/grub-mkconfig.in 2009-12-05 21:42:51.908543561 +0000
...
+++ grub2-1.97~beta4/util/grub-mkconfig_lib.in 2009-12-05 21:42:18.876544591 +0000
After:
Code:
+++ /usr/sbin/grub-mkconfig 2009-12-05 21:42:51.908543561 +0000
...
+++ /usr/lib/grub/grub-mkconfig_lib 2009-12-05 21:42:18.876544591 +0000
Once saved, you can apply the patch.
Code:
patch -p0 < legacy_detection.patch
It may give some feedback to you on "Hunk Succeeded", that is all OK. If it were to say "Hunk Failed", then you'd know that the patch didn't apply as expected.
Update Initramfs
Next, we hook btrfs into the boot process. It helps if btrfs-tools is installed first.
Code:
apt-get install btrfs-tools
Now we start creating our files.
First, is the hook
Code:
nano /usr/share/initramfs-tools/hooks/btrfs
Paste in the following contents and save.
Code:
#!/bin/sh -e
# initramfs hook for btrfs
if [ "$1" = "prereqs" ]; then
exit 0
fi
. /usr/share/initramfs-tools/hook-functions
if [ -x "`which btrfsctl`" ]; then
copy_exec "`which btrfsctl`" /sbin
fi
Second are the modules
Code:
nano /usr/share/initramfs-tools/modules.d/btrfs
Paste in the following contents and save.
Code:
# initramfs modules for btrfs
libcrc32c
crc32c
zlib_deflate
btrfs
Last is the Premount script.
Code:
nano /usr/share/initramfs-tools/scripts/local-premount/btrfs
Paste in the following contents and save.
Code:
#!/bin/sh -e
# initramfs script for btrfs
if [ "$1" = "prereqs" ]; then
exit 0
fi
modprobe btrfs
if [ -x /sbin/btrfsctl ]; then
/sbin/btrfsctl -a 2>/dev/null
fi
Then make the following files executable.
Code:
chmod +x /usr/share/initramfs-tools/scripts/local-premount/btrfs
chmod +x /usr/share/initramfs-tools/hooks/btrfs
And to round up the entire process, rebuild the ramdisk and update grub.
Code:
update-initramfs -u -k all
update-grub
Et Voila! We can now reboot our system.
When you boot up, you can see proof of your new btrfs system as per below!
Part 2: Usage
NOTE: If you are running on Karmic
To use some of the commands in this section, it's recommend that you acquire the latest release.
And if that isn't enough of an excuse, it's recommended because of the bug fixes too - see here.
I already have a repository setup for Karmic with the correct packages inside, feel free to add and install via the following method.
Code:
sudo add-apt-repository ppa:ibuclaw/ppa
sudo apt-get update
sudo apt-get install btrfs-tools btrfs-kernel-source
sudo update-initramfs -u -k all
sudo reboot
Once rebooted, I recommend running:
Code:
sudo btrfs-vol -b /
Before doing anything else. What this does, is a balance operation that reads in all of the FS data and metadata and rewrites it across the file system. As such, it may take some time.
OK, with that done, time to try out some of the cool things you can do.
Features List
Incremental backup and Writable snapshots
Snapshots are integrated into the file system with no extra work done. This means that you don't need to wait around for hours just for an image to be created, the snapshot acts more like a baseline, and changes to the Live System get written elsewhere on the disk whilst the Snapshot stays static.
To create a snapshot of the root subvolume.
Code:
cd /
sudo btrfsctl -s snapshot.root /
ls /snapshot.root
The first argument is the snapshot name, the second is the subvolume you wish to snapshot. The snapshot is created in the directory you are currently residing in.
And as an exercise you can try deleting and recovering files on your Desktop.
To recover, a simple 'cp -a' should do the trick, but rsync would be the better option.
Code:
sudo cp -a /snapshot.root/home/iain/Desktop ~/
Snapshots are writeable, meaning that you can instead change data in the snapshot without affecting the Live System also.
This can be useful for example, when you want to have a chroot for compiling, or running certain applications in their own environment.
Code:
sudo chroot /snapshot.root
If this is not the behaviour you wish to have, then you can chmod the directory to prevent normal users from tampering it.
Code:
sudo chmod 700 /snapshot.root
Lastly, to delete snapshots:
Code:
sudo btrfsctl -D snapshot.root /
The first argument is the snapshot name, the second is the path of the directory the snapshot resides in.
Subvolumes (separate internal file system roots)
Unlike snapshots, subvolumes are immutable, meaning that once you create one, it can't be removed unless you reformat the volume.
The best use I've found for subvolumes is to apply finer grain snapshots throughout the file system, rather than one great one for /.
One example can be the /home directory.
In recovery mode, this can be implemented with the following:
Code:
cd /
mv /home /home.old
btrfsctl -S home /
Then we set the correct permission for the subvolume (default is 700), and move our data in.
Code:
chmod 755 /home
mv /home.old/* /home
rmdir /home.old
Then to create a snapshot:
Code:
btrfsctl -s snapshot.home /home
ls /snapshot.home
Compression and other Mount options
Wouldn't recommend trying it yet (although I'm pretty certain I saw a speed increase after enabling it), but feel free to add compress to the fstab file.
Code:
UUID=4be84d08-94cb-4013-ae0b-ce1d72d96db1 / btrfs defaults,compress 0 1
And remount using:
Code:
sudo mount -o remount /
NOTE: The compress option is a type of smart compression, as in it was compress highly compressible files, but back off and blacklist incompressible content.
Also, please bare in mind the following caveats:
- If compression for a given set of pages fails to make them smaller, the file is flagged to avoid future compression attempts later. To get around this, there is 'compress_force' - which will force compression, even at horrendous cost to performance (thank-you jdong).
- The looking up of the actual size of the compressed file is currently unimplemented.
- With compression enabled, your system may deadlock all IO operations if under heavy read/write duty.
See here for more supported options: http://btrfs.wiki.kernel.org/index.p...#Mount_Options
Integrated multiple device support
Another cool feature is the ability to have a file system that spans two, or more partitions or devices.
If possible, try this nice exercise to see the before and after of the size of /
Code:
df -h /
sudo mkfs.btrfs /dev/sdb
sudo btrfs-vol -a /dev/sdb /
df -h /
And it should have increased!
To balance the load between the devices:
Code:
sudo btrfs-vol -b /
By default, meta data will be mirrored across two devices and file system data will be striped across all of the devices present.
Removing devices uses the same logic.
Code:
sudo btrfs-vol -r /dev/sdb /
df -h /
And notice that the size of / has now shrunk again.
For a more detailed look into it, see here.
Offline file system check
Self explanitory, really.
Code:
sudo btrfsck /dev/sda5
NOTE: btrfsck is NOT an online checker. IT IS OFFLINE ONLY, contrary to what the documentation said at one point. Running btrfsck online can lead to filesystem corruption! (thank-you for pointing this out jdong).
Online file system defragmentation
Lastly, the feature everyone has been waiting for...
The argument being the location of the subvolume you wish to defragment.
Quite boring, really. There is not even a progress bar. 
For more small hints that I have not included, see the Btrfs wiki at http://btrfs.wiki.kernel.org/
Part 3: Common Errors and HowTOs
Most pitfalls can be avoided if you treat your system as a stable one.
ie: Set it so your system only scans for Security Updates, and checks once every fortnight.
udev failing to configure
If you were to upgrade udev, at all, you will run into this.
At this point in time, I have no explanation for why this happens, but you will know what it is when you see it:
udevadm trigger is not permitted while udev is unconfigured.
udevadm settle is not permitted while udev is unconfigured.
Gave up waiting for root device.
If you get this then the only fix is to reinstall udev. Boot into LiveCD, open a terminal and mount all file systems:
Code:
sudo mount /dev/sda5 /mnt
sudo mount /dev/sda1 /mnt/boot
for fs in proc sys dev dev/pts; do sudo mount --bind /$fs /mnt/$fs; done
chroot into the file system
and reinstall.
Code:
aptitude reinstall udev
update-initramfs -u -k all
Then reboot, and everything should be resolved again.
Symlinks missing in /dev
Again, the cause of this is unknown, but it's effect does crop up from time to time with various applications complaining.
The workaround is to edit /etc/rc.local
Code:
sudo nano /etc/rc.local
And put in the following before exit 0
Code:
find /lib/udev/devices -type l -exec cp -a "{}" /dev/ \;
General Protection faults
This most likely happens when libraries have mysteriously become corrupt/altered.
See the below output for when X refused to start at one point:
[ 1 157.189485] Xorg[2309] general protection ip:4f6e1b sp:bfd1b32c error:0 in libc-2.10.1.so[413000+142000]
The workaround is just to reinstall the affected library, in my case, I ran:
Code:
sudo aptitude reinstall libc6 libc6-i686
GTK Themes Change After System Update
Not sure why this happens, but the GConf database goes corrupt sometimes after a big system update.
This is always rectified by running:
Code:
sudo gconftool-schemas --register-all
And a logout / login.
Separate Btrfs /home Subvolume
I covered the creation of subvolumes in this guide earlier. What I didn't cover was that you can use them similarly to actual partitions.
Going back on creating a subvolume for /home, You can also go on to create an entry in /etc/fstab for the new subvolume.
Code:
# / was on /dev/sda5 during installation
UUID=4be84d08-94cb-4013-ae0b-ce1d72d96db1 / btrfs defaults 0 1
# /home
UUID=4be84d08-94cb-4013-ae0b-ce1d72d96db1 /home btrfs defaults,subvol=home 0 1
And it will be mounted as a separate partition every time on boot.
This is useful for when, say, you need to boot into a recovery snapshot that doesn't include /home or some other need partition directories.
Epilogue
As I type this, I am sitting at a workstation with a Btrfs / installation of Ubuntu, compromised of two 250GB hard drives with the file system spanning across both in a RAID0 style format. As I never use this workstation often, I downloaded about 20GBs worth of native Linux games just for the odd occasions where I require some action to stimulate myself back into focus.
An interesting idea I conjured up whilst writing this (but haven't gotten round to testing yet), is that it may be possible to have separate installations of Linux inside their own snapshots/subvolumes.
Which is cool - not quite amazing yet, but cool. I have always find an enjoyment in using fringe and bleeding edge technology, it's like looking at a mirror which reflects back a vision of the world some time in the future. Using Btrfs over the past 3 months has convinced me enough to convert all my workstations to it - with the exception of my Netbook. I kind of see Ext4 as just another file system to get by on, whereas Btrfs is a tool to get work done on. And while the occasional fun hiccup occurs, I shall always regard this file system as a glimpse of what is to come...
Tips and Suggestions welcome.
Adv Reply
Originally Posted by marksquare
Bookmarks