From 984a35cfc0ae09821fb39307b98ec8399bcd8982 Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Mon, 19 Oct 2009 11:49:20 +0100 Subject: [PATCH] New tool: virt-tar This adds a new tool call virt-tar which is a general purpose archive and uploading tool. It doesn't add any functionality which wasn't previously possible using guestfish, but makes it simpler to access for some users. Examples: virt-tar -zx myguest /home home.tar.gz virt-tar -zu myguest uploadstuff.tar.gz /tmp --- .gitignore | 1 + Makefile.am | 3 +- guestfish.pod | 3 +- po/POTFILES.in | 1 + tools/Makefile.am | 2 +- tools/virt-tar | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 295 insertions(+), 3 deletions(-) create mode 100755 tools/virt-tar diff --git a/.gitignore b/.gitignore index 4467a63..507f9f1 100644 --- a/.gitignore +++ b/.gitignore @@ -74,6 +74,7 @@ html/virt-df.1.html html/virt-edit.1.html html/virt-inspector.1.html html/virt-rescue.1.html +html/virt-tar.1.html images/100kallnewlines images/100kallspaces images/100kallzeroes diff --git a/Makefile.am b/Makefile.am index 73d4f63..f4d4dd1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -168,7 +168,8 @@ all-local: -name 'virt-df' -o \ -name 'virt-edit' -o \ -name 'virt-inspector' -o \ - -name 'virt-rescue' | \ + -name 'virt-rescue' -o \ + -name 'virt-tar' | \ grep -v '^perl/blib/' | \ grep -v '^capitests/' | \ grep -v '^daemon/lib/' | \ diff --git a/guestfish.pod b/guestfish.pod index cf45c6e..66d9914 100644 --- a/guestfish.pod +++ b/guestfish.pod @@ -604,7 +604,8 @@ L, L, L, L, -L. +L, +L. =head1 AUTHORS diff --git a/po/POTFILES.in b/po/POTFILES.in index b99493b..2017c5f 100644 --- a/po/POTFILES.in +++ b/po/POTFILES.in @@ -88,3 +88,4 @@ tools/virt-cat tools/virt-df tools/virt-edit tools/virt-rescue +tools/virt-tar diff --git a/tools/Makefile.am b/tools/Makefile.am index d5fc23c..b6f95d2 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -15,7 +15,7 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -tools = cat df edit rescue +tools = cat df edit rescue tar EXTRA_DIST = \ run-locally \ diff --git a/tools/virt-tar b/tools/virt-tar new file mode 100755 index 0000000..16013b8 --- /dev/null +++ b/tools/virt-tar @@ -0,0 +1,288 @@ +#!/usr/bin/perl -w +# virt-tar +# Copyright (C) 2009 Red Hat Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +use warnings; +use strict; + +use Sys::Guestfs; +use Sys::Guestfs::Lib qw(open_guest get_partitions resolve_windows_path + inspect_all_partitions inspect_partition + inspect_operating_systems mount_operating_system); +use Pod::Usage; +use Getopt::Long; +use File::Temp qw/tempfile/; +use Locale::TextDomain 'libguestfs'; + +=encoding utf8 + +=head1 NAME + +virt-tar - Extract or upload files to a virtual machine + +=head1 SYNOPSIS + + virt-tar [--options] -x domname directory tarball + + virt-tar [--options] -u domname tarball directory + + virt-tar [--options] disk.img [disk.img ...] -x directory tarball + + virt-tar [--options] disk.img [disk.img ...] -u tarball directory + +=head1 EXAMPLES + +Download C from the VM into a local tarball: + + virt-tar -x domname /home home.tar + + virt-tar -zx domname /home home.tar.gz + +Upload a local tarball and unpack it inside C in the VM: + + virt-tar -u domname uploadstuff.tar /tmp + + virt-tar -zu domname uploadstuff.tar.gz /tmp + +=head1 WARNING + +You must I use C with the C<-u> option (upload) on live +virtual machines. If you do this, you risk disk corruption in the VM. +C tries to stop you from doing this, but doesn't catch all +cases. + +You can use C<-x> (extract) on live virtual machines, but you might +get inconsistent results or errors if there is filesystem activity +inside the VM. If the live VM is synched and quiescent, then +C will usually work, but the only way to guarantee +consistent results is if the virtual machine is shut down. + +=head1 DESCRIPTION + +C is a general purpose archive tool for downloading and +uploading parts of a guest filesystem. There are many possibilities: +making backups, uploading data files, snooping on guest activity, +fixing or customizing guests, etc. + +If you want to just view a single file, use L. If you +just want to edit a single file, use L. For more +complex cases you should look at the L tool. + +There are two modes of operation: C<-x> (eXtract) downloads a +directory and its contents (recursively) from the virtual machine into +a local tarball. C<-u> uploads from a local tarball, unpacking it +into a directory inside the virtual machine. You cannot use these two +options together. + +In addition, you may need to use the C<-z> (gZip) option to enable +compression. When uploading, you have to specify C<-z> if the upload +file is compressed because virt-tar won't detect this on its own. + +C can only handle tar (optionally gzipped) format tarballs. +For example it cannot do PKZip files or bzip2 compression. If you +want that then you'll have to rebuild the tarballs yourself. (This is +a limitation of the L API). + +=head1 OPTIONS + +=over 4 + +=cut + +my $help; + +=item B<--help> + +Display brief help. + +=cut + +my $version; + +=item B<--version> + +Display version number and exit. + +=cut + +my $uri; + +=item B<--connect URI> | B<-c URI> + +If using libvirt, connect to the given I. If omitted, then we +connect to the default libvirt hypervisor. + +If you specify guest block devices directly, then libvirt is not used +at all. + +=cut + +my $mode; + +=item B<-x> | B<--extract> | B<--download> + +=item B<-u> | B<--upload> + +Use C<-x> to extract (download) a directory from a virtual machine +to a local tarball. + +Use C<-u> to upload and unpack from a local tarball into a virtual +machine. Please read the L section above before using this +option. + +You must specify exactly one of these options. + +=cut + +my $gzip; + +=item B<-z> | B<--gzip> + +Specify that the input or output tarball is gzip-compressed. + +=back + +=cut + +sub set_mode_x +{ + die __"virt-tar: extract/upload mode specified twice on the command line\n" + if $mode; + $mode = "x"; +} + +sub set_mode_u +{ + die __"virt-tar: extract/upload mode specified twice on the command line\n" + if $mode; + $mode = "u"; +} + +Getopt::Long::Configure ("bundling"); +GetOptions ("help|?" => \$help, + "version" => \$version, + "connect|c=s" => \$uri, + "extract|download|x" => \&set_mode_x, + "upload|u" => \&set_mode_u, + "gzip|z" => \$gzip, + ) or pod2usage (2); +pod2usage (1) if $help; +if ($version) { + my $g = Sys::Guestfs->new (); + my %h = $g->version (); + print "$h{major}.$h{minor}.$h{release}$h{extra}\n"; + exit +} + +pod2usage (__"virt-tar: no image, VM names, directory or filename given") + if @ARGV <= 2; + +die __"virt-tar: either -x or -u must be specified on the command line\n" + unless $mode; + +# Note: 'pop' reads arguments right to left. +my ($tarball, $directory); +if ($mode eq "x") { + $tarball = pop @ARGV; + $directory = pop @ARGV; +} else { # $mode eq "u" + $directory = pop @ARGV; + $tarball = pop @ARGV; + die __"virt-tar: $tarball: file not found\n" unless -f $tarball; +} +die __"virt-tar: $directory: directory name must start with '/' character\n" + unless substr ($directory, 0, 1) eq "/"; + +my @args = (\@ARGV); +push @args, address => $uri if $uri; +push @args, rw => 1 if $mode eq "u"; + +my $g = open_guest (@args); +$g->launch (); + +# List of possible filesystems. +my @partitions = get_partitions ($g); + +# Now query each one to build up a picture of what's in it. +my %fses = + inspect_all_partitions ($g, \@partitions, + use_windows_registry => 0); + +my $oses = inspect_operating_systems ($g, \%fses); + +my @roots = keys %$oses; +die __"no root device found in this operating system image\n" if @roots == 0; +die __"multiboot operating systems are not supported by virt-tar\n" if @roots > 1; +my $root_dev = $roots[0]; + +my $os = $oses->{$root_dev}; +mount_operating_system ($g, $os, $mode eq "u" ? 0 : 1); + +# Do the tar command. +if ($mode eq "x") { + if ($gzip) { + $g->tgz_out ($directory, $tarball); + } else { + $g->tar_out ($directory, $tarball); + } +} else { # mode eq "u" + if ($gzip) { + $g->tgz_in ($tarball, $directory); + } else { + $g->tar_in ($tarball, $directory); + } +} + +$g->sync (); +$g->umount_all (); + +undef $g; + +exit 0; + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHOR + +Richard W.M. Jones L + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -- 1.8.3.1