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

NAME

6       virt-edit - Edit a file in a virtual machine
7

SYNOPSIS

9        virt-edit [--options] -d domname file [file ...]
10
11        virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
12
13        virt-edit [-d domname|-a disk.img] file -e 'expr'
14
15       Old-style:
16
17        virt-edit domname file
18
19        virt-edit disk.img [disk.img ...] file
20

WARNING

22       Using "virt-edit" on live virtual machines, or concurrently with other
23       disk editing tools, can be dangerous, potentially causing disk
24       corruption.  The virtual machine must be shut down before you use this
25       command, and disk images must not be edited concurrently.
26

DESCRIPTION

28       "virt-edit" is a command line tool to edit "file" where each "file"
29       exists in the named virtual machine (or disk image).
30
31       Multiple filenames can be given, in which case they are each edited in
32       turn.  Each filename must be a full path, starting at the root
33       directory (starting with '/').
34
35       If you want to just view a file, use virt-cat(1).
36
37       For more complex cases you should look at the guestfish(1) tool (see
38       "USING GUESTFISH" below).
39
40       "virt-edit" cannot be used to create a new file.  guestfish(1) can do
41       that and much more.
42

EXAMPLES

44       Edit the named files interactively:
45
46        virt-edit -d mydomain /boot/grub/grub.conf
47
48        virt-edit -d mydomain /etc/passwd
49
50       For Windows guests, some Windows paths are understood:
51
52        virt-edit -d mywindomain 'c:\autoexec.bat'
53
54       If Perl is installed, you can also edit files non-interactively (see
55       "NON-INTERACTIVE EDITING" below).  To change the init default level to
56       5:
57
58        virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
59

OPTIONS

61       --help
62           Display brief help.
63
64       -a file
65       --add file
66           Add file which should be a disk image from a virtual machine.  If
67           the virtual machine has multiple block devices, you must supply all
68           of them with separate -a options.
69
70           The format of the disk image is auto-detected.  To override this
71           and force a particular format use the --format=.. option.
72
73       -a URI
74       --add URI
75           Add a remote disk.  See "ADDING REMOTE STORAGE" in guestfish(1).
76
77       -b EXTENSION
78       --backup EXTENSION
79           Create a backup of the original file in the guest disk image.  The
80           backup has the original filename with "extension" added.
81
82           Usually the first character of "extension" would be a dot "."  so
83           you would write:
84
85            virt-edit -b .orig [etc]
86
87           By default, no backup file is made.
88
89       -c URI
90       --connect URI
91           If using libvirt, connect to the given URI.  If omitted, then we
92           connect to the default libvirt hypervisor.
93
94           If you specify guest block devices directly, then libvirt is not
95           used at all.
96
97       -d GUEST
98       --domain GUEST
99           Add all the disks from the named libvirt guest.  Domain UUIDs can
100           be used instead of names.
101
102       --echo-keys
103           When prompting for keys and passphrases, virt-edit normally turns
104           echoing off so you cannot see what you are typing.  If you are not
105           worried about Tempest attacks and there is no one else in the room
106           you can specify this flag to see what you are typing.
107
108       -e EXPR
109       --edit EXPR
110       --expr EXPR
111           Instead of launching the external editor, non-interactively apply
112           the Perl expression "EXPR" to each line in the file.  See "NON-
113           INTERACTIVE EDITING" below.
114
115           Be careful to properly quote the expression to prevent it from
116           being altered by the shell.
117
118           Note that this option is only available when Perl 5 is installed.
119
120       --format=raw|qcow2|..
121       --format
122           The default for the -a option is to auto-detect the format of the
123           disk image.  Using this forces the disk format for -a options which
124           follow on the command line.  Using --format with no argument
125           switches back to auto-detection for subsequent -a options.
126
127           For example:
128
129            virt-edit --format=raw -a disk.img file
130
131           forces raw format (no auto-detection) for disk.img.
132
133            virt-edit --format=raw -a disk.img --format -a another.img file
134
135           forces raw format (no auto-detection) for disk.img and reverts to
136           auto-detection for another.img.
137
138           If you have untrusted raw-format guest disk images, you should use
139           this option to specify the disk format.  This avoids a possible
140           security problem with malicious guests (CVE-2010-3851).
141
142       --keys-from-stdin
143           Read key or passphrase parameters from stdin.  The default is to
144           try to read passphrases from the user by opening /dev/tty.
145
146       -m dev[:mountpoint[:options[:fstype]]]
147       --mount dev[:mountpoint[:options[:fstype]]]
148           Mount the named partition or logical volume on the given
149           mountpoint.
150
151           If the mountpoint is omitted, it defaults to /.
152
153           Specifying any mountpoint disables the inspection of the guest and
154           the mount of its root and all of its mountpoints, so make sure to
155           mount all the mountpoints needed to work with the filenames given
156           as arguments.
157
158           If you don’t know what filesystems a disk image contains, you can
159           either run guestfish without this option, then list the partitions,
160           filesystems and LVs available (see "list-partitions", "list-
161           filesystems" and "lvs" commands), or you can use the
162           virt-filesystems(1) program.
163
164           The third (and rarely used) part of the mount parameter is the list
165           of mount options used to mount the underlying filesystem.  If this
166           is not given, then the mount options are either the empty string or
167           "ro" (the latter if the --ro flag is used).  By specifying the
168           mount options, you override this default choice.  Probably the only
169           time you would use this is to enable ACLs and/or extended
170           attributes if the filesystem can support them:
171
172            -m /dev/sda1:/:acl,user_xattr
173
174           Using this flag is equivalent to using the "mount-options" command.
175
176           The fourth part of the parameter is the filesystem driver to use,
177           such as "ext3" or "ntfs". This is rarely needed, but can be useful
178           if multiple drivers are valid for a filesystem (eg: "ext2" and
179           "ext3"), or if libguestfs misidentifies a filesystem.
180
181       -v
182       --verbose
183           Enable verbose messages for debugging.
184
185       -V
186       --version
187           Display version number and exit.
188
189       -x  Enable tracing of libguestfs API calls.
190

OLD-STYLE COMMAND LINE ARGUMENTS

192       Previous versions of virt-edit allowed you to write either:
193
194        virt-edit disk.img [disk.img ...] file
195
196       or
197
198        virt-edit guestname file
199
200       whereas in this version you should use -a or -d respectively to avoid
201       the confusing case where a disk image might have the same name as a
202       guest.
203
204       For compatibility the old style is still supported.
205

NON-INTERACTIVE EDITING

207       "virt-edit" normally calls out to $EDITOR (or vi) so the system
208       administrator can interactively edit the file.
209
210       There are two ways also to use "virt-edit" from scripts in order to
211       make automated edits to files.  (Note that although you can use
212       "virt-edit" like this, it’s less error-prone to write scripts directly
213       using the libguestfs API and Augeas for configuration file editing.)
214
215       The first method is to temporarily set $EDITOR to any script or program
216       you want to run.  The script is invoked as "$EDITOR tmpfile" and it
217       should update "tmpfile" in place however it likes.
218
219       The second method is to use the -e parameter of "virt-edit" to run a
220       short Perl snippet in the style of sed(1).  For example to replace all
221       instances of "foo" with "bar" in a file:
222
223        virt-edit -d domname filename -e 's/foo/bar/'
224
225       The full power of Perl regular expressions can be used (see perlre(1)).
226       For example to delete root’s password you could do:
227
228        virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
229
230       What really happens is that the snippet is evaluated as a Perl
231       expression for each line of the file.  The line, including the final
232       "\n", is passed in $_ and the expression should update $_ or leave it
233       unchanged.
234
235       To delete a line, set $_ to the empty string.  For example, to delete
236       the "apache" user account from the password file you can do:
237
238        virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
239
240       To insert a line, prepend or append it to $_.  However appending lines
241       to the end of the file is rather difficult this way since there is no
242       concept of "last line of the file" - your expression just doesn't get
243       called again.  You might want to use the first method (setting $EDITOR)
244       if you want to do this.
245
246       The variable $lineno contains the current line number.  As is
247       traditional, the first line in the file is number 1.
248
249       The return value from the expression is ignored, but the expression may
250       call "die" in order to abort the whole program, leaving the original
251       file untouched.
252
253       Remember when matching the end of a line that $_ may contain the final
254       "\n", or (for DOS files) "\r\n", or if the file does not end with a
255       newline then neither of these.  Thus to match or substitute some text
256       at the end of a line, use this regular expression:
257
258        /some text(\r?\n)?$/
259
260       Alternately, use the perl "chomp" function, being careful not to chomp
261       $_ itself (since that would remove all newlines from the file):
262
263        my $m = $_; chomp $m; $m =~ /some text$/
264

WINDOWS PATHS

266       "virt-edit" has a limited ability to understand Windows drive letters
267       and paths (eg. E:\foo\bar.txt).
268
269       If and only if the guest is running Windows then:
270
271       ·   Drive letter prefixes like "C:" are resolved against the Windows
272           Registry to the correct filesystem.
273
274       ·   Any backslash ("\") characters in the path are replaced with
275           forward slashes so that libguestfs can process it.
276
277       ·   The path is resolved case insensitively to locate the file that
278           should be edited.
279
280       There are some known shortcomings:
281
282       ·   Some NTFS symbolic links may not be followed correctly.
283
284       ·   NTFS junction points that cross filesystems are not followed.
285

USING GUESTFISH

287       guestfish(1) is a more powerful, lower level tool which you can use
288       when "virt-edit" doesn't work.
289
290       Using "virt-edit" is approximately equivalent to doing:
291
292        guestfish --rw -i -d domname edit /file
293
294       where "domname" is the name of the libvirt guest, and /file is the full
295       path to the file.
296
297       The command above uses libguestfs’s guest inspection feature and so
298       does not work on guests that libguestfs cannot inspect, or on things
299       like arbitrary disk images that don't contain guests.  To edit a file
300       on a disk image directly, use:
301
302        guestfish --rw -a disk.img -m /dev/sda1 edit /file
303
304       where disk.img is the disk image, /dev/sda1 is the filesystem within
305       the disk image to edit, and /file is the full path to the file.
306
307       "virt-edit" cannot create new files.  Use the guestfish commands
308       "touch", "write" or "upload" instead:
309
310        guestfish --rw -i -d domname touch /newfile
311
312        guestfish --rw -i -d domname write /newfile "new content"
313
314        guestfish --rw -i -d domname upload localfile /newfile
315

ENVIRONMENT VARIABLES

317       "EDITOR"
318           If set, this string is used as the editor.  It may contain
319           arguments, eg. "emacs -nw"
320
321           If not set, "vi" is used.
322

EXIT STATUS

324       This program returns 0 if successful, or non-zero if there was an
325       error.
326

SEE ALSO

328       guestfs(3), guestfish(1), virt-cat(1), virt-copy-in(1), virt-tar-in(1),
329       http://libguestfs.org/, perl(1), perlre(1).
330

AUTHOR

332       Richard W.M. Jones http://people.redhat.com/~rjones/
333
335       Copyright (C) 2009-2018 Red Hat Inc.
336

LICENSE

338       This program is free software; you can redistribute it and/or modify it
339       under the terms of the GNU General Public License as published by the
340       Free Software Foundation; either version 2 of the License, or (at your
341       option) any later version.
342
343       This program is distributed in the hope that it will be useful, but
344       WITHOUT ANY WARRANTY; without even the implied warranty of
345       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
346       General Public License for more details.
347
348       You should have received a copy of the GNU General Public License along
349       with this program; if not, write to the Free Software Foundation, Inc.,
350       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
351

BUGS

353       To get a list of bugs against libguestfs, use this link:
354       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
355
356       To report a new bug against libguestfs, use this link:
357       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
358
359       When reporting a bug, please supply:
360
361       ·   The version of libguestfs.
362
363       ·   Where you got libguestfs (eg. which Linux distro, compiled from
364           source, etc)
365
366       ·   Describe the bug accurately and give a way to reproduce it.
367
368       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
369           into the bug report.
370
371
372
373libguestfs-1.38.2                 2018-05-15                      virt-edit(1)
Impressum