5 virt-edit - Edit a file in a virtual machine
9 virt-edit [--options] -d domname file [file ...]
11 virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
13 virt-edit [-d domname|-a disk.img] file -e 'expr'
17 virt-edit domname file
19 virt-edit disk.img [disk.img ...] file
23 You must I<not> use C<virt-edit> on live virtual machines. If you do
24 this, you risk disk corruption in the VM. C<virt-edit> tries to stop
25 you from doing this, but doesn't catch all cases.
29 C<virt-edit> is a command line tool to edit C<file> where each C<file>
30 exists in the named virtual machine (or disk image).
32 Multiple filenames can be given, in which case they are each edited in
33 turn. Each filename must be a full path, starting at the root
34 directory (starting with '/').
36 If you want to just view a file, use L<virt-cat(1)>.
38 For more complex cases you should look at the L<guestfish(1)> tool
39 (see L</USING GUESTFISH> below).
41 C<virt-edit> cannot be used to create a new file. L<guestfish(1)> can
42 do that and much more.
46 Edit the named files interactively:
48 virt-edit -d mydomain /boot/grub/grub.conf
50 virt-edit -d mydomain /etc/passwd
52 For Windows guests, some Windows paths are understood:
54 virt-edit -d mywindomain 'c:\autoexec.bat'
56 If Perl is installed, you can also edit files non-interactively (see
57 L</NON-INTERACTIVE EDITING> below).
58 To change the init default level to 5:
60 virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
74 Add I<file> which should be a disk image from a virtual machine. If
75 the virtual machine has multiple block devices, you must supply all of
76 them with separate I<-a> options.
78 The format of the disk image is auto-detected. To override this and
79 force a particular format use the I<--format=..> option.
83 =item B<--backup> extension
85 Create a backup of the original file I<in the guest disk image>.
86 The backup has the original filename with C<extension> added.
88 Usually the first character of C<extension> would be a dot C<.>
91 virt-edit -b .orig [etc]
93 By default, no backup file is made.
97 =item B<--connect URI>
99 If using libvirt, connect to the given I<URI>. If omitted, then we
100 connect to the default libvirt hypervisor.
102 If you specify guest block devices directly, then libvirt is not used
107 =item B<--domain> guest
109 Add all the disks from the named libvirt guest. Domain UUIDs can be
110 used instead of names.
114 When prompting for keys and passphrases, virt-edit normally turns
115 echoing off so you cannot see what you are typing. If you are not
116 worried about Tempest attacks and there is no one else in the room you
117 can specify this flag to see what you are typing.
123 Instead of launching the external editor, non-interactively
124 apply the Perl expression C<EXPR> to each line in the file.
125 See L</NON-INTERACTIVE EDITING> below.
127 Be careful to properly quote the expression to prevent it from
128 being altered by the shell.
130 Note that this option is only available when Perl 5 is installed.
132 =item B<--format> raw|qcow2|...
136 The default for the I<-a> option is to auto-detect the format of the
137 disk image. Using this forces the disk format for I<-a> options which
138 follow on the command line. Using I<--format> with no argument
139 switches back to auto-detection for subsequent I<-a> options.
143 virt-edit --format=raw -a disk.img file
145 forces raw format (no auto-detection) for C<disk.img>.
147 virt-edit --format=raw -a disk.img --format -a another.img file
149 forces raw format (no auto-detection) for C<disk.img> and reverts to
150 auto-detection for C<another.img>.
152 If you have untrusted raw-format guest disk images, you should use
153 this option to specify the disk format. This avoids a possible
154 security problem with malicious guests (CVE-2010-3851).
156 =item B<--keys-from-stdin>
158 Read key or passphrase parameters from stdin. The default is
159 to try to read passphrases from the user by opening C</dev/tty>.
165 Enable verbose messages for debugging.
171 Display version number and exit.
175 Enable tracing of libguestfs API calls.
179 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
181 Previous versions of virt-edit allowed you to write either:
183 virt-edit disk.img [disk.img ...] file
187 virt-edit guestname file
189 whereas in this version you should use I<-a> or I<-d> respectively
190 to avoid the confusing case where a disk image might have the same
193 For compatibility the old style is still supported.
195 =head1 NON-INTERACTIVE EDITING
197 C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
198 the system administrator can interactively edit the file.
200 There are two ways also to use C<virt-edit> from scripts in order to
201 make automated edits to files. (Note that although you I<can> use
202 C<virt-edit> like this, it's less error-prone to write scripts
203 directly using the libguestfs API and Augeas for configuration file
206 The first method is to temporarily set C<$EDITOR> to any script or
207 program you want to run. The script is invoked as C<$EDITOR tmpfile>
208 and it should update C<tmpfile> in place however it likes.
210 The second method is to use the I<-e> parameter of C<virt-edit> to run
211 a short Perl snippet in the style of L<sed(1)>. For example to
212 replace all instances of C<foo> with C<bar> in a file:
214 virt-edit -d domname filename -e 's/foo/bar/'
216 The full power of Perl regular expressions can be used (see
217 L<perlre(1)>). For example to delete root's password you could do:
219 virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
221 What really happens is that the snippet is evaluated as a Perl
222 expression for each line of the file. The line, including the final
223 C<\n>, is passed in C<$_> and the expression should update C<$_> or
226 To delete a line, set C<$_> to the empty string. For example, to
227 delete the C<apache> user account from the password file you can do:
229 virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
231 To insert a line, prepend or append it to C<$_>. However appending
232 lines to the end of the file is rather difficult this way since there
233 is no concept of "last line of the file" - your expression just
234 doesn't get called again. You might want to use the first method
235 (setting C<$EDITOR>) if you want to do this.
237 The variable C<$lineno> contains the current line number.
238 As is traditional, the first line in the file is number C<1>.
240 The return value from the expression is ignored, but the expression
241 may call C<die> in order to abort the whole program, leaving the
242 original file untouched.
244 Remember when matching the end of a line that C<$_> may contain the
245 final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
246 with a newline then neither of these. Thus to match or substitute
247 some text at the end of a line, use this regular expression:
251 Alternately, use the perl C<chomp> function, being careful not to
252 chomp C<$_> itself (since that would remove all newlines from the
255 my $m = $_; chomp $m; $m =~ /some text$/
259 C<virt-edit> has a limited ability to understand Windows drive letters
260 and paths (eg. C<E:\foo\bar.txt>).
262 If and only if the guest is running Windows then:
268 Drive letter prefixes like C<C:> are resolved against the
269 Windows Registry to the correct filesystem.
273 Any backslash (C<\>) characters in the path are replaced
274 with forward slashes so that libguestfs can process it.
278 The path is resolved case insensitively to locate the file
279 that should be edited.
283 There are some known shortcomings:
289 Some NTFS symbolic links may not be followed correctly.
293 NTFS junction points that cross filesystems are not followed.
297 =head1 USING GUESTFISH
299 L<guestfish(1)> is a more powerful, lower level tool which you can use
300 when C<virt-edit> doesn't work.
302 Using C<virt-edit> is approximately equivalent to doing:
304 guestfish --rw -i -d domname edit /file
306 where C<domname> is the name of the libvirt guest, and C</file> is the
307 full path to the file.
309 The command above uses libguestfs's guest inspection feature and so
310 does not work on guests that libguestfs cannot inspect, or on things
311 like arbitrary disk images that don't contain guests. To edit a file
312 on a disk image directly, use:
314 guestfish --rw -a disk.img -m /dev/sda1 edit /file
316 where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
317 within the disk image to edit, and C</file> is the full path to the
320 C<virt-edit> cannot create new files. Use the guestfish commands
321 C<touch>, C<write> or C<upload> instead:
323 guestfish --rw -i -d domname touch /newfile
325 guestfish --rw -i -d domname write /newfile "new content"
327 guestfish --rw -i -d domname upload localfile /newfile
329 =head1 ENVIRONMENT VARIABLES
335 If set, this string is used as the editor. It may contain arguments,
338 If not set, C<vi> is used.
344 Libvirt guest names can contain arbitrary characters, some of which
345 have meaning to the shell such as C<#> and space. You may need to
346 quote or escape these characters on the command line. See the shell
347 manual page L<sh(1)> for details.
351 This program returns 0 if successful, or non-zero if there was an
362 L<Sys::Guestfs::Lib(3)>,
364 L<http://libguestfs.org/>,
370 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
374 Copyright (C) 2009-2011 Red Hat Inc.
376 This program is free software; you can redistribute it and/or modify
377 it under the terms of the GNU General Public License as published by
378 the Free Software Foundation; either version 2 of the License, or
379 (at your option) any later version.
381 This program is distributed in the hope that it will be useful,
382 but WITHOUT ANY WARRANTY; without even the implied warranty of
383 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
384 GNU General Public License for more details.
386 You should have received a copy of the GNU General Public License
387 along with this program; if not, write to the Free Software
388 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.