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.
95 =item B<--connect URI> | B<-c URI>
97 If using libvirt, connect to the given I<URI>. If omitted, then we
98 connect to the default libvirt hypervisor.
100 If you specify guest block devices directly, then libvirt is not used
105 =item B<--domain> guest
107 Add all the disks from the named libvirt guest. Domain UUIDs can be
108 used instead of names.
112 When prompting for keys and passphrases, virt-edit normally turns
113 echoing off so you cannot see what you are typing. If you are not
114 worried about Tempest attacks and there is no one else in the room you
115 can specify this flag to see what you are typing.
121 Instead of launching the external editor, non-interactively
122 apply the Perl expression C<EXPR> to each line in the file.
123 See L</NON-INTERACTIVE EDITING> below.
125 Be careful to properly quote the expression to prevent it from
126 being altered by the shell.
128 Note that this option is only available when Perl 5 is installed.
130 =item B<--format> raw|qcow2|...
134 The default for the I<-a> option is to auto-detect the format of the
135 disk image. Using this forces the disk format for I<-a> options which
136 follow on the command line. Using I<--format> with no argument
137 switches back to auto-detection for subsequent I<-a> options.
141 virt-edit --format=raw -a disk.img file
143 forces raw format (no auto-detection) for C<disk.img>.
145 virt-edit --format=raw -a disk.img --format -a another.img file
147 forces raw format (no auto-detection) for C<disk.img> and reverts to
148 auto-detection for C<another.img>.
150 If you have untrusted raw-format guest disk images, you should use
151 this option to specify the disk format. This avoids a possible
152 security problem with malicious guests (CVE-2010-3851).
154 =item B<--keys-from-stdin>
156 Read key or passphrase parameters from stdin. The default is
157 to try to read passphrases from the user by opening C</dev/tty>.
163 Enable verbose messages for debugging.
169 Display version number and exit.
173 Enable tracing of libguestfs API calls.
177 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
179 Previous versions of virt-edit allowed you to write either:
181 virt-edit disk.img [disk.img ...] file
185 virt-edit guestname file
187 whereas in this version you should use I<-a> or I<-d> respectively
188 to avoid the confusing case where a disk image might have the same
191 For compatibility the old style is still supported.
193 =head1 NON-INTERACTIVE EDITING
195 C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
196 the system administrator can interactively edit the file.
198 There are two ways also to use C<virt-edit> from scripts in order to
199 make automated edits to files. (Note that although you I<can> use
200 C<virt-edit> like this, it's less error-prone to write scripts
201 directly using the libguestfs API and Augeas for configuration file
204 The first method is to temporarily set C<$EDITOR> to any script or
205 program you want to run. The script is invoked as C<$EDITOR tmpfile>
206 and it should update C<tmpfile> in place however it likes.
208 The second method is to use the I<-e> parameter of C<virt-edit> to run
209 a short Perl snippet in the style of L<sed(1)>. For example to
210 replace all instances of C<foo> with C<bar> in a file:
212 virt-edit -d domname filename -e 's/foo/bar/'
214 The full power of Perl regular expressions can be used (see
215 L<perlre(1)>). For example to delete root's password you could do:
217 virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
219 What really happens is that the snippet is evaluated as a Perl
220 expression for each line of the file. The line, including the final
221 C<\n>, is passed in C<$_> and the expression should update C<$_> or
224 To delete a line, set C<$_> to the empty string. For example, to
225 delete the C<apache> user account from the password file you can do:
227 virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
229 To insert a line, prepend or append it to C<$_>. However appending
230 lines to the end of the file is rather difficult this way since there
231 is no concept of "last line of the file" - your expression just
232 doesn't get called again. You might want to use the first method
233 (setting C<$EDITOR>) if you want to do this.
235 The variable C<$lineno> contains the current line number.
236 As is traditional, the first line in the file is number C<1>.
238 The return value from the expression is ignored, but the expression
239 may call C<die> in order to abort the whole program, leaving the
240 original file untouched.
242 Remember when matching the end of a line that C<$_> may contain the
243 final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
244 with a newline then neither of these. Thus to match or substitute
245 some text at the end of a line, use this regular expression:
249 Alternately, use the perl C<chomp> function, being careful not to
250 chomp C<$_> itself (since that would remove all newlines from the
253 my $m = $_; chomp $m; $m =~ /some text$/
257 C<virt-edit> has a limited ability to understand Windows drive letters
258 and paths (eg. C<E:\foo\bar.txt>).
260 If and only if the guest is running Windows then:
266 Drive letter prefixes like C<C:> are resolved against the
267 Windows Registry to the correct filesystem.
271 Any backslash (C<\>) characters in the path are replaced
272 with forward slashes so that libguestfs can process it.
276 The path is resolved case insensitively to locate the file
277 that should be edited.
281 There are some known shortcomings:
287 Some NTFS symbolic links may not be followed correctly.
291 NTFS junction points that cross filesystems are not followed.
295 =head1 USING GUESTFISH
297 L<guestfish(1)> is a more powerful, lower level tool which you can use
298 when C<virt-edit> doesn't work.
300 Using C<virt-edit> is approximately equivalent to doing:
302 guestfish --rw -i -d domname edit /file
304 where C<domname> is the name of the libvirt guest, and C</file> is the
305 full path to the file.
307 The command above uses libguestfs's guest inspection feature and so
308 does not work on guests that libguestfs cannot inspect, or on things
309 like arbitrary disk images that don't contain guests. To edit a file
310 on a disk image directly, use:
312 guestfish --rw -a disk.img -m /dev/sda1 edit /file
314 where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
315 within the disk image to edit, and C</file> is the full path to the
318 C<virt-edit> cannot create new files. Use the guestfish commands
319 C<touch>, C<write> or C<upload> instead:
321 guestfish --rw -i -d domname touch /newfile
323 guestfish --rw -i -d domname write /newfile "new content"
325 guestfish --rw -i -d domname upload localfile /newfile
327 =head1 ENVIRONMENT VARIABLES
333 If set, this string is used as the editor. It may contain arguments,
336 If not set, C<vi> is used.
342 Libvirt guest names can contain arbitrary characters, some of which
343 have meaning to the shell such as C<#> and space. You may need to
344 quote or escape these characters on the command line. See the shell
345 manual page L<sh(1)> for details.
355 L<Sys::Guestfs::Lib(3)>,
357 L<http://libguestfs.org/>,
363 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
367 Copyright (C) 2009-2011 Red Hat Inc.
369 This program is free software; you can redistribute it and/or modify
370 it under the terms of the GNU General Public License as published by
371 the Free Software Foundation; either version 2 of the License, or
372 (at your option) any later version.
374 This program is distributed in the hope that it will be useful,
375 but WITHOUT ANY WARRANTY; without even the implied warranty of
376 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
377 GNU General Public License for more details.
379 You should have received a copy of the GNU General Public License
380 along with this program; if not, write to the Free Software
381 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.