Rewrite virt-edit in C.

4 files changed, 1164 insertions, 0 deletions

diff --git a/edit/Makefile.am b/edit/Makefile.am
new file mode 100644
index 00000000..5195b514
--- /dev/null
+++ b/edit/Makefile.am
@@ -0,0 +1,75 @@
+# libguestfs virt-edit
+# Copyright (C) 2009-2011 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+include $(top_srcdir)/subdir-rules.mk
+
+EXTRA_DIST = \
+	test-virt-edit.sh \
+	virt-edit.pod
+
+CLEANFILES = stamp-virt-edit.pod
+
+bin_PROGRAMS = virt-edit
+
+SHARED_SOURCE_FILES = \
+	../fish/config.c \
+	../fish/inspect.c \
+	../fish/keys.c \
+	../fish/options.h \
+	../fish/options.c \
+	../fish/virt.c
+
+virt_edit_SOURCES = \
+	$(SHARED_SOURCE_FILES) \
+	virt-edit.c
+
+virt_edit_CFLAGS = \
+	-I$(top_srcdir)/src -I$(top_builddir)/src \
+	-I$(top_srcdir)/fish \
+	-I$(srcdir)/../gnulib/lib -I../gnulib/lib \
+	-DLOCALEBASEDIR=\""$(datadir)/locale"\" \
+	$(LIBCONFIG_CFLAGS) \
+	$(WARN_CFLAGS) $(WERROR_CFLAGS)
+
+virt_edit_LDADD = \
+	$(LIBCONFIG_LIBS) \
+	$(top_builddir)/src/libguestfs.la \
+	../gnulib/lib/libgnu.la
+
+# Manual pages and HTML files for the website.
+man_MANS = virt-edit.1
+noinst_DATA = $(top_builddir)/html/virt-edit.1.html
+
+virt-edit.1 $(top_builddir)/html/virt-edit.1.html: stamp-virt-edit.pod
+
+stamp-virt-edit.pod: virt-edit.pod
+	$(top_srcdir)/podwrapper.sh \
+	  --man virt-edit.1 \
+	  --html $(top_builddir)/html/virt-edit.1.html \
+	  $<
+	touch $@
+
+# Tests.
+
+random_val := $(shell awk 'BEGIN{srand(); print 1+int(255*rand())}' < /dev/null)
+
+TESTS_ENVIRONMENT = \
+	MALLOC_PERTURB_=$(random_val) \
+	LD_LIBRARY_PATH=$(top_builddir)/src/.libs \
+	LIBGUESTFS_PATH=$(top_builddir)/appliance
+
+TESTS = test-virt-edit.sh
diff --git a/edit/test-virt-edit.sh b/edit/test-virt-edit.sh
new file mode 100755
index 00000000..d43851b5
--- /dev/null
+++ b/edit/test-virt-edit.sh
@@ -0,0 +1,42 @@
+#!/bin/bash -
+
+export LANG=C
+set -e
+
+# Make a copy of the Fedora image so we can write to it then
+# discard it.
+cp ../images/fedora.img test.img
+
+# Edit interactively.  We have to simulate this by setting $EDITOR.
+# The command will be: echo newline >> /tmp/file
+export EDITOR='echo newline >>'
+./virt-edit -a test.img /etc/test3
+if [ "$(../cat/virt-cat -a test.img /etc/test3)" != "a
+b
+c
+d
+e
+f
+newline" ]; then
+    echo "$0: error: mismatch in interactive editing of file /etc/test3"
+    exit 1
+fi
+unset EDITOR
+
+# Edit non-interactively, only if we have 'perl' binary.
+if perl --version >/dev/null 2>&1; then
+    ./virt-edit -a test.img /etc/test3 -e 's/^[a-f]/$lineno/'
+    if [ "$(../cat/virt-cat -a test.img /etc/test3)" != "1
+2
+3
+4
+5
+6
+newline" ]; then
+        echo "$0: error: mismatch in non-interactive editing of file /etc/test3"
+        exit 1
+    fi
+fi
+
+# Discard test image.
+rm test.img
diff --git a/edit/virt-edit.c b/edit/virt-edit.c
new file mode 100644
index 00000000..dc2e1302
--- /dev/null
+++ b/edit/virt-edit.c
@@ -0,0 +1,666 @@
+/* virt-edit
+ * Copyright (C) 2009-2011 Red Hat Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <inttypes.h>
+#include <unistd.h>
+#include <locale.h>
+#include <getopt.h>
+#include <assert.h>
+#include <libintl.h>
+#include <sys/time.h>
+#include <sys/stat.h>
+#include <utime.h>
+
+#include "progname.h"
+#include "xvasprintf.h"
+#include "c-ctype.h"
+
+#include "guestfs.h"
+#include "options.h"
+
+/* Currently open libguestfs handle. */
+guestfs_h *g;
+
+int read_only = 0;
+int live = 0;
+int verbose = 0;
+int keys_from_stdin = 0;
+int echo_keys = 0;
+const char *libvirt_uri = NULL;
+int inspector = 1;
+
+static const char *backup_extension = NULL;
+static const char *perl_expr = NULL;
+
+static void edit (const char *filename, const char *root);
+static char *edit_interactively (const char *tmpfile);
+static char *edit_non_interactively (const char *tmpfile);
+static int is_windows (guestfs_h *g, const char *root);
+static char *windows_path (guestfs_h *g, const char *root, const char *filename);
+static char *generate_random_name (const char *filename);
+static char *generate_backup_name (const char *filename);
+
+static inline char *
+bad_cast (char const *s)
+{
+  return (char *) s;
+}
+
+static void __attribute__((noreturn))
+usage (int status)
+{
+  if (status != EXIT_SUCCESS)
+    fprintf (stderr, _("Try `%s --help' for more information.\n"),
+             program_name);
+  else {
+    fprintf (stdout,
+           _("%s: Edit a file in a virtual machine\n"
+             "Copyright (C) 2009-2011 Red Hat Inc.\n"
+             "Usage:\n"
+             "  %s [--options] -d domname file [file ...]\n"
+             "  %s [--options] -a disk.img [-a disk.img ...] file [file ...]\n"
+             "Options:\n"
+             "  -a|--add image       Add image\n"
+             "  -b|--backup .ext     Backup original as original.ext\n"
+             "  -c|--connect uri     Specify libvirt URI for -d option\n"
+             "  -d|--domain guest    Add disks from libvirt guest\n"
+             "  --echo-keys          Don't turn off echo for passphrases\n"
+             "  -e|--expr expr       Non-interactive editing using Perl expr\n"
+             "  --format[=raw|..]    Force disk format for -a option\n"
+             "  --help               Display brief help\n"
+             "  --keys-from-stdin    Read passphrases from stdin\n"
+             "  -v|--verbose         Verbose messages\n"
+             "  -V|--version         Display version and exit\n"
+             "  -x                   Trace libguestfs API calls\n"
+             "For more information, see the manpage %s(1).\n"),
+             program_name, program_name, program_name,
+             program_name);
+  }
+  exit (status);
+}
+
+int
+main (int argc, char *argv[])
+{
+  /* Set global program name that is not polluted with libtool artifacts.  */
+  set_program_name (argv[0]);
+
+  setlocale (LC_ALL, "");
+  bindtextdomain (PACKAGE, LOCALEBASEDIR);
+  textdomain (PACKAGE);
+
+  /* We use random(3) below. */
+  srandom (time (NULL));
+
+  enum { HELP_OPTION = CHAR_MAX + 1 };
+
+  static const char *options = "a:b:c:d:e:vVx";
+  static const struct option long_options[] = {
+    { "add", 1, 0, 'a' },
+    { "backup", 1, 0, 'b' },
+    { "connect", 1, 0, 'c' },
+    { "domain", 1, 0, 'd' },
+    { "echo-keys", 0, 0, 0 },
+    { "expr", 1, 0, 'e' },
+    { "format", 2, 0, 0 },
+    { "help", 0, 0, HELP_OPTION },
+    { "keys-from-stdin", 0, 0, 0 },
+    { "verbose", 0, 0, 'v' },
+    { "version", 0, 0, 'V' },
+    { 0, 0, 0, 0 }
+  };
+  struct drv *drvs = NULL;
+  struct drv *drv;
+  const char *format = NULL;
+  int c;
+  int option_index;
+  char *root, **roots;
+
+  g = guestfs_create ();
+  if (g == NULL) {
+    fprintf (stderr, _("guestfs_create: failed to create handle\n"));
+    exit (EXIT_FAILURE);
+  }
+
+  argv[0] = bad_cast (program_name);
+
+  for (;;) {
+    c = getopt_long (argc, argv, options, long_options, &option_index);
+    if (c == -1) break;
+
+    switch (c) {
+    case 0:			/* options which are long only */
+      if (STREQ (long_options[option_index].name, "keys-from-stdin")) {
+        keys_from_stdin = 1;
+      } else if (STREQ (long_options[option_index].name, "echo-keys")) {
+        echo_keys = 1;
+      } else if (STREQ (long_options[option_index].name, "format")) {
+        if (!optarg || STREQ (optarg, ""))
+          format = NULL;
+        else
+          format = optarg;
+      } else {
+        fprintf (stderr, _("%s: unknown long option: %s (%d)\n"),
+                 program_name, long_options[option_index].name, option_index);
+        exit (EXIT_FAILURE);
+      }
+      break;
+
+    case 'a':
+      OPTION_a;
+      break;
+
+    case 'b':
+      if (backup_extension) {
+        fprintf (stderr, _("%s: -b option given multiple times\n"),
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
+      backup_extension = optarg;
+      break;
+
+    case 'c':
+      OPTION_c;
+      break;
+
+    case 'd':
+      OPTION_d;
+      break;
+
+    case 'e':
+      if (perl_expr) {
+        fprintf (stderr, _("%s: -e option given multiple times\n"),
+                 program_name);
+        exit (EXIT_FAILURE);
+      }
+      perl_expr = optarg;
+      break;
+
+    case 'h':
+      usage (EXIT_SUCCESS);
+
+    case 'v':
+      OPTION_v;
+      break;
+
+    case 'V':
+      OPTION_V;
+      break;
+
+    case 'x':
+      OPTION_x;
+      break;
+
+    case HELP_OPTION:
+      usage (EXIT_SUCCESS);
+
+    default:
+      usage (EXIT_FAILURE);
+    }
+  }
+
+  /* Old-style syntax?  There were no -a or -d options in the old
+   * virt-edit which is how we detect this.
+   */
+  if (drvs == NULL) {
+    /* argc - 1 because last parameter is the single filename. */
+    while (optind < argc - 1) {
+      if (strchr (argv[optind], '/') ||
+          access (argv[optind], F_OK) == 0) { /* simulate -a option */
+        drv = malloc (sizeof (struct drv));
+        if (!drv) {
+          perror ("malloc");
+          exit (EXIT_FAILURE);
+        }
+        drv->type = drv_a;
+        drv->a.filename = argv[optind];
+        drv->a.format = NULL;
+        drv->next = drvs;
+        drvs = drv;
+      } else {                  /* simulate -d option */
+        drv = malloc (sizeof (struct drv));
+        if (!drv) {
+          perror ("malloc");
+          exit (EXIT_FAILURE);
+        }
+        drv->type = drv_d;
+        drv->d.guest = argv[optind];
+        drv->next = drvs;
+        drvs = drv;
+      }
+
+      optind++;
+    }
+  }
+
+  /* These are really constants, but they have to be variables for the
+   * options parsing code.  Assert here that they have known-good
+   * values.
+   */
+  assert (read_only == 0);
+  assert (inspector == 1);
+  assert (live == 0);
+
+  /* User must specify at least one filename on the command line. */
+  if (optind >= argc || argc - optind < 1)
+    usage (EXIT_FAILURE);
+
+  /* User must have specified some drives. */
+  if (drvs == NULL)
+    usage (EXIT_FAILURE);
+
+  /* Add drives. */
+  add_drives (drvs, 'a');
+
+  if (guestfs_launch (g) == -1)
+    exit (EXIT_FAILURE);
+
+  inspect_mount ();
+
+  /* Free up data structures, no longer needed after this point. */
+  free_drives (drvs);
+
+  /* Get root mountpoint. */
+  roots = guestfs_inspect_get_roots (g);
+  if (!roots)
+    exit (EXIT_FAILURE);
+  /* see fish/inspect.c:inspect_mount */
+  assert (roots[0] != NULL && roots[1] == NULL);
+  root = roots[0];
+  free (roots);
+
+  while (optind < argc) {
+    edit (argv[optind], root);
+    optind++;
+  }
+
+  free (root);
+
+  /* Cleanly unmount the disks after editing. */
+  if (guestfs_umount_all (g) == -1 || guestfs_sync (g) == -1)
+    exit (EXIT_FAILURE);
+
+  guestfs_close (g);
+
+  exit (EXIT_SUCCESS);
+}
+
+static void
+edit (const char *filename, const char *root)
+{
+  char *filename_to_free = NULL;
+  const char *tmpdir = guestfs_tmpdir ();
+  char tmpfile[strlen (tmpdir) + 32];
+  sprintf (tmpfile, "%s/virteditXXXXXX", tmpdir);
+  int fd;
+  char fdbuf[32];
+  char *upload_from = NULL;
+  char *newname = NULL;
+  char *backupname = NULL;
+
+  /* Windows?  Special handling is required. */
+  if (is_windows (g, root))
+    filename = filename_to_free = windows_path (g, root, filename);
+
+  /* Download the file to a temporary. */
+  fd = mkstemp (tmpfile);
+  if (fd == -1) {
+    perror ("mkstemp");
+    exit (EXIT_FAILURE);
+  }
+
+  snprintf (fdbuf, sizeof fdbuf, "/dev/fd/%d", fd);
+
+  if (guestfs_download (g, filename, fdbuf) == -1)
+    goto error;
+
+  if (close (fd) == -1) {
+    perror (tmpfile);
+    goto error;
+  }
+
+  if (!perl_expr)
+    upload_from = edit_interactively (tmpfile);
+  else
+    upload_from = edit_non_interactively (tmpfile);
+
+  /* We don't always need to upload: upload_from could be NULL because
+   * the user closed the editor without changing the file.
+   */
+  if (upload_from) {
+    /* Upload to a new file in the same directory, so if it fails we
+     * don't end up with a partially written file.  Give the new file
+     * a completely random name so we have only a tiny chance of
+     * overwriting some existing file.
+     */
+    newname = generate_random_name (filename);
+
+    if (guestfs_upload (g, upload_from, newname) == -1)
+      goto error;
+
+    /* Backup or overwrite the file. */
+    if (backup_extension) {
+      backupname = generate_backup_name (filename);
+      if (guestfs_mv (g, filename, backupname) == -1)
+        goto error;
+    }
+    if (guestfs_mv (g, newname, filename) == -1)
+      goto error;
+  }
+
+  unlink (tmpfile);
+  free (filename_to_free);
+  free (upload_from);
+  free (newname);
+  free (backupname);
+  return;
+
+ error:
+  unlink (tmpfile);
+  exit (EXIT_FAILURE);
+}
+
+static char *
+edit_interactively (const char *tmpfile)
+{
+  struct utimbuf times;
+  struct stat oldstat, newstat;
+  const char *editor;
+  char *cmd;
+  int r;
+  char *ret;
+
+  /* Set the time back a few seconds on the original file.  This is so
+   * that if the user is very fast at editing, or if EDITOR is an
+   * automatic editor, then the edit might happen within the 1 second
+   * granularity of mtime, and we would think the file hasn't changed.
+   */
+  if (stat (tmpfile, &oldstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  times.actime = oldstat.st_atime - 5;
+  times.modtime = oldstat.st_mtime - 5;
+  if (utime (tmpfile, &times) == -1) {
+    perror ("utimes");
+    exit (EXIT_FAILURE);
+  }
+
+  if (stat (tmpfile, &oldstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  editor = getenv ("EDITOR");
+  if (editor == NULL)
+    editor = "vi";
+
+  if (asprintf (&cmd, "%s %s", editor, tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (verbose)
+    fprintf (stderr, "%s\n", cmd);
+
+  r = system (cmd);
+  if (r == -1 || WEXITSTATUS (r) != 0)
+    exit (EXIT_FAILURE);
+
+  free (cmd);
+
+  if (stat (tmpfile, &newstat) == -1) {
+    perror (tmpfile);
+    exit (EXIT_FAILURE);
+  }
+
+  if (oldstat.st_ctime == newstat.st_ctime &&
+      oldstat.st_mtime == newstat.st_mtime) {
+    printf ("File not changed.\n");
+    return NULL;
+  }
+
+  ret = strdup (tmpfile);
+  if (!ret) {
+    perror ("strdup");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret;
+}
+
+static char *
+edit_non_interactively (const char *tmpfile)
+{
+  char *cmd, *outfile, *ret;
+  int r;
+
+  assert (perl_expr != NULL);
+
+  /* Pass the expression to Perl via the environment.  This sidesteps
+   * any quoting problems with the already complex Perl command line.
+   */
+  setenv ("virt_edit_expr", perl_expr, 1);
+
+  /* Call out to a canned Perl script. */
+  if (asprintf (&cmd,
+                "perl -e '"
+                "$lineno = 0; "
+                "$expr = $ENV{virt_edit_expr}; "
+                "while (<STDIN>) { "
+                "  $lineno++; "
+                "  eval $expr; "
+                "  die if $@; "
+                "  print STDOUT $_ or die \"print: $!\"; "
+                "} "
+                "close STDOUT or die \"close: $!\"; "
+                "' < %s > %s.out",
+                tmpfile, tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (verbose)
+    fprintf (stderr, "%s\n", cmd);
+
+  r = system (cmd);
+  if (r == -1 || WEXITSTATUS (r) != 0)
+    exit (EXIT_FAILURE);
+
+  free (cmd);
+
+  if (asprintf (&outfile, "%s.out", tmpfile) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  if (rename (outfile, tmpfile) == -1) {
+    perror ("rename");
+    exit (EXIT_FAILURE);
+  }
+
+  free (outfile);
+
+  ret = strdup (tmpfile);
+  if (!ret) {
+    perror ("strdup");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret; /* caller will free */
+}
+
+static int
+is_windows (guestfs_h *g, const char *root)
+{
+  char *type;
+  int w;
+
+  type = guestfs_inspect_get_type (g, root);
+  if (!type)
+    return 0;
+
+  w = STREQ (type, "windows");
+  free (type);
+  return w;
+}
+
+static void mount_drive_letter (char drive_letter, const char *root);
+
+static char *
+windows_path (guestfs_h *g, const char *root, const char *path)
+{
+  char *ret;
+  size_t i;
+
+  /* If there is a drive letter, rewrite the path. */
+  if (c_isalpha (path[0]) && path[1] == ':') {
+    char drive_letter = c_tolower (path[0]);
+    /* This returns the newly allocated string. */
+    mount_drive_letter (drive_letter, root);
+    ret = strdup (path + 2);
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+  else if (!*path) {
+    ret = strdup ("/");
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+  else {
+    ret = strdup (path);
+    if (ret == NULL) {
+      perror ("strdup");
+      exit (EXIT_FAILURE);
+    }
+  }
+
+  /* Blindly convert any backslashes into forward slashes.  Is this good? */
+  for (i = 0; i < strlen (ret); ++i)
+    if (ret[i] == '\\')
+      ret[i] = '/';
+
+  char *t = guestfs_case_sensitive_path (g, ret);
+  free (ret);
+  ret = t;
+
+  return ret;
+}
+
+static void
+mount_drive_letter (char drive_letter, const char *root)
+{
+  char **drives;
+  char *device;
+  size_t i;
+
+  /* Resolve the drive letter using the drive mappings table. */
+  drives = guestfs_inspect_get_drive_mappings (g, root);
+  if (drives == NULL || drives[0] == NULL) {
+    fprintf (stderr, _("%s: to use Windows drive letters, this must be a Windows guest\n"),
+             program_name);
+    exit (EXIT_FAILURE);
+  }
+
+  device = NULL;
+  for (i = 0; drives[i] != NULL; i += 2) {
+    if (c_tolower (drives[i][0]) == drive_letter && drives[i][1] == '\0') {
+      device = drives[i+1];
+      break;
+    }
+  }
+
+  if (device == NULL) {
+    fprintf (stderr, _("%s: drive '%c:' not found.\n"),
+             program_name, drive_letter);
+    exit (EXIT_FAILURE);
+  }
+
+  /* Unmount current disk and remount device. */
+  if (guestfs_umount_all (g) == -1)
+    exit (EXIT_FAILURE);
+
+  if (guestfs_mount_options (g, "", device, "/") == -1)
+    exit (EXIT_FAILURE);
+
+  for (i = 0; drives[i] != NULL; ++i)
+    free (drives[i]);
+  free (drives);
+  /* Don't need to free (device) because that string was in the
+   * drives array.
+   */
+}
+
+static char
+random_char (void)
+{
+  char c[] = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  return c[random () % (sizeof c - 1)];
+}
+
+static char *
+generate_random_name (const char *filename)
+{
+  char *ret, *p;
+  size_t i;
+
+  ret = malloc (strlen (filename) + 16);
+  if (!ret) {
+    perror ("malloc");
+    exit (EXIT_FAILURE);
+  }
+  strcpy (ret, filename);
+
+  p = strrchr (ret, '/');
+  assert (p);
+  p++;
+
+  /* Because of "+ 16" above, there should be enough space in the
+   * output buffer to write 8 random characters here.
+   */
+  for (i = 0; i < 8; ++i)
+    *p++ = random_char ();
+  *p++ = '\0';
+
+  return ret; /* caller will free */
+}
+
+static char *
+generate_backup_name (const char *filename)
+{
+  char *ret;
+
+  assert (backup_extension != NULL);
+
+  if (asprintf (&ret, "%s%s", filename, backup_extension) == -1) {
+    perror ("asprintf");
+    exit (EXIT_FAILURE);
+  }
+
+  return ret; /* caller will free */
+}
diff --git a/edit/virt-edit.pod b/edit/virt-edit.pod
new file mode 100644
index 00000000..ba4e3a6a
--- /dev/null
+++ b/edit/virt-edit.pod
@@ -0,0 +1,381 @@
+=encoding utf8
+
+=head1 NAME
+
+virt-edit - Edit a file in a virtual machine
+
+=head1 SYNOPSIS
+
+ virt-edit [--options] -d domname file [file ...]
+
+ virt-edit [--options] -a disk.img [-a disk.img ...] file [file ...]
+
+ virt-edit [-d domname|-a disk.img] file -e 'expr'
+
+Old-style:
+
+ virt-edit domname file
+
+ virt-edit disk.img [disk.img ...] file
+
+=head1 WARNING
+
+You must I<not> use C<virt-edit> on live virtual machines.  If you do
+this, you risk disk corruption in the VM.  C<virt-edit> tries to stop
+you from doing this, but doesn't catch all cases.
+
+=head1 DESCRIPTION
+
+C<virt-edit> is a command line tool to edit C<file> where each C<file>
+exists in the named virtual machine (or disk image).
+
+Multiple filenames can be given, in which case they are each edited in
+turn.  Each filename must be a full path, starting at the root
+directory (starting with '/').
+
+If you want to just view a file, use L<virt-cat(1)>.
+
+For more complex cases you should look at the L<guestfish(1)> tool
+(see L</USING GUESTFISH> below).
+
+C<virt-edit> cannot be used to create a new file.  L<guestfish(1)> can
+do that and much more.
+
+=head1 EXAMPLES
+
+Edit the named files interactively:
+
+ virt-edit -d mydomain /boot/grub/grub.conf
+
+ virt-edit -d mydomain /etc/passwd
+
+For Windows guests, some Windows paths are understood:
+
+ virt-edit -d mywindomain 'c:\autoexec.bat'
+
+If Perl is installed, you can also edit files non-interactively (see
+L</NON-INTERACTIVE EDITING> below).
+To change the init default level to 5:
+
+ virt-edit -d mydomain /etc/inittab -e 's/^id:.*/id:5:initdefault:/'
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display brief help.
+
+=item B<-a> file
+
+=item B<--add> file
+
+Add I<file> which should be a disk image from a virtual machine.  If
+the virtual machine has multiple block devices, you must supply all of
+them with separate I<-a> options.
+
+The format of the disk image is auto-detected.  To override this and
+force a particular format use the I<--format=..> option.
+
+=item B<-b> extension
+
+=item B<--backup> extension
+
+Create a backup of the original file I<in the guest disk image>.
+The backup has the original filename with C<extension> added.
+
+Usually the first character of C<extension> would be a dot C<.>
+so you would write:
+
+ virt-edit -b .orig [etc]
+
+By default, no backup file is made.
+
+=item B<--connect URI> | B<-c URI>
+
+If using libvirt, connect to the given I<URI>.  If omitted, then we
+connect to the default libvirt hypervisor.
+
+If you specify guest block devices directly, then libvirt is not used
+at all.
+
+=item B<-d> guest
+
+=item B<--domain> guest
+
+Add all the disks from the named libvirt guest.  Domain UUIDs can be
+used instead of names.
+
+=item B<--echo-keys>
+
+When prompting for keys and passphrases, virt-cat normally turns
+echoing off so you cannot see what you are typing.  If you are not
+worried about Tempest attacks and there is no one else in the room you
+can specify this flag to see what you are typing.
+
+=item B<--format> raw|qcow2|...
+
+=item B<--format>
+
+The default for the I<-a> option is to auto-detect the format of the
+disk image.  Using this forces the disk format for I<-a> options which
+follow on the command line.  Using I<--format> with no argument
+switches back to auto-detection for subsequent I<-a> options.
+
+For example:
+
+ virt-edit --format=raw -a disk.img file
+
+forces raw format (no auto-detection) for C<disk.img>.
+
+ virt-edit --format=raw -a disk.img --format -a another.img file
+
+forces raw format (no auto-detection) for C<disk.img> and reverts to
+auto-detection for C<another.img>.
+
+If you have untrusted raw-format guest disk images, you should use
+this option to specify the disk format.  This avoids a possible
+security problem with malicious guests (CVE-2010-3851).
+
+=item B<-e> EXPR
+
+=item B<--expr> EXPR
+
+Instead of launching the external editor, non-interactively
+apply the Perl expression C<EXPR> to each line in the file.
+See L</NON-INTERACTIVE EDITING> below.
+
+Be careful to properly quote the expression to prevent it from
+being altered by the shell.
+
+Note that this option is only available when Perl 5 is installed.
+
+=item B<--keys-from-stdin>
+
+Read key or passphrase parameters from stdin.  The default is
+to try to read passphrases from the user by opening C</dev/tty>.
+
+=item B<-v>
+
+=item B<--verbose>
+
+Enable verbose messages for debugging.
+
+=item B<-V>
+
+=item B<--version>
+
+Display version number and exit.
+
+=item B<-x>
+
+Enable tracing of libguestfs API calls.
+
+=back
+
+=head1 OLD-STYLE COMMAND LINE ARGUMENTS
+
+Previous versions of virt-edit allowed you to write either:
+
+ virt-edit disk.img [disk.img ...] file
+
+or
+
+ virt-edit guestname file
+
+whereas in this version you should use I<-a> or I<-d> respectively
+to avoid the confusing case where a disk image might have the same
+name as a guest.
+
+For compatibility the old style is still supported.
+
+=head1 NON-INTERACTIVE EDITING
+
+C<virt-edit> normally calls out to C<$EDITOR> (or vi) so
+the system administrator can interactively edit the file.
+
+There are two ways also to use C<virt-edit> from scripts in order to
+make automated edits to files.  (Note that although you I<can> use
+C<virt-edit> like this, it's less error-prone to write scripts
+directly using the libguestfs API and Augeas for configuration file
+editing.)
+
+The first method is to temporarily set C<$EDITOR> to any script or
+program you want to run.  The script is invoked as C<$EDITOR tmpfile>
+and it should update C<tmpfile> in place however it likes.
+
+The second method is to use the I<-e> parameter of C<virt-edit> to run
+a short Perl snippet in the style of L<sed(1)>.  For example to
+replace all instances of C<foo> with C<bar> in a file:
+
+ virt-edit -d domname filename -e 's/foo/bar/'
+
+The full power of Perl regular expressions can be used (see
+L<perlre(1)>).  For example to delete root's password you could do:
+
+ virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
+
+What really happens is that the snippet is evaluated as a Perl
+expression for each line of the file.  The line, including the final
+C<\n>, is passed in C<$_> and the expression should update C<$_> or
+leave it unchanged.
+
+To delete a line, set C<$_> to the empty string.  For example, to
+delete the C<apache> user account from the password file you can do:
+
+ virt-edit -d mydomain /etc/passwd -e '$_ = "" if /^apache:/'
+
+To insert a line, prepend or append it to C<$_>.  However appending
+lines to the end of the file is rather difficult this way since there
+is no concept of "last line of the file" - your expression just
+doesn't get called again.  You might want to use the first method
+(setting C<$EDITOR>) if you want to do this.
+
+The variable C<$lineno> contains the current line number.
+As is traditional, the first line in the file is number C<1>.
+
+The return value from the expression is ignored, but the expression
+may call C<die> in order to abort the whole program, leaving the
+original file untouched.
+
+Remember when matching the end of a line that C<$_> may contain the
+final C<\n>, or (for DOS files) C<\r\n>, or if the file does not end
+with a newline then neither of these.  Thus to match or substitute
+some text at the end of a line, use this regular expression:
+
+ /some text(\r?\n)?$/
+
+Alternately, use the perl C<chomp> function, being careful not to
+chomp C<$_> itself (since that would remove all newlines from the
+file):
+
+ my $m = $_; chomp $m; $m =~ /some text$/
+
+=head1 WINDOWS PATHS
+
+C<virt-edit> has a limited ability to understand Windows drive letters
+and paths (eg. C<E:\foo\bar.txt>).
+
+If and only if the guest is running Windows then:
+
+=over 4
+
+=item *
+
+Drive letter prefixes like C<C:> are resolved against the
+Windows Registry to the correct filesystem.
+
+=item *
+
+Any backslash (C<\>) characters in the path are replaced
+with forward slashes so that libguestfs can process it.
+
+=item *
+
+The path is resolved case insensitively to locate the file
+that should be edited.
+
+=back
+
+There are some known shortcomings:
+
+=over 4
+
+=item *
+
+Some NTFS symbolic links may not be followed correctly.
+
+=item *
+
+NTFS junction points that cross filesystems are not followed.
+
+=back
+
+=head1 USING GUESTFISH
+
+L<guestfish(1)> is a more powerful, lower level tool which you can use
+when C<virt-edit> doesn't work.
+
+Using C<virt-edit> is approximately equivalent to doing:
+
+ guestfish --rw -i -d domname edit /file
+
+where C<domname> is the name of the libvirt guest, and C</file> is the
+full path to the file.
+
+The command above uses libguestfs's guest inspection feature and so
+does not work on guests that libguestfs cannot inspect, or on things
+like arbitrary disk images that don't contain guests.  To edit a file
+on a disk image directly, use:
+
+ guestfish --rw -a disk.img -m /dev/sda1 edit /file
+
+where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
+within the disk image to edit, and C</file> is the full path to the
+file.
+
+C<virt-edit> cannot create new files.  Use the guestfish commands
+C<touch>, C<write> or C<upload> instead:
+
+ guestfish --rw -i -d domname touch /newfile
+
+ guestfish --rw -i -d domname write /newfile "new content"
+
+ guestfish --rw -i -d domname upload localfile /newfile
+
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item C<EDITOR>
+
+If set, this string is used as the editor.  It may contain arguments,
+eg. C<"emacs -nw">
+
+If not set, C<vi> is used.
+
+=back
+
+=head1 SHELL QUOTING
+
+Libvirt guest names can contain arbitrary characters, some of which
+have meaning to the shell such as C<#> and space.  You may need to
+quote or escape these characters on the command line.  See the shell
+manual page L<sh(1)> for details.
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfish(1)>,
+L<virt-cat(1)>,
+L<virt-copy-in(1)>,
+L<virt-tar-in(1)>,
+L<Sys::Guestfs(3)>,
+L<Sys::Guestfs::Lib(3)>,
+L<Sys::Virt(3)>,
+L<http://libguestfs.org/>,
+L<perl(1)>,
+L<perlre(1)>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009-2011 Red Hat Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.