test-tool: Document the -t command line option.
[libguestfs.git] / cat / virt-ls.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-ls - List files in a virtual machine
6
7 =head1 SYNOPSIS
8
9  virt-ls [--options] -d domname directory [directory ...]
10
11  virt-ls [--options] -a disk.img [-a disk.img ...] directory [directory ...]
12
13 Old style:
14
15  virt-ls [--options] domname directory
16
17  virt-ls [--options] disk.img [disk.img ...] directory
18
19 =head1 DESCRIPTION
20
21 C<virt-ls> lists filenames, file sizes, checksums, extended attributes
22 and more from a virtual machine or disk image.
23
24 Multiple directory names can be given, in which case the output from
25 each is concatenated.
26
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>
29 option.
30
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.
34
35 =head1 EXAMPLES
36
37 Get a list of all files and directories in a virtual machine:
38
39  virt-ls -R -d guest /
40
41 List all setuid or setgid programs in a Linux virtual machine:
42
43  virt-ls -lR -d guest / | grep '^- [42]'
44
45 List all public-writable directories in a Linux virtual machine:
46
47  virt-ls -lR -d guest / | grep '^d ...7'
48
49 List all Unix domain sockets in a Linux virtual machine:
50
51  virt-ls -lR -d guest / | grep '^s'
52
53 List all regular files with filenames ending in '.png':
54
55  virt-ls -lR -d guest / | grep -i '^-.*\.png$'
56
57 To display files larger than 10MB in home directories:
58
59  virt-ls -lR -d guest /home | awk '$3 > 10*1024*1024'
60
61 Find everything modified in the last 7 days:
62
63  virt-ls -lR -d guest --time-days / | awk '$6 <= 7'
64
65 Find regular files modified in the last 24 hours:
66
67  virt-ls -lR -d guest --time-days / | grep '^-' | awk '$6 < 1'
68
69 =head2 DIFFERENCES IN SNAPSHOTS AND BACKING FILES
70
71 Find the differences between files in a guest and an earlier snapshot
72 of the same guest.
73
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
77
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.
83
84 =head1 OUTPUT MODES
85
86 C<virt-ls> has four output modes, controlled by different
87 combinations of the I<-l> and I<-R> options.
88
89 =head2 SIMPLE LISTING
90
91 A simple listing is like the ordinary L<ls(1)> command:
92
93  $ virt-ls -d guest /
94  bin
95  boot
96  [etc.]
97
98 =head2 LONG LISTING
99
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).
102
103  $ virt-ls -l -d guest /
104  total 204
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
107  [etc.]
108
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>
111 instead.
112
113 =head2 RECURSIVE LISTING
114
115 With the I<-R> (I<--recursive>) option, C<virt-ls> lists the names of
116 files and directories recursively:
117
118  $ virt-ls -R -d guest /tmp
119  foo
120  foo/bar
121  [etc.]
122
123 To generate this output, C<virt-ls> runs the C<guestfs_find0> function
124 and converts C<\0> characters to C<\n>.
125
126 =head2 RECURSIVE LONG LISTING
127
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.
131
132 Most of the interesting features of C<virt-ls> are only available when
133 using I<-lR> mode.
134
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.
142
143 Note that this output format is completely unrelated to the C<ls -lR>
144 command.
145
146  $ virt-ls -lR -d guest /bin
147  d 0555       4096 /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
153  [etc.]
154
155 These basic fields are always shown:
156
157 =over 4
158
159 =item type
160
161 The file type, one of:
162 C<-> (regular file),
163 C<d> (directory),
164 C<c> (character device),
165 C<b> (block device),
166 C<p> (named pipe),
167 C<l> (symbolic link),
168 C<s> (socket) or
169 C<u> (unknown).
170
171 =item permissions
172
173 The Unix permissions, displayed as a 4 digit octal number.
174
175 =item size
176
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.
180
181 =item path
182
183 The full path of the file or directory.
184
185 =item link
186
187 For symbolic links only, the link target.
188
189 =back
190
191 In I<-lR> mode, additional command line options enable the display of
192 more fields.
193
194 With the I<--uids> flag, these additional fields are displayed before
195 the path:
196
197 =over 4
198
199 =item uid
200
201 =item gid
202
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.
205
206 =back
207
208 With the I<--times> flag, these additional fields are displayed:
209
210 =over 4
211
212 =item atime
213
214 The time of last access.
215
216 =item mtime
217
218 The time of last modification.
219
220 =item ctime
221
222 The time of last status change.
223
224 =back
225
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.
228
229 With the I<--extra-stats> flag, these additional fields are displayed:
230
231 =over 4
232
233 =item device
234
235 The device containing the file (displayed as major:minor).
236 This may not match devices as known to the guest.
237
238 =item inode
239
240 The inode number.
241
242 =item nlink
243
244 The number of hard links.
245
246 =item rdev
247
248 For block and char special files, the device
249 (displayed as major:minor).
250
251 =item blocks
252
253 The number of 512 byte blocks allocated to the file.
254
255 =back
256
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.
260
261 =head1 OPTIONS
262
263 =over 4
264
265 =item B<--help>
266
267 Display brief help.
268
269 =item B<-a> file
270
271 =item B<--add> file
272
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.
276
277 The format of the disk image is auto-detected.  To override this and
278 force a particular format use the I<--format=..> option.
279
280 =item B<--checksum>
281
282 =item B<--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512>
283
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.
287
288 This option only has effect in I<-lR> output mode.  See
289 L</RECURSIVE LONG LISTING> above.
290
291 =item B<-c> URI
292
293 =item B<--connect> URI
294
295 If using libvirt, connect to the given I<URI>.  If omitted, then we
296 connect to the default libvirt hypervisor.
297
298 If you specify guest block devices directly (I<-a>), then libvirt is
299 not used at all.
300
301 =item B<--csv>
302
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.
306
307 =item B<-d> guest
308
309 =item B<--domain> guest
310
311 Add all the disks from the named libvirt guest.  Domain UUIDs can be
312 used instead of names.
313
314 =item B<--echo-keys>
315
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.
320
321 =item B<--extra-stats>
322
323 Display extra stats.
324
325 This option only has effect in I<-lR> output mode.  See
326 L</RECURSIVE LONG LISTING> above.
327
328 =item B<--format=raw|qcow2|..>
329
330 =item B<--format>
331
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.
336
337 For example:
338
339  virt-ls --format=raw -a disk.img /dir
340
341 forces raw format (no auto-detection) for C<disk.img>.
342
343  virt-ls --format=raw -a disk.img --format -a another.img /dir
344
345 forces raw format (no auto-detection) for C<disk.img> and reverts to
346 auto-detection for C<another.img>.
347
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).
351
352 =item B<-h>
353
354 =item B<--human-readable>
355
356 Display file sizes in human-readable format.
357
358 This option only has effect in I<-lR> output mode.  See
359 L</RECURSIVE LONG LISTING> above.
360
361 =item B<--keys-from-stdin>
362
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>.
365
366 =item B<-l>
367
368 =item B<--long>
369
370 =item B<-R>
371
372 =item B<--recursive>
373
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
376 L</SIMPLE LISTING>.
377
378 C<virt-ls -l> produces a "long listing", which shows more detail.  See
379 L</LONG LISTING>.
380
381 C<virt-ls -R> produces a recursive list of files starting at the named
382 directory.  See L</RECURSIVE LISTING>.
383
384 C<virt-ls -lR> produces a recursive long listing which can be more
385 easily parsed.  See L</RECURSIVE LONG LISTING>.
386
387 =item B<--times>
388
389 Display time fields.
390
391 This option only has effect in I<-lR> output mode.  See
392 L</RECURSIVE LONG LISTING> above.
393
394 =item B<--time-days>
395
396 Display time fields as days before now (negative if in the future).
397
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.
400
401 This option only has effect in I<-lR> output mode.  See
402 L</RECURSIVE LONG LISTING> above.
403
404 =item B<--time-relative>
405
406 Display time fields as seconds before now (negative if in the future).
407
408 This option only has effect in I<-lR> output mode.  See
409 L</RECURSIVE LONG LISTING> above.
410
411 =item B<--time-t>
412
413 Display time fields as seconds since the Unix epoch.
414
415 This option only has effect in I<-lR> output mode.  See
416 L</RECURSIVE LONG LISTING> above.
417
418 =item B<--uids>
419
420 Display UID and GID fields.
421
422 This option only has effect in I<-lR> output mode.  See
423 L</RECURSIVE LONG LISTING> above.
424
425 =item B<-v>
426
427 =item B<--verbose>
428
429 Enable verbose messages for debugging.
430
431 =item B<-V>
432
433 =item B<--version>
434
435 Display version number and exit.
436
437 =item B<-x>
438
439 Enable tracing of libguestfs API calls.
440
441 =back
442
443 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
444
445 Previous versions of virt-ls allowed you to write either:
446
447  virt-ls disk.img [disk.img ...] /dir
448
449 or
450
451  virt-ls guestname /dir
452
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
455 name as a guest.
456
457 For compatibility the old style is still supported.
458
459 =head1 NOTE ABOUT CSV FORMAT
460
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.
463
464 Myth: Just split fields at commas.  Reality: This does I<not> work
465 reliably.  This example has two columns:
466
467  "foo,bar",baz
468
469 Myth: Read the file one line at a time.  Reality: This does I<not>
470 work reliably.  This example has one row:
471
472  "foo
473  bar",baz
474
475 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
476 also packaged in major Linux distributions).
477
478 For other languages, use a CSV processing library (eg. C<Text::CSV>
479 for Perl or Python's built-in csv library).
480
481 Most spreadsheets and databases can import CSV directly.
482
483 =head1 SHELL QUOTING
484
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.
489
490 =head1 EXIT STATUS
491
492 This program returns 0 if successful, or non-zero if there was an
493 error.
494
495 =head1 SEE ALSO
496
497 L<guestfs(3)>,
498 L<guestfish(1)>,
499 L<virt-cat(1)>,
500 L<virt-copy-out(1)>,
501 L<virt-tar-out(1)>,
502 L<Sys::Guestfs(3)>,
503 L<Sys::Guestfs::Lib(3)>,
504 L<Sys::Virt(3)>,
505 L<http://libguestfs.org/>.
506
507 =head1 AUTHOR
508
509 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
510
511 =head1 COPYRIGHT
512
513 Copyright (C) 2009-2011 Red Hat Inc.
514
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.
519
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.
524
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.