test-tool: Document the -t command line option.
[libguestfs.git] / edit / virt-edit.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-edit - Edit a file in a virtual machine
6
7 =head1 SYNOPSIS
8
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
21 =head1 WARNING
22
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.
26
27 =head1 DESCRIPTION
28
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).
31
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 '/').
35
36 If you want to just view a file, use L<virt-cat(1)>.
37
38 For more complex cases you should look at the L<guestfish(1)> tool
39 (see L</USING GUESTFISH> below).
40
41 C<virt-edit> cannot be used to create a new file.  L<guestfish(1)> can
42 do that and much more.
43
44 =head1 EXAMPLES
45
46 Edit the named files interactively:
47
48  virt-edit -d mydomain /boot/grub/grub.conf
49
50  virt-edit -d mydomain /etc/passwd
51
52 For Windows guests, some Windows paths are understood:
53
54  virt-edit -d mywindomain 'c:\autoexec.bat'
55
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:
59
60  virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
61
62 =head1 OPTIONS
63
64 =over 4
65
66 =item B<--help>
67
68 Display brief help.
69
70 =item B<-a> file
71
72 =item B<--add> file
73
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.
77
78 The format of the disk image is auto-detected.  To override this and
79 force a particular format use the I<--format=..> option.
80
81 =item B<-b> extension
82
83 =item B<--backup> extension
84
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.
87
88 Usually the first character of C<extension> would be a dot C<.>
89 so you would write:
90
91  virt-edit -b .orig [etc]
92
93 By default, no backup file is made.
94
95 =item B<-c URI>
96
97 =item B<--connect URI>
98
99 If using libvirt, connect to the given I<URI>.  If omitted, then we
100 connect to the default libvirt hypervisor.
101
102 If you specify guest block devices directly, then libvirt is not used
103 at all.
104
105 =item B<-d> guest
106
107 =item B<--domain> guest
108
109 Add all the disks from the named libvirt guest.  Domain UUIDs can be
110 used instead of names.
111
112 =item B<--echo-keys>
113
114 When prompting for keys and passphrases, virt-edit normally turns
115 echoing off so you cannot see what you are typing.  If you are not
116 worried about Tempest attacks and there is no one else in the room you
117 can specify this flag to see what you are typing.
118
119 =item B<-e> EXPR
120
121 =item B<--expr> EXPR
122
123 Instead of launching the external editor, non-interactively
124 apply the Perl expression C<EXPR> to each line in the file.
125 See L</NON-INTERACTIVE EDITING> below.
126
127 Be careful to properly quote the expression to prevent it from
128 being altered by the shell.
129
130 Note that this option is only available when Perl 5 is installed.
131
132 =item B<--format> raw|qcow2|...
133
134 =item B<--format>
135
136 The default for the I<-a> option is to auto-detect the format of the
137 disk image.  Using this forces the disk format for I<-a> options which
138 follow on the command line.  Using I<--format> with no argument
139 switches back to auto-detection for subsequent I<-a> options.
140
141 For example:
142
143  virt-edit --format=raw -a disk.img file
144
145 forces raw format (no auto-detection) for C<disk.img>.
146
147  virt-edit --format=raw -a disk.img --format -a another.img file
148
149 forces raw format (no auto-detection) for C<disk.img> and reverts to
150 auto-detection for C<another.img>.
151
152 If you have untrusted raw-format guest disk images, you should use
153 this option to specify the disk format.  This avoids a possible
154 security problem with malicious guests (CVE-2010-3851).
155
156 =item B<--keys-from-stdin>
157
158 Read key or passphrase parameters from stdin.  The default is
159 to try to read passphrases from the user by opening C</dev/tty>.
160
161 =item B<-v>
162
163 =item B<--verbose>
164
165 Enable verbose messages for debugging.
166
167 =item B<-V>
168
169 =item B<--version>
170
171 Display version number and exit.
172
173 =item B<-x>
174
175 Enable tracing of libguestfs API calls.
176
177 =back
178
179 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
180
181 Previous versions of virt-edit allowed you to write either:
182
183  virt-edit disk.img [disk.img ...] file
184
185 or
186
187  virt-edit guestname file
188
189 whereas in this version you should use I<-a> or I<-d> respectively
190 to avoid the confusing case where a disk image might have the same
191 name as a guest.
192
193 For compatibility the old style is still supported.
194
195 =head1 NON-INTERACTIVE EDITING
196
197 C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
198 the system administrator can interactively edit the file.
199
200 There are two ways also to use C<virt-edit> from scripts in order to
201 make automated edits to files.  (Note that although you I<can> use
202 C<virt-edit> like this, it's less error-prone to write scripts
203 directly using the libguestfs API and Augeas for configuration file
204 editing.)
205
206 The first method is to temporarily set C<$EDITOR> to any script or
207 program you want to run.  The script is invoked as C<$EDITOR tmpfile>
208 and it should update C<tmpfile> in place however it likes.
209
210 The second method is to use the I<-e> parameter of C<virt-edit> to run
211 a short Perl snippet in the style of L<sed(1)>.  For example to
212 replace all instances of C<foo> with C<bar> in a file:
213
214  virt-edit -d domname filename -e 's/foo/bar/'
215
216 The full power of Perl regular expressions can be used (see
217 L<perlre(1)>).  For example to delete root's password you could do:
218
219  virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
220
221 What really happens is that the snippet is evaluated as a Perl
222 expression for each line of the file.  The line, including the final
223 C<\n>, is passed in C<$_> and the expression should update C<$_> or
224 leave it unchanged.
225
226 To delete a line, set C<$_> to the empty string.  For example, to
227 delete the C<apache> user account from the password file you can do:
228
229  virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
230
231 To insert a line, prepend or append it to C<$_>.  However appending
232 lines to the end of the file is rather difficult this way since there
233 is no concept of "last line of the file" - your expression just
234 doesn't get called again.  You might want to use the first method
235 (setting C<$EDITOR>) if you want to do this.
236
237 The variable C<$lineno> contains the current line number.
238 As is traditional, the first line in the file is number C<1>.
239
240 The return value from the expression is ignored, but the expression
241 may call C<die> in order to abort the whole program, leaving the
242 original file untouched.
243
244 Remember when matching the end of a line that C<$_> may contain the
245 final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
246 with a newline then neither of these.  Thus to match or substitute
247 some text at the end of a line, use this regular expression:
248
249  /some text(\r?\n)?$/
250
251 Alternately, use the perl C<chomp> function, being careful not to
252 chomp C<$_> itself (since that would remove all newlines from the
253 file):
254
255  my $m = $_; chomp $m; $m =~ /some text$/
256
257 =head1 WINDOWS PATHS
258
259 C<virt-edit> has a limited ability to understand Windows drive letters
260 and paths (eg. C<E:\foo\bar.txt>).
261
262 If and only if the guest is running Windows then:
263
264 =over 4
265
266 =item *
267
268 Drive letter prefixes like C<C:> are resolved against the
269 Windows Registry to the correct filesystem.
270
271 =item *
272
273 Any backslash (C<\>) characters in the path are replaced
274 with forward slashes so that libguestfs can process it.
275
276 =item *
277
278 The path is resolved case insensitively to locate the file
279 that should be edited.
280
281 =back
282
283 There are some known shortcomings:
284
285 =over 4
286
287 =item *
288
289 Some NTFS symbolic links may not be followed correctly.
290
291 =item *
292
293 NTFS junction points that cross filesystems are not followed.
294
295 =back
296
297 =head1 USING GUESTFISH
298
299 L<guestfish(1)> is a more powerful, lower level tool which you can use
300 when C<virt-edit> doesn't work.
301
302 Using C<virt-edit> is approximately equivalent to doing:
303
304  guestfish --rw -i -d domname edit /file
305
306 where C<domname> is the name of the libvirt guest, and C</file> is the
307 full path to the file.
308
309 The command above uses libguestfs's guest inspection feature and so
310 does not work on guests that libguestfs cannot inspect, or on things
311 like arbitrary disk images that don't contain guests.  To edit a file
312 on a disk image directly, use:
313
314  guestfish --rw -a disk.img -m /dev/sda1 edit /file
315
316 where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
317 within the disk image to edit, and C</file> is the full path to the
318 file.
319
320 C<virt-edit> cannot create new files.  Use the guestfish commands
321 C<touch>, C<write> or C<upload> instead:
322
323  guestfish --rw -i -d domname touch /newfile
324
325  guestfish --rw -i -d domname write /newfile "new content"
326
327  guestfish --rw -i -d domname upload localfile /newfile
328
329 =head1 ENVIRONMENT VARIABLES
330
331 =over 4
332
333 =item C<EDITOR>
334
335 If set, this string is used as the editor.  It may contain arguments,
336 eg. C<"emacs -nw">
337
338 If not set, C<vi> is used.
339
340 =back
341
342 =head1 SHELL QUOTING
343
344 Libvirt guest names can contain arbitrary characters, some of which
345 have meaning to the shell such as C<#> and space.  You may need to
346 quote or escape these characters on the command line.  See the shell
347 manual page L<sh(1)> for details.
348
349 =head1 EXIT STATUS
350
351 This program returns 0 if successful, or non-zero if there was an
352 error.
353
354 =head1 SEE ALSO
355
356 L<guestfs(3)>,
357 L<guestfish(1)>,
358 L<virt-cat(1)>,
359 L<virt-copy-in(1)>,
360 L<virt-tar-in(1)>,
361 L<Sys::Guestfs(3)>,
362 L<Sys::Guestfs::Lib(3)>,
363 L<Sys::Virt(3)>,
364 L<http://libguestfs.org/>,
365 L<perl(1)>,
366 L<perlre(1)>.
367
368 =head1 AUTHOR
369
370 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
371
372 =head1 COPYRIGHT
373
374 Copyright (C) 2009-2011 Red Hat Inc.
375
376 This program is free software; you can redistribute it and/or modify
377 it under the terms of the GNU General Public License as published by
378 the Free Software Foundation; either version 2 of the License, or
379 (at your option) any later version.
380
381 This program is distributed in the hope that it will be useful,
382 but WITHOUT ANY WARRANTY; without even the implied warranty of
383 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
384 GNU General Public License for more details.
385
386 You should have received a copy of the GNU General Public License
387 along with this program; if not, write to the Free Software
388 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.