1virt-ls(1) Virtualization Support virt-ls(1)
2
6 virt-ls - List files in a virtual machine
7
9 virt-ls [--options] -d domname directory [directory ...]
10 virt-ls [--options] -a disk.img [-a disk.img ...] directory [directory ...]
12 Old style:
14 virt-ls [--options] domname directory
16 virt-ls [--options] disk.img [disk.img ...] directory
18
20 "virt-ls" lists filenames, file sizes, checksums, extended attributes
21 and more from a virtual machine or disk image.
22 Multiple directory names can be given, in which case the output from
24 each is concatenated.
25 To list directories from a libvirt guest use the -d option to specify
27 the name of the guest. For a disk image, use the -a option.
28 "virt-ls" can do many simple file listings. For more complicated cases
30 you may need to use guestfish(1), or write a program directly to the
31 guestfs(3) API.
32
34 Get a list of all files and directories in a virtual machine:
35 virt-ls -R -d guest /
37 List all setuid or setgid programs in a Linux virtual machine:
39 virt-ls -lR -d guest / | grep '^- [42]'
41 List all public-writable directories in a Linux virtual machine:
43 virt-ls -lR -d guest / | grep '^d ...7'
45 List all Unix domain sockets in a Linux virtual machine:
47 virt-ls -lR -d guest / | grep '^s'
49 List all regular files with filenames ending in '.png':
51 virt-ls -lR -d guest / | grep -i '^-.*\.png$'
53 To display files larger than 10MB in home directories:
55 virt-ls -lR -d guest /home | awk '$3 > 10*1024*1024'
57 Find everything modified in the last 7 days:
59 virt-ls -lR -d guest --time-days / | awk '$6 <= 7'
61 Find regular files modified in the last 24 hours:
63 virt-ls -lR -d guest --time-days / | grep '^-' | awk '$6 < 1'
65 DIFFERENCES IN SNAPSHOTS AND BACKING FILES
67 Find the differences between files in a guest and an earlier snapshot
68 of the same guest.
69 virt-ls -lR -a snapshot.img / --uids --time-t > old
71 virt-ls -lR -a current.img / --uids --time-t > new
72 diff -u old new | less
73 The commands above won't find files where the content has changed but
75 the metadata (eg. file size and modification date) is the same. To do
76 that, you need to add the --checksum parameter to both "virt-ls"
77 commands. --checksum can be quite slow since it has to read and
78 compute a checksum of every regular file in the virtual machine.
79
81 "virt-ls" has four output modes, controlled by different combinations
82 of the -l and -R options.
83 SIMPLE LISTING
85 A simple listing is like the ordinary ls(1) command:
86 $ virt-ls -d guest /
88 bin
89 boot
90 [etc.]
91 LONG LISTING
93 With the -l (--long) option, the output is like the "ls -l" command
94 (more specifically, like the "guestfs_ll" function).
95 $ virt-ls -l -d guest /
97 total 204
98 dr-xr-xr-x. 2 root root 4096 2009-08-25 19:06 bin
99 dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot
100 [etc.]
101 Note that while this is useful for displaying a directory, do not try
103 parsing this output in another program. Use "RECURSIVE LONG LISTING"
104 instead.
105 RECURSIVE LISTING
107 With the -R (--recursive) option, "virt-ls" lists the names of files
108 and directories recursively:
109 $ virt-ls -R -d guest /tmp
111 foo
112 foo/bar
113 [etc.]
114 To generate this output, "virt-ls" runs the "guestfs_find0" function
116 and converts "\0" characters to "\n".
117 RECURSIVE LONG LISTING
119 Using -lR options together changes the output to display directories
120 recursively, with file stats, and optionally other features such as
121 checksums and extended attributes.
122 Most of the interesting features of "virt-ls" are only available when
124 using -lR mode.
125 The fields are normally space-separated. Filenames are not quoted, so
127 you cannot use the output in another program (because filenames can
128 contain spaces and other unsafe characters). If the guest was
129 untrusted and someone knew you were using "virt-ls" to analyze the
130 guest, they could play tricks on you by creating filenames with
131 embedded newline characters. To safely parse the output in another
132 program, use the --csv (Comma-Separated Values) option.
133 Note that this output format is completely unrelated to the "ls -lR"
135 command.
136 $ virt-ls -lR -d guest /bin
138 d 0555 4096 /bin
139 - 0755 123 /bin/alsaunmute
140 - 0755 28328 /bin/arch
141 l 0777 4 /bin/awk -> gawk
142 - 0755 27216 /bin/basename
143 - 0755 943360 /bin/bash
144 [etc.]
145 These basic fields are always shown:
147 type
149 The file type, one of: "-" (regular file), "d" (directory), "c"
150 (character device), "b" (block device), "p" (named pipe), "l"
151 (symbolic link), "s" (socket) or "u" (unknown).
152 permissions
154 The Unix permissions, displayed as a 4 digit octal number.
155 size
157 The size of the file. This is shown in bytes unless -h or
158 --human-readable option is given, in which case this is shown as a
159 human-readable number.
160 path
162 The full path of the file or directory.
163 link
165 For symbolic links only, the link target.
166 In -lR mode, additional command line options enable the display of more
168 fields.
169 With the --uids flag, these additional fields are displayed before the
171 path:
172 uid
174 gid The UID and GID of the owner of the file (displayed numerically).
175 Note these only make sense in the context of a Unix-like guest.
176 With the --times flag, these additional fields are displayed:
178 atime
180 The time of last access.
181 mtime
183 The time of last modification.
184 ctime
186 The time of last status change.
187 The time fields are displayed as string dates and times, unless one of
189 the --time-t, --time-relative or --time-days flags is given.
190 With the --extra-stats flag, these additional fields are displayed:
192 device
194 The device containing the file (displayed as major:minor). This
195 may not match devices as known to the guest.
196 inode
198 The inode number.
199 nlink
201 The number of hard links.
202 rdev
204 For block and char special files, the device (displayed as
205 major:minor).
206 blocks
208 The number of 512 byte blocks allocated to the file.
209 With the --checksum flag, the checksum of the file contents is shown
211 (only for regular files). Computing file checksums can take a
212 considerable amount of time.
213
215 --help
216 Display brief help.
217 -a file
219 --add file
220 Add file which should be a disk image from a virtual machine. If
221 the virtual machine has multiple block devices, you must supply all
222 of them with separate -a options.
223 The format of the disk image is auto-detected. To override this
225 and force a particular format use the --format=.. option.
226 --checksum
228 --checksum=crc|md5|sha1|sha224|sha256|sha384|sha512
229 Display checksum over file contents for regular files. With no
230 argument, this defaults to using md5. Using an argument, you can
231 select the checksum type to use.
232 This option only has effect in -lR output mode. See "RECURSIVE
234 LONG LISTING" above.
235 -c URI
237 --connect URI
238 If using libvirt, connect to the given URI. If omitted, then we
239 connect to the default libvirt hypervisor.
240 If you specify guest block devices directly (-a), then libvirt is
242 not used at all.
243 --csv
245 Write out the results in CSV format (comma-separated values). This
246 format can be imported easily into databases and spreadsheets, but
247 read "NOTE ABOUT CSV FORMAT" below.
248 -d guest
250 --domain guest
251 Add all the disks from the named libvirt guest. Domain UUIDs can
252 be used instead of names.
253 --echo-keys
255 When prompting for keys and passphrases, virt-ls normally turns
256 echoing off so you cannot see what you are typing. If you are not
257 worried about Tempest attacks and there is no one else in the room
258 you can specify this flag to see what you are typing.
259 --extra-stats
261 Display extra stats.
262 This option only has effect in -lR output mode. See "RECURSIVE
264 LONG LISTING" above.
265 --format=raw|qcow2|..
267 --format
268 The default for the -a option is to auto-detect the format of the
269 disk image. Using this forces the disk format for -a options which
270 follow on the command line. Using --format with no argument
271 switches back to auto-detection for subsequent -a options.
272 For example:
274 virt-ls --format=raw -a disk.img /dir
276 forces raw format (no auto-detection) for "disk.img".
278 virt-ls --format=raw -a disk.img --format -a another.img /dir
280 forces raw format (no auto-detection) for "disk.img" and reverts to
282 auto-detection for "another.img".
283 If you have untrusted raw-format guest disk images, you should use
285 this option to specify the disk format. This avoids a possible
286 security problem with malicious guests (CVE-2010-3851).
287 -h
289 --human-readable
290 Display file sizes in human-readable format.
291 This option only has effect in -lR output mode. See "RECURSIVE
293 LONG LISTING" above.
294 --keys-from-stdin
296 Read key or passphrase parameters from stdin. The default is to
297 try to read passphrases from the user by opening "/dev/tty".
298 -l
300 --long
301 -R
302 --recursive
303 Select the mode. With neither of these options, "virt-ls" produces
304 a simple, flat list of the files in the named directory. See
305 "SIMPLE LISTING".
306 "virt-ls -l" produces a "long listing", which shows more detail.
308 See "LONG LISTING".
309 "virt-ls -R" produces a recursive list of files starting at the
311 named directory. See "RECURSIVE LISTING".
312 "virt-ls -lR" produces a recursive long listing which can be more
314 easily parsed. See "RECURSIVE LONG LISTING".
315 --times
317 Display time fields.
318 This option only has effect in -lR output mode. See "RECURSIVE
320 LONG LISTING" above.
321 --time-days
323 Display time fields as days before now (negative if in the future).
324 Note that 0 in output means "up to 1 day before now", or that the
326 age of the file is between 0 and 86399 seconds.
327 This option only has effect in -lR output mode. See "RECURSIVE
329 LONG LISTING" above.
330 --time-relative
332 Display time fields as seconds before now (negative if in the
333 future).
334 This option only has effect in -lR output mode. See "RECURSIVE
336 LONG LISTING" above.
337 --time-t
339 Display time fields as seconds since the Unix epoch.
340 This option only has effect in -lR output mode. See "RECURSIVE
342 LONG LISTING" above.
343 --uids
345 Display UID and GID fields.
346 This option only has effect in -lR output mode. See "RECURSIVE
348 LONG LISTING" above.
349 -v
351 --verbose
352 Enable verbose messages for debugging.
353 -V
355 --version
356 Display version number and exit.
357 -x Enable tracing of libguestfs API calls.
359
361 Previous versions of virt-ls allowed you to write either:
362 virt-ls disk.img [disk.img ...] /dir
364 or
366 virt-ls guestname /dir
368 whereas in this version you should use -a or -d respectively to avoid
370 the confusing case where a disk image might have the same name as a
371 guest.
372 For compatibility the old style is still supported.
374
376 Comma-separated values (CSV) is a deceptive format. It seems like it
377 should be easy to parse, but it is definitely not easy to parse.
378 Myth: Just split fields at commas. Reality: This does not work
380 reliably. This example has two columns:
381 "foo,bar",baz
383 Myth: Read the file one line at a time. Reality: This does not work
385 reliably. This example has one row:
386 "foo
388 bar",baz
389 For shell scripts, use "csvtool" (http://merjis.com/developers/csv also
391 packaged in major Linux distributions).
392 For other languages, use a CSV processing library (eg. "Text::CSV" for
394 Perl or Python's built-in csv library).
395 Most spreadsheets and databases can import CSV directly.
397
399 Libvirt guest names can contain arbitrary characters, some of which
400 have meaning to the shell such as "#" and space. You may need to quote
401 or escape these characters on the command line. See the shell manual
402 page sh(1) for details.
403
405 This program returns 0 if successful, or non-zero if there was an
406 error.
407
409 guestfs(3), guestfish(1), virt-cat(1), virt-copy-out(1),
410 virt-tar-out(1), http://libguestfs.org/.
411
413 Richard W.M. Jones http://people.redhat.com/~rjones/
414
416 Copyright (C) 2009-2013 Red Hat Inc.
417
419 This program is free software; you can redistribute it and/or modify it
420 under the terms of the GNU General Public License as published by the
421 Free Software Foundation; either version 2 of the License, or (at your
422 option) any later version.
423 This program is distributed in the hope that it will be useful, but
425 WITHOUT ANY WARRANTY; without even the implied warranty of
426 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
427 General Public License for more details.
428 You should have received a copy of the GNU General Public License along
430 with this program; if not, write to the Free Software Foundation, Inc.,
431 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
432
434 To get a list of bugs against libguestfs, use this link:
435 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
436 To report a new bug against libguestfs, use this link:
438 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
439 When reporting a bug, please supply:
441 · The version of libguestfs.
443 · Where you got libguestfs (eg. which Linux distro, compiled from
445 source, etc)
446 · Describe the bug accurately and give a way to reproduce it.
448 · Run libguestfs-test-tool(1) and paste the complete, unedited output
450 into the bug report.
451libguestfs-1.20.11 2013-08-27 virt-ls(1)