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.