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 setsansible_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.
-
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>
wherecan be either `/dev/sdb` or `/dev/sdc`.
-
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.
-
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.
-
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.
-
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.
-
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
- Managing the Btrfs File System
- Oracle Linux Documentation
- Oracle Linux Training
- Oracle Linux Training Station
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.
Get Started With the Btrfs File System on Oracle Linux
F49219-07
August 2024