diff options
Diffstat (limited to 'cat/virt-filesystems.pod')
| -rwxr-xr-x | cat/virt-filesystems.pod | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/cat/virt-filesystems.pod b/cat/virt-filesystems.pod new file mode 100755 index 00000000..12f0b633 --- /dev/null +++ b/cat/virt-filesystems.pod @@ -0,0 +1,349 @@ +=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. |