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       --key SELECTOR
143           Specify a key for LUKS, to automatically open a LUKS device when
144           using the inspection.  "SELECTOR" can be in one of the following
145           formats:
146
147           --key "DEVICE":key:KEY_STRING
148               Use the specified "KEY_STRING" as passphrase.
149
150           --key "DEVICE":file:FILENAME
151               Read the passphrase from FILENAME.
152
153       --keys-from-stdin
154           Read key or passphrase parameters from stdin.  The default is to
155           try to read passphrases from the user by opening /dev/tty.
156
157       -m dev[:mountpoint[:options[:fstype]]]
158       --mount dev[:mountpoint[:options[:fstype]]]
159           Mount the named partition or logical volume on the given
160           mountpoint.
161
162           If the mountpoint is omitted, it defaults to /.
163
164           Specifying any mountpoint disables the inspection of the guest and
165           the mount of its root and all of its mountpoints, so make sure to
166           mount all the mountpoints needed to work with the filenames given
167           as arguments.
168
169           If you don’t know what filesystems a disk image contains, you can
170           either run guestfish without this option, then list the partitions,
171           filesystems and LVs available (see "list-partitions", "list-
172           filesystems" and "lvs" commands), or you can use the
173           virt-filesystems(1) program.
174
175           The third (and rarely used) part of the mount parameter is the list
176           of mount options used to mount the underlying filesystem.  If this
177           is not given, then the mount options are either the empty string or
178           "ro" (the latter if the --ro flag is used).  By specifying the
179           mount options, you override this default choice.  Probably the only
180           time you would use this is to enable ACLs and/or extended
181           attributes if the filesystem can support them:
182
183            -m /dev/sda1:/:acl,user_xattr
184
185           Using this flag is equivalent to using the "mount-options" command.
186
187           The fourth part of the parameter is the filesystem driver to use,
188           such as "ext3" or "ntfs". This is rarely needed, but can be useful
189           if multiple drivers are valid for a filesystem (eg: "ext2" and
190           "ext3"), or if libguestfs misidentifies a filesystem.
191
192       -v
193       --verbose
194           Enable verbose messages for debugging.
195
196       -V
197       --version
198           Display version number and exit.
199
200       -x  Enable tracing of libguestfs API calls.
201

OLD-STYLE COMMAND LINE ARGUMENTS

203       Previous versions of virt-edit allowed you to write either:
204
205        virt-edit disk.img [disk.img ...] file
206
207       or
208
209        virt-edit guestname file
210
211       whereas in this version you should use -a or -d respectively to avoid
212       the confusing case where a disk image might have the same name as a
213       guest.
214
215       For compatibility the old style is still supported.
216

NON-INTERACTIVE EDITING

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

WINDOWS PATHS

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

USING GUESTFISH

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

ENVIRONMENT VARIABLES

328       "EDITOR"
329           If set, this string is used as the editor.  It may contain
330           arguments, eg. "emacs -nw"
331
332           If not set, "vi" is used.
333

EXIT STATUS

335       This program returns 0 if successful, or non-zero if there was an
336       error.
337

SEE ALSO

339       guestfs(3), guestfish(1), virt-cat(1), virt-copy-in(1), virt-tar-in(1),
340       http://libguestfs.org/, perl(1), perlre(1).
341

AUTHOR

343       Richard W.M. Jones http://people.redhat.com/~rjones/
344
346       Copyright (C) 2009-2019 Red Hat Inc.
347

LICENSE

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

BUGS

364       To get a list of bugs against libguestfs, use this link:
365       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
366
367       To report a new bug against libguestfs, use this link:
368       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
369
370       When reporting a bug, please supply:
371
372       ·   The version of libguestfs.
373
374       ·   Where you got libguestfs (eg. which Linux distro, compiled from
375           source, etc)
376
377       ·   Describe the bug accurately and give a way to reproduce it.
378
379       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
380           into the bug report.
381
382
383
384libguestfs-1.40.2                 2019-02-07                      virt-edit(1)
Impressum