1virt-edit(1) Virtualization Support virt-edit(1)
2
6 virt-edit - Edit a file in a virtual machine
7
9 virt-edit [--options] domname file
10 virt-edit [--options] disk.img [disk.img ...] file
12 virt-edit [domname|disk.img] file -e 'expr'
14
16 You must not use "virt-edit" on live virtual machines. If you do this,
17 you risk disk corruption in the VM. "virt-edit" tries to stop you from
18 doing this, but doesn't catch all cases.
19
21 "virt-edit" is a command line tool to edit "file" where "file" exists
22 in the named virtual machine (or disk image).
23 If you want to just view a file, use virt-cat(1).
25 For more complex cases you should look at the guestfish(1) tool (see
27 "USING GUESTFISH" below).
28 "virt-edit" cannot be used to create a new file, nor to edit multiple
30 files. guestfish(1) can do that and much more.
31
33 Edit the named files interactively:
34 virt-edit mydomain /boot/grub/grub.conf
36 virt-edit mydomain /etc/passwd
38 You can also edit files non-interactively (see "NON-INTERACTIVE
40 EDITING" below). To change the init default level to 5:
41 virt-edit mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
43
45 --help
46 Display brief help.
47 --version
49 Display version number and exit.
50 --backup extension | -b extension
52 Create a backup of the original file in the guest disk image. The
53 backup has the original filename with "extension" added.
54 Usually the first character of "extension" would be a dot "." so
56 you would write:
57 virt-edit -b .orig [etc]
59 By default, no backup file is made.
61 --connect URI | -c URI
63 If using libvirt, connect to the given URI. If omitted, then we
64 connect to the default libvirt hypervisor.
65 If you specify guest block devices directly, then libvirt is not
67 used at all.
68 --format raw
70 Specify the format of disk images given on the command line. If
71 this is omitted then the format is autodetected from the content of
72 the disk image.
73 If disk images are requested from libvirt, then this program asks
75 libvirt for this information. In this case, the value of the
76 format parameter is ignored.
77 If working with untrusted raw-format guest disk images, you should
79 ensure the format is always specified.
80 --expr EXPR | -e EXPR
82 Instead of launching the external editor, non-interactively apply
83 the Perl expression "EXPR" to each line in the file. See "NON-
84 INTERACTIVE EDITING" below.
85 Be careful to properly quote the expression to prevent it from
87 being altered by the shell.
88
90 "virt-edit" normally calls out to $EDITOR (or vi) so the system
91 administrator can interactively edit the file.
92 There are two ways also to use "virt-edit" from scripts in order to
94 make automated edits to files. (Note that although you can use
95 "virt-edit" like this, it's less error-prone to write scripts directly
96 using the libguestfs API and Augeas for configuration file editing.)
97 The first method is to temporarily set $EDITOR to any script or program
99 you want to run. The script is invoked as "$EDITOR tmpfile" and it
100 should update "tmpfile" in place however it likes.
101 The second method is to use the "-e" parameter of "virt-edit" to run a
103 short Perl snippet in the style of sed(1). For example to replace all
104 instances of "foo" with "bar" in a file:
105 virt-edit domname filename -e 's/foo/bar/'
107 The full power of Perl regular expressions can be used (see perlre(1)).
109 For example to delete root's password you could do:
110 virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
112 What really happens is that the snippet is evaluated as a Perl
114 expression for each line of the file. The line, including the final
115 "\n", is passed in $_ and the expression should update $_ or leave it
116 unchanged.
117 To delete a line, set $_ to the empty string. For example, to delete
119 the "apache" user account from the password file you can do:
120 virt-edit mydomain /etc/passwd -e '$_ = "" if /^apache:/'
122 To insert a line, prepend or append it to $_. However appending lines
124 to the end of the file is rather difficult this way since there is no
125 concept of "last line of the file" - your expression just doesn't get
126 called again. You might want to use the first method (setting $EDITOR)
127 if you want to do this.
128 The variable $lineno contains the current line number. As is
130 traditional, the first line in the file is number 1.
131 The return value from the expression is ignored, but the expression may
133 call "die" in order to abort the whole program, leaving the original
134 file untouched.
135 Remember when matching the end of a line that $_ may contain the final
137 "\n", or (for DOS files) "\r\n", or if the file does not end with a
138 newline then neither of these. Thus to match or substitute some text
139 at the end of a line, use this regular expression:
140 /some text(\r?\n)?$/
142 Alternately, use the perl "chomp" function, being careful not to chomp
144 $_ itself (since that would remove all newlines from the file):
145 my $m = $_; chomp $m; $m =~ /some text$/
147
149 guestfish(1) is a more powerful, lower level tool which you can use
150 when "virt-edit" doesn't work.
151 Using "virt-edit" is approximately equivalent to doing:
153 guestfish --rw -i -d domname edit /file
155 where "domname" is the name of the libvirt guest, and "/file" is the
157 full path to the file.
158 The command above uses libguestfs's guest inspection feature and so
160 does not work on guests that libguestfs cannot inspect, or on things
161 like arbitrary disk images that don't contain guests. To edit a file
162 on a disk image directly, use:
163 guestfish --rw -a disk.img -m /dev/sda1 edit /file
165 where "disk.img" is the disk image, "/dev/sda1" is the filesystem
167 within the disk image to edit, and "/file" is the full path to the
168 file.
169 "virt-edit" cannot create new files. Use the guestfish commands
171 "touch", "write" or "upload" instead:
172 guestfish --rw -i -d domname touch /newfile
174 guestfish --rw -i -d domname write /newfile "new content"
176 guestfish --rw -i -d domname upload localfile /newfile
178 "virt-edit" cannot edit multiple files, but guestfish can do it like
180 this:
181 guestfish --rw -i -d domname edit /file1 : edit /file2
183
185 "EDITOR"
186 If set, this string is used as the editor. It may contain
187 arguments, eg. "emacs -nw"
188 If not set, "vi" is used.
190
192 Libvirt guest names can contain arbitrary characters, some of which
193 have meaning to the shell such as "#" and space. You may need to quote
194 or escape these characters on the command line. See the shell manual
195 page sh(1) for details.
196
198 guestfs(3), guestfish(1), virt-cat(1), Sys::Guestfs(3),
199 Sys::Guestfs::Lib(3), Sys::Virt(3), <http://libguestfs.org/>, perl(1),
200 perlre(1).
201
203 Richard W.M. Jones <http://people.redhat.com/~rjones/>
204
206 Copyright (C) 2009-2011 Red Hat Inc.
207 This program is free software; you can redistribute it and/or modify it
209 under the terms of the GNU General Public License as published by the
210 Free Software Foundation; either version 2 of the License, or (at your
211 option) any later version.
212 This program is distributed in the hope that it will be useful, but
214 WITHOUT ANY WARRANTY; without even the implied warranty of
215 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
216 General Public License for more details.
217 You should have received a copy of the GNU General Public License along
219 with this program; if not, write to the Free Software Foundation, Inc.,
220 675 Mass Ave, Cambridge, MA 02139, USA.
221libguestfs-1.8.15 2011-11-10 virt-edit(1)