# BTRFS

## Table of Contents

- [BTRFS](#btrfs)
  - [Table of Contents](#table-of-contents)
  - [Placeholders](#placeholders)
  - [BTRFS Command Shorthands](#btrfs-command-shorthands)
  - [Information on Filesystem](#information-on-filesystem)
  - [Drive Manipulation](#drive-manipulation)
    - [Replace Drives](#replace-drives)
  - [Filesystem Manipulation](#filesystem-manipulation)
    - [Upgrading Btrfs Block Group Cache to V2](#upgrading-btrfs-block-group-cache-to-v2)
    - [Defrag](#defrag)
  - [Balances](#balances)
  - [Scrub](#scrub)
  - [Snapshots](#snapshots)
    - [Create Snapshots](#create-snapshots)
    - [Delete Snapshots](#delete-snapshots)
  - [Backup Procedures](#backup-procedures)
  - [Recovery](#recovery)

## Placeholders

Replace the placeholders below with the appropriate values for your setup:

- **Devices**
  - Block device: `<device>` (e.g., /dev/sda)
  - Source device to replace: `<source-device>` (e.g., /dev/sdb)
  - Target device: `<target-device>` (e.g., /dev/sdc)
  - UUID: `<uuid>` (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)

- **Paths**
  - Mount point: `<mountpoint>` (e.g., /mnt/media)
  - Subvolume name: `<subvolume>` (e.g., root, home, backups, snapshots)
  - Subvolume ID: `<subvolume-id>` (e.g., 257)
  - Snapshot label: `<snapshot-label>` (e.g., 2024-09-15)

## BTRFS Command Shorthands

Most `btrfs` subcommands accept shortened aliases. The table below lists the common ones used throughout this document.

| Long form                     | Short form              |
| ----------------------------- | ----------------------- |
| `btrfs filesystem`            | `btrfs fi`              |
| `btrfs filesystem show`       | `btrfs fi show`         |
| `btrfs filesystem usage`      | `btrfs fi usage`        |
| `btrfs filesystem df`         | `btrfs fi df`           |
| `btrfs filesystem resize`     | `btrfs fi resize`       |
| `btrfs filesystem defragment` | `btrfs fi defrag`       |
| `btrfs subvolume`             | `btrfs sub`             |
| `btrfs subvolume list`        | `btrfs sub list`        |
| `btrfs subvolume snapshot`    | `btrfs sub snap`        |
| `btrfs subvolume delete`      | `btrfs sub del`         |
| `btrfs subvolume get-default` | `btrfs sub get-default` |
| `btrfs subvolume set-default` | `btrfs sub set-default` |
| `btrfs device`                | `btrfs dev`             |
| `btrfs device add`            | `btrfs dev add`         |
| `btrfs device usage`          | `btrfs dev usage`       |
| `btrfs device stats`          | `btrfs dev stats`       |
| `btrfs balance start`         | `btrfs bal start`       |
| `btrfs balance status`        | `btrfs bal status`      |
| `btrfs balance cancel`        | `btrfs bal cancel`      |
| `btrfs inspect-internal`      | `btrfs insp`            |

## Information on Filesystem

**Show Basic Filesystem Information**

Display basic information (size, IDs, paths, etc.) for the specified mountpoint:

```bash
btrfs fi show <mountpoint>
```

**Display detailed usage information**

To show detailed usage information (allocated, unallocated, free, used, etc.) for the specified mountpoint:

```bash
btrfs fi usage <mountpoint>
```

**Display detailed usage information as a table**

```bash
btrfs fi usage -T <mountpoint>
```

- `-T` The tabular flag gives you a nice grid that shows exactly how much Data, Metadata, and System space is allocated per device.

**Display Detailed Allocation Information**

View block groups and used space:

```bash
btrfs fi df <mountpoint>
```

**Get Detailed Device Usage Statistics**

Physical size, unallocated space, RAID levels, etc.:

```bash
btrfs device usage <mountpoint>
```

**Scan and Display BTRFS Information**

Scan all devices or a specific drive:

```bash
btrfs device scan <device>
```

**Retrieve Statistics and Error Information**

Read errors, write errors, flush errors, etc.:

```bash
btrfs device stats <mountpoint>
```

**List BTRFS Subvolumes**

```bash
btrfs subvolume list <mountpoint>
```

**Default Subvolume**

Check if a non-standard subvolume is set as the default:

```bash
btrfs subvol get-default <mountpoint>
btrfs subvol list <mountpoint>
```

Change the default subvolume:

```bash
btrfs subvol set-default <subvolume-id> <mountpoint>
```

**Verify Current Cache Version**

Check if your filesystem is using cache V1 by device:

```bash
btrfs inspect-internal dump-super -f <device> | grep cache_generation
```

By UUID:

```bash
btrfs inspect-internal dump-super -f $(blkid -U <uuid>) | grep cache_generation
```

- If `cache_generation` is present, cache V1 is in use. If absent, the filesystem is already using V2.

## Drive Manipulation

**Mount Whole Drive**

```bash
mount UUID=<uuid> <mountpoint>
```

**Mount Subvolume by Name**

```bash
mount UUID=<uuid> -o subvol=<subvolume> <mountpoint>
```

**Mount Subvolume by ID**

```bash
btrfs subvol list /
mount -o subvolid=<subvolume-id> /dev/disk/by-uuid/<uuid> <mountpoint>
```

**Add a New Drive**

```bash
btrfs device add <device> <mountpoint>
```

**Resize Filesystem**

Grow the filesystem on a specific device to its maximum:

```bash
btrfs filesystem resize 1:max <mountpoint>
```

**Create Subvolumes**

```bash
btrfs subvol create <mountpoint>/<subvolume>
```

### Replace Drives

**Start the replacement process:**

Copies data from the old drive to the new drive while the filesystem remains mounted:

```bash
btrfs replace start <source-device> <target-device> <mountpoint>
```

- `<source-device>`: Drive to be replaced.
- `<target-device>`: Drive to replace it with.
- `<mountpoint>`: Mount point of the BTRFS filesystem.

**Monitor the progress:**

```bash
btrfs replace status <mountpoint>
```

**Monitor progress interactively:**

```bash
btrfs replace status -i <mountpoint>
```

- `-i`: Updates progress in real time.

**Notes:**

- `btrfs replace` works on a live mounted filesystem — no unmounting required.
- Useful for both failing drive replacement and capacity upgrades.
- Ensure the target drive has enough space to accommodate the source data.

## Filesystem Manipulation

### Upgrading Btrfs Block Group Cache to V2

**Non-root filesystems (running system):**

```bash
mount -o remount,clear_cache,space_cache=v2 <mountpoint>
```

**Root filesystem (running system):**

1. Check if using cache V1:

   ```bash
   btrfs inspect-internal dump-super -f <device> | grep cache_generation
   ```

2. Enable cache V2 via GRUB:

   ```bash
   nano /etc/default/grub
   # Add to GRUB_CMDLINE_LINUX_DEFAULT or GRUB_CMDLINE_LINUX:
   # rootflags=clear_cache,space_cache=v2
   ```

   Example:

   ```bash
   GRUB_CMDLINE_LINUX_DEFAULT="quiet splash rootflags=clear_cache,space_cache=v2"
   ```

   ```bash
   update-grub
   reboot
   ```

3. Verify the change:

   ```bash
   btrfs inspect-internal dump-super -f <device> | grep cache_generation
   ```

4. Remove `clear_cache` from GRUB after confirming:

   ```bash
   nano /etc/default/grub
   # Remove clear_cache from rootflags, then:
   update-grub
   ```

**From a live system:**

```bash
apt update
apt install btrfs-progs
lsblk -o NAME,UUID
blkid
mount -o clear_cache,space_cache=v2 /dev/disk/by-uuid/<uuid> <mountpoint>
btrfs inspect-internal dump-super -f /dev/disk/by-uuid/<uuid> | grep cache_generation
umount <mountpoint>
```

### Defrag

```bash
btrfs filesystem defrag -r -v -clzo <mountpoint>
```

- `-r`: Recursive.
- `-v`: Verbose.
- `-clzo`: Optional LZO compression to save space.

## Balances

**Full balance on nearly empty block groups:**

```bash
btrfs balance start --full-balance -dusage=0 -musage=0 <mountpoint>
```

- `--full-balance`: Default but with a warning if not specified.
- `-dusage=0`: Only balance data block groups that are ~0% full.
- `-musage=0`: Only balance metadata block groups that are ~0% full.

**Full balance on partially used block groups:**

```bash
btrfs balance start --full-balance -dusage=50 -musage=50 <mountpoint>
```

- `-dusage=50`: Include data block groups less than 50% full.
- `-musage=50`: Include metadata block groups less than 50% full.

**Balance data in the background:**

```bash
btrfs balance start --bg -d <mountpoint>
```

**Balance metadata in the background:**

```bash
btrfs balance start --bg -m <mountpoint>
```

**Balance data and metadata in the background:**

```bash
btrfs balance start --bg --full-balance -dusage=0 -musage=0 <mountpoint>
```

**Balance a limited number of chunks:**

```bash
btrfs balance start --bg -dlimit=100 <mountpoint>
```

**Cancel a balance:**

```bash
btrfs balance cancel <mountpoint>
```

**Monitor balance status:**

```bash
btrfs balance status <mountpoint>
```

## Scrub

**Start a scrub**

The scrub operation verifies data integrity against checksums

```bash
btrfs scrub start <mountpoint>
```

**Check scrub status:**

```bash
btrfs scrub status <mountpoint>
```

**Cancel a scrub:**

```bash
btrfs scrub cancel <mountpoint>
```

## Snapshots

### Create Snapshots

1. **Mount the snapshots subvolume:**

   ```bash
   mount UUID=<uuid> -o subvol=snapshots <mountpoint>
   ```

2. **Create a snapshot:**

   ```bash
   btrfs subvolume snapshot <source-subvolume> "<mountpoint>/<snapshot-label>"
   ```

3. **Unmount after creating:**

   ```bash
   umount <mountpoint>
   ```

### Delete Snapshots

1. **Mount the snapshots subvolume:**

   ```bash
   mount -o subvol=snapshots /dev/disk/by-uuid/<uuid> <mountpoint>
   ```

2. **List available snapshots:**

   ```bash
   btrfs subvol list <mountpoint>
   ```

3. **Delete the desired snapshot:**

   ```bash
   btrfs subvolume delete <mountpoint>/<snapshot-label>
   ```

4. **Unmount after deleting:**

   ```bash
   umount <mountpoint>
   ```

## Backup Procedures

**Snapshot backup procedure:**

1. Mount snapshot location:

   ```bash
   mount UUID=<uuid> -o subvol=snapshots <mountpoint>
   ```

2. Create snapshots for the desired subvolumes:

   ```bash
   btrfs subvolume snapshot / "<mountpoint>/root/<snapshot-label>"
   btrfs subvolume snapshot /home "<mountpoint>/home/<snapshot-label>"
   btrfs subvolume snapshot <source-subvolume> "<mountpoint>/<subvolume>/<snapshot-label>"
   ```

3. Unmount after creating snapshots:

   ```bash
   umount <mountpoint>
   ```

## Recovery

1. **Mount a Subvolume with Recovery Options:**

   ```bash
   mount -o recovery,subvol=<subvolume> UUID=<uuid> <mountpoint>
   ```

2. **Clear Cache During Mount:**

   ```bash
   mount -o clear_cache,subvol=<subvolume> UUID=<uuid> <mountpoint>
   ```

3. **Data Restoration with btrfs restore:**

   ```bash
   btrfs restore -D <device>
   ```