virt-tar(1)

1virt-tar(1)                 Virtualization Support                 virt-tar(1)
2
3
4

NAME

6       virt-tar - Extract or upload files to a virtual machine
7

SYNOPSIS

9        virt-tar [--options] -x domname directory tarball
10
11        virt-tar [--options] -u domname tarball directory
12
13        virt-tar [--options] disk.img [disk.img ...] -x directory tarball
14
15        virt-tar [--options] disk.img [disk.img ...] -u tarball directory
16

EXAMPLES

18       Download "/home" from the VM into a local tarball:
19
20        virt-tar -x domname /home home.tar
21
22        virt-tar -zx domname /home home.tar.gz
23
24       Upload a local tarball and unpack it inside "/tmp" in the VM:
25
26        virt-tar -u domname uploadstuff.tar /tmp
27
28        virt-tar -zu domname uploadstuff.tar.gz /tmp
29

WARNING

31       You must not use "virt-tar" with the "-u" option (upload) on live
32       virtual machines.  If you do this, you risk disk corruption in the VM.
33       "virt-tar" tries to stop you from doing this, but doesn't catch all
34       cases.
35
36       You can use "-x" (extract) on live virtual machines, but you might get
37       inconsistent results or errors if there is filesystem activity inside
38       the VM.  If the live VM is synched and quiescent, then "virt-tar" will
39       usually work, but the only way to guarantee consistent results is if
40       the virtual machine is shut down.
41

DESCRIPTION

43       "virt-tar" is a general purpose archive tool for downloading and
44       uploading parts of a guest filesystem.  There are many possibilities:
45       making backups, uploading data files, snooping on guest activity,
46       fixing or customizing guests, etc.
47
48       If you want to just view a single file, use virt-cat(1).  If you just
49       want to edit a single file, use virt-edit(1).  For more complex cases
50       you should look at the guestfish(1) tool.
51
52       There are two modes of operation: "-x" (eXtract) downloads a directory
53       and its contents (recursively) from the virtual machine into a local
54       tarball.  "-u" uploads from a local tarball, unpacking it into a
55       directory inside the virtual machine.  You cannot use these two options
56       together.
57
58       In addition, you may need to use the "-z" (gZip) option to enable
59       compression.  When uploading, you have to specify "-z" if the upload
60       file is compressed because virt-tar won't detect this on its own.
61
62       "virt-tar" can only handle tar (optionally gzipped) format tarballs.
63       For example it cannot do PKZip files or bzip2 compression.  If you want
64       that then you'll have to rebuild the tarballs yourself.  (This is a
65       limitation of the libguestfs(3) API).
66

OPTIONS

68       --help
69           Display brief help.
70
71       --version
72           Display version number and exit.
73
74       --connect URI | -c URI
75           If using libvirt, connect to the given URI.  If omitted, then we
76           connect to the default libvirt hypervisor.
77
78           If you specify guest block devices directly, then libvirt is not
79           used at all.
80
81       --format raw
82           Specify the format of disk images given on the command line.  If
83           this is omitted then the format is autodetected from the content of
84           the disk image.
85
86           If disk images are requested from libvirt, then this program asks
87           libvirt for this information.  In this case, the value of the
88           format parameter is ignored.
89
90           If working with untrusted raw-format guest disk images, you should
91           ensure the format is always specified.
92
93       -x | --extract | --download
94       -u | --upload
95           Use "-x" to extract (download) a directory from a virtual machine
96           to a local tarball.
97
98           Use "-u" to upload and unpack from a local tarball into a virtual
99           machine.  Please read the "WARNING" section above before using this
100           option.
101
102           You must specify exactly one of these options.
103
104       -z | --gzip
105           Specify that the input or output tarball is gzip-compressed.
106

SHELL QUOTING

108       Libvirt guest names can contain arbitrary characters, some of which
109       have meaning to the shell such as "#" and space.  You may need to quote
110       or escape these characters on the command line.  See the shell manual
111       page sh(1) for details.
112

AUTHOR

118       Richard W.M. Jones <http://people.redhat.com/~rjones/>
119

COPYRIGHT

121       Copyright (C) 2009 Red Hat Inc.
122
123       This program is free software; you can redistribute it and/or modify it
124       under the terms of the GNU General Public License as published by the
125       Free Software Foundation; either version 2 of the License, or (at your
126       option) any later version.
127
128       This program is distributed in the hope that it will be useful, but
129       WITHOUT ANY WARRANTY; without even the implied warranty of
130       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
131       General Public License for more details.
132
133       You should have received a copy of the GNU General Public License along
134       with this program; if not, write to the Free Software Foundation, Inc.,
135       675 Mass Ave, Cambridge, MA 02139, USA.
136
137
138
139libguestfs-1.8.15                 2011-11-10                       virt-tar(1)