Note:

This tutorial is available in an Oracle-provided free lab environment.
It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Get Started With the Btrfs File System on Oracle Linux

Introduction

The Btrfs file system provides the capacity to handle pooling, snapshots, checksums, and multi-device spanning in existing Linux file systems. For an overview of the Btrfs file system and its features, see Oracle Linux: Managing Local File Systems.

This tutorial describes setting up a directory on external storage on your Oracle Linux system to use the Btrfs file system.

Objectives

In this tutorial, you will learn how to:

Create a Btrfs file system
Run basic Btrfs commands to perform tasks such as:
- Checking file system usage
- Extend the size of the file system
- Recover a missing device
Test and see how the file system works

Prerequisites

Minimum of a single Oracle Linux system running the UEK kernel
Each system should have Oracle Linux installed and configured with:
- A non-root user account with sudo access
- Access to the Internet

Deploy Oracle Linux

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/ol
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e add_block_storage=true -e block_count=4
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.

The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.

Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Check the Installation of the Btrfs Packages

Open a terminal and connect via SSH to the ol-node-01 instance.
```
ssh oracle@<ip_address_of_instance>
```
Check whether the system contains the btrfs-progs package.
```
dnf list installed | grep btrfs-progs
```
If the package is not in the system, install it and its dependent packages.
```
sudo dnf install -y btrfs-progs
```

Create the Btrfs File System

Check the devices that you would use for the file system.
```
lsblk
```
Your lab instance includes the following additional block volumes:
- /dev/sdb
- /dev/sdc
- /dev/sdd
- /dev/sde
Run the following command to create the Btrfs file system.
```
sudo mkfs.btrfs /dev/sdb /dev/sdc
```
In the output, the Devices section lists the two devices used to create the file system. By default, the command configures the file system with Raid 0 to stripe the data and Raid 1 to mirror the metadata.
Create a directory on which to mount the file system.
```
sudo mkdir /data
```
Mount the file system.
```
sudo mount /dev/sdb /data
```
Verify the file system configuration.
```
sudo btrfs filesystem usage /data
```
Alternatively, you can also type:
```
sudo btrfs filesystem df /data
```
Make the file system mount automatically on reboot.
1. Get the Btrfs UUID.
```
sudo btrfs filesystem show
```
  Note that /dev/sdb and /dev/sdc have identical UIDs. You can further verify their identical UIDs with either of the following commands:
  - lsblk -o NAME,UUID,MOUNTPOINT
  - sudo blkid -s UUID -o value <device-name> where can be either `/dev/sdb` or `/dev/sdc`.
2. Add the following line to the /etc/fstab file:
  
  <UUID> /data btrfs defaults 0 0
  
  Note: You can add the line by using the tee command as follows:
```
echo "UUID=$(sudo blkid -s UUID -o value /dev/sdc) /data btrfs defaults 0 0" | sudo tee -a /etc/fstab
```

Test the New File System

Create a file in /data.
```
sudo fallocate -l 5G /data/test1.img
```
Check the file system usage due to the new file.
```
sudo btrfs filesystem usage /data
```
Part of the output indicates that the file in /data is now striped across the two devices:

Data,single: Size:5.01GiB, Used:5.00GiB (99.87%)

/dev/sdb 2.01Gib /dev/sdc 3.00Gib

Extend the Btrfs File System

Add the /dev/sdd device to the file system.
```
sudo btrfs device add /dev/sdd /data
```
View the new file system configuration.
```
sudo btrfs filesystem usage /data
```
The Unallocated section of the output includes the new device you just added.

Unallocated:

/dev/sdb 46.98GiB /dev/sdc 45.99GiB /dev/sdd 50.00GiB
Reconfigure /data to use the new file system configuration.

While the file system has expanded, /data is still distributed based on the previous configuration. This step adjusts the directory to the new configuration.
```
sudo btrfs balance start --bg /data
```
The --bg option causes the process to run in the background.
To monitor the progress of the operation, issue one of the following commands:

Note: The balance operation might take about 7 minutes to complete. Only proceed to the next step once monitoring indicates the completion of the process.
1. To check the progress at a point in time in the process, type:
```
sudo btrfs balance status /data
```
  The output specifies the percentage of completion. If the operation completes, then the command output shows No balance found on /data.
2. To run continuous monitoring, type:
```
sudo watch -t -n5 btrfs balance status /data
```
  The screen periodically displays the percentage of completion of the process, for example, 2 out of about 8 chunks balanced (3 considered), 75% left.
  
  At the end of the process, the output reports No balance found on /data.
  
  Press Ctrl+C to exit real-time monitoring.
Check the results of the balance process.
```
sudo btrfs filesystem usage /data
```
Part of the output indicates that /data is now striped across the three devices:

Data,single: Size:11.00GiB, Used:10.00GiB (90.91%)

/dev/sdb 2.00Gib /dev/sdc 1.00Gib /dev/sdd 3.00Gib

Recover the File System After a Device Loss

To complete the exercise in this section, a scenario in which a device is lost due to a hardware failure is created.

Simulate a Failure

Detach the /dev/sdd device with the following command:
```
echo 1 | sudo tee /sys/block/sdd/device/delete
```
Check the status of the file system.
```
sudo btrfs filesystem show
```
The output reports some missing devices.
Determine which device is missing.
```
sudo btrfs filesystem usage /data
```
By comparing the command output with the previous filesystem show command, you can identify /dev/sdd as the missing device.

Perform a Recovery Operation

Remount the file system in degraded mode.

sudo mount -o remount,rw,degraded /data

Replace the missing device.
```
sudo btrfs replace start -r 3 /dev/sde /data
```
You specify -r 3 based on the original configuration of 3 devices.
Check the status of the replacement process.
```
sudo btrfs replace status /data
```
The command periodically displays the percentage of process completion, such as 2.0 done, 0 write errs, 0 uncorr. read errs.

The process takes about 5 minutes to complete. At its completion, a notification similar to the following displays:

Started on 30.Sep 16:32:17, finished on 30.Sep 16:40:06, 0 write errs, 0 uncorr. read errs
Check the file system status.
```
sudo btrfs filesystem show
```
The list of devices now includes /dev/sde.
Reconfigure /data to use the new file system configuration.
```
sudo btrfs balance start --bg /data
```
To monitor the progress of the balancing operation, issue one of the following commands:

Note: The balance operation might take about 7 minutes to complete. Only proceed to the next step once monitoring indicates the completion of the process.
1. To check the progress at a point in time in the process, type:
```
sudo btrfs balance status /data
```
  The output specifies the percentage of completion. If the operation completes, then the command output shows No balance found on /data.
2. To run continuous monitoring, type:
```
sudo watch -t -n5 btrfs balance status /data
```
  The screen periodically displays the percentage of completion of the process, for example, 2 out of about 8 chunks balanced (3 considered), 75% left.
  
  At the end of the process, the output reports No balance found on /data.
  
  Press Ctrl+C to exit real-time monitoring.
Check the results of the balance process.
```
sudo btrfs filesystem usage /data
```
The output shows that /data is now striped across /dev/sdb, /dev/sdc, and /dev/sde.

Summary

That completes our introduction to using Btrfs and the capabilities of using and extending the filesystem. Check out our other Btrfs content available on the Oracle Linux Training Station.

For More Information

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

Title and Copyright Information

Get Started With the Btrfs File System on Oracle Linux

F49219-07

August 2024

Oracle and/or its affiliates.