mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
fbc2555903
This tool replaces virt-list-filesystems and virt-list-partitions with a new tool written in C with a more uniform command line structure and output. This existing Perl tools are deprecated but remain indefinitely.
350 lines
9.5 KiB
Plaintext
Executable File
350 lines
9.5 KiB
Plaintext
Executable File
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
virt-filesystems - List filesystems, partitions, block devices, LVM in a virtual machine or disk image
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
virt-filesystems [--options] -d domname
|
|
|
|
virt-filesystems [--options] -a disk.img [-a disk.img ...]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This tool allows you to discover filesystems, partitions, logical
|
|
volumes, and their sizes in a disk image or virtual machine. It is a
|
|
replacement for L<virt-list-filesystems(1)> and
|
|
L<virt-list-partitions(1)>.
|
|
|
|
One use for this tool is from shell scripts to iterate over all
|
|
filesystems from a disk image:
|
|
|
|
for fs in $(virt-filesystems -a disk.img); do
|
|
# ...
|
|
done
|
|
|
|
Another use is to list partitions before using another tool to modify
|
|
those partitions (such as L<virt-resize(1)>). If you are curious
|
|
about what an unknown disk image contains, use this tool along with
|
|
L<virt-inspector(1)>.
|
|
|
|
Various command line options control what this program displays. You
|
|
need to give either I<-a> or I<-d> options to specify the disk image
|
|
or libvirt guest respectively. If you just specify that then the
|
|
program shows filesystems found, one per line, like this:
|
|
|
|
$ virt-filesystems -a disk.img
|
|
/dev/sda1
|
|
/dev/vg_guest/lv_root
|
|
|
|
If you add I<-l> or I<--long> then the output includes extra
|
|
information:
|
|
|
|
$ virt-filesystems -a disk.img -l
|
|
Name Type VFS Label Size
|
|
/dev/sda1 filesystem ext4 boot 524288000
|
|
/dev/vg_guest/lv_root filesystem ext4 root 10212081664
|
|
|
|
If you add I<--extra> then non-mountable (swap, unknown) filesystems
|
|
are shown as well:
|
|
|
|
$ virt-filesystems -a disk.img --extra
|
|
/dev/sda1
|
|
/dev/vg_guest/lv_root
|
|
/dev/vg_guest/lv_swap
|
|
/dev/vg_guest/lv_data
|
|
|
|
If you add I<--partitions> then partitions are shown instead of filesystems:
|
|
|
|
$ virt-filesystems -a disk.img --partitions
|
|
/dev/sda1
|
|
/dev/sda2
|
|
|
|
Similarly you can use I<--logical-volumes>, I<--volume-groups>,
|
|
I<--physical-volumes>, I<--block-devices> to list those items.
|
|
|
|
You can use these options in combination as well (if you want a
|
|
combination including filesystems, you have to add I<--filesystems>).
|
|
Notice that some items fall into several categories (eg. C</dev/sda1>
|
|
might be both a partition and a filesystem). These items are listed
|
|
several times. To get a list which includes absolutely everything
|
|
that virt-filesystems knows about, use the I<--all> option.
|
|
|
|
UUIDs (because they are quite long) are not shown by default. Add the
|
|
I<--uuid> option to display device and filesystem UUIDs in the long
|
|
output.
|
|
|
|
I<--all --long --uuid> is a useful combination to display all possible
|
|
information about everything.
|
|
|
|
$ virt-filesystems -a win.img --all --long --uuid -h
|
|
Name Type VFS Label Size Parent UUID
|
|
/dev/sda1 filesystem ntfs System Reserved 100M - F81C92571C92112C
|
|
/dev/sda2 filesystem ntfs - 20G - F2E8996AE8992E3B
|
|
/dev/sda1 partition - - 100M /dev/sda -
|
|
/dev/sda2 partition - - 20G /dev/sda -
|
|
/dev/sda device - - 20G - -
|
|
|
|
For machine-readable output, use I<--csv> to get Comma-Separated Values.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<--help>
|
|
|
|
Display brief help.
|
|
|
|
=item B<-a> file
|
|
|
|
=item B<--add> file
|
|
|
|
Add I<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<--all>
|
|
|
|
Display everything. This is currently the same as specifying these
|
|
options: I<--filesystems>, I<--extra>, I<--partitions>,
|
|
I<--block-devices>, I<--logical-volumes>, I<--volume-groups>,
|
|
I<--physical-volumes>. (More may be added to this list in future).
|
|
|
|
See also I<--long>.
|
|
|
|
=item B<--blkdevs>
|
|
|
|
=item B<--block-devices>
|
|
|
|
Display block devices.
|
|
|
|
=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.
|
|
|
|
=item B<--echo-keys>
|
|
|
|
When prompting for keys and passphrases, virt-filesystems normally
|
|
turns echoing off so you cannot see what you are typing. If you are
|
|
not worried about Tempest attacks and there is no one else in the room
|
|
you can specify this flag to see what you are typing.
|
|
|
|
=item B<--extra>
|
|
|
|
This causes filesystems that are not normally, mountable filesystems
|
|
to be displayed. This category includes swapspace, and filesystems
|
|
that are empty or contain unknown data.
|
|
|
|
This option implies I<--filesystems>.
|
|
|
|
=item B<--filesystems>
|
|
|
|
Display mountable filesystems. If no display option was selected then
|
|
this option is implied.
|
|
|
|
With I<--extra>, non-mountable filesystems are shown too.
|
|
|
|
=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-filesystems --format=raw -a disk.img
|
|
|
|
forces raw format (no auto-detection) for C<disk.img>.
|
|
|
|
virt-filesystems --format=raw -a disk.img --format -a another.img
|
|
|
|
forces raw format (no auto-detection) for C<disk.img> and reverts to
|
|
auto-detection for C<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). See also
|
|
L</add-drive-opts>.
|
|
|
|
=item B<-h>
|
|
|
|
=item B<--human-readable>
|
|
|
|
In I<--long> mode, display sizes in human-readable format.
|
|
|
|
=item B<--keys-from-stdin>
|
|
|
|
Read key or passphrase parameters from stdin. The default is
|
|
to try to read passphrases from the user by opening C</dev/tty>.
|
|
|
|
=item B<-l>
|
|
|
|
=item B<--long>
|
|
|
|
Display extra columns of data ("long format").
|
|
|
|
A title row is added unless you also specify I<--no-title>.
|
|
|
|
The extra columns displayed depend on what output you select, and the
|
|
ordering of columns may change in future versions. Use the title row,
|
|
I<--csv> output and/or L<csvtool(1)> to match columns to data in
|
|
external programs.
|
|
|
|
Use I<-h> if you want sizes to be displayed in human-readable format.
|
|
The default is to show raw numbers of I<bytes>.
|
|
|
|
Use I<--uuid> to display UUIDs too.
|
|
|
|
=item B<--lvs>
|
|
|
|
=item B<--logvols>
|
|
|
|
=item B<--logical-volumes>
|
|
|
|
Display LVM logical volumes. In this mode, these are displayed
|
|
irrespective of whether the LVs contain filesystems.
|
|
|
|
=item B<--no-title>
|
|
|
|
In I<--long> mode, don't add a title row.
|
|
|
|
Note that the order of the columns is not fixed, and may change in
|
|
future versions of virt-filesystems, so using this option may give you
|
|
unexpected surprises.
|
|
|
|
=item B<--parts>
|
|
|
|
=item B<--partitions>
|
|
|
|
Display partitions. In this mode, these are displayed
|
|
irrespective of whether the partitions contain filesystems.
|
|
|
|
=item B<--pvs>
|
|
|
|
=item B<--physvols>
|
|
|
|
=item B<--physical-volumes>
|
|
|
|
Display LVM physical volumes.
|
|
|
|
=item B<--uuid>
|
|
|
|
=item B<--uuids>
|
|
|
|
In I<--long> mode, display UUIDs as well.
|
|
|
|
=item B<-v>
|
|
|
|
=item B<--verbose>
|
|
|
|
Enable verbose messages for debugging.
|
|
|
|
=item B<-V>
|
|
|
|
=item B<--version>
|
|
|
|
Display version number and exit.
|
|
|
|
=item B<--vgs>
|
|
|
|
=item B<--volgroups>
|
|
|
|
=item B<--volume-groups>
|
|
|
|
Display LVM volume groups.
|
|
|
|
=item B<-x>
|
|
|
|
Enable tracing of libguestfs API calls.
|
|
|
|
=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<http://merjis.com/developers/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 SHELL QUOTING
|
|
|
|
Libvirt guest names can contain arbitrary characters, some of which
|
|
have meaning to the shell such as C<#> and space. You may need to
|
|
quote or escape these characters on the command line. See the shell
|
|
manual page L<sh(1)> for details.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<guestfs(3)>,
|
|
L<guestfish(1)>,
|
|
L<virt-cat(1)>,
|
|
L<virt-df(1)>,
|
|
L<virt-list-filesystems(1)>,
|
|
L<virt-list-partitions(1)>,
|
|
L<csvtool(1)>,
|
|
L<http://libguestfs.org/>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Richard W.M. Jones L<http://people.redhat.com/~rjones/>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2010 Red Hat Inc.
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|