utilities/btrfs-list
utilities/btrfs-list
1
0
Fork 0
mirror of https://github.com/speed47/btrfs-list synced 2024-06-28 22:14:36 +00:00
Code Issues Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Stéphane Lesimple 2022-01-03 18:50:55 +01:00
parent 4f286276f9
commit fcf4a98f85
2 changed files with 97 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
README.md
View File

@ -4,10 +4,11 @@ Btrfs is a great filesystem, but its userland tools are not very user-frienfly y
As a long-time user, I've developed `btrfs-list` as a wrapper to make sense out of the `btrfs sub list` and `btrfs qgroup show` commands.
You need `btrfs-list` if either:
- You'd like to have a nice overview of your subvolumes/snapshots
- You'd like to have a nice tree-style overview of your subvolumes/snapshots
- You've already used ZFS before and you're missing the _zfs list_ command
- You're looking for exactly which snapshot to destroy to regain some space
- You're looking for a more accurate estimation of how much space is remaining on your FS for all btrfs supported data profiles, as corner cases of raid1/raid10 are not handled well by _btrfs-progs_, and raid5/raid6 are not implemented at all yet
- You're using `btrfs-progs` < v5.7 and you're looking for a more accurate estimation of how much space is remaining on your FS for all btrfs supported data profiles,
as corner cases of raid1/raid10 are not handled well by older versions of `btrfs-progs`, and raid5/raid6 were not implemented at all
Basically it turns this:
![btrfs_sub_list](https://user-images.githubusercontent.com/218502/53362053-99564e00-3939-11e9-9072-1d9ef617971f.PNG)
@ -73,7 +74,94 @@ SIZE can be a number (in bytes), or a number followed by k, M, G, T or P.
# Examples
## Display heavy snapshots
## Quick view
```
root@nas:~# btrfs-list /git
NAME TYPE REFER EXCL MOUNTPOINT
git fs - 58.96G (single, 17.27G free)
[main] mainvol 60.61G 292.00k /git
.beeshome subvol 56.64M 56.64M
.snaps/20220103_005415_daily.0 rosnap 60.54G 144.00k
.snaps/20220101_004815_daily.2 rosnap 60.42G 160.00k
.snaps/20211229_004815_daily.5 rosnap 60.42G 160.00k
.snaps/20220102_005203_daily.1 rosnap 60.42G 160.00k
.snaps/20220103_114214_hourly.6 rosnap 60.54G 144.00k
.snaps/20220103_154814_hourly.2 rosnap 60.61G 144.00k
.snaps/20220103_175114_hourly.0 rosnap 60.61G 144.00k
.snaps/20211230_004815_daily.4 rosnap 60.42G 160.00k
.snaps/20211231_004815_daily.3 rosnap 60.42G 160.00k
.snaps/20220103_144814_hourly.3 rosnap 60.61G 144.00k
.snaps/20220103_164815_hourly.1 rosnap 60.61G 144.00k
.snaps/20220103_124215_hourly.5 rosnap 60.54G 2.23M
.snaps/20220103_134556_hourly.4 rosnap 60.60G 480.00k
.snaps/20220103_104215_hourly.7 rosnap 60.54G 144.00k
```
## Detailed view
```
root@nas:/mnt/b# btrfs-list -qad .
NAME ID PARENT TOPLVL GEN CGEN UUID PARENTUUID RCVD_UUID OTIME TYPE EXCL MOUNTPOINT
7cb8325f - - - - - - - - - fs 157.00M (raid5, 3.59G free, 2.74G unallocatable)
[main] 5 - - - - - - - - mainvol - /mnt/b
sub1 258 5 5 21 8 ae9c..6cae - - - subvol -
sub1/.snap1 259 258 258 9 9 2d50..2094 ae9c..6cae - 2022-01-03 18:39:48 snap -
sub1/.snap2 260 258 258 10 10 a2e9..1431 ae9c..6cae - 2022-01-03 18:39:48 snap -
sub1/.snap3 270 258 258 20 20 b054..6ce2 ae9c..6cae - 2022-01-03 18:41:26 snap -
sub1/.snap4 271 258 258 21 21 ae07..cc69 ae9c..6cae - 2022-01-03 18:41:27 snap -
sub1/subsub1 261 258 258 14 11 bdf1..e7fe - - - subvol -
sub1/subsub1/.snapA1 262 261 261 12 12 ab9b..e6df bdf1..e7fe - 2022-01-03 18:40:09 snap -
sub1/subsub1/.snapA2 263 261 261 13 13 407c..1a14 bdf1..e7fe - 2022-01-03 18:40:09 snap -
sub2 265 5 5 19 15 bc35..8104 - - - subvol -
sub3 266 5 5 17 16 eb52..da06 - - - subvol -
sub3/subsub3 267 266 266 32 17 eb81..00af - - - subvol -
sub3-snaps/.snapK 280 279 279 30 30 41b9..442a eb81..00af - 2022-01-03 18:43:25 snap -
sub3-snaps/.snapL 281 279 279 31 31 3308..f953 eb81..00af - 2022-01-03 18:43:25 snap -
sub2/subsub2 268 265 265 28 18 2189..08b4 - - - subvol -
sub2/subsub2/.snapB 269 268 268 19 19 259d..0afd 2189..08b4 - 2022-01-03 18:41:15 snap -
sub2/subsub2/.snapC 272 268 268 24 22 8ae4..1313 2189..08b4 - 2022-01-03 18:41:49 snap -
sub2/subsub2/.snapB-backup 294 268 268 24 24 fe27..2169 259d..0afd - 2022-01-03 18:42:05 snap -
sub2/subsub2/.snapC-backup 274 268 268 24 24 da86..1964 8ae4..1313 - 2022-01-03 18:42:03 snap -
sub2/subsub2/.snapD 273 268 268 23 23 713f..6a28 2189..08b4 - 2022-01-03 18:41:50 snap -
sub2-snaps/.snapX 276 275 275 26 26 97ef..7187 2189..08b4 - 2022-01-03 18:43:04 snap -
sub2-snaps/.snapZ 278 275 275 28 28 4c08..f7fb 2189..08b4 - 2022-01-03 18:43:06 snap -
sub2-snaps 275 5 5 28 25 3ce4..2ae3 - - - subvol -
sub3-snaps 279 5 5 32 29 05c9..0620 - - - subvol -
sub4-snaps 284 5 5 37 34 2366..b451 - - - subvol -
(deleted) - - - - - 05eb..d578 - - - deleted -
sub4-snaps/sub4-bkp1 285 284 284 35 35 0134..77cb 05eb..d578 - 2022-01-03 18:45:11 snap -
sub4-snaps/sub4-bkp2 286 284 284 36 36 587b..e3e0 05eb..d578 - 2022-01-03 18:45:11 snap -
sub4-snaps/sub4-bkp3 287 284 284 37 37 55eb..e32e 05eb..d578 - 2022-01-03 18:45:12 snap -
```
Note that the hierarchy here is the hierarchy between the subvolumes and snapshots, not the folder hierarchy.
This is why for example `sub3-snaps/.snapK` is under `sub3/subsub3`, because it is a snapshot of this subvolume,
even if in the folder hierarchy, it is under `sub3-snaps`.
Same goes for `.snapD` and `.snapX`, these are at a different spot in the folder hierarchy, but both are snapshots
of the `sub2/subsub2` subvolume, hence are placed under it.
We also have 3 snapshots of a `(deleted)` subvolume, these ghosts subvolumes are shown with the option `-d`.
## View free space of all btrfs filesystems at a glance
```
root@nas:/tmp/md5# btrfs-list -f
NAME TYPE EXCL MOUNTPOINT
var fs 18.09G (single, 5.62G free)
root fs 950.39M (single, 36.61M free)
newtank fs 15.61T (raid1, 764.30G free)
git fs 58.96G (single, 17.27G free)
opt fs 1.11G (single, 668.23M free)
incoming fs 26.18T (single, 1.07T free)
7cb8325f fs 157.00M (raid5, 3.59G free, 2.74G unallocatable)
home fs 13.64G (single, 5.99G free)
slash fs 19.80G (single, 11.70G free)
varlog fs 12.26G (single, 3.96G free)
```
## Display heavy snapshots only
```
root@nas:~# btrfs-list --snap-min-excl 4G --snap-only /tank
@ -90,54 +178,11 @@ NAME TYPE REFER
.syncthing-bkp rosnap 40.48G 8.15G
```
## Display verbose information
```
root@nas:~# btrfs-list --show-all /mnt/a
NAME ID GEN CGEN UUID TYPE REFER EXCL MOUNTPOINT
203be355 -1 - - - fs - 134.09M (868.78M free)
[main] 5 - - - mainvol 16.00k 16.00k
sub1 256 23 6 7e5e30e0-4e68-da46-aa38-381048b0a794 subvol 33.02M 16.00k /mnt/a/test
sub1/.snap1 257 7 7 c8b1b7c9-26e0-b346-858f-a37d346ce8b6 snap 16.00k 16.00k
sub1/.snap2 259 8 8 dbf3e766-0a47-d24b-914e-246cc24f6b6a snap 10.02M 16.00k
sub1/subsub1 260 29 9 f3dfc28f-84a4-6a43-8e2c-c5163d134e52 snap 16.02M 16.00k /mnt/a
sub1/subsub1/.snapA1 263 12 12 728b929f-8c33-d541-806d-94871eaa75a6 snap 47.02M 31.02M
sub1/subsub1/.snapA2 265 14 14 45281588-176e-7e4c-9d9b-79375cfcb6f3 snap 47.02M 16.00k
subroot 266 15 15 66a0de92-f6c3-c441-8b18-1110b5b89a0e snap 47.02M 16.00k
sub1/subsub1/.snapA3 268 17 17 6e19b614-e6b6-a945-9ea6-1857329d8d06 snap 16.02M 16.00k
sub1/.snap3 261 10 10 196f1987-161e-a644-b9f9-abcf406bdabd snap 26.02M 16.00k
sub1/.snap4 262 11 11 41c86ef5-09ec-2449-aa70-d963430c7b1b snap 49.02M 23.02M
sub1/.snap5 264 13 13 7c53673b-c078-834e-97f3-1e07a2a6cf77 snap 49.02M 16.00k
sub1/.snap6 267 16 16 6bfd05d5-bc7e-5d40-aeda-81764c6c5b2b snap 33.02M 16.00k
snapq222 269 22 21 12005af8-92b4-0646-a4fa-4ff1480797ee snap 33.03M 32.00k
snapmulti 270 23 22 628a9b53-003c-fb40-be89-eee5bbbbeb42 snap 33.03M 32.00k
```
## Get accurate free space amount
For some configurations, `btrfs filesystem usage` *Free (estimated)* section is misleading, for example in a 5-devices RAID1 setup with 4 devices of 133M and 1 device of 500M:
Note: this is fixed with recent versions of `btrfs-progs` (v5.7 onwards), but we'll keep this feature to continue
supporting older releases of `btrfs-progs` if for some reason you're stuck with older versions.
```
root@nas:~# btrfs-list /mnt/a
NAME TYPE REFER EXCL MOUNTPOINT
8c4ca5e5 fs - 0.00 (456.44M free) (418.00M realfree)
[main] mainvol 16.00k 16.00k /mnt/a
```
The *free* amount is reported by `btrfs filesystem usage`, the *realfree* is the adjusted amount by `btrfs-list`. Let's verify that we got it right:
```
root@nas:~# dd if=/dev/urandom of=/mnt/a/big
dd: writing to '/mnt/a/big': No space left on device
853114+0 records in
853113+0 records out
436793856 bytes (437 MB, 417 MiB) copied, 3.55206 s, 123 MB/s
root@nas:~# ls -lh /mnt/a/big
-rw-r--r-- 1 root root 417M Mar 2 19:31 /mnt/a/big
root@nas:~# btrfs-list /mnt/a
NAME TYPE REFER EXCL MOUNTPOINT
8c4ca5e5 fs - 416.56M (39.88M free) (320.00k realfree)
[main] mainvol 416.58M 416.58M /mnt/a
```
For RAID5/6 setups, old versions of `btrfs filesystem usage` always display 0 bytes in the *Free (estimated)* section,
and you have no way to know the free space of your filesystem. `btrfs-list` handles this transparently by doing
the calculations needed to report the proper amount of free space, even in RAID5/6 setups.

2
btrfs-list
View File

@ -3,7 +3,7 @@
#
# SPDX-License-Identifier: GPL-2.0-only
#
# btrfs-list: a wrapper to btrfs-progs to show a nice overview of your btrfs subvolumes and snapshots, a la 'zfs list'
# btrfs-list: a wrapper to btrfs-progs to show a nice tree-style overview of your btrfs subvolumes and snapshots, a la 'zfs list'
#
# Check for the latest version at:
# https://github.com/speed47/btrfs-list