5 virt-ls - List files in a virtual machine
9 virt-ls [--options] -d domname directory [directory ...]
11 virt-ls [--options] -a disk.img [-a disk.img ...] directory [directory ...]
15 virt-ls [--options] domname directory
17 virt-ls [--options] disk.img [disk.img ...] directory
21 C<virt-ls> lists filenames, file sizes, checksums, extended attributes
22 and more from a virtual machine or disk image.
24 Multiple directory names can be given, in which case the output from
27 To list directories from a libvirt guest use the I<-d> option to
28 specify the name of the guest. For a disk image, use the I<-a>
31 C<virt-ls> can do many simple file listings. For more complicated
32 cases you may need to use L<guestfish(1)>, or write a program directly
33 to the L<guestfs(3)> API.
37 Get a list of all files and directories in a virtual machine:
41 List all setuid or setgid programs in a Linux virtual machine:
43 virt-ls -lR -d guest / | grep '^- [42]'
45 List all public-writable directories in a Linux virtual machine:
47 virt-ls -lR -d guest / | grep '^d ...7'
49 List all Unix domain sockets in a Linux virtual machine:
51 virt-ls -lR -d guest / | grep '^s'
53 List all regular files with filenames ending in '.png':
55 virt-ls -lR -d guest / | grep -i '^-.*\.png$'
57 To display files larger than 10MB in home directories:
59 virt-ls -lR -d guest /home | awk '$3 > 10*1024*1024'
61 Find everything modified in the last 7 days:
63 virt-ls -lR -d guest --time-days / | awk '$6 <= 7'
65 Find regular files modified in the last 24 hours:
67 virt-ls -lR -d guest --time-days / | grep '^-' | awk '$6 < 1'
69 =head2 DIFFERENCES IN SNAPSHOTS AND BACKING FILES
71 Find the differences between files in a guest and an earlier snapshot
74 virt-ls -lR -a snapshot.img / --uids --time-t > old
75 virt-ls -lR -a current.img / --uids --time-t > new
76 diff -u old new | less
78 The commands above won't find files where the content has changed but
79 the metadata (eg. file size and modification date) is the same. To do
80 that, you need to add the I<--checksum> parameter to both C<virt-ls>
81 commands. I<--checksum> can be quite slow since it has to read and
82 compute a checksum of every regular file in the virtual machine.
86 C<virt-ls> has four output modes, controlled by different
87 combinations of the I<-l> and I<-R> options.
91 A simple listing is like the ordinary L<ls(1)> command:
100 With the I<-l> (I<--long>) option, the output is like the C<ls -l>
101 command (more specifically, like the C<guestfs_ll> function).
103 $ virt-ls -l -d guest /
105 dr-xr-xr-x. 2 root root 4096 2009-08-25 19:06 bin
106 dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot
109 Note that while this is useful for displaying a directory, do not try
110 parsing this output in another program. Use L</RECURSIVE LONG LISTING>
113 =head2 RECURSIVE LISTING
115 With the I<-R> (I<--recursive>) option, C<virt-ls> lists the names of
116 files and directories recursively:
118 $ virt-ls -R -d guest /tmp
123 To generate this output, C<virt-ls> runs the C<guestfs_find0> function
124 and converts C<\0> characters to C<\n>.
126 =head2 RECURSIVE LONG LISTING
128 Using I<-lR> options together changes the output to display
129 directories recursively, with file stats, and optionally other
130 features such as checksums and extended attributes.
132 Most of the interesting features of C<virt-ls> are only available when
135 The fields are normally space-separated. Filenames are B<not> quoted,
136 so you cannot use the output in another program (because filenames can
137 contain spaces and other unsafe characters). If the guest was
138 untrusted and someone knew you were using C<virt-ls> to analyze the
139 guest, they could play tricks on you by creating filenames with
140 embedded newline characters. To B<safely> parse the output in another
141 program, use the I<--csv> (Comma-Separated Values) option.
143 Note that this output format is completely unrelated to the C<ls -lR>
146 $ virt-ls -lR -d guest /bin
148 - 0755 123 /bin/alsaunmute
149 - 0755 28328 /bin/arch
150 l 0777 4 /bin/awk -> gawk
151 - 0755 27216 /bin/basename
152 - 0755 943360 /bin/bash
155 These basic fields are always shown:
161 The file type, one of:
164 C<c> (character device),
167 C<l> (symbolic link),
173 The Unix permissions, displayed as a 4 digit octal number.
177 The size of the file. This is shown in bytes unless I<-h> or
178 I<--human-readable> option is given, in which case this is shown as a
179 human-readable number.
183 The full path of the file or directory.
187 For symbolic links only, the link target.
191 In I<-lR> mode, additional command line options enable the display of
194 With the I<--uids> flag, these additional fields are displayed before
203 The UID and GID of the owner of the file (displayed numerically).
204 Note these only make sense in the context of a Unix-like guest.
208 With the I<--times> flag, these additional fields are displayed:
214 The time of last access.
218 The time of last modification.
222 The time of last status change.
226 The time fields are displayed as string dates and times, unless one of
227 the I<--time-t>, I<--time-relative> or I<--time-days> flags is given.
229 With the I<--extra-stats> flag, these additional fields are displayed:
235 The device containing the file (displayed as major:minor).
236 This may not match devices as known to the guest.
244 The number of hard links.
248 For block and char special files, the device
249 (displayed as major:minor).
253 The number of 512 byte blocks allocated to the file.
257 With the I<--checksum> flag, the checksum of the file contents is
258 shown (only for regular files). Computing file checksums can take a
259 considerable amount of time.
273 Add I<file> which should be a disk image from a virtual machine. If
274 the virtual machine has multiple block devices, you must supply all of
275 them with separate I<-a> options.
277 The format of the disk image is auto-detected. To override this and
278 force a particular format use the I<--format=..> option.
282 =item B<--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512>
284 Display checksum over file contents for regular files. With no
285 argument, this defaults to using I<md5>. Using an argument, you can
286 select the checksum type to use.
288 This option only has effect in I<-lR> output mode. See
289 L</RECURSIVE LONG LISTING> above.
293 =item B<--connect> URI
295 If using libvirt, connect to the given I<URI>. If omitted, then we
296 connect to the default libvirt hypervisor.
298 If you specify guest block devices directly (I<-a>), then libvirt is
303 Write out the results in CSV format (comma-separated values). This
304 format can be imported easily into databases and spreadsheets, but
305 read L</NOTE ABOUT CSV FORMAT> below.
309 =item B<--domain> guest
311 Add all the disks from the named libvirt guest. Domain UUIDs can be
312 used instead of names.
316 When prompting for keys and passphrases, virt-ls normally turns
317 echoing off so you cannot see what you are typing. If you are not
318 worried about Tempest attacks and there is no one else in the room you
319 can specify this flag to see what you are typing.
321 =item B<--extra-stats>
325 This option only has effect in I<-lR> output mode. See
326 L</RECURSIVE LONG LISTING> above.
328 =item B<--format=raw|qcow2|..>
332 The default for the I<-a> option is to auto-detect the format of the
333 disk image. Using this forces the disk format for I<-a> options which
334 follow on the command line. Using I<--format> with no argument
335 switches back to auto-detection for subsequent I<-a> options.
339 virt-ls --format=raw -a disk.img /dir
341 forces raw format (no auto-detection) for C<disk.img>.
343 virt-ls --format=raw -a disk.img --format -a another.img /dir
345 forces raw format (no auto-detection) for C<disk.img> and reverts to
346 auto-detection for C<another.img>.
348 If you have untrusted raw-format guest disk images, you should use
349 this option to specify the disk format. This avoids a possible
350 security problem with malicious guests (CVE-2010-3851).
354 =item B<--human-readable>
356 Display file sizes in human-readable format.
358 This option only has effect in I<-lR> output mode. See
359 L</RECURSIVE LONG LISTING> above.
361 =item B<--keys-from-stdin>
363 Read key or passphrase parameters from stdin. The default is
364 to try to read passphrases from the user by opening C</dev/tty>.
374 Select the mode. With neither of these options, C<virt-ls> produces a
375 simple, flat list of the files in the named directory. See
378 C<virt-ls -l> produces a "long listing", which shows more detail. See
381 C<virt-ls -R> produces a recursive list of files starting at the named
382 directory. See L</RECURSIVE LISTING>.
384 C<virt-ls -lR> produces a recursive long listing which can be more
385 easily parsed. See L</RECURSIVE LONG LISTING>.
391 This option only has effect in I<-lR> output mode. See
392 L</RECURSIVE LONG LISTING> above.
396 Display time fields as days before now (negative if in the future).
398 Note that C<0> in output means "up to 1 day before now", or that the
399 age of the file is between 0 and 86399 seconds.
401 This option only has effect in I<-lR> output mode. See
402 L</RECURSIVE LONG LISTING> above.
404 =item B<--time-relative>
406 Display time fields as seconds before now (negative if in the future).
408 This option only has effect in I<-lR> output mode. See
409 L</RECURSIVE LONG LISTING> above.
413 Display time fields as seconds since the Unix epoch.
415 This option only has effect in I<-lR> output mode. See
416 L</RECURSIVE LONG LISTING> above.
420 Display UID and GID fields.
422 This option only has effect in I<-lR> output mode. See
423 L</RECURSIVE LONG LISTING> above.
429 Enable verbose messages for debugging.
435 Display version number and exit.
439 Enable tracing of libguestfs API calls.
443 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
445 Previous versions of virt-ls allowed you to write either:
447 virt-ls disk.img [disk.img ...] /dir
451 virt-ls guestname /dir
453 whereas in this version you should use I<-a> or I<-d> respectively
454 to avoid the confusing case where a disk image might have the same
457 For compatibility the old style is still supported.
459 =head1 NOTE ABOUT CSV FORMAT
461 Comma-separated values (CSV) is a deceptive format. It I<seems> like
462 it should be easy to parse, but it is definitely not easy to parse.
464 Myth: Just split fields at commas. Reality: This does I<not> work
465 reliably. This example has two columns:
469 Myth: Read the file one line at a time. Reality: This does I<not>
470 work reliably. This example has one row:
475 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
476 also packaged in major Linux distributions).
478 For other languages, use a CSV processing library (eg. C<Text::CSV>
479 for Perl or Python's built-in csv library).
481 Most spreadsheets and databases can import CSV directly.
485 Libvirt guest names can contain arbitrary characters, some of which
486 have meaning to the shell such as C<#> and space. You may need to
487 quote or escape these characters on the command line. See the shell
488 manual page L<sh(1)> for details.
492 This program returns 0 if successful, or non-zero if there was an
503 L<Sys::Guestfs::Lib(3)>,
505 L<http://libguestfs.org/>.
509 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
513 Copyright (C) 2009-2011 Red Hat Inc.
515 This program is free software; you can redistribute it and/or modify
516 it under the terms of the GNU General Public License as published by
517 the Free Software Foundation; either version 2 of the License, or
518 (at your option) any later version.
520 This program is distributed in the hope that it will be useful,
521 but WITHOUT ANY WARRANTY; without even the implied warranty of
522 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
523 GNU General Public License for more details.
525 You should have received a copy of the GNU General Public License
526 along with this program; if not, write to the Free Software
527 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.