1virt-edit(1) Virtualization Support virt-edit(1)
2
6 virt-edit - Edit a file in a virtual machine
7
9 virt-edit [--options] -d domname file [file ...]
10 virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
12 virt-edit [-d domname|-a disk.img] file -e 'expr'
14 Old-style:
16 virt-edit domname file
18 virt-edit disk.img [disk.img ...] file
20
22 You must not use "virt-edit" on live virtual machines. If you do this,
23 you risk disk corruption in the VM. "virt-edit" tries to stop you from
24 doing this, but doesn't catch all cases.
25
27 "virt-edit" is a command line tool to edit "file" where each "file"
28 exists in the named virtual machine (or disk image).
29 Multiple filenames can be given, in which case they are each edited in
31 turn. Each filename must be a full path, starting at the root
32 directory (starting with '/').
33 If you want to just view a file, use virt-cat(1).
35 For more complex cases you should look at the guestfish(1) tool (see
37 "USING GUESTFISH" below).
38 "virt-edit" cannot be used to create a new file. guestfish(1) can do
40 that and much more.
41
43 Edit the named files interactively:
44 virt-edit -d mydomain /boot/grub/grub.conf
46 virt-edit -d mydomain /etc/passwd
48 For Windows guests, some Windows paths are understood:
50 virt-edit -d mywindomain 'c:\autoexec.bat'
52 If Perl is installed, you can also edit files non-interactively (see
54 "NON-INTERACTIVE EDITING" below). To change the init default level to
55 5:
56 virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
58
60 --help
61 Display brief help.
62 -a file
64 --add file
65 Add file which should be a disk image from a virtual machine. If
66 the virtual machine has multiple block devices, you must supply all
67 of them with separate -a options.
68 The format of the disk image is auto-detected. To override this
70 and force a particular format use the --format=.. option.
71 -b extension
73 --backup extension
74 Create a backup of the original file in the guest disk image. The
75 backup has the original filename with "extension" added.
76 Usually the first character of "extension" would be a dot "." so
78 you would write:
79 virt-edit -b .orig [etc]
81 By default, no backup file is made.
83 -c URI
85 --connect URI
86 If using libvirt, connect to the given URI. If omitted, then we
87 connect to the default libvirt hypervisor.
88 If you specify guest block devices directly, then libvirt is not
90 used at all.
91 -d guest
93 --domain guest
94 Add all the disks from the named libvirt guest. Domain UUIDs can
95 be used instead of names.
96 --echo-keys
98 When prompting for keys and passphrases, virt-edit normally turns
99 echoing off so you cannot see what you are typing. If you are not
100 worried about Tempest attacks and there is no one else in the room
101 you can specify this flag to see what you are typing.
102 -e EXPR
104 --expr EXPR
105 Instead of launching the external editor, non-interactively apply
106 the Perl expression "EXPR" to each line in the file. See "NON-
107 INTERACTIVE EDITING" below.
108 Be careful to properly quote the expression to prevent it from
110 being altered by the shell.
111 Note that this option is only available when Perl 5 is installed.
113 --format=raw|qcow2|..
115 --format
116 The default for the -a option is to auto-detect the format of the
117 disk image. Using this forces the disk format for -a options which
118 follow on the command line. Using --format with no argument
119 switches back to auto-detection for subsequent -a options.
120 For example:
122 virt-edit --format=raw -a disk.img file
124 forces raw format (no auto-detection) for "disk.img".
126 virt-edit --format=raw -a disk.img --format -a another.img file
128 forces raw format (no auto-detection) for "disk.img" and reverts to
130 auto-detection for "another.img".
131 If you have untrusted raw-format guest disk images, you should use
133 this option to specify the disk format. This avoids a possible
134 security problem with malicious guests (CVE-2010-3851).
135 --keys-from-stdin
137 Read key or passphrase parameters from stdin. The default is to
138 try to read passphrases from the user by opening "/dev/tty".
139 -v
141 --verbose
142 Enable verbose messages for debugging.
143 -V
145 --version
146 Display version number and exit.
147 -x Enable tracing of libguestfs API calls.
149
151 Previous versions of virt-edit allowed you to write either:
152 virt-edit disk.img [disk.img ...] file
154 or
156 virt-edit guestname file
158 whereas in this version you should use -a or -d respectively to avoid
160 the confusing case where a disk image might have the same name as a
161 guest.
162 For compatibility the old style is still supported.
164
166 "virt-edit" normally calls out to $EDITOR (or vi) so the system
167 administrator can interactively edit the file.
168 There are two ways also to use "virt-edit" from scripts in order to
170 make automated edits to files. (Note that although you can use
171 "virt-edit" like this, it's less error-prone to write scripts directly
172 using the libguestfs API and Augeas for configuration file editing.)
173 The first method is to temporarily set $EDITOR to any script or program
175 you want to run. The script is invoked as "$EDITOR tmpfile" and it
176 should update "tmpfile" in place however it likes.
177 The second method is to use the -e parameter of "virt-edit" to run a
179 short Perl snippet in the style of sed(1). For example to replace all
180 instances of "foo" with "bar" in a file:
181 virt-edit -d domname filename -e 's/foo/bar/'
183 The full power of Perl regular expressions can be used (see perlre(1)).
185 For example to delete root's password you could do:
186 virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
188 What really happens is that the snippet is evaluated as a Perl
190 expression for each line of the file. The line, including the final
191 "\n", is passed in $_ and the expression should update $_ or leave it
192 unchanged.
193 To delete a line, set $_ to the empty string. For example, to delete
195 the "apache" user account from the password file you can do:
196 virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
198 To insert a line, prepend or append it to $_. However appending lines
200 to the end of the file is rather difficult this way since there is no
201 concept of "last line of the file" - your expression just doesn't get
202 called again. You might want to use the first method (setting $EDITOR)
203 if you want to do this.
204 The variable $lineno contains the current line number. As is
206 traditional, the first line in the file is number 1.
207 The return value from the expression is ignored, but the expression may
209 call "die" in order to abort the whole program, leaving the original
210 file untouched.
211 Remember when matching the end of a line that $_ may contain the final
213 "\n", or (for DOS files) "\r\n", or if the file does not end with a
214 newline then neither of these. Thus to match or substitute some text
215 at the end of a line, use this regular expression:
216 /some text(\r?\n)?$/
218 Alternately, use the perl "chomp" function, being careful not to chomp
220 $_ itself (since that would remove all newlines from the file):
221 my $m = $_; chomp $m; $m =~ /some text$/
223
225 "virt-edit" has a limited ability to understand Windows drive letters
226 and paths (eg. "E:\foo\bar.txt").
227 If and only if the guest is running Windows then:
229 · Drive letter prefixes like "C:" are resolved against the Windows
231 Registry to the correct filesystem.
232 · Any backslash ("\") characters in the path are replaced with
234 forward slashes so that libguestfs can process it.
235 · The path is resolved case insensitively to locate the file that
237 should be edited.
238 There are some known shortcomings:
240 · Some NTFS symbolic links may not be followed correctly.
242 · NTFS junction points that cross filesystems are not followed.
244
246 guestfish(1) is a more powerful, lower level tool which you can use
247 when "virt-edit" doesn't work.
248 Using "virt-edit" is approximately equivalent to doing:
250 guestfish --rw -i -d domname edit /file
252 where "domname" is the name of the libvirt guest, and "/file" is the
254 full path to the file.
255 The command above uses libguestfs's guest inspection feature and so
257 does not work on guests that libguestfs cannot inspect, or on things
258 like arbitrary disk images that don't contain guests. To edit a file
259 on a disk image directly, use:
260 guestfish --rw -a disk.img -m /dev/sda1 edit /file
262 where "disk.img" is the disk image, "/dev/sda1" is the filesystem
264 within the disk image to edit, and "/file" is the full path to the
265 file.
266 "virt-edit" cannot create new files. Use the guestfish commands
268 "touch", "write" or "upload" instead:
269 guestfish --rw -i -d domname touch /newfile
271 guestfish --rw -i -d domname write /newfile "new content"
273 guestfish --rw -i -d domname upload localfile /newfile
275
277 "EDITOR"
278 If set, this string is used as the editor. It may contain
279 arguments, eg. "emacs -nw"
280 If not set, "vi" is used.
282
284 Libvirt guest names can contain arbitrary characters, some of which
285 have meaning to the shell such as "#" and space. You may need to quote
286 or escape these characters on the command line. See the shell manual
287 page sh(1) for details.
288
290 This program returns 0 if successful, or non-zero if there was an
291 error.
292
294 guestfs(3), guestfish(1), virt-cat(1), virt-copy-in(1), virt-tar-in(1),
295 http://libguestfs.org/, perl(1), perlre(1).
296
298 Richard W.M. Jones http://people.redhat.com/~rjones/
299
301 Copyright (C) 2009-2013 Red Hat Inc.
302
304 This program is free software; you can redistribute it and/or modify it
305 under the terms of the GNU General Public License as published by the
306 Free Software Foundation; either version 2 of the License, or (at your
307 option) any later version.
308 This program is distributed in the hope that it will be useful, but
310 WITHOUT ANY WARRANTY; without even the implied warranty of
311 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
312 General Public License for more details.
313 You should have received a copy of the GNU General Public License along
315 with this program; if not, write to the Free Software Foundation, Inc.,
316 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
317
319 To get a list of bugs against libguestfs, use this link:
320 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
321 To report a new bug against libguestfs, use this link:
323 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
324 When reporting a bug, please supply:
326 · The version of libguestfs.
328 · Where you got libguestfs (eg. which Linux distro, compiled from
330 source, etc)
331 · Describe the bug accurately and give a way to reproduce it.
333 · Run libguestfs-test-tool(1) and paste the complete, unedited output
335 into the bug report.
336libguestfs-1.20.11 2013-08-27 virt-edit(1)