tools/virt-edit

   1 #!/usr/bin/perl -w
   2 # virt-edit
   3 # Copyright (C) 2009-2011 Red Hat Inc.
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18
  19 use warnings;
  20 use strict;
  21
  22 use Sys::Guestfs;
  23 use Sys::Guestfs::Lib qw(open_guest);
  24 use Pod::Usage;
  25 use Getopt::Long;
  26 use File::Temp qw/tempfile/;
  27 use File::Basename;
  28 use Locale::TextDomain 'libguestfs';
  29
  30 =encoding utf8
  31
  32 =head1 NAME
  33
  34 virt-edit - Edit a file in a virtual machine
  35
  36 =head1 SYNOPSIS
  37
  38  virt-edit [--options] domname file
  39
  40  virt-edit [--options] disk.img [disk.img ...] file
  41
  42  virt-edit [domname|disk.img] file -e 'expr'
  43
  44 =head1 WARNING
  45
  46 You must I<not> use C<virt-edit> on live virtual machines.  If you do
  47 this, you risk disk corruption in the VM.  C<virt-edit> tries to stop
  48 you from doing this, but doesn't catch all cases.
  49
  50 =head1 DESCRIPTION
  51
  52 C<virt-edit> is a command line tool to edit C<file> where C<file>
  53 exists in the named virtual machine (or disk image).
  54
  55 If you want to just view a file, use L<virt-cat(1)>.
  56
  57 For more complex cases you should look at the L<guestfish(1)> tool
  58 (see L</USING GUESTFISH> below).
  59
  60 C<virt-edit> cannot be used to create a new file, nor to edit
  61 multiple files.  L<guestfish(1)> can do that and much more.
  62
  63 =head1 EXAMPLES
  64
  65 Edit the named files interactively:
  66
  67  virt-edit mydomain /boot/grub/grub.conf
  68
  69  virt-edit mydomain /etc/passwd
  70
  71 For Windows guests, some Windows paths are understood:
  72
  73  virt-edit mywindomain 'c:\autoexec.bat'
  74
  75 You can also edit files non-interactively (see
  76 L</NON-INTERACTIVE EDITING> below).
  77 To change the init default level to 5:
  78
  79  virt-edit mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
  80
  81 =head1 OPTIONS
  82
  83 =over 4
  84
  85 =cut
  86
  87 my $help;
  88
  89 =item B<--help>
  90
  91 Display brief help.
  92
  93 =cut
  94
  95 my $version;
  96
  97 =item B<--version>
  98
  99 Display version number and exit.
 100
 101 =cut
 102
 103 my $backup;
 104
 105 =item B<--backup extension> | B<-b extension>
 106
 107 Create a backup of the original file I<in the guest disk image>.
 108 The backup has the original filename with C<extension> added.
 109
 110 Usually the first character of C<extension> would be a dot C<.>
 111 so you would write:
 112
 113  virt-edit -b .orig [etc]
 114
 115 By default, no backup file is made.
 116
 117 =cut
 118
 119 my $uri;
 120
 121 =item B<--connect URI> | B<-c URI>
 122
 123 If using libvirt, connect to the given I<URI>.  If omitted, then we
 124 connect to the default libvirt hypervisor.
 125
 126 If you specify guest block devices directly, then libvirt is not used
 127 at all.
 128
 129 =cut
 130
 131 my $format;
 132
 133 =item B<--format> raw
 134
 135 Specify the format of disk images given on the command line.  If this
 136 is omitted then the format is autodetected from the content of the
 137 disk image.
 138
 139 If disk images are requested from libvirt, then this program asks
 140 libvirt for this information.  In this case, the value of the format
 141 parameter is ignored.
 142
 143 If working with untrusted raw-format guest disk images, you should
 144 ensure the format is always specified.
 145
 146 =cut
 147
 148 my $expr;
 149
 150 =item B<--expr EXPR> | B<-e EXPR>
 151
 152 Instead of launching the external editor, non-interactively
 153 apply the Perl expression C<EXPR> to each line in the file.
 154 See L</NON-INTERACTIVE EDITING> below.
 155
 156 Be careful to properly quote the expression to prevent it from
 157 being altered by the shell.
 158
 159 =back
 160
 161 =cut
 162
 163 GetOptions ("help|?" => \$help,
 164             "version" => \$version,
 165             "connect|c=s" => \$uri,
 166             "format=s" => \$format,
 167             "expr|e=s" => \$expr,
 168             "backup|b=s" => \$backup,
 169     ) or pod2usage (2);
 170 pod2usage (1) if $help;
 171 if ($version) {
 172     my $g = Sys::Guestfs->new ();
 173     my %h = $g->version ();
 174     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 175     exit
 176 }
 177
 178 pod2usage (__"virt-edit: no image, VM names or filenames to edit given")
 179     if @ARGV <= 1;
 180
 181 my $filename = pop @ARGV;
 182
 183 my $g;
 184 if ($uri) {
 185     $g = open_guest (\@ARGV, address => $uri, rw => 1, format => $format);
 186 } else {
 187     $g = open_guest (\@ARGV, rw => 1, format => $format);
 188 }
 189
 190 $g->launch ();
 191
 192 my @roots = $g->inspect_os ();
 193 if (@roots == 0) {
 194     die __x("{prog}: No operating system could be detected inside this disk image.\n\nThis may be because the file is not a disk image, or is not a virtual machine\nimage, or because the OS type is not understood by libguestfs.\n\nIf you feel this is an error, please file a bug report including as much\ninformation about the disk image as possible.\n",
 195             prog => basename ($0));
 196 }
 197 if (@roots > 1) {
 198     die __x("{prog}: multiboot operating systems are not supported.\n",
 199             prog => basename ($0))
 200 }
 201 my $root = $roots[0];
 202 my %fses = $g->inspect_get_mountpoints ($root);
 203 my @fses = sort { length $a <=> length $b } keys %fses;
 204 foreach (@fses) {
 205     $g->mount_options ("", $fses{$_}, $_);
 206 }
 207
 208 # Special handling for Windows filenames.
 209 $filename = windows_path ($g, $root, $filename)
 210     if $g->inspect_get_type ($root) eq "windows";
 211
 212 my ($fh, $tempname) = tempfile (UNLINK => 1);
 213 my $fddev = "/dev/fd/" . fileno ($fh);
 214
 215 # Allow this to fail in case eg. the file does not exist.
 216 $g->download ($filename, $fddev);
 217
 218 close $fh or die "close: $!";
 219
 220 my $do_upload = $tempname;
 221
 222 if (!defined $expr) {
 223     # Interactively edit the file.
 224     my $oldctime = (stat ($tempname))[10];
 225
 226     my $editor = $ENV{EDITOR};
 227     $editor ||= "vi";
 228     system ("$editor $tempname") == 0
 229         or die "edit failed: $editor: $?";
 230
 231     my $newctime = (stat ($tempname))[10];
 232
 233     if ($oldctime == $newctime) {
 234         $do_upload = undef;
 235         print __"File not changed.\n";
 236     }
 237 } else {
 238     my ($fh, $tempout) = tempfile (UNLINK => 1);
 239
 240     # Apply a Perl expression to the lines of the file.
 241     open IFILE, $tempname or die "$tempname: $!";
 242     my $lineno = 0;
 243     while (<IFILE>) {
 244         $lineno++;
 245         eval $expr;
 246         die if $@;
 247         print $fh $_ or die "print: $!";
 248     }
 249     close $fh or die "close: $!";
 250
 251     $do_upload = $tempout;
 252 }
 253
 254 if (defined $do_upload) {
 255     # Upload to a new file, so if it fails we don't end up with
 256     # a partially written file.  Give the new file a completely
 257     # random name so we have only a tiny chance of overwriting
 258     # some existing file.
 259     my $dirname = $filename;
 260     $dirname =~ s{/[^/]+$}{/};
 261
 262     my @chars = ('a'..'z', 'A'..'Z', '0'..'9');
 263     my $newname = $dirname;
 264     foreach (0..7) {
 265         $newname .= $chars[rand @chars];
 266     }
 267
 268     $g->upload ($do_upload, $newname);
 269
 270     # Backup or overwrite?
 271     $g->mv ($filename, "$filename$backup") if defined $backup;
 272     $g->mv ($newname, $filename);
 273
 274     $g->umount_all ();
 275     $g->sync ();
 276 }
 277
 278 undef $g;
 279
 280 =head1 NON-INTERACTIVE EDITING
 281
 282 C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
 283 the system administrator can interactively edit the file.
 284
 285 There are two ways also to use C<virt-edit> from scripts in order to
 286 make automated edits to files.  (Note that although you I<can> use
 287 C<virt-edit> like this, it's less error-prone to write scripts
 288 directly using the libguestfs API and Augeas for configuration file
 289 editing.)
 290
 291 The first method is to temporarily set C<$EDITOR> to any script or
 292 program you want to run.  The script is invoked as C<$EDITOR tmpfile>
 293 and it should update C<tmpfile> in place however it likes.
 294
 295 The second method is to use the C<-e> parameter of C<virt-edit> to run
 296 a short Perl snippet in the style of L<sed(1)>.  For example to
 297 replace all instances of C<foo> with C<bar> in a file:
 298
 299  virt-edit domname filename -e 's/foo/bar/'
 300
 301 The full power of Perl regular expressions can be used (see
 302 L<perlre(1)>).  For example to delete root's password you could do:
 303
 304  virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
 305
 306 What really happens is that the snippet is evaluated as a Perl
 307 expression for each line of the file.  The line, including the final
 308 C<\n>, is passed in C<$_> and the expression should update C<$_> or
 309 leave it unchanged.
 310
 311 To delete a line, set C<$_> to the empty string.  For example, to
 312 delete the C<apache> user account from the password file you can do:
 313
 314  virt-edit mydomain /etc/passwd -e '$_ = "" if /^apache:/'
 315
 316 To insert a line, prepend or append it to C<$_>.  However appending
 317 lines to the end of the file is rather difficult this way since there
 318 is no concept of "last line of the file" - your expression just
 319 doesn't get called again.  You might want to use the first method
 320 (setting C<$EDITOR>) if you want to do this.
 321
 322 The variable C<$lineno> contains the current line number.
 323 As is traditional, the first line in the file is number C<1>.
 324
 325 The return value from the expression is ignored, but the expression
 326 may call C<die> in order to abort the whole program, leaving the
 327 original file untouched.
 328
 329 Remember when matching the end of a line that C<$_> may contain the
 330 final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
 331 with a newline then neither of these.  Thus to match or substitute
 332 some text at the end of a line, use this regular expression:
 333
 334  /some text(\r?\n)?$/
 335
 336 Alternately, use the perl C<chomp> function, being careful not to
 337 chomp C<$_> itself (since that would remove all newlines from the
 338 file):
 339
 340  my $m = $_; chomp $m; $m =~ /some text$/
 341
 342 =head1 WINDOWS PATHS
 343
 344 C<virt-edit> has a limited ability to understand Windows drive letters
 345 and paths (eg. C<E:\foo\bar.txt>).
 346
 347 If and only if the guest is running Windows then:
 348
 349 =over 4
 350
 351 =item *
 352
 353 Drive letter prefixes like C<C:> are resolved against the
 354 Windows Registry to the correct filesystem.
 355
 356 =item *
 357
 358 Any backslash (C<\>) characters in the path are replaced
 359 with forward slashes so that libguestfs can process it.
 360
 361 =item *
 362
 363 The path is resolved case insensitively to locate the file
 364 that should be edited.
 365
 366 =back
 367
 368 There are some known shortcomings:
 369
 370 =over 4
 371
 372 =item *
 373
 374 Some NTFS symbolic links may not be followed correctly.
 375
 376 =item *
 377
 378 NTFS junction points that cross filesystems are not followed.
 379
 380 =back
 381
 382 =cut
 383
 384 sub windows_path
 385 {
 386     my $g = shift;
 387     my $root = shift;
 388     my $filename = shift;
 389
 390     # Deal with drive letters.
 391     if ($filename =~ /^([a-z]):(.*)/i) {
 392         $filename = $2;
 393         my $drive_letter = $1;
 394
 395         # Look up the drive letter in the drive mapping table.  We
 396         # have to do a case insensitive comparison, the slow way.
 397         my $device;
 398         my %drives = $g->inspect_get_drive_mappings ($root);
 399         foreach (keys %drives) {
 400             if (lc $_ eq lc $drive_letter) {
 401                 $device = $drives{$_};
 402                 last;
 403             }
 404         }
 405
 406         die __x("virt-edit: drive '{x}:' not found\n", x => $drive_letter)
 407             unless defined $device;
 408
 409         # Unmount current disk and remount $device.
 410         $g->umount_all ();
 411         $g->mount_options ("", $device, "/");
 412     }
 413
 414     # Replace any backslashes in the rest of the path with
 415     # forward slashes.
 416     $filename =~ s{\\}{/}g;
 417
 418     # If the user put \foo on the command line without quoting it
 419     # properly, then we'll see that here as a bare path.  Add a more
 420     # descriptive error message here.
 421     if (substr ($filename, 0, 1) ne "/") {
 422         die __x("virt-edit: '{f}' does not start with a / or \\ character.
 423 If you are using Windows style paths with backslashes like C:\\foo.txt
 424 then don't forget that you must quote them with single quotes to
 425 prevent the shell from munging the backslashes.\n",
 426                 f => $filename)
 427     }
 428
 429     # Case sensitivity.
 430     $filename = $g->case_sensitive_path ($filename);
 431
 432     return $filename;
 433 }
 434
 435 =head1 USING GUESTFISH
 436
 437 L<guestfish(1)> is a more powerful, lower level tool which you can use
 438 when C<virt-edit> doesn't work.
 439
 440 Using C<virt-edit> is approximately equivalent to doing:
 441
 442  guestfish --rw -i -d domname edit /file
 443
 444 where C<domname> is the name of the libvirt guest, and C</file> is the
 445 full path to the file.
 446
 447 The command above uses libguestfs's guest inspection feature and so
 448 does not work on guests that libguestfs cannot inspect, or on things
 449 like arbitrary disk images that don't contain guests.  To edit a file
 450 on a disk image directly, use:
 451
 452  guestfish --rw -a disk.img -m /dev/sda1 edit /file
 453
 454 where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
 455 within the disk image to edit, and C</file> is the full path to the
 456 file.
 457
 458 C<virt-edit> cannot create new files.  Use the guestfish commands
 459 C<touch>, C<write> or C<upload> instead:
 460
 461  guestfish --rw -i -d domname touch /newfile
 462
 463  guestfish --rw -i -d domname write /newfile "new content"
 464
 465  guestfish --rw -i -d domname upload localfile /newfile
 466
 467 C<virt-edit> cannot edit multiple files, but guestfish can
 468 do it like this:
 469
 470  guestfish --rw -i -d domname edit /file1 : edit /file2
 471
 472 =cut
 473
 474 exit 0;
 475
 476 =head1 ENVIRONMENT VARIABLES
 477
 478 =over 4
 479
 480 =item C<EDITOR>
 481
 482 If set, this string is used as the editor.  It may contain arguments,
 483 eg. C<"emacs -nw">
 484
 485 If not set, C<vi> is used.
 486
 487 =back
 488
 489 =head1 SHELL QUOTING
 490
 491 Libvirt guest names can contain arbitrary characters, some of which
 492 have meaning to the shell such as C<#> and space.  You may need to
 493 quote or escape these characters on the command line.  See the shell
 494 manual page L<sh(1)> for details.
 495
 496 =head1 SEE ALSO
 497
 498 L<guestfs(3)>,
 499 L<guestfish(1)>,
 500 L<virt-cat(1)>,
 501 L<virt-copy-in(1)>,
 502 L<virt-tar-in(1)>,
 503 L<Sys::Guestfs(3)>,
 504 L<Sys::Guestfs::Lib(3)>,
 505 L<Sys::Virt(3)>,
 506 L<http://libguestfs.org/>,
 507 L<perl(1)>,
 508 L<perlre(1)>.
 509
 510 =head1 AUTHOR
 511
 512 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 513
 514 =head1 COPYRIGHT
 515
 516 Copyright (C) 2009-2011 Red Hat Inc.
 517
 518 This program is free software; you can redistribute it and/or modify
 519 it under the terms of the GNU General Public License as published by
 520 the Free Software Foundation; either version 2 of the License, or
 521 (at your option) any later version.
 522
 523 This program is distributed in the hope that it will be useful,
 524 but WITHOUT ANY WARRANTY; without even the implied warranty of
 525 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 526 GNU General Public License for more details.
 527
 528 You should have received a copy of the GNU General Public License
 529 along with this program; if not, write to the Free Software
 530 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.