tools/virt-tar

   1 #!/usr/bin/perl -w
   2 # virt-tar
   3 # Copyright (C) 2009-2010 Red Hat Inc.
   4 #
   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.
   9 #
  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.
  14 #
  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.
  18
  19 use warnings;
  20 use strict;
  21
  22 use Sys::Guestfs;
  23 use Sys::Guestfs::Lib qw(open_guest);
  24 use Pod::Usage;
  25 use Getopt::Long;
  26 use File::Basename;
  27 use Locale::TextDomain 'libguestfs';
  28
  29 =encoding utf8
  30
  31 =head1 NAME
  32
  33 virt-tar - Extract or upload files to a virtual machine
  34
  35 =head1 SYNOPSIS
  36
  37  virt-tar [--options] -x domname directory tarball
  38
  39  virt-tar [--options] -u domname tarball directory
  40
  41  virt-tar [--options] disk.img [disk.img ...] -x directory tarball
  42
  43  virt-tar [--options] disk.img [disk.img ...] -u tarball directory
  44
  45 =head1 NOTE
  46
  47 This tool is obsolete.  Use L<virt-copy-in(1)>, L<virt-copy-out(1)>,
  48 L<virt-tar-in(1)>, L<virt-tar-out(1)> as replacements.
  49
  50 =head1 EXAMPLES
  51
  52 Download C</home> from the VM into a local tarball:
  53
  54  virt-tar -x domname /home home.tar
  55
  56  virt-tar -zx domname /home home.tar.gz
  57
  58 Upload a local tarball and unpack it inside C</tmp> in the VM:
  59
  60  virt-tar -u domname uploadstuff.tar /tmp
  61
  62  virt-tar -zu domname uploadstuff.tar.gz /tmp
  63
  64 =head1 WARNING
  65
  66 You must I<not> use C<virt-tar> with the I<-u> option (upload) on live
  67 virtual machines.  If you do this, you risk disk corruption in the VM.
  68 C<virt-tar> tries to stop you from doing this, but doesn't catch all
  69 cases.
  70
  71 You can use I<-x> (extract) on live virtual machines, but you might
  72 get inconsistent results or errors if there is filesystem activity
  73 inside the VM.  If the live VM is synched and quiescent, then
  74 C<virt-tar> will usually work, but the only way to guarantee
  75 consistent results is if the virtual machine is shut down.
  76
  77 =head1 DESCRIPTION
  78
  79 C<virt-tar> is a general purpose archive tool for downloading and
  80 uploading parts of a guest filesystem.  There are many possibilities:
  81 making backups, uploading data files, snooping on guest activity,
  82 fixing or customizing guests, etc.
  83
  84 If you want to just view a single file, use L<virt-cat(1)>.  If you
  85 just want to edit a single file, use L<virt-edit(1)>.  For more
  86 complex cases you should look at the L<guestfish(1)> tool.
  87
  88 There are two modes of operation: I<-x> (eXtract) downloads a
  89 directory and its contents (recursively) from the virtual machine into
  90 a local tarball.  I<-u> uploads from a local tarball, unpacking it
  91 into a directory inside the virtual machine.  You cannot use these two
  92 options together.
  93
  94 In addition, you may need to use the I<-z> (gZip) option to enable
  95 compression.  When uploading, you have to specify I<-z> if the upload
  96 file is compressed because virt-tar won't detect this on its own.
  97
  98 C<virt-tar> can only handle tar (optionally gzipped) format tarballs.
  99 For example it cannot do PKZip files or bzip2 compression.  If you
 100 want that then you'll have to rebuild the tarballs yourself.  (This is
 101 a limitation of the L<libguestfs(3)> API).
 102
 103 =head1 OPTIONS
 104
 105 =over 4
 106
 107 =cut
 108
 109 my $help;
 110
 111 =item B<--help>
 112
 113 Display brief help.
 114
 115 =cut
 116
 117 my $version;
 118
 119 =item B<--version>
 120
 121 Display version number and exit.
 122
 123 =cut
 124
 125 my $uri;
 126
 127 =item B<--connect URI> | B<-c URI>
 128
 129 If using libvirt, connect to the given I<URI>.  If omitted, then we
 130 connect to the default libvirt hypervisor.
 131
 132 If you specify guest block devices directly, then libvirt is not used
 133 at all.
 134
 135 =cut
 136
 137 my $format;
 138
 139 =item B<--format> raw
 140
 141 Specify the format of disk images given on the command line.  If this
 142 is omitted then the format is autodetected from the content of the
 143 disk image.
 144
 145 If disk images are requested from libvirt, then this program asks
 146 libvirt for this information.  In this case, the value of the format
 147 parameter is ignored.
 148
 149 If working with untrusted raw-format guest disk images, you should
 150 ensure the format is always specified.
 151
 152 =cut
 153
 154 my $mode;
 155
 156 =item B<-x> | B<--extract> | B<--download>
 157
 158 =item B<-u> | B<--upload>
 159
 160 Use I<-x> to extract (download) a directory from a virtual machine
 161 to a local tarball.
 162
 163 Use I<-u> to upload and unpack from a local tarball into a virtual
 164 machine.  Please read the L</WARNING> section above before using this
 165 option.
 166
 167 You must specify exactly one of these options.
 168
 169 =cut
 170
 171 my $gzip;
 172
 173 =item B<-z> | B<--gzip>
 174
 175 Specify that the input or output tarball is gzip-compressed.
 176
 177 =back
 178
 179 =cut
 180
 181 sub set_mode_x
 182 {
 183     die __"virt-tar: extract/upload mode specified twice on the command line\n"
 184         if $mode;
 185     $mode = "x";
 186 }
 187
 188 sub set_mode_u
 189 {
 190     die __"virt-tar: extract/upload mode specified twice on the command line\n"
 191         if $mode;
 192     $mode = "u";
 193 }
 194
 195 Getopt::Long::Configure ("bundling");
 196 GetOptions ("help|?" => \$help,
 197             "version" => \$version,
 198             "connect|c=s" => \$uri,
 199             "format=s" => \$format,
 200             "extract|download|x" => \&set_mode_x,
 201             "upload|u" => \&set_mode_u,
 202             "gzip|z" => \$gzip,
 203     ) or pod2usage (2);
 204 pod2usage (1) if $help;
 205 if ($version) {
 206     my $g = Sys::Guestfs->new ();
 207     my %h = $g->version ();
 208     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 209     exit
 210 }
 211
 212 pod2usage (__"virt-tar: no image, VM names, directory or filename given")
 213     if @ARGV <= 2;
 214
 215 die __"virt-tar: either -x or -u must be specified on the command line\n"
 216     unless $mode;
 217
 218 # Note: 'pop' reads arguments right to left.
 219 my ($tarball, $directory);
 220 if ($mode eq "x") {
 221     $tarball = pop @ARGV;
 222     $directory = pop @ARGV;
 223 } else { # $mode eq "u"
 224     $directory = pop @ARGV;
 225     $tarball = pop @ARGV;
 226     die __x("virt-tar: {tarball}: file not found\n",
 227             tarball => $tarball) unless -f $tarball;
 228 }
 229 die __x("virt-tar: {dir}: directory name must start with '/' character\n",
 230         dir => $directory)
 231     unless substr ($directory, 0, 1) eq "/";
 232
 233 my @args = (\@ARGV);
 234 push @args, address => $uri if $uri;
 235 push @args, rw => 1 if $mode eq "u";
 236 push @args, format => $format if defined $format;
 237
 238 my $g = open_guest (@args);
 239 $g->launch ();
 240
 241 my @roots = $g->inspect_os ();
 242 if (@roots == 0) {
 243     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",
 244             prog => basename ($0));
 245 }
 246 if (@roots > 1) {
 247     die __x("{prog}: multiboot operating systems are not supported.\n",
 248             prog => basename ($0))
 249 }
 250 my %fses = $g->inspect_get_mountpoints ($roots[0]);
 251 my @fses = sort { length $a <=> length $b } keys %fses;
 252 my $mountopts = $mode eq "u" ? "" : "ro";
 253 foreach (@fses) {
 254     $g->mount_options ($mountopts, $fses{$_}, $_);
 255 }
 256
 257 # Do the tar command.
 258 if ($mode eq "x") {
 259     if ($gzip) {
 260         $g->tgz_out ($directory, $tarball);
 261     } else {
 262         $g->tar_out ($directory, $tarball);
 263     }
 264 } else { # mode eq "u"
 265     if ($gzip) {
 266         $g->tgz_in ($tarball, $directory);
 267     } else {
 268         $g->tar_in ($tarball, $directory);
 269     }
 270 }
 271
 272 $g->sync ();
 273 $g->umount_all ();
 274
 275 undef $g;
 276
 277 exit 0;
 278
 279 =head1 SHELL QUOTING
 280
 281 Libvirt guest names can contain arbitrary characters, some of which
 282 have meaning to the shell such as C<#> and space.  You may need to
 283 quote or escape these characters on the command line.  See the shell
 284 manual page L<sh(1)> for details.
 285
 286 =head1 SEE ALSO
 287
 288 L<guestfs(3)>,
 289 L<guestfish(1)>,
 290 L<virt-cat(1)>,
 291 L<virt-edit(1)>,
 292 L<virt-copy-in(1)>,
 293 L<virt-copy-out(1)>,
 294 L<virt-tar-in(1)>,
 295 L<virt-tar-out(1)>,
 296 L<Sys::Guestfs(3)>,
 297 L<Sys::Guestfs::Lib(3)>,
 298 L<Sys::Virt(3)>,
 299 L<http://libguestfs.org/>.
 300
 301 =head1 AUTHOR
 302
 303 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 304
 305 =head1 COPYRIGHT
 306
 307 Copyright (C) 2009 Red Hat Inc.
 308
 309 This program is free software; you can redistribute it and/or modify
 310 it under the terms of the GNU General Public License as published by
 311 the Free Software Foundation; either version 2 of the License, or
 312 (at your option) any later version.
 313
 314 This program is distributed in the hope that it will be useful,
 315 but WITHOUT ANY WARRANTY; without even the implied warranty of
 316 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 317 GNU General Public License for more details.
 318
 319 You should have received a copy of the GNU General Public License
 320 along with this program; if not, write to the Free Software
 321 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.