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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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<-c URI>
 128
 129 =item B<--connect URI>
 130
 131 If using libvirt, connect to the given I<URI>.  If omitted, then we
 132 connect to the default libvirt hypervisor.
 133
 134 If you specify guest block devices directly, then libvirt is not used
 135 at all.
 136
 137 =cut
 138
 139 my $format;
 140
 141 =item B<--format> raw
 142
 143 Specify the format of disk images given on the command line.  If this
 144 is omitted then the format is autodetected from the content of the
 145 disk image.
 146
 147 If disk images are requested from libvirt, then this program asks
 148 libvirt for this information.  In this case, the value of the format
 149 parameter is ignored.
 150
 151 If working with untrusted raw-format guest disk images, you should
 152 ensure the format is always specified.
 153
 154 =cut
 155
 156 my $mode;
 157
 158 =item B<-x>
 159
 160 =item B<--extract>
 161
 162 =item B<--download>
 163
 164 =item B<-u>
 165
 166 =item B<--upload>
 167
 168 Use I<-x> to extract (download) a directory from a virtual machine
 169 to a local tarball.
 170
 171 Use I<-u> to upload and unpack from a local tarball into a virtual
 172 machine.  Please read the L</WARNING> section above before using this
 173 option.
 174
 175 You must specify exactly one of these options.
 176
 177 =cut
 178
 179 my $gzip;
 180
 181 =item B<-z>
 182
 183 =item B<--gzip>
 184
 185 Specify that the input or output tarball is gzip-compressed.
 186
 187 =back
 188
 189 =cut
 190
 191 sub set_mode_x
 192 {
 193     die __"virt-tar: extract/upload mode specified twice on the command line\n"
 194         if $mode;
 195     $mode = "x";
 196 }
 197
 198 sub set_mode_u
 199 {
 200     die __"virt-tar: extract/upload mode specified twice on the command line\n"
 201         if $mode;
 202     $mode = "u";
 203 }
 204
 205 Getopt::Long::Configure ("bundling");
 206 GetOptions ("help|?" => \$help,
 207             "version" => \$version,
 208             "connect|c=s" => \$uri,
 209             "format=s" => \$format,
 210             "extract|download|x" => \&set_mode_x,
 211             "upload|u" => \&set_mode_u,
 212             "gzip|z" => \$gzip,
 213     ) or pod2usage (2);
 214 pod2usage (1) if $help;
 215 if ($version) {
 216     my $g = Sys::Guestfs->new ();
 217     my %h = $g->version ();
 218     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 219     exit
 220 }
 221
 222 pod2usage (__"virt-tar: no image, VM names, directory or filename given")
 223     if @ARGV <= 2;
 224
 225 die __"virt-tar: either -x or -u must be specified on the command line\n"
 226     unless $mode;
 227
 228 # Note: 'pop' reads arguments right to left.
 229 my ($tarball, $directory);
 230 if ($mode eq "x") {
 231     $tarball = pop @ARGV;
 232     $directory = pop @ARGV;
 233 } else { # $mode eq "u"
 234     $directory = pop @ARGV;
 235     $tarball = pop @ARGV;
 236     die __x("virt-tar: {tarball}: file not found\n",
 237             tarball => $tarball) unless -f $tarball;
 238 }
 239 die __x("virt-tar: {dir}: directory name must start with '/' character\n",
 240         dir => $directory)
 241     unless substr ($directory, 0, 1) eq "/";
 242
 243 my @args = (\@ARGV);
 244 push @args, address => $uri if $uri;
 245 push @args, rw => 1 if $mode eq "u";
 246 push @args, format => $format if defined $format;
 247
 248 my $g = open_guest (@args);
 249 $g->launch ();
 250
 251 my @roots = $g->inspect_os ();
 252 if (@roots == 0) {
 253     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",
 254             prog => basename ($0));
 255 }
 256 if (@roots > 1) {
 257     die __x("{prog}: multiboot operating systems are not supported.\n",
 258             prog => basename ($0))
 259 }
 260 my %fses = $g->inspect_get_mountpoints ($roots[0]);
 261 my @fses = sort { length $a <=> length $b } keys %fses;
 262 my $mountopts = $mode eq "u" ? "" : "ro";
 263 foreach (@fses) {
 264     $g->mount_options ($mountopts, $fses{$_}, $_);
 265 }
 266
 267 # Do the tar command.
 268 if ($mode eq "x") {
 269     if ($gzip) {
 270         $g->tgz_out ($directory, $tarball);
 271     } else {
 272         $g->tar_out ($directory, $tarball);
 273     }
 274 } else { # mode eq "u"
 275     if ($gzip) {
 276         $g->tgz_in ($tarball, $directory);
 277     } else {
 278         $g->tar_in ($tarball, $directory);
 279     }
 280 }
 281
 282 $g->sync ();
 283 $g->umount_all ();
 284
 285 undef $g;
 286
 287 exit 0;
 288
 289 =head1 SHELL QUOTING
 290
 291 Libvirt guest names can contain arbitrary characters, some of which
 292 have meaning to the shell such as C<#> and space.  You may need to
 293 quote or escape these characters on the command line.  See the shell
 294 manual page L<sh(1)> for details.
 295
 296 =head1 SEE ALSO
 297
 298 L<guestfs(3)>,
 299 L<guestfish(1)>,
 300 L<virt-cat(1)>,
 301 L<virt-edit(1)>,
 302 L<virt-copy-in(1)>,
 303 L<virt-copy-out(1)>,
 304 L<virt-tar-in(1)>,
 305 L<virt-tar-out(1)>,
 306 L<Sys::Guestfs(3)>,
 307 L<Sys::Guestfs::Lib(3)>,
 308 L<Sys::Virt(3)>,
 309 L<http://libguestfs.org/>.
 310
 311 =head1 AUTHOR
 312
 313 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 314
 315 =head1 COPYRIGHT
 316
 317 Copyright (C) 2009 Red Hat Inc.
 318
 319 This program is free software; you can redistribute it and/or modify
 320 it under the terms of the GNU General Public License as published by
 321 the Free Software Foundation; either version 2 of the License, or
 322 (at your option) any later version.
 323
 324 This program is distributed in the hope that it will be useful,
 325 but WITHOUT ANY WARRANTY; without even the implied warranty of
 326 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 327 GNU General Public License for more details.
 328
 329 You should have received a copy of the GNU General Public License
 330 along with this program; if not, write to the Free Software
 331 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.