speed47 / btrfs-list Goto Github PK

Get a nice tree-style view of your btrfs subvolumes/snapshots, including their size, a la 'zfs list'

Perl 100.00%

btrfs btrfs-snapshots btrfs-progs btrfs-tools

btrfs-list's Introduction

Overview

Btrfs is a great filesystem, but its userland tools are not very user-friendly yet. 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 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 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: into this:

Prerequisites

btrfs-progs v3.18 at least (Dec 2014)
The quota feature enabled on your Btrfs filesystems (optional, to get space usage for subvolumes and snapshots)

Usage

Usage: btrfs-list [options] [mountpoint1 [mountpoint2 [...]]]

If no mountpoints are specified, display info for all btrfs filesystems.

  -h, --help                 display this message
      --debug                enable debug output
  -q, --quiet                silence quota disabled & quota rescan warnings,
                               repeat to silence all other warnings.
      --version              display version info
      --color WHEN           colorize the output; WHEN can be 'never',
                               'always', or 'auto' (default is:
                               colorize if STDOUT is a term)
  -n, --no-color             synonym of --color=never
      --bright               use bright colors (better for dark terminals)
  -H, --no-header            hide header from output
  -r, --raw                  show raw numbers instead of human-readable
      --btrfs-binary BIN     path to the btrfs binary to use instead of using
                               the first binary found in the PATH
      --ignore-version-check try to continue even if btrfs-progs seems too old
      --ignore-root-check    try to continue even if we are not root

  -s, --hide-snap            hide all snapshots
  -S, --snap-only            only show snapshots
  -d, --deleted              show deleted parents of orphaned snapshots
      --snap-min-excl SIZE   hide snapshots whose exclusively allocated extents
                               take up less space than SIZE
      --snap-max-excl SIZE   hide snapshots whose exclusively allocated extents
                               take up more space than SIZE
  -f, --free-space           only show free space on the filesystem
  -u, --used                 display used space instead of free space

  -p, --profile PROFILE      override data profile detection and consider it
                                as 'dup', 'single', 'raid0', 'raid1',
                                'raid1c3', 'raid1c4', 'raid10', 'raid5' or
                               'raid6' for free space calculation

  -a, --show-all             show all information for each item
      --show-gen             show generation of each item
      --show-cgen            show generation at creation of each item
      --show-id              show id of each item
      --show-parent          show parent id of each item
      --show-toplevel        show top level of each item
      --show-uuid            show uuid of each item
      --show-puuid           show parent uuid of each item
      --show-ruuid           show received uuid of each item
      --show-otime           show snap creation time

  -w, --wide                 don't truncate uuids on output (this is the
                               default if STDOUT is NOT a term)
      --no-wide              always truncate uuids on output (useful to
                               override above default)
      --max-name-len LEN     trim long subvol names to LEN. 0 means never trim.
                               Defaults to 80 if STDOUT is a term, 0 otherwise.
      --indent LEN           number of spaces to indent the tree, default: 3.

SIZE can be a number (in bytes), or a number followed by k, M, G, T or P.

Examples

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
NAME                                                          TYPE     REFER      EXCL MOUNTPOINT
      backups/.snaps/skyline/20130213_231649_lastskyline    rosnap    22.52G    19.58G
      backups/.snaps/box/20171231_221207_monthly.12         rosnap    88.73G     4.96G
      backups/.snaps/box/20180130_221209_monthly.11         rosnap    91.25G     4.90G
      backups/.snaps/box/20180307_154215_monthly.10         rosnap    96.28G    10.72G
      backups/.snaps/box/20190120_193004_weekly.3           rosnap    56.45G     4.25G
      backups/.snaps/nasroot/20180122_091325_monthly.12     rosnap    34.65G    10.79G
      backups/.snaps/nasroot/20180221_092311_monthly.11     rosnap    31.96G     4.98G
      backups/.snaps/nasroot/20180323_092734_monthly.10     rosnap    33.69G     7.05G
      backups/.snaps/nasroot/20180820_205559_monthly.5      rosnap    31.74G     5.37G
      .syncthing-bkp                                        rosnap    40.48G     8.15G

Get accurate free space amount

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.

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.

btrfs-list's People

Contributors

Stargazers

Watchers

Forkers

amc90 johanvdw turkerali benedridge

btrfs-list's Issues

screenshots

UUIDs not shown

UUIDs are not shown.

└> sudo btrfs filesystem show
Label: 'label'  uuid: bd56f0a1-b50b-49a3-846b-f3f9b6fbe5a3
        Total devices 1 FS bytes used 2.53TiB
        devid    1 size 3.64TiB used 2.57TiB path /dev/sdc

versus

└> sudo ./btrfs-list -q -a 
NAME      ID PARENT TOPLVL GEN CGEN       UUID PARENTUUID  RCVD_UUID                OTIME    TYPE     EXCL  MOUNTPOINT
label    -      -      -   -    -          -          -          -                    -      fs    2.53T (single/dup, 1.10T/3.64T free, 30.27%)
    [main]  5      -      -   -    -          -          -          -                    - mainvol       -  /media/user/label

Insecure $ENV{ENV} while running with -T switch at /usr/share/perl5/IPC/Open3.pm line 281.

Doesn't work in Fedora 29:

Insecure $ENV{ENV} while running with -T switch at /usr/share/perl5/IPC/Open3.pm line 281.

After Restore of snapshot: No dependencies are shown

After I restored a snapshot the dependencies are not shown.

To reproduce the issue...
Generate a test volume and some snapshots

btrfs subvolume create test   # Create new subvolume
btrfs subvolume snapshot test test-backup  # Do a backup
btrfs subvolume snapshot test test-backup2   # Another backup

Show it with btrfs-list

btrfs-list /mnt/pro/ |grep -E 'NAME|single|test'
NAME                                          TYPE    REFER     EXCL  MOUNTPOINT
b04de56b                                        fs       -   374.04G (single, 546.00G free)
   test                                     subvol   16.00k   16.00k 
      test-backup                             snap   16.00k   16.00k 
      test-backup2                            snap   16.00k   16.00k

If you now have to restore your test-backup2 you do

btrfs subvolume delete test
Delete subvolume (no-commit): '/mnt/pro/test'
btrfs subvolume snapshot test-backup2 test
Create a snapshot of 'test-backup2' in './test'

And after some days create a new backup
btrfs subvolume snapshot test test-backup-after-restore

Now btrfs-list didn't show dependencies ("test-backup-after-restore" should depend to "test")

btrfs-list /mnt/pro/ |grep -E 'NAME|single|test'
NAME                                          TYPE    REFER     EXCL  MOUNTPOINT
b04de56b                                        fs       -   374.04G (single, 546.00G free)
test-backup2                                  snap   16.00k   16.00k 
test                                          snap   16.00k   16.00k 
test-backup                                   snap   16.00k   16.00k 
test-backup-after-restore                     snap   16.00k   16.00k

"test-backup-after-restore" is shown as snapshot with normal btrfs tool:

btrfs subvolume show test
test
        Name:                   test
        UUID:                   8db29b7d-5331-7742-af40-92b65eb22884
        Parent UUID:            57fadfee-483f-0b42-9229-c68bf12ddabc
        Received UUID:          -
        Creation time:          2022-01-02 10:41:07 +0100
        Subvolume ID:           474
        Generation:             87841
        Gen at creation:        87834
        Parent ID:              5
        Top level ID:           5
        Flags:                  -
        Send transid:           0
        Send time:              2022-01-02 10:41:07 +0100
        Receive transid:        0
        Receive time:           -
        Snapshot(s):
                                test-backup-after-restore
        Quota group:            0/474
          Limit referenced:     -
          Limit exclusive:      -
          Usage referenced:     16.00KiB
          Usage exclusive:      16.00KiB

Version info warning

When I run command
# ./btrfs-list
it prints warning message

WARNING: your kernel seems older (v4.13.x) than the btrfs-progs userspace tool (v4.4), some features might not be supported.
NAME      ID     TYPE     REFER      USED
backup     -       fs         -   650.80M (5.45G free)

I wrote simple patch

diff --git a/btrfs-list b/btrfs-list
index 09b4100..900e191 100755
--- a/btrfs-list
+++ b/btrfs-list
@@ -1,6 +1,7 @@
 #! /usr/bin/perl -T
 use strict;
 use warnings;
+use version;
 use IPC::Open3;
 use Symbol 'gensym';
 use Getopt::Long;
@@ -123,7 +124,7 @@ if ($version lt '3.16')
 @cmd = run_cmd( { can_fail => 0 }, qw{ uname -r } );
 my ($kerver) = $cmd[1][0] =~ /^(\d+\.\d+)/;
 my ($shortversion) = $version =~ /^(\d+\.\d+)/;
-if ($kerver lt $shortversion)
+if (version->declare($kerver)->numify lt version->declare($shortversion)->numify)
 {
        print STDERR "WARNING: your kernel seems older (v$kerver.x) than the btrfs-progs userspace tool (v$version), some features might not be supported.\n";
 }

Automatically request root permissions

Could you add functionality to make the script automatically ask for root permissions when it is not run as root?
Because it requires it to function properly/at all...

Fe. instead of the well-know sudo you could be using pkexec which automatically generates Popup when run under a GUI?
(pkexec is the PolicyKit's version of sudo) 😉

Truncated names of subvolumes and/or snapshots containing spaces

> btrfs-list --version
btrfs-list v2.2 using btrfs v5.4.1

Having a snapshot and a subvolume containing spaces in its name.

CAMERA_BACKUP/@2023-07-02                                                                                   subvol       -  
CAMERA_BACKUP/.@2023-07-02                                                                                  rosnap       -

Original was something like CAMERA_BACKUP/.@2023-07-02 Some description

Is it possible to add a path truncate option?

I have a path from docker: /var/lib/docker/btrfs/subvolumes/66281c586c95bc969e46ea749970d5d6f77a63a8c8fafec2580e5cc41486df34
That path is very large, because of that the table is not properly arranged in the terminal.

alignment broken

indented snaps last 4 columns are not aligned correctly 2 spaces offset

NAME                          TYPE    REFER     EXCL  MOUNTPOINT
dalivgdab9                      fs       -     4.87G (raid1, 818.28G/825.18G free, 99.16%)
    [main]                 mainvol   16.00k   16.00k /vgd
    adm                     subvol   32.00k   16.00k
        snaps/adm-2023-02-11  rosnap   32.00k   16.00k
    iso                     subvol    2.69G   16.00k
        snaps/iso-2023-02-11  rosnap    2.69G   16.00k
    jail/don                subvol    2.29G    2.29G
    snaps/jail-2023-02-11   rosnap   16.00k   16.00k

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.