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.