=head1 DESCRIPTION
-C<virt-ls> is a command line tool to list the names of files in a
-directory inside a virtual machine or disk image.
+C<virt-ls> lists filenames, file sizes, checksums, extended attributes
+and more from a virtual machine or disk image.
-Multiple directory names can be given, in which case the output
-from each is concatenated.
-
-C<virt-ls> is just a simple wrapper around L<libguestfs(3)>
-functionality. For more complex cases you should look at the
-L<guestfish(1)> tool.
+Multiple directory names can be given, in which case the output from
+each is concatenated.
To list directories from a libvirt guest use the I<-d> option to
specify the name of the guest. For a disk image, use the I<-a>
option.
-C<virt-ls> can be used in one of three modes: simple, long and
-recursive. A simple listing is like the ordinary L<ls(1)> command:
+C<virt-ls> can do many simple file listings. For more complicated
+cases you may need to use L<guestfish(1)>, or write a program directly
+to the L<guestfs(3)> API.
+
+=head1 EXAMPLES
+
+Get a list of all files and directories in a virtual machine:
+
+ virt-ls -R -d guest /
+
+List all setuid or setgid programs in a Linux virtual machine:
+
+ virt-ls -lR -d guest / | grep '^- [42]'
+
+List all public-writable directories in a Linux virtual machine:
+
+ virt-ls -lR -d guest / | grep '^d ...7'
+
+List all Unix domain sockets in a Linux virtual machine:
+
+ virt-ls -lR -d guest / | grep '^s'
+
+List all regular files with filenames ending in '.png':
+
+ virt-ls -lR -d guest / | grep -i '^-.*\.png$'
+
+To display files larger than 10MB in home directories:
+
+ virt-ls -lR -d guest /home | awk '$3 > 10*1024*1024'
+
+Find everything modified in the last 7 days:
+
+ virt-ls -lR -d guest --time-days / | awk '$6 <= 7'
- $ virt-ls -d myguest /
+Find regular files modified in the last 24 hours:
+
+ virt-ls -lR -d guest --time-days / | grep '^-' | awk '$6 < 1'
+
+=head2 DIFFERENCES IN SNAPSHOTS AND BACKING FILES
+
+Find the differences between files in a guest and an earlier snapshot
+of the same guest.
+
+ virt-ls -lR -a snapshot.img / --uids --time-t > old
+ virt-ls -lR -a current.img / --uids --time-t > new
+ diff -u old new | less
+
+The commands above won't find files where the content has changed but
+the metadata (eg. file size and modification date) is the same. To do
+that, you need to add the I<--checksum> parameter to both C<virt-ls>
+commands. I<--checksum> can be quite slow since it has to read and
+compute a checksum of every regular file in the virtual machine.
+
+=head1 OUTPUT MODES
+
+C<virt-ls> has four output modes, controlled by different
+combinations of the I<-l> and I<-R> options.
+
+=head2 SIMPLE LISTING
+
+A simple listing is like the ordinary L<ls(1)> command:
+
+ $ virt-ls -d guest /
bin
boot
[etc.]
-With the I<-l> (I<--long>) option, C<virt-ls> shows more detail:
+=head2 LONG LISTING
- $ virt-ls -l -d myguest /
+With the I<-l> (I<--long>) option, the output is like the C<ls -l>
+command (more specifically, like the C<guestfs_ll> function).
+
+ $ virt-ls -l -d guest /
total 204
dr-xr-xr-x. 2 root root 4096 2009-08-25 19:06 bin
dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot
[etc.]
-With the I<-R> (I<--recursive>) option, C<virt-ls> lists the
-names of files and directories recursively:
+Note that while this is useful for displaying a directory, do not try
+parsing this output in another program. Use L</RECURSIVE LONG LISTING>
+instead.
+
+=head2 RECURSIVE LISTING
- $ virt-ls -R -d myguest /tmp
+With the I<-R> (I<--recursive>) option, C<virt-ls> lists the names of
+files and directories recursively:
+
+ $ virt-ls -R -d guest /tmp
foo
foo/bar
[etc.]
-You I<cannot> combine these options. To do more complicated things,
-use L<guestfish(1)>.
+To generate this output, C<virt-ls> runs the C<guestfs_find0> function
+and converts C<\0> characters to C<\n>.
+
+=head2 RECURSIVE LONG LISTING
+
+Using I<-lR> options together changes the output to display
+directories recursively, with file stats, and optionally other
+features such as checksums and extended attributes.
+
+Most of the interesting features of C<virt-ls> are only available when
+using I<-lR> mode.
+
+The fields are normally space-separated. Filenames are B<not> quoted,
+so you cannot use the output in another program (because filenames can
+contain spaces and other unsafe characters). If the guest was
+untrusted and someone knew you were using C<virt-ls> to analyze the
+guest, they could play tricks on you by creating filenames with
+embedded newline characters. To B<safely> parse the output in another
+program, use the I<--csv> (Comma-Separated Values) option.
+
+Note that this output format is completely unrelated to the C<ls -lR>
+command.
+
+ $ virt-ls -lR -d guest /bin
+ d 0555 4096 /bin
+ - 0755 123 /bin/alsaunmute
+ - 0755 28328 /bin/arch
+ l 0777 4 /bin/awk -> gawk
+ - 0755 27216 /bin/basename
+ - 0755 943360 /bin/bash
+ [etc.]
+
+These basic fields are always shown:
+
+=over 4
+
+=item type
+
+The file type, one of:
+C<-> (regular file),
+C<d> (directory),
+C<c> (character device),
+C<b> (block device),
+C<p> (named pipe),
+C<l> (symbolic link),
+C<s> (socket) or
+C<u> (unknown).
+
+=item permissions
+
+The Unix permissions, displayed as a 4 digit octal number.
+
+=item size
+
+The size of the file. This is shown in bytes unless I<-h> or
+I<--human-readable> option is given, in which case this is shown as a
+human-readable number.
+
+=item path
+
+The full path of the file or directory.
+
+=item link
+
+For symbolic links only, the link target.
+
+=back
+
+In I<-lR> mode, additional command line options enable the display of
+more fields.
+
+With the I<--uids> flag, these additional fields are displayed before
+the path:
+
+=over 4
+
+=item uid
+
+=item gid
+
+The UID and GID of the owner of the file (displayed numerically).
+Note these only make sense in the context of a Unix-like guest.
+
+=back
+
+With the I<--times> flag, these additional fields are displayed:
+
+=over 4
+
+=item atime
+
+The time of last access.
+
+=item mtime
+
+The time of last modification.
+
+=item ctime
+
+The time of last status change.
+
+=back
+
+The time fields are displayed as string dates and times, unless one of
+the I<--time-t>, I<--time-relative> or I<--time-days> flags is given.
+
+With the I<--extra-stats> flag, these additional fields are displayed:
+
+=over 4
+
+=item device
+
+The device containing the file (displayed as major:minor).
+This may not match devices as known to the guest.
+
+=item inode
+
+The inode number.
+
+=item nlink
+
+The number of hard links.
+
+=item rdev
+
+For block and char special files, the device
+(displayed as major:minor).
+
+=item blocks
+
+The number of 512 byte blocks allocated to the file.
+
+=back
+
+With the I<--checksum> flag, the checksum of the file contents is
+shown (only for regular files). Computing file checksums can take a
+considerable amount of time.
=head1 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<--checksum>
+
+=item B<--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512>
+
+Display checksum over file contents for regular files. With no
+argument, this defaults to using I<md5>. Using an argument, you can
+select the checksum type to use.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
=item B<-c> URI
=item B<--connect> URI
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
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-stats>
+
+Display extra stats.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
=item B<--format=raw|qcow2|..>
=item B<--format>
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>
+
+Display file sizes in human-readable format.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
=item B<--keys-from-stdin>
Read key or passphrase parameters from stdin. The default is
=item B<-R> | B<--recursive>
-Select the mode. With neither of these options, C<virt-ls>
-produces a simple, flat list of the files in the named directory.
+Select the mode. With neither of these options, C<virt-ls> produces a
+simple, flat list of the files in the named directory. See
+L</SIMPLE LISTING>.
-C<virt-ls -l> produces a "long listing", which shows more detail (just
-like the plain C<ls -l> command).
+C<virt-ls -l> produces a "long listing", which shows more detail. See
+L</LONG LISTING>.
C<virt-ls -R> produces a recursive list of files starting at the named
-directory. See the documentation for L<guestfs(3)/guestfs_find0>
-for precise details.
+directory. See L</RECURSIVE LISTING>.
+
+C<virt-ls -lR> produces a recursive long listing which can be more
+easily parsed. See L</RECURSIVE LONG LISTING>.
+
+=item B<--times>
+
+Display time fields.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
+=item B<--time-days>
+
+Display time fields as days before now (negative if in the future).
+
+Note that C<0> in output means "up to 1 day before now", or that the
+age of the file is between 0 and 86399 seconds.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
+=item B<--time-relative>
+
+Display time fields as seconds before now (negative if in the future).
-You cannot combine these options.
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
+=item B<--time-t>
+
+Display time fields as seconds since the Unix epoch.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
+
+=item B<--uids>
+
+Display UID and GID fields.
+
+This option only has effect in I<-lR> output mode. See
+L</RECURSIVE LONG LISTING> above.
=item B<-v>
For compatibility the old style is still supported.
+=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
L<guestfs(3)>,
L<guestfish(1)>,
L<virt-cat(1)>,
-L<virt-tar(1)>,
+L<virt-copy-out(1)>,
+L<virt-tar-out(1)>,
L<Sys::Guestfs(3)>,
L<Sys::Guestfs::Lib(3)>,
L<Sys::Virt(3)>,
=head1 COPYRIGHT
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2011 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
git.annexia.org / libguestfs.git / blobdiff