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> | B<--long>
 367
 368 =item B<-R> | B<--recursive>
 369
 370 Select the mode.  With neither of these options, C<virt-ls> produces a
 371 simple, flat list of the files in the named directory.  See
 372 L</SIMPLE LISTING>.
 373
 374 C<virt-ls -l> produces a "long listing", which shows more detail.  See
 375 L</LONG LISTING>.
 376
 377 C<virt-ls -R> produces a recursive list of files starting at the named
 378 directory.  See L</RECURSIVE LISTING>.
 379
 380 C<virt-ls -lR> produces a recursive long listing which can be more
 381 easily parsed.  See L</RECURSIVE LONG LISTING>.
 382
 383 =item B<--times>
 384
 385 Display time fields.
 386
 387 This option only has effect in I<-lR> output mode.  See
 388 L</RECURSIVE LONG LISTING> above.
 389
 390 =item B<--time-days>
 391
 392 Display time fields as days before now (negative if in the future).
 393
 394 Note that C<0> in output means "up to 1 day before now", or that the
 395 age of the file is between 0 and 86399 seconds.
 396
 397 This option only has effect in I<-lR> output mode.  See
 398 L</RECURSIVE LONG LISTING> above.
 399
 400 =item B<--time-relative>
 401
 402 Display time fields as seconds before now (negative if in the future).
 403
 404 This option only has effect in I<-lR> output mode.  See
 405 L</RECURSIVE LONG LISTING> above.
 406
 407 =item B<--time-t>
 408
 409 Display time fields as seconds since the Unix epoch.
 410
 411 This option only has effect in I<-lR> output mode.  See
 412 L</RECURSIVE LONG LISTING> above.
 413
 414 =item B<--uids>
 415
 416 Display UID and GID fields.
 417
 418 This option only has effect in I<-lR> output mode.  See
 419 L</RECURSIVE LONG LISTING> above.
 420
 421 =item B<-v>
 422
 423 =item B<--verbose>
 424
 425 Enable verbose messages for debugging.
 426
 427 =item B<-V>
 428
 429 =item B<--version>
 430
 431 Display version number and exit.
 432
 433 =item B<-x>
 434
 435 Enable tracing of libguestfs API calls.
 436
 437 =back
 438
 439 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 440
 441 Previous versions of virt-ls allowed you to write either:
 442
 443  virt-ls disk.img [disk.img ...] /dir
 444
 445 or
 446
 447  virt-ls guestname /dir
 448
 449 whereas in this version you should use I<-a> or I<-d> respectively
 450 to avoid the confusing case where a disk image might have the same
 451 name as a guest.
 452
 453 For compatibility the old style is still supported.
 454
 455 =head1 NOTE ABOUT CSV FORMAT
 456
 457 Comma-separated values (CSV) is a deceptive format.  It I<seems> like
 458 it should be easy to parse, but it is definitely not easy to parse.
 459
 460 Myth: Just split fields at commas.  Reality: This does I<not> work
 461 reliably.  This example has two columns:
 462
 463  "foo,bar",baz
 464
 465 Myth: Read the file one line at a time.  Reality: This does I<not>
 466 work reliably.  This example has one row:
 467
 468  "foo
 469  bar",baz
 470
 471 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
 472 also packaged in major Linux distributions).
 473
 474 For other languages, use a CSV processing library (eg. C<Text::CSV>
 475 for Perl or Python's built-in csv library).
 476
 477 Most spreadsheets and databases can import CSV directly.
 478
 479 =head1 SHELL QUOTING
 480
 481 Libvirt guest names can contain arbitrary characters, some of which
 482 have meaning to the shell such as C<#> and space.  You may need to
 483 quote or escape these characters on the command line.  See the shell
 484 manual page L<sh(1)> for details.
 485
 486 =head1 SEE ALSO
 487
 488 L<guestfs(3)>,
 489 L<guestfish(1)>,
 490 L<virt-cat(1)>,
 491 L<virt-copy-out(1)>,
 492 L<virt-tar-out(1)>,
 493 L<Sys::Guestfs(3)>,
 494 L<Sys::Guestfs::Lib(3)>,
 495 L<Sys::Virt(3)>,
 496 L<http://libguestfs.org/>.
 497
 498 =head1 AUTHOR
 499
 500 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 501
 502 =head1 COPYRIGHT
 503
 504 Copyright (C) 2009-2011 Red Hat Inc.
 505
 506 This program is free software; you can redistribute it and/or modify
 507 it under the terms of the GNU General Public License as published by
 508 the Free Software Foundation; either version 2 of the License, or
 509 (at your option) any later version.
 510
 511 This program is distributed in the hope that it will be useful,
 512 but WITHOUT ANY WARRANTY; without even the implied warranty of
 513 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 514 GNU General Public License for more details.
 515
 516 You should have received a copy of the GNU General Public License
 517 along with this program; if not, write to the Free Software
 518 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.