3 # Copyright (C) 2009-2010 Red Hat Inc.
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or
8 # (at your option) any later version.
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, write to the Free Software
17 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23 use Sys::Guestfs::Lib qw(open_guest);
26 use File::Temp qw/tempdir/;
28 use Locale::TextDomain 'libguestfs';
34 virt-ls - List files in a virtual machine
38 virt-ls [--options] domname directory
40 virt-ls [--options] disk.img [disk.img ...] directory
44 C<virt-ls> is a command line tool to list the names of files in a
45 directory inside a virtual machine or disk image.
47 C<virt-ls> is just a simple wrapper around L<libguestfs(3)>
48 functionality. For more complex cases you should look at the
51 C<virt-ls> can be used in one of three modes: simple, long and
52 recursive. A simple listing is like the ordinary L<ls(1)> command:
59 With the C<-l> (C<--long>) option, C<virt-ls> shows more detail:
61 $ virt-ls -l myguest /
63 dr-xr-xr-x. 2 root root 4096 2009-08-25 19:06 bin
64 dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot
67 With the C<-R> (C<--recursive>) option, C<virt-ls> lists the
68 names of files and directories recursively:
70 $ virt-ls -R myguest /tmp
75 You I<cannot> combine these options. To do more complicated things,
96 Display version number and exit.
102 =item B<--connect URI> | B<-c URI>
104 If using libvirt, connect to the given I<URI>. If omitted, then we
105 connect to the default libvirt hypervisor.
107 If you specify guest block devices directly, then libvirt is not used
114 =item B<--format> raw
116 Specify the format of disk images given on the command line. If this
117 is omitted then the format is autodetected from the content of the
120 If disk images are requested from libvirt, then this program asks
121 libvirt for this information. In this case, the value of the format
122 parameter is ignored.
124 If working with untrusted raw-format guest disk images, you should
125 ensure the format is always specified.
131 =item B<-l> | B<--long>
133 =item B<-R> | B<--recursive>
135 Select the mode. With neither of these options, C<virt-ls>
136 produces a simple, flat list of the files in the named directory.
138 C<virt-ls -l> produces a "long listing", which shows more detail (just
139 like the plain C<ls -l> command).
141 C<virt-ls -R> produces a recursive list of files starting at the named
142 directory. See the documentation for L<guestfs(3)/guestfs_find>
145 You cannot combine these options.
153 die __"virt-ls: cannot combine -l and -R options\n" if $mode;
159 die __"virt-ls: cannot combine -l and -R options\n" if $mode;
163 GetOptions ("help|?" => \$help,
164 "version" => \$version,
165 "connect|c=s" => \$uri,
166 "format=s" => \$format,
167 "long|l" => \&set_mode_l,
168 "recursive|R" => \&set_mode_R,
170 pod2usage (1) if $help;
172 my $g = Sys::Guestfs->new ();
173 my %h = $g->version ();
174 print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
178 pod2usage (__"virt-ls: no image, VM names or directory to list given")
181 my $directory = pop @ARGV;
185 $g = open_guest (\@ARGV, address => $uri, format => $format);
187 $g = open_guest (\@ARGV, format => $format);
192 my @roots = $g->inspect_os ();
194 die __x("{prog}: No operating system could be detected inside this disk image.\n\nThis may be because the file is not a disk image, or is not a virtual machine\nimage, or because the OS type is not understood by libguestfs.\n\nIf you feel this is an error, please file a bug report including as much\ninformation about the disk image as possible.\n",
195 prog => basename ($0));
198 die __x("{prog}: multiboot operating systems are not supported.\n",
199 prog => basename ($0))
201 my %fses = $g->inspect_get_mountpoints ($roots[0]);
202 my @fses = sort { length $a <=> length $b } keys %fses;
204 $g->mount_ro ($fses{$_}, $_);
208 my @r = $g->ls ($directory);
209 print "$_\n" foreach @r;
210 } elsif ($mode eq "l") {
211 print ($g->ll ($directory));
212 } else { # $mode eq "R"
213 my $dir = tempdir (CLEANUP => 1);
214 $g->find0 ($directory, "$dir/find0");
215 open F, "$dir/find0" or die "$dir/find0: $!\n";
218 while (($r = read (F, $line, 1024)) > 0) {
227 Libvirt guest names can contain arbitrary characters, some of which
228 have meaning to the shell such as C<#> and space. You may need to
229 quote or escape these characters on the command line. See the shell
230 manual page L<sh(1)> for details.
239 L<Sys::Guestfs::Lib(3)>,
241 L<http://libguestfs.org/>.
245 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
249 Copyright (C) 2009 Red Hat Inc.
251 This program is free software; you can redistribute it and/or modify
252 it under the terms of the GNU General Public License as published by
253 the Free Software Foundation; either version 2 of the License, or
254 (at your option) any later version.
256 This program is distributed in the hope that it will be useful,
257 but WITHOUT ANY WARRANTY; without even the implied warranty of
258 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
259 GNU General Public License for more details.
261 You should have received a copy of the GNU General Public License
262 along with this program; if not, write to the Free Software
263 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.