mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
55bf7de97c
Run the following command over the source: perl -pi.bak -e 's/(20[01][0-9])-2016/$1-2017/g' `git ls-files` (Thanks Rich for the perl snippet, as used in past years.)
271 lines
6.9 KiB
Plaintext
271 lines
6.9 KiB
Plaintext
=head1 NAME
|
|
|
|
virt-df - Display free space on virtual filesystems
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
All guests:
|
|
|
|
virt-df [--options]
|
|
|
|
Single guest:
|
|
|
|
virt-df [--options] -d domname
|
|
|
|
virt-df [--options] -a disk.img [-a disk.img ...]
|
|
|
|
Old style:
|
|
|
|
virt-df [--options] domname
|
|
|
|
virt-df [--options] disk.img [disk.img ...]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
C<virt-df> is a command line tool to display free space on virtual
|
|
machine filesystems. Unlike other tools, it doesn't just display the
|
|
size of disk allocated to a virtual machine, but can look inside disk
|
|
images to see how much space is really being used.
|
|
|
|
If used without any I<-a> or I<-d> arguments, C<virt-df> checks with
|
|
libvirt to get a list of all active and inactive guests, and performs
|
|
a C<df>-type operation on each one in turn, printing out the results.
|
|
|
|
If any I<-a> or I<-d> arguments are specified, C<virt-df> performs a
|
|
C<df>-type operation on either the single named libvirt domain, or on
|
|
the disk image(s) listed on the command line (which must all belong to
|
|
a single VM). B<In this mode (with arguments), C<virt-df> will only
|
|
work for a single guest>. If you want to run on multiple guests, then
|
|
you have to invoke C<virt-df> multiple times.
|
|
|
|
Use the I<--csv> option to get a format which can be easily parsed by
|
|
other programs. Other options are similar to the standard L<df(1)>
|
|
command.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Show disk usage for a single libvirt guest called C<F14x64>. Make the
|
|
output human-readable:
|
|
|
|
# virt-df -d F14x64 -h
|
|
Filesystem Size Used Available Use%
|
|
F14x64:/dev/sda1 484M 66M 393M 14%
|
|
F14x64:/dev/vg_f13x64/lv_root 7.4G 3.4G 4.0G 46%
|
|
|
|
Show disk usage for a disk image file called F<test.img>:
|
|
|
|
$ virt-df -a test1.img
|
|
Filesystem 1K-blocks Used Available Use%
|
|
test1.img:/dev/sda1 99099 1551 92432 2%
|
|
|
|
If a single guest has multiple disks, use the I<-a> option repeatedly.
|
|
A plus sign (C<+>) is displayed for each additional disk. B<Note: Do
|
|
not do this with unrelated guest disks.>
|
|
|
|
$ virt-df -a Win7x32TwoDisks-a -a Win7x32TwoDisks-b
|
|
Filesystem 1K-blocks Used Available Use%
|
|
Win7x32TwoDisks-a+:/dev/sda1 102396 24712 77684 25%
|
|
Win7x32TwoDisks-a+:/dev/sda2 12478460 7403416 5075044 60%
|
|
Win7x32TwoDisks-a+:/dev/sdb1 521212 55728 465484 11%
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<--help>
|
|
|
|
Display brief help.
|
|
|
|
=item B<-a> FILE
|
|
|
|
=item B<--add> FILE
|
|
|
|
Add C<FILE> which should be a disk image from a virtual machine. If
|
|
the virtual machine has multiple block devices, you must supply all of
|
|
them with separate I<-a> options.
|
|
|
|
The format of the disk image is auto-detected. To override this and
|
|
force a particular format use the I<--format=..> option.
|
|
|
|
=item B<-a> URI
|
|
|
|
=item B<--add> URI
|
|
|
|
Add a remote disk. See L<guestfish(1)/ADDING REMOTE STORAGE>.
|
|
|
|
=item B<-c> URI
|
|
|
|
=item B<--connect> URI
|
|
|
|
If using libvirt, connect to the given I<URI>. If omitted, then we
|
|
connect to the default libvirt hypervisor.
|
|
|
|
If you specify guest block devices directly (I<-a>), then libvirt is
|
|
not used at all.
|
|
|
|
=item B<--csv>
|
|
|
|
Write out the results in CSV format (comma-separated values). This
|
|
format can be imported easily into databases and spreadsheets, but
|
|
read L</NOTE ABOUT CSV FORMAT> below.
|
|
|
|
=item B<-d> guest
|
|
|
|
=item B<--domain> guest
|
|
|
|
Add all the disks from the named libvirt guest. Domain UUIDs can be
|
|
used instead of names.
|
|
|
|
=item B<--format=raw|qcow2|..>
|
|
|
|
=item B<--format>
|
|
|
|
The default for the I<-a> option is to auto-detect the format of the
|
|
disk image. Using this forces the disk format for I<-a> options which
|
|
follow on the command line. Using I<--format> with no argument
|
|
switches back to auto-detection for subsequent I<-a> options.
|
|
|
|
For example:
|
|
|
|
virt-df --format=raw -a disk.img
|
|
|
|
forces raw format (no auto-detection) for F<disk.img>.
|
|
|
|
virt-df --format=raw -a disk.img --format -a another.img
|
|
|
|
forces raw format (no auto-detection) for F<disk.img> and reverts to
|
|
auto-detection for F<another.img>.
|
|
|
|
If you have untrusted raw-format guest disk images, you should use
|
|
this option to specify the disk format. This avoids a possible
|
|
security problem with malicious guests (CVE-2010-3851).
|
|
|
|
=item B<-h>
|
|
|
|
=item B<--human-readable>
|
|
|
|
Print sizes in human-readable format.
|
|
|
|
You are not allowed to use I<-h> and I<--csv> at the same time.
|
|
|
|
=item B<-i>
|
|
|
|
=item B<--inodes>
|
|
|
|
Print inodes instead of blocks.
|
|
|
|
=item B<--one-per-guest>
|
|
|
|
Since libguestfs 1.22, this is the default. This option does nothing
|
|
and is left here for backwards compatibility with older scripts.
|
|
|
|
=item B<-P> nr_threads
|
|
|
|
Since libguestfs 1.22, virt-df is multithreaded and examines guests in
|
|
parallel. By default the number of threads to use is chosen based on
|
|
the amount of free memory available at the time that virt-df is
|
|
started. You can force virt-df to use at most C<nr_threads> by using
|
|
the I<-P> option.
|
|
|
|
Note that I<-P 0> means to autodetect, and I<-P 1> means to use a
|
|
single thread.
|
|
|
|
=item B<--uuid>
|
|
|
|
Print UUIDs instead of names. This is useful for following
|
|
a guest even when the guest is migrated or renamed, or when
|
|
two guests happen to have the same name.
|
|
|
|
Note that only domains that we fetch from libvirt come with UUIDs.
|
|
For disk images, we still print the disk image name even when
|
|
this option is specified.
|
|
|
|
=item B<-v>
|
|
|
|
=item B<--verbose>
|
|
|
|
Enable verbose messages for debugging.
|
|
|
|
=item B<-V>
|
|
|
|
=item B<--version>
|
|
|
|
Display version number and exit.
|
|
|
|
=item B<-x>
|
|
|
|
Enable tracing of libguestfs API calls.
|
|
|
|
=back
|
|
|
|
=head1 STATVFS NUMBERS
|
|
|
|
C<virt-df> (and L<df(1)>) get information by issuing a L<statvfs(3)>
|
|
system call. You can get the same information directly, either from
|
|
the host (using libguestfs) or inside the guest:
|
|
|
|
=over 4
|
|
|
|
=item From the host
|
|
|
|
Run this command:
|
|
|
|
guestfish --ro -d GuestName -i statvfs /
|
|
|
|
(change F</> to see stats for other filesystems).
|
|
|
|
=item From inside the guest
|
|
|
|
Run this command:
|
|
|
|
python -c 'import os; s = os.statvfs ("/"); print s'
|
|
|
|
(change F</> to see stats for other filesystems).
|
|
|
|
=back
|
|
|
|
=head1 NOTE ABOUT CSV FORMAT
|
|
|
|
Comma-separated values (CSV) is a deceptive format. It I<seems> like
|
|
it should be easy to parse, but it is definitely not easy to parse.
|
|
|
|
Myth: Just split fields at commas. Reality: This does I<not> work
|
|
reliably. This example has two columns:
|
|
|
|
"foo,bar",baz
|
|
|
|
Myth: Read the file one line at a time. Reality: This does I<not>
|
|
work reliably. This example has one row:
|
|
|
|
"foo
|
|
bar",baz
|
|
|
|
For shell scripts, use C<csvtool> (L<https://github.com/Chris00/ocaml-csv>
|
|
also packaged in major Linux distributions).
|
|
|
|
For other languages, use a CSV processing library (eg. C<Text::CSV>
|
|
for Perl or Python's built-in csv library).
|
|
|
|
Most spreadsheets and databases can import CSV directly.
|
|
|
|
=head1 EXIT STATUS
|
|
|
|
This program returns 0 if successful, or non-zero if there was an
|
|
error.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<df(1)>,
|
|
L<guestfs(3)>,
|
|
L<guestfish(1)>,
|
|
L<virt-filesystems(1)>,
|
|
L<http://libguestfs.org/>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Richard W.M. Jones L<http://people.redhat.com/~rjones/>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2009-2017 Red Hat Inc.
|