partinfo

#!/usr/bin/perl
our $VERSION = '2.8 (2025-07-01)';
#
# partinfo -- Show summary of space on AFS server partitions.
#
# Takes an AFS server as an argument and then runs vos partinfo on it,
# parsing the output and producing a slightly more verbose report that
# includes percent full on each partition and how much more data can be
# added to that partition before putting it over 90% full.
#
# Written by Neil Crellin <neilc@stanford.edu>
# Modifications by Russ Allbery <eagle@eyrie.org>
# Copyright 1998, 1999, 2003, 2004, 2011, 2013
#     The Board of Trustees of the Leland Stanford Junior University
#
# Modifications by Bill MacAllister <bill@ca-zephyr.org>
# Copyright 2018
#    Bill MacAllister <bill@ca-zephyr.org>
#
# This program is free software; you may redistribute it and/or modify it
# under the same terms as Perl itself.

##############################################################################
# Modules and declarations
##############################################################################

use 5.006;
use strict;
use warnings;

use Getopt::Long qw(GetOptions);

my $opt_human;

# Term::ANSIColor is also loaded dynamically if color is requested
# with the -c option.

##############################################################################
# Site configuration
##############################################################################

# If set assumes Auristor syntax
our $YFS_SERVER;

# The default thresholds.  The first gives the threshold before the partition
# is considered reasonably well-utilized, and defaults to 60%.  The second
# gives the threshold before the partition is considered full (and also
# determines how much space is shown as available in the last column of the
# report).  It defaults to 90%.  These are used for colorizing the output and
# can be overridden with the -T command-line option.
our $PARTINFO_EMPTY = 60;
our $PARTINFO_FULL  = 90;

# The full path to vos.  vos may be in an sbin directory, which may not be on
# the user's path by default, so check there first.
our $VOS = grep { -x $_ } qw(/usr/local/sbin/vos /usr/sbin/vos);
$VOS ||= 'vos';

# Load the configuration file if it exists.
if (-f '/etc/afs-admin-tools/config') {
    require '/etc/afs-admin-tools/config';
}

##############################################################################
# Utilities
##############################################################################

# Return human readable byte value
sub human_bytes {
    my ($b) = @_;

    my $return_b = $b;
    if ($b =~ /^\d+$/) {
        my $k = 1024;
        my $m = $k * 1024;
        my $g = $m * 1024;
        my $t = $g * 1024;
        if ($b > $t) {
            $return_b = sprintf('%.2fT', $b / $t);
        } elsif ($b > $g) {
            $return_b = sprintf('%.2fG', $b / $g);
        } elsif ($b > $m) {
            $return_b = sprintf('%.2fM', $b / $m);
        } elsif ($b > $k) {
            $return_b = sprintf('%.2fK', $b / $k);
        } else {
            $return_b = "${b}B";
        }
    }

    return $return_b;
}

##############################################################################
# Output formatting
##############################################################################

# Given the percentage of free space on a partition, return the color string
# to use for that partition.  Uses the $THRESH_* global variables, which can
# be overridden with -T.
sub choose_color {
    my ($pfree) = @_;
    if    ($pfree < $PARTINFO_EMPTY) { return color('green') }
    elsif ($pfree > $PARTINFO_FULL)  { return color('red') }
    else                             { return '' }
}

# Print the heading for the output.
sub heading {
    printf "%17s: %10s %10s %10s %8s %10s\n",
      'Partition', 'Total', 'Used', 'Free', '%Full', 'Available';
}

# Given the partition tag, the total space, the free space, and a flag saying
# whether to use color, output one line of formatted output.  We can't easily
# use formats because they mess up when colors are used.
sub show {
    my ($partition, $total, $free, $color) = @_;
    my $used   = $total - $free;
    my $usable = int($free - ((100 - $PARTINFO_FULL) / 100) * $total);
    my $pfree  = 100 * $used / $total;
    my $cstart = $color ? choose_color($pfree) : '';
    my $cend   = $color ? color('reset')       : '';
    my $fmt    = "%17s: %10d %10d %10d %s%7.2f%%%s %10d\n";
    if ($opt_human) {
        $total  = human_bytes($total * 1024);
        $used   = human_bytes($used * 1024);
        $free   = human_bytes($free * 1024);
        $usable = human_bytes($usable * 1024);
        $fmt    = "%17s: %10s %10s %10s %s%7.2f%%%s %10s\n";
    }
    printf($fmt,
        $partition, $total, $used, $free, $cstart, $pfree, $cend, $usable);
    return;
}

##############################################################################
# Main routine
##############################################################################

# Parse our options.
my $fullpath = $0;
$0 =~ s%.*/%%;
my ($color, $help, $quiet, $thresholds, $totals, $version);
Getopt::Long::config('bundling', 'no_ignore_case');
GetOptions(
    'color|c'        => \$color,
    'help|h'         => \$help,
    'human'          => \$opt_human,
    'quiet|q'        => \$quiet,
    'thresholds|T=s' => \$thresholds,
    'total|t'        => \$totals,
    'version|v'      => \$version
) or exit 1;
if ($help) {
    exec('perldoc', '-t', $fullpath);
    exit 1;
} elsif ($version) {
    print "partinfo $VERSION\n";
    exit 1;
}
if ($color) {
    require Term::ANSIColor;
    Term::ANSIColor->import('color');
}
if (@ARGV != 1) {
    die "Usage: $0 [-chqtv] [-T <empty>,<full>] <afssvr>\n";
}
my $server = shift;
if (($server =~ /^\d+$/)) {
    $server = 'afssvr' . $server;
}

# Check for AFS flavor
my $vos_version = `vos --version`;
if ($vos_version =~ /^auristor/xms) {
    $YFS_SERVER = 1;
}

# Process threshold argument if provided.
if ($thresholds) {
    if ($thresholds !~ /^(\d{1,2}|100),(\d{1,2}|100)$/) {
        die "$0: argument to -T must be two numbers 0-100, "
          . "separated by a comma\n";
    }
    ($PARTINFO_EMPTY, $PARTINFO_FULL) = ($1, $2);
}

# Run vos partinfo and parse the output.  Print out a line for each partition,
# and copy any other output to standard output without changing it.
if (!$quiet) {
    heading;
}
my ($ttotal, $tfree);
open(PARTINFO, "$VOS partinfo -server $server |")
  or die "$0: can't fork: $!\n";
while (<PARTINFO>) {
    if (m%^Free space on partition (/vicep\S+): (\d+) K .* total (\d+)$%) {
        my ($partition, $free, $total) = ($1, $2, $3);
        $partition = "$server $partition";
        show($partition, $total, $free, $color);
        if ($totals) {
            $ttotal += $total;
            $tfree  += $free;
        }
    } elsif (
        m%^Free \s+ space \s+ on \s+ server \s+ (\S+)
               \s+ partition \s+ (/vicep\S+):
               \s+ (\d+) \s+ K \s+ blocks
               \s+ out \s+ of \s+ total \s+ (\d+)$%xms
      )
    {
        my ($server, $partition, $free, $total) = ($1, $2, $3, $4);
        show($partition, $total, $free, $color);
        if ($totals) {
            $ttotal += $total;
            $tfree  += $free;
        }
    } else {
        print;
    }
}
close PARTINFO;

# Print totals if we're supposed to.
if ($totals) {
    print "\n";
    show('TOTAL', $ttotal, $tfree, $color);
}

__END__

############################################################################
# Documentation
############################################################################

=for stopwords
AFS Crellin afs-admin-tools afssvr -chqtv partinfo vos afssvr1 afssvr5

=head1 NAME

partinfo - Show summary of space on AFS server partitions

=head1 SYNOPSIS

partinfo [B<-chqtv>] [-T <empty>,<full>] I<afssvr>

=head1 DESCRIPTION

B<partinfo> does a vos partinfo on a particular AFS server to determine
the amount of used and free space.  Unlike vos partinfo, however, it also
formats the output into a more easily readable tabular form, displays the
total disk space, the used disk space, and the free disk space, calculates
what percent full the partition is, and displays the amount that can still
be put on the partition before it goes over a particular threshold.

Normally, B<partinfo> displays a header above the output giving the
meaning of the columns, but this can optionally be suppressed.
B<partinfo> can also optionally use color to highlight partitions with
plenty of free space and partitions that are too full.

There are two thresholds that B<partinfo> cares about.  The first is the
threshold before which the partition will be considered to be mostly
empty.  This will only change the output if color is requested with B<-c>;
if it is, the partition will be shown in green.  It defaults to 60%.  The
second is the threshold after which the partition will be considered full.
The final column, available space, is the amount of space remaining on the
partition before it goes over this threshold, and partitions over this
threshold will be shown in red if color is requested with B<-c>.  The
thresholds may be changed at the top of this script or overridden for one
invocation with B<-T>.

If the server given is just a number, C<afssvr> will be prepended to form
the server name.

=head1 OPTIONS

=over 4

=item B<-c>, B<--color>

Use color to highlight interesting data.  Currently this just means that
the percent full column will be shown in green for partitions under 60%
full and in red for partitions over 90% full.  Using this option requires
that the Term::ANSIColor module be installed and available on the user's
system (this module is not required if B<-c> is not used).

To override the above thresholds, see the B<-T> option.

=item B<--human>

Display quote values in human readable format.

=item B<-h>, B<--help>

Print out this documentation (which is done simply by feeding the script
to C<perldoc -t>).

=item B<-q>, B<--quiet>

Suppress the header normally printed to explain the meanings of each
column of data.

=item B<-t>, B<--total>

Print totals for the entire server.

=item B<-T> I<empty>,I<full>

=item B<--thresholds>=I<empty>,I<full>

Override the default thresholds of 60% (before which a partition will be
considered mostly empty) and 90% (after which the partition will be
considered full).  B<-T> should take two integers between 0 and 100
separated by a comma.

=item B<-v>, B<--version>

Print out the version of B<partinfo> and exit.

=back

=head1 CONFIGURATION

B<partinfo> loads configuration settings from
F</etc/afs-admin-tools/config> if that file exists.  If it exists, it must
be Perl code suitable for loading with C<require>.  This means that each
line of the configuration file should be of the form:

    our $VARIABLE = VALUE;

where C<$VARIABLE> is the configuration variable being set and C<VALUE> is
the value to set it to (which should be enclosed in quotes if it's not a
number).  The file should end with:

    1;

so that Perl knows the file was loaded correctly.

The supported configuration variables are:

=over 4

=item $PARTINFO_EMPTY

=item $PARTINFO_FULL

The default thresholds.  The first gives the threshold before the
partition is considered reasonably well-utilized, and defaults to 60%.
The second gives the threshold before the partition is considered full
(and also determines how much space is shown as available in the last
column of the report).  It defaults to 90%.  These are used for colorizing
the output (with the B<-c> option) and can be overridden with the B<-T>
command-line option.

=item $VOS

The full path to the AFS B<vos> utility.  If this variable is not set,
B<partinfo> defaults to F</usr/local/sbin/vos> or F</usr/sbin/vos> if they
exist, and otherwise looks for B<vos> on the user's PATH.

=back

=head1 EXAMPLES

The following command shows the current status of afssvr1:

    partinfo afssvr1

This command shows the same data, but without the header and with color
highlighting of interesting percent full data:

    partinfo -qc afssvr1

This command does the same for afssvr5:

    partinfo --color --quiet afssvr5

Use thresholds of 70% and 95% instead, showing the results in color:

    partinfo -T 70,95 -c afssvr5

=head1 AUTHORS

Original Perl script written by Neil Crellin <neilc@stanford.edu>,
modified by Russ Allbery <eagle@eyrie.org> to use formats, to include an
explanatory header, to use color if wanted, and to add optional totals.

Bill MacAllister <bill@ca-zephyr.org>, modifications to support Auristor.

=head1 COPYRIGHT AND LICENSE

Copyright 1998, 1999, 2003, 2004, 2011 The Board of Trustees of the Leland
Stanford Junior University.

Copyright 2018 Bill MacAllister <bill@ca-zephyr.org>

This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.

=head1 SEE ALSO

L<vos(1)>, L<vos_partinfo(1)>

This script is part of the afs-admin-tools package.  The original Russ
Allbery version is available is available from the afs-admin-tools web
page at L<http://www.eyrie.org/~eagle/software/afs-admin-tools/>.

This version is available from L<https://github.com/auristor/afs-admin-tools>.

=cut