June 2015 - Libguestfs - libguestfs List Archives

[PATCH] (Almost) new tool: virt-get-kernel
by Pino Toscano 15 Jun '15

15 Jun '15

Extract the guest kernel/ramdisk extraction from virt-builder into a separate utility, so it can be used and improved without cluttering virt-builder. Currently it does what virt-builder --get-kernel did, adding also the options for remote disks and libvirt access, much like other libguestfs tools. virt-builder --get-kernel now just spawns virt-get-kernel. --- .gitignore | 5 ++ Makefile.am | 3 +- builder/Makefile.am | 2 - builder/builder.ml | 15 +++- builder/get_kernel.ml | 92 -------------------- builder/get_kernel.mli | 19 ----- configure.ac | 1 + get-kernel/Makefile.am | 146 ++++++++++++++++++++++++++++++++ get-kernel/get_kernel.ml | 185 +++++++++++++++++++++++++++++++++++++++++ get-kernel/virt-get-kernel.pod | 148 +++++++++++++++++++++++++++++++++ po/POTFILES-ml | 2 +- run.in | 1 + 12 files changed, 502 insertions(+), 117 deletions(-) delete mode 100644 builder/get_kernel.ml delete mode 100644 builder/get_kernel.mli create mode 100644 get-kernel/Makefile.am create mode 100644 get-kernel/get_kernel.ml create mode 100644 get-kernel/virt-get-kernel.pod diff --git a/.gitignore b/.gitignore index d1292d9..6f14915 100644 --- a/.gitignore +++ b/.gitignore @@ -193,6 +193,10 @@ Makefile.in /generator/generator /generator/.pod2text.data* /generator/stamp-generator +/get-kernel/.depend +/get-kernel/stamp-virt-get-kernel.pod +/get-kernel/virt-get-kernel +/get-kernel/virt-get-kernel.1 /.gitattributes /.git-module-status /gnulib @@ -245,6 +249,7 @@ Makefile.in /html/virt-edit.1.html /html/virt-filesystems.1.html /html/virt-format.1.html +/html/virt-get-kernel.1.html /html/virt-index-validate.1.html /html/virt-inspector.1.html /html/virt-list-filesystems.1.html diff --git a/Makefile.am b/Makefile.am index 331a34e..ad6d9d3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -133,6 +133,7 @@ SUBDIRS += \ mllib \ customize \ builder builder/website \ + get-kernel \ resize \ sparsify \ sysprep \ @@ -353,7 +354,7 @@ all-local: grep -v -E '^python/utils.c$$' | \ LC_ALL=C sort > po/POTFILES cd $(srcdir); \ - find builder customize mllib resize sparsify sysprep v2v -name '*.ml' | \ + find builder customize get-kernel mllib resize sparsify sysprep v2v -name '*.ml' | \ LC_ALL=C sort > po/POTFILES-ml # Try to stop people using 'make install' without 'DESTDIR'. diff --git a/builder/Makefile.am b/builder/Makefile.am index 28b2adf..d69e25f 100644 --- a/builder/Makefile.am +++ b/builder/Makefile.am @@ -39,7 +39,6 @@ CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-builder SOURCES_MLI = \ cache.mli \ downloader.mli \ - get_kernel.mli \ index_parser.mli \ ini_reader.mli \ languages.mli \ @@ -56,7 +55,6 @@ SOURCES_ML = \ ini_reader.ml \ paths.ml \ languages.ml \ - get_kernel.ml \ cache.ml \ sources.ml \ downloader.ml \ diff --git a/builder/builder.ml b/builder/builder.ml index 5ea69c0..1f618ad 100644 --- a/builder/builder.ml +++ b/builder/builder.ml @@ -91,8 +91,19 @@ let main () = let mode = match mode with | `Get_kernel -> (* --get-kernel is really a different program ... *) - Get_kernel.get_kernel ?format ?output arg; - exit 0 + let cmd = + sprintf "virt-get-kernel%s%s%s%s --add %s" + (if verbose () then " --verbose" else "") + (if trace () then " -x" else "") + (match format with + | None -> "" + | Some format -> sprintf " --format %s" (quote format)) + (match output with + | None -> "" + | Some output -> sprintf " --output %s" (quote output)) + (quote arg) in + if verbose () then printf "%s\n%!" cmd; + exit (Sys.command cmd) | `Delete_cache -> (* --delete-cache *) (match cache with diff --git a/builder/get_kernel.ml b/builder/get_kernel.ml deleted file mode 100644 index 5cea647..0000000 --- a/builder/get_kernel.ml +++ /dev/null @@ -1,92 +0,0 @@ -(* virt-builder - * Copyright (C) 2013 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., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - *) - -open Common_gettext.Gettext -open Common_utils - -open Utils - -module G = Guestfs - -open Printf - -(* Originally: - * http://rwmj.wordpress.com/2013/09/13/get-kernel-and-initramfs-from-a-disk-i… - *) -let rec get_kernel ?format ?output disk = - let g = new G.guestfs () in - if trace () then g#set_trace true; - if verbose () then g#set_verbose true; - g#add_drive_opts ?format ~readonly:true disk; - g#launch (); - - let roots = g#inspect_os () in - if Array.length roots = 0 then - error (f_"get-kernel: no operating system found"); - if Array.length roots > 1 then - error (f_"get-kernel: dual/multi-boot images are not supported by this tool"); - let root = roots.(0) in - - (* Mount up the disks. *) - let mps = g#inspect_get_mountpoints root in - let cmp (a,_) (b,_) = compare (String.length a) (String.length b) in - let mps = List.sort cmp mps in - List.iter ( - fun (mp, dev) -> - try g#mount_ro dev mp - with Guestfs.Error msg -> warning (f_"%s (ignored)") msg - ) mps; - - (* Get all kernels and initramfses. *) - let glob w = Array.to_list (g#glob_expand w) in - let kernels = glob "/boot/vmlinuz-*" in - let initrds = glob "/boot/initramfs-*" in - - (* Old RHEL: *) - let initrds = if initrds <> [] then initrds else glob "/boot/initrd-*" in - - (* Debian/Ubuntu: *) - let initrds = if initrds <> [] then initrds else glob "/boot/initrd.img-*" in - - (* Sort by version to get the latest version as first element. *) - let kernels = List.rev (List.sort compare_version kernels) in - let initrds = List.rev (List.sort compare_version initrds) in - - if kernels = [] then - error (f_"no kernel found"); - - (* Download the latest. *) - let outputdir = - match output with - | None -> Filename.current_dir_name - | Some dir -> dir in - let kernel_in = List.hd kernels in - let kernel_out = outputdir // Filename.basename kernel_in in - printf "download: %s -> %s\n%!" kernel_in kernel_out; - g#download kernel_in kernel_out; - - if initrds <> [] then ( - let initrd_in = List.hd initrds in - let initrd_out = outputdir // Filename.basename initrd_in in - printf "download: %s -> %s\n%!" initrd_in initrd_out; - g#download initrd_in initrd_out - ); - - (* Shutdown. *) - g#shutdown (); - g#close () diff --git a/builder/get_kernel.mli b/builder/get_kernel.mli deleted file mode 100644 index 5f47ca1..0000000 --- a/builder/get_kernel.mli +++ /dev/null @@ -1,19 +0,0 @@ -(* virt-builder - * Copyright (C) 2013 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., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - *) - -val get_kernel : ?format:string -> ?output:string -> string -> unit diff --git a/configure.ac b/configure.ac index 2c82c35..e0da1ad 100644 --- a/configure.ac +++ b/configure.ac @@ -1749,6 +1749,7 @@ AC_CONFIG_FILES([Makefile format/Makefile fuse/Makefile generator/Makefile + get-kernel/Makefile gnulib/lib/Makefile gnulib/tests/Makefile gobject/libguestfs-gobject-1.0.pc diff --git a/get-kernel/Makefile.am b/get-kernel/Makefile.am new file mode 100644 index 0000000..f217128 --- /dev/null +++ b/get-kernel/Makefile.am @@ -0,0 +1,146 @@ +# libguestfs get-kernel tool +# Copyright (C) 2015 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +include $(top_srcdir)/subdir-rules.mk + +EXTRA_DIST = \ + $(SOURCES_ML) $(SOURCES_C) \ + virt-get-kernel.pod + +CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-get-kernel + +SOURCES_ML = \ + get_kernel.ml + +SOURCES_C = \ + $(top_srcdir)/mllib/uri-c.c \ + $(top_srcdir)/fish/uri.c + +man_MANS = +noinst_DATA = +bin_PROGRAMS = + +if HAVE_OCAML + +bin_PROGRAMS += virt-get-kernel + +virt_get_kernel_SOURCES = $(SOURCES_C) +virt_get_kernel_CPPFLAGS = \ + -I. \ + -I$(top_builddir) \ + -I$(top_srcdir)/gnulib/lib -I$(top_builddir)/gnulib/lib \ + -I$(shell $(OCAMLC) -where) \ + -I$(top_srcdir)/gnulib/lib \ + -I$(top_srcdir)/src \ + -I$(top_srcdir)/fish +virt_get_kernel_CFLAGS = \ + -pthread \ + $(WARN_CFLAGS) $(WERROR_CFLAGS) \ + $(LIBXML2_CFLAGS) + +BOBJECTS = \ + $(top_builddir)/mllib/libdir.cmo \ + $(top_builddir)/mllib/config.cmo \ + $(top_builddir)/mllib/common_gettext.cmo \ + $(top_builddir)/mllib/common_utils.cmo \ + $(top_builddir)/mllib/uRI.cmo \ + $(SOURCES_ML:.ml=.cmo) +XOBJECTS = $(BOBJECTS:.cmo=.cmx) + +# -I $(top_builddir)/src/.libs is a hack which forces corresponding -L +# option to be passed to gcc, so we don't try linking against an +# installed copy of libguestfs. +OCAMLPACKAGES = \ + -package str,unix \ + -I $(top_builddir)/src/.libs \ + -I $(top_builddir)/gnulib/lib/.libs \ + -I $(top_builddir)/ocaml \ + -I $(top_builddir)/mllib +if HAVE_OCAML_PKG_GETTEXT +OCAMLPACKAGES += -package gettext-stub +endif + +OCAMLCLIBS = \ + -pthread -lpthread \ + -lutils \ + $(LIBXML2_LIBS) \ + $(LIBINTL) \ + -lgnu + +OCAMLFLAGS = $(OCAML_FLAGS) $(OCAML_WARN_ERROR) + +if !HAVE_OCAMLOPT +OBJECTS = $(BOBJECTS) +BEST = c +OCAMLLINKFLAGS = mlguestfs.cma -custom +else +OBJECTS = $(XOBJECTS) +BEST = opt +OCAMLLINKFLAGS = mlguestfs.cmxa +endif + +virt_get_kernel_DEPENDENCIES = $(OBJECTS) $(top_srcdir)/ocaml-link.sh +virt_get_kernel_LINK = \ + $(top_srcdir)/ocaml-link.sh -cclib '$(OCAMLCLIBS)' -- \ + $(OCAMLFIND) $(BEST) $(OCAMLFLAGS) $(OCAMLPACKAGES) $(OCAMLLINKFLAGS) \ + $(OBJECTS) -o $@ + +.mli.cmi: + $(OCAMLFIND) ocamlc $(OCAMLFLAGS) $(OCAMLPACKAGES) -c $< -o $@ +.ml.cmo: + $(OCAMLFIND) ocamlc $(OCAMLFLAGS) $(OCAMLPACKAGES) -c $< -o $@ +if HAVE_OCAMLOPT +.ml.cmx: + $(OCAMLFIND) ocamlopt $(OCAMLFLAGS) $(OCAMLPACKAGES) -c $< -o $@ +endif + +# Manual pages and HTML files for the website. + +man_MANS += virt-get-kernel.1 +noinst_DATA += $(top_builddir)/html/virt-get-kernel.1.html + +virt-get-kernel.1 $(top_builddir)/html/virt-get-kernel.1.html: stamp-virt-get-kernel.pod + +stamp-virt-get-kernel.pod: virt-get-kernel.pod + $(PODWRAPPER) \ + --man virt-get-kernel.1 \ + --html $(top_builddir)/html/virt-get-kernel.1.html \ + --license GPLv2+ \ + $< + touch $@ + +CLEANFILES += stamp-virt-get-kernel.pod + +# Dependencies. +depend: .depend + +.depend: $(wildcard $(abs_srcdir)/*.mli) $(wildcard $(abs_srcdir)/*.ml) + rm -f $@ $@-t + $(OCAMLFIND) ocamldep -I ../ocaml -I $(abs_srcdir) -I $(abs_top_builddir)/mllib $^ | \ + $(SED) 's/ *$$//' | \ + $(SED) -e :a -e '/ *\\$$/N; s/ *\\\n */ /; ta' | \ + $(SED) -e 's,$(abs_srcdir)/,$(builddir)/,g' | \ + sort > $@-t + mv $@-t $@ + +-include .depend + +endif + +DISTCLEANFILES = .depend + +.PHONY: depend diff --git a/get-kernel/get_kernel.ml b/get-kernel/get_kernel.ml new file mode 100644 index 0000000..646a240 --- /dev/null +++ b/get-kernel/get_kernel.ml @@ -0,0 +1,185 @@ +(* virt-get-kernel + * Copyright (C) 2013-2015 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., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + *) + +open Common_gettext.Gettext +open Common_utils + +module G = Guestfs + +open Printf + +(* Main program. *) +let main () = + let add, output = + let domain = ref None in + let file = ref None in + let libvirturi = ref "" in + let format = ref "" in + let output = ref "" in + let machine_readable = ref false in + + let set_file arg = + if !file <> None then + error (f_"--add option can only be given once"); + let uri = + try URI.parse_uri arg + with Invalid_argument "URI.parse_uri" -> + error (f_"error parsing URI '%s'. Look for error messages printed above.") arg in + file := Some uri + and set_domain dom = + if !domain <> None then + error (f_"--domain option can only be given once"); + domain := Some dom in + + let ditto = " -\"-" in + let argspec = Arg.align [ + "-a", Arg.String set_file, s_"file" ^ " " ^ s_"Add disk image file"; + "--add", Arg.String set_file, s_"file" ^ " " ^ s_"Add disk image file"; + "-c", Arg.Set_string libvirturi, s_"uri" ^ " " ^ s_"Set libvirt URI"; + "--connect", Arg.Set_string libvirturi, s_"uri" ^ " " ^ s_"Set libvirt URI"; + "-d", Arg.String set_domain, s_"domain" ^ " " ^ s_"Set libvirt guest name"; + "--domain", Arg.String set_domain, s_"domain" ^ " " ^ s_"Set libvirt guest name"; + "--format", Arg.Set_string format, s_"format" ^ " " ^ s_"Format of input disk"; + "--short-options", Arg.Unit display_short_options, " " ^ s_"List short options"; + "--long-options", Arg.Unit display_long_options, " " ^ s_"List long options"; + "--machine-readable", Arg.Set machine_readable, " " ^ s_"Make output machine readable"; + "-o", Arg.Set_string output, s_"directory" ^ " " ^ s_"Output directory"; + "--output", Arg.Set_string output, ditto; + "-v", Arg.Unit set_verbose, " " ^ s_"Enable debugging messages"; + "--verbose", Arg.Unit set_verbose, ditto; + "-V", Arg.Unit print_version_and_exit, + " " ^ s_"Display version and exit"; + "--version", Arg.Unit print_version_and_exit, ditto; + "-x", Arg.Unit set_trace, " " ^ s_"Enable tracing of libguestfs calls"; + ] in + long_options := argspec; + let anon_fun _ = raise (Arg.Bad (s_"extra parameter on the command line")) in + let usage_msg = + sprintf (f_"\ +%s: extract kernel and ramdisk from a guest + +A short summary of the options is given below. For detailed help please +read the man page virt-get-kernel(1). +") + prog in + Arg.parse argspec anon_fun usage_msg; + + (* Machine-readable mode? Print out some facts about what + * this binary supports. + *) + if !machine_readable then ( + printf "virt-get-kernel\n"; + exit 0 + ); + + (* Check -a and -d options. *) + let file = !file in + let domain = !domain in + let libvirturi = match !libvirturi with "" -> None | s -> Some s in + let add = + match file, domain with + | None, None -> + error (f_"you must give either -a or -d options. Read virt-get-kernel(1) man page for further information.") + | Some _, Some _ -> + error (f_"you cannot give -a and -d options together. Read virt-get-kernel(1) man page for further information.") + | None, Some dom -> + fun (g : Guestfs.guestfs) -> + let readonlydisk = "ignore" (* ignore CDs, data drives *) in + ignore (g#add_domain + ~readonly:true ~allowuuid:true ~readonlydisk + ?libvirturi dom) + | Some uri, None -> + fun g -> + let { URI.path = path; protocol = protocol; + server = server; username = username; + password = password } = uri in + let format = match !format with "" -> None | s -> Some s in + g#add_drive + ~readonly:true ?format ~protocol ?server ?username ?secret:password + path + in + + (* Dereference the rest of the args. *) + let output = match !output with "" -> None | str -> Some str in + + add, output in + + (* Connect to libguestfs. *) + let g = new G.guestfs () in + if trace () then g#set_trace true; + if verbose () then g#set_verbose true; + add g; + g#launch (); + + let roots = g#inspect_os () in + if Array.length roots = 0 then + error (f_"get-kernel: no operating system found"); + if Array.length roots > 1 then + error (f_"get-kernel: dual/multi-boot images are not supported by this tool"); + let root = roots.(0) in + + (* Mount up the disks. *) + let mps = g#inspect_get_mountpoints root in + let cmp (a,_) (b,_) = compare (String.length a) (String.length b) in + let mps = List.sort cmp mps in + List.iter ( + fun (mp, dev) -> + try g#mount_ro dev mp + with Guestfs.Error msg -> warning (f_"%s (ignored)") msg + ) mps; + + (* Get all kernels and initramfses. *) + let glob w = Array.to_list (g#glob_expand w) in + let kernels = glob "/boot/vmlinuz-*" in + let initrds = glob "/boot/initramfs-*" in + + (* Old RHEL: *) + let initrds = if initrds <> [] then initrds else glob "/boot/initrd-*" in + + (* Debian/Ubuntu: *) + let initrds = if initrds <> [] then initrds else glob "/boot/initrd.img-*" in + + (* Sort by version to get the latest version as first element. *) + let kernels = List.rev (List.sort compare_version kernels) in + let initrds = List.rev (List.sort compare_version initrds) in + + if kernels = [] then + error (f_"no kernel found"); + + (* Download the latest. *) + let outputdir = + match output with + | None -> Filename.current_dir_name + | Some dir -> dir in + let kernel_in = List.hd kernels in + let kernel_out = outputdir // Filename.basename kernel_in in + printf "download: %s -> %s\n%!" kernel_in kernel_out; + g#download kernel_in kernel_out; + + if initrds <> [] then ( + let initrd_in = List.hd initrds in + let initrd_out = outputdir // Filename.basename initrd_in in + printf "download: %s -> %s\n%!" initrd_in initrd_out; + g#download initrd_in initrd_out + ); + + (* Shutdown. *) + g#shutdown (); + g#close () + +let () = run_main_and_handle_errors main diff --git a/get-kernel/virt-get-kernel.pod b/get-kernel/virt-get-kernel.pod new file mode 100644 index 0000000..e130b4c --- /dev/null +++ b/get-kernel/virt-get-kernel.pod @@ -0,0 +1,148 @@ +=head1 NAME + +virt-get-kernel - Extract kernel and ramdisk from guests + +=head1 SYNOPSIS + + virt-get-kernel [--options] -d domname + + virt-get-kernel [--options] -a disk.img + +=head1 DESCRIPTION + +This option extracts the kernel and initramfs from a guest. + +The format of the disk image is automatically detected unless you +specify it by using the I<--format> option. + +In the case where the guest contains multiple kernels, the one with +the highest version number is chosen. To extract arbitrary kernels +from the disk image, see L<guestfish(1)>. To extract the entire +C</boot> directory of a guest, see L<virt-copy-out(1)>. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display help. + +=item B<-a> file + +=item B<--add> file + +Add I<file> which should be a disk image from a virtual machine. + +The format of the disk image is auto-detected. To override this and +force a particular format use the I<--format> option. + +=item B<-a> URI + +=item B<--add> URI + +Add a remote disk. The URI format is compatible with guestfish. +See L<guestfish(1)/ADDING REMOTE STORAGE>. + +=item B<-c> URI + +=item B<--connect> 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 (I<-a>), 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<--format> raw|qcow2|.. + +=item B<--format> auto + +The default for the I<-a> option is to auto-detect the format of the +disk image. Using this forces the disk format for the I<-a> option +on the command line. + +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<--machine-readable> + +This option is used to make the output more machine friendly +when being parsed by other programs. See +L</MACHINE READABLE OUTPUT> below. + +=item B<-o> directory + +=item B<--output> directory + +This option specifies the output directory where kernel and initramfs +from the guest are written. + +If not specified, the default output is the current directory. + +=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 MACHINE READABLE OUTPUT + +The I<--machine-readable> option can be used to make the output more +machine friendly, which is useful when calling virt-get-kernel from +other programs, GUIs etc. + +Use the option on its own to query the capabilities of the +virt-get-kernel binary. Typical output looks like this: + + $ virt-get-kernel --machine-readable + virt-get-kernel + +A list of features is printed, one per line, and the program exits +with status 0. + +=head1 ENVIRONMENT VARIABLES + +For other environment variables which affect all libguestfs programs, +see L<guestfs(3)/ENVIRONMENT VARIABLES>. + +=head1 EXIT STATUS + +This program returns 0 if successful, or non-zero if there was an +error. + +=head1 SEE ALSO + +L<guestfs(3)>, +L<guestfish(1)>, +L<guestmount(1)>, +L<virt-copy-out(1)>, +L<http://libguestfs.org/>. + +=head1 AUTHOR + +Richard W.M. Jones L<http://people.redhat.com/~rjones/> + +=head1 COPYRIGHT + +Copyright (C) 2013-2015 Red Hat Inc. diff --git a/po/POTFILES-ml b/po/POTFILES-ml index 3fc60e5..8725385 100644 --- a/po/POTFILES-ml +++ b/po/POTFILES-ml @@ -2,7 +2,6 @@ builder/builder.ml builder/cache.ml builder/cmdline.ml builder/downloader.ml -builder/get_kernel.ml builder/index_parser.ml builder/ini_reader.ml builder/languages.ml @@ -26,6 +25,7 @@ customize/random_seed.ml customize/ssh_key.ml customize/timezone.ml customize/urandom.ml +get-kernel/get_kernel.ml mllib/JSON.ml mllib/JSON_tests.ml mllib/common_gettext.ml diff --git a/run.in b/run.in index 8fdf454..6709cdd 100755 --- a/run.in +++ b/run.in @@ -92,6 +92,7 @@ prepend PATH "$b/erlang" prepend PATH "$b/fish" prepend PATH "$b/format" prepend PATH "$b/fuse" +prepend PATH "$b/get-kernel" prepend PATH "$b/inspector" prepend PATH "$b/make-fs" prepend PATH "$b/p2v" -- 2.1.0

2 3

[PATCH] pod: Use F<> for filenames instead of C<>.
by Richard W.M. Jones 15 Jun '15

15 Jun '15

Done using a sequence of regular expressions like this: perl -pi.bak -e 's{C</}{F</}g' `git ls-files \*.pod` generator/actions.ml perl -pi.bak -e 's{C<C:\\}{F<C:\\}g' `git ls-files \*.pod` generator/actions.ml [etc] and then tediously checking every change by hand. --- align/virt-alignment-scan.pod | 8 +- appliance/libguestfs-make-fixed-appliance.pod | 6 +- builder/virt-builder.pod | 58 +++--- builder/virt-index-validate.pod | 2 +- cat/virt-cat.pod | 16 +- cat/virt-filesystems.pod | 12 +- cat/virt-log.pod | 10 +- cat/virt-ls.pod | 10 +- customize/virt-customize.pod | 10 +- daemon/guestfsd.pod | 16 +- df/virt-df.pod | 12 +- diff/virt-diff.pod | 8 +- edit/virt-edit.pod | 18 +- examples/guestfs-faq.pod | 28 +-- examples/guestfs-performance.pod | 20 +- examples/guestfs-recipes.pod | 22 +- examples/guestfs-testing.pod | 6 +- fish/guestfish.pod | 60 +++--- fish/libguestfs-tools.conf.pod | 10 +- fish/virt-copy-in.pod | 4 +- format/virt-format.pod | 12 +- fuse/guestmount.pod | 8 +- generator/actions.ml | 250 +++++++++++----------- guestfs-release-notes.pod | 38 ++-- inspector/virt-inspector.pod | 12 +- java/examples/guestfs-java.pod | 8 +- make-fs/virt-make-fs.pod | 2 +- p2v/virt-p2v-make-disk.pod | 8 +- p2v/virt-p2v-make-kickstart.pod | 20 +- p2v/virt-p2v.pod | 26 +-- rescue/virt-rescue.pod | 20 +- resize/virt-resize.pod | 14 +- sparsify/virt-sparsify.pod | 6 +- src/guestfs.pod | 288 +++++++++++++------------- sysprep/virt-sysprep.pod | 14 +- v2v/test-harness/virt-v2v-test-harness.pod | 8 +- v2v/virt-v2v.pod | 46 ++-- 37 files changed, 558 insertions(+), 558 deletions(-) diff --git a/align/virt-alignment-scan.pod b/align/virt-alignment-scan.pod index 2a740a4..54f3ffd 100644 --- a/align/virt-alignment-scan.pod +++ b/align/virt-alignment-scan.pod @@ -67,7 +67,7 @@ program. The columns are: =item col 1 -The device and partition name (eg. C</dev/sda1> meaning the +The device and partition name (eg. F</dev/sda1> meaning the first partition on the first block device). When listing all libvirt domains (no I<-a> or I<-d> option given) this @@ -151,12 +151,12 @@ For example: virt-alignment-scan --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-alignment-scan --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 diff --git a/appliance/libguestfs-make-fixed-appliance.pod b/appliance/libguestfs-make-fixed-appliance.pod index 3242afc..9807f80 100644 --- a/appliance/libguestfs-make-fixed-appliance.pod +++ b/appliance/libguestfs-make-fixed-appliance.pod @@ -112,7 +112,7 @@ Display the version number and exit. Instead of creating the appliance in an output directory, create a compressed tarball of the appliance in the current directory called -C<appliance-I<VERSION>.tar.xz> where C<VERSION> is the version of +F<appliance-I<VERSION>.tar.xz> where C<VERSION> is the version of libguestfs. Using I<--xz> can take some time. If working normally, the tool is @@ -132,8 +132,8 @@ into a full appliance by running C<supermin --build>. However, a simpler "fixed appliance" can also be used. libguestfs detects this by looking for a directory on the path containing four -files called C<kernel>, C<initrd>, C<root> and C<README.fixed> (note -the C<README.fixed> file must be present as well). +files called F<kernel>, F<initrd>, F<root> and F<README.fixed> (note +the F<README.fixed> file must be present as well). If the fixed appliance is found, libguestfs skips supermin entirely and just runs qemu with the kernel, initrd and root disk from the diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod index aa19ea2..41cda1a 100644 --- a/builder/virt-builder.pod +++ b/builder/virt-builder.pod @@ -77,7 +77,7 @@ The first time this runs it has to download the template over the network, but this gets cached (see L</CACHING>). The name of the output file is derived from the template name, so -above it will be C<fedora-20.img>. You can change the output filename +above it will be F<fedora-20.img>. You can change the output filename using the I<-o> option: virt-builder fedora-20 -o mydisk.img @@ -87,7 +87,7 @@ logical volumes. virt-builder fedora-20 --format qcow2 -As above, but write the output in qcow2 format to C<fedora-20.qcow2>. +As above, but write the output in qcow2 format to F<fedora-20.qcow2>. virt-builder fedora-20 --size 20G @@ -104,7 +104,7 @@ As above, but using an i386 template, if available. virt-builder fedora-20 --root-password file:/tmp/rootpw Create a Fedora 20 image. The root password is taken from the file -C</tmp/rootpw>. +F</tmp/rootpw>. Note if you I<don't> set I<--root-password> then the guest is given a I<random> root password. @@ -168,7 +168,7 @@ Or: --edit '/etc/yum.conf: s/gpgcheck=1/gpgcheck=0/' -which edits C</etc/yum.conf> inside the disk image (during disk image +which edits F</etc/yum.conf> inside the disk image (during disk image creation, long before boot). You can combine these options, and have multiple options of all types. @@ -220,7 +220,7 @@ C<FORMAT> is usually C<raw> or C<qcow2>. Use C<raw> for ISOs. I<--cache> DIR sets the directory to use/check for cached template files. If not set, defaults to either -C<$XDG_CACHE_HOME/virt-builder/> or C<$HOME/.cache/virt-builder/>. +F<$XDG_CACHE_HOME/virt-builder/> or F<$HOME/.cache/virt-builder/>. I<--no-cache> disables template caching. @@ -295,7 +295,7 @@ specify it by using the I<--format> option. In the case where the guest contains multiple kernels, the one with the highest version number is chosen. To extract arbitrary kernels from the disk image, see L<guestfish(1)>. To extract the entire -C</boot> directory of a guest, see L<virt-copy-out(1)>. +F</boot> directory of a guest, see L<virt-copy-out(1)>. =item B<--gpg> GPG @@ -436,7 +436,7 @@ the install). =item B<--output> filename -Write the output to C<filename>. If you don't specify this option, +Write the output to F<filename>. If you don't specify this option, then the output filename is generated by taking the C<os-version> string and adding C<.img> (for raw format) or C<.qcow2> (for qcow2 format). @@ -680,7 +680,7 @@ See L<localectl(1)> and L<https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-…> for more details. -=head3 Keyboard layout using C</etc/sysconfig/keyboard> +=head3 Keyboard layout using F</etc/sysconfig/keyboard> For RHEL E<le> 6, Fedora E<le> 18 and similar, upload or modify the keyboard configuration file using the I<--upload>, I<--write> or @@ -693,7 +693,7 @@ The format of this file can be found documented in many places online. =head3 Keyboard layout with Debian-derived distros -For Debian-derived distros using C</etc/default/keyboard>, upload or +For Debian-derived distros using F</etc/default/keyboard>, upload or modify the keyboard file using the I<--upload>, I<--write> or I<--edit> options. For example: @@ -757,17 +757,17 @@ logged in one of the following locations: =over 4 -=item C</tmp/builder.log> +=item F</tmp/builder.log> On Linux, BSD and other guests. -=item C<C:\Temp\builder.log> +=item F<C:\Temp\builder.log> On Windows, DOS guests. -=item C</builder.log> +=item F</builder.log> -If C</tmp> or C<C:\Temp> is missing. +If F</tmp> or F<C:\Temp> is missing. =back @@ -781,7 +781,7 @@ the guest, so they can login without supplying a password. The C<SELECTOR> part of the option value is optional; in this case, I<--ssh-inject> C<USER> means that we look in the I<current> -user's C<~/.ssh> directory to find the default public ID file. That +user's F<~/.ssh> directory to find the default public ID file. That key is uploaded. "default public ID" is the I<default_ID_file> file described in L<ssh-copy-id(1)>. @@ -791,7 +791,7 @@ If specified, the C<SELECTOR> can be in one of the following formats: =item B<--ssh-inject> USER:file:FILENAME -Read the ssh key from C<FILENAME>. C<FILENAME> is usually a I<.pub> +Read the ssh key from F<FILENAME>. F<FILENAME> is usually a I<.pub> file. =item B<--ssh-inject> USER:string:KEY_STRING @@ -801,8 +801,8 @@ string like I<ssh-rsa AAAA.... user@localhost>. =back -In any case, the C<~USER/.ssh> directory and the -C<~USER/.ssh/authorized_keys> file will be created if not existing +In any case, the F<~USER/.ssh> directory and the +F<~USER/.ssh/authorized_keys> file will be created if not existing already. =head2 FIRST BOOT SCRIPTS @@ -1013,7 +1013,7 @@ Run L<virt-rescue(1)> on the disk image: virt-rescue -a disk.img This gives you a rescue shell. You can mount the filesystems from the -disk image on C</sysroot> and examine them using ordinary Linux +disk image on F</sysroot> and examine them using ordinary Linux commands. You can also chroot into the guest to reinstall the bootloader. The virt-rescue man page has a lot more information and examples. @@ -1061,12 +1061,12 @@ with the I<.conf> extension and located in the following paths: =item * $XDG_CONFIG_HOME/virt-builder/repos.d/ (C<$XDG_CONFIG_HOME> is -C<$HOME/.config> if not set). +F<$HOME/.config> if not set). =item * $XDG_CONFIG_DIRS/virt-builder/repos.d/ (where C<$XDG_CONFIG_DIRS> -means any of the directories in that environment variable, or just C</etc/xdg> +means any of the directories in that environment variable, or just F</etc/xdg> if not set) =back @@ -1218,7 +1218,7 @@ using the following command: gpg --clearsign --armor index -This will create the final file called C<index.asc> which can be +This will create the final file called F<index.asc> which can be uploaded to the server (and is the I<uri=..> URL). As noted above, signing the index file is optional, but recommended. @@ -1420,7 +1420,7 @@ A tool called L<virt-index-validate(1)> is available to validate the index file to ensure it is correct. Note that the parser and tool can work on either the signed or -unsigned index file (ie. C<index> or C<index.asc>). +unsigned index file (ie. F<index> or F<index.asc>). The index is always encoded in UTF-8. @@ -1431,8 +1431,8 @@ The index is always encoded in UTF-8. Since the templates are usually very large, downloaded templates are cached in the user's home directory. -The location of the cache is C<$XDG_CACHE_HOME/virt-builder/> or -C<$HOME/.cache/virt-builder>. +The location of the cache is F<$XDG_CACHE_HOME/virt-builder/> or +F<$HOME/.cache/virt-builder>. You can print out information about the cache directory, including which guests are currently cached, by doing: @@ -1494,7 +1494,7 @@ To install a Fedora guest using a local mirror: =head4 Using a local mirror with Debian Assuming that you are using C<apt-proxy> to mirror the repository, you -should create a new C<sources.list> file to point to your proxy (see +should create a new F<sources.list> file to point to your proxy (see L<https://help.ubuntu.com/community/AptProxy>) and then do: virt-builder debian-7 \ @@ -1664,9 +1664,9 @@ SELinux labels correctly in the disk image. Sometimes fixfiles is not possible during installation, in which case this option falls back on: -=item Touching C</.autorelabel> +=item Touching F</.autorelabel> -Guest templates may already contain a file called C</.autorelabel>, or +Guest templates may already contain a file called F</.autorelabel>, or it is touched if I<--selinux-relabel> cannot run fixfiles. For guests that use SELinux, this causes fixfiles to run at first @@ -1727,13 +1727,13 @@ This can point to the directory containing data files used for Windows firstboot installation. Normally you do not need to set this. If not set, a compiled-in -default will be used (something like C</usr/share/virt-tools>). +default will be used (something like F</usr/share/virt-tools>). This directory may contain the following files: =over 4 -=item C<rhsrvany.exe> +=item F<rhsrvany.exe> This is the RHSrvAny Windows binary, used to install a "firstboot" script in Windows guests. It is required if you intend to use the diff --git a/builder/virt-index-validate.pod b/builder/virt-index-validate.pod index d48a93a..7a033e3 100644 --- a/builder/virt-index-validate.pod +++ b/builder/virt-index-validate.pod @@ -13,7 +13,7 @@ that it knows how to use. This index file has a specific format which virt-index-validate knows how to validate. Note that virt-index-validate can validate either the signed or -unsigned index file (ie. either C<index> or C<index.asc>). It can +unsigned index file (ie. either F<index> or F<index.asc>). It can only validate a local file, not a URL. =head1 OPTIONS diff --git a/cat/virt-cat.pod b/cat/virt-cat.pod index da9bb9b..acd43e0 100644 --- a/cat/virt-cat.pod +++ b/cat/virt-cat.pod @@ -29,7 +29,7 @@ L<guestfish(1)> tool (see L</USING GUESTFISH> below). =head1 EXAMPLES -Display C</etc/fstab> file from inside the libvirt VM called +Display F</etc/fstab> file from inside the libvirt VM called C<mydomain>: virt-cat -d mydomain /etc/fstab @@ -110,12 +110,12 @@ For example: virt-cat --format=raw -a disk.img file -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-cat --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>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -124,7 +124,7 @@ security problem with malicious guests (CVE-2010-3851). =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-m dev[:mountpoint[:options[:fstype]]]> @@ -132,7 +132,7 @@ to try to read passphrases from the user by opening C</dev/tty>. Mount the named partition or logical volume on the given mountpoint. -If the mountpoint is omitted, it defaults to C</>. +If the mountpoint is omitted, it defaults to F</>. Specifying any mountpoint disables the inspection of the guest and the mount of its root and all of its mountpoints, so make sure @@ -205,7 +205,7 @@ journal. =head1 WINDOWS PATHS C<virt-cat> has a limited ability to understand Windows drive letters -and paths (eg. C<E:\foo\bar.txt>). +and paths (eg. F<E:\foo\bar.txt>). If and only if the guest is running Windows then: @@ -262,7 +262,7 @@ file from a disk image directly, use: guestfish --ro -a disk.img -m /dev/sda1 download file - -where C<disk.img> is the disk image, C</dev/sda1> is the filesystem +where F<disk.img> is the disk image, F</dev/sda1> is the filesystem within the disk image, and C<file> is the full path to the file. =head1 EXIT STATUS diff --git a/cat/virt-filesystems.pod b/cat/virt-filesystems.pod index 00f15dc..fd8e18d 100644 --- a/cat/virt-filesystems.pod +++ b/cat/virt-filesystems.pod @@ -64,7 +64,7 @@ I<--physical-volumes>, I<--block-devices> to list those items. You can use these options in combination as well (if you want a combination including filesystems, you have to add I<--filesystems>). -Notice that some items fall into several categories (eg. C</dev/sda1> +Notice that some items fall into several categories (eg. F</dev/sda1> might be both a partition and a filesystem). These items are listed several times. To get a list which includes absolutely everything that virt-filesystems knows about, use the I<--all> option. @@ -184,12 +184,12 @@ For example: virt-filesystems --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-filesystems --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -204,7 +204,7 @@ In I<--long> mode, display sizes in human-readable format. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-l> @@ -300,7 +300,7 @@ in future versions of this tool. The filesystem, partition, block device or LVM name. For device and partition names these are displayed as canonical -libguestfs names, so that for example C</dev/sda2> is the second +libguestfs names, so that for example F</dev/sda2> is the second partition on the first device. If the I<--long> option is B<not> specified, then only the name column diff --git a/cat/virt-log.pod b/cat/virt-log.pod index c258cdc..096fcf3 100644 --- a/cat/virt-log.pod +++ b/cat/virt-log.pod @@ -14,7 +14,7 @@ C<virt-log> is a command line tool to display the log files from the named virtual machine (or disk image). This tool understands and displays both plain text log files -(eg. C</var/log/messages>) and binary formats such as the systemd +(eg. F</var/log/messages>) and binary formats such as the systemd journal. To display other types of files, use L<virt-cat(1)>. To copy files @@ -93,12 +93,12 @@ For example: virt-log --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-log --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -107,7 +107,7 @@ security problem with malicious guests (CVE-2010-3851). =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-v> diff --git a/cat/virt-ls.pod b/cat/virt-ls.pod index aa7919d..e9a226d 100644 --- a/cat/virt-ls.pod +++ b/cat/virt-ls.pod @@ -332,12 +332,12 @@ For example: virt-ls --format=raw -a disk.img /dir -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-ls --format=raw -a disk.img --format -a another.img /dir -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -355,7 +355,7 @@ L</RECURSIVE LONG LISTING> above. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-m dev[:mountpoint[:options[:fstype]]]> @@ -363,7 +363,7 @@ to try to read passphrases from the user by opening C</dev/tty>. Mount the named partition or logical volume on the given mountpoint. -If the mountpoint is omitted, it defaults to C</>. +If the mountpoint is omitted, it defaults to F</>. Specifying any mountpoint disables the inspection of the guest and the mount of its root and all of its mountpoints, so make sure diff --git a/customize/virt-customize.pod b/customize/virt-customize.pod index dc64bf9..838e40c 100644 --- a/customize/virt-customize.pod +++ b/customize/virt-customize.pod @@ -106,12 +106,12 @@ For example: virt-customize --format raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-customize --format raw -a disk.img --format auto -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -231,13 +231,13 @@ This can point to the directory containing data files used for Windows firstboot installation. Normally you do not need to set this. If not set, a compiled-in -default will be used (something like C</usr/share/virt-tools>). +default will be used (something like F</usr/share/virt-tools>). This directory may contain the following files: =over 4 -=item C<rhsrvany.exe> +=item F<rhsrvany.exe> This is the RHSrvAny Windows binary, used to install a "firstboot" script in Windows guests. It is required if you intend to use the diff --git a/daemon/guestfsd.pod b/daemon/guestfsd.pod index 0f9c8b0..1ed31a9 100644 --- a/daemon/guestfsd.pod +++ b/daemon/guestfsd.pod @@ -17,13 +17,13 @@ does in both the libguestfs appliance and when using libguestfs live. For the architecture of the libguestfs appliance, see L<guestfs(3)/ARCHITECTURE>. -After the appliance boots, the C</init> script in the appliance starts +After the appliance boots, the F</init> script in the appliance starts C<guestfsd> with no arguments. C<guestfsd> opens the virtio-serial port on a known path (see L</FILES>). It initiates the protocol (see L<guestfs(3)/COMMUNICATION PROTOCOL>) and processes requests one at a time from the library until the appliance is destroyed. -Filesystems are mounted under C</sysroot> and all filesystem +Filesystems are mounted under F</sysroot> and all filesystem operations happen relative to this directory. =head2 LIBGUESTFS LIVE @@ -32,7 +32,7 @@ In the libguestfs live case, C<guestfsd -r> is started from the rc-scripts, systemd, etc. The C<-r> option causes the daemon to operate on the root filesystem -instead of C</sysroot>. +instead of F</sysroot>. Currently (because of limitations in virtio-serial) only one client can connect at a time, and C<guestfsd> must be restarted after each @@ -52,8 +52,8 @@ Display brief help. =item B<-r> -Set the root filesystem to be C</> (instead of the default which is -C</sysroot>). Also do not unmount filesystems when the daemon exits. +Set the root filesystem to be F</> (instead of the default which is +F</sysroot>). Also do not unmount filesystems when the daemon exits. This option is used to enable libguestfs live. @@ -77,11 +77,11 @@ error. =over 4 -=item C</dev/virtio-ports/org.libguestfs.channel.0> +=item F</dev/virtio-ports/org.libguestfs.channel.0> The virtio serial port which C<guestfsd> connects to. -=item C</proc/cmdline> +=item F</proc/cmdline> The Linux command line is parsed to discover C<guestfs_*> flags. The following flags are understood: @@ -99,7 +99,7 @@ information. =item B<guestfs_channel=PATH> Set the path to the virtio-serial channel to something other than the -default (which is C</dev/virtio-ports/org.libguestfs.channel.0>). +default (which is F</dev/virtio-ports/org.libguestfs.channel.0>). This is used by the User-Mode Linux backend to use a regular emulated serial port instead of virtio-serial. diff --git a/df/virt-df.pod b/df/virt-df.pod index 331f6fc..3f7fc3f 100644 --- a/df/virt-df.pod +++ b/df/virt-df.pod @@ -52,7 +52,7 @@ output human-readable: F14x64:/dev/sda1 484M 66M 393M 14% F14x64:/dev/vg_f13x64/lv_root 7.4G 3.4G 4.0G 46% -Show disk usage for a disk image file called C<test.img>: +Show disk usage for a disk image file called F<test.img>: $ virt-df -a test1.img Filesystem 1K-blocks Used Available Use% @@ -129,12 +129,12 @@ For example: virt-df --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-df --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -212,7 +212,7 @@ Run this command: guestfish --ro -d GuestName -i statvfs / -(change C</> to see stats for other filesystems). +(change F</> to see stats for other filesystems). =item From inside the guest @@ -220,7 +220,7 @@ Run this command: python -c 'import os; s = os.statvfs ("/"); print s' -(change C</> to see stats for other filesystems). +(change F</> to see stats for other filesystems). =back diff --git a/diff/virt-diff.pod b/diff/virt-diff.pod index 22e0aa0..afab185 100644 --- a/diff/virt-diff.pod +++ b/diff/virt-diff.pod @@ -149,12 +149,12 @@ For example: virt-diff --format=raw -a disk.img [...] -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-diff --format=raw -a disk.img --format -a another.img [...] -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -169,7 +169,7 @@ Display file sizes in human-readable format. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<--times> diff --git a/edit/virt-edit.pod b/edit/virt-edit.pod index 537fee0..57b9142 100644 --- a/edit/virt-edit.pod +++ b/edit/virt-edit.pod @@ -148,12 +148,12 @@ For example: virt-edit --format=raw -a disk.img file -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<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>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -162,7 +162,7 @@ security problem with malicious guests (CVE-2010-3851). =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-m dev[:mountpoint[:options[:fstype]]]> @@ -170,7 +170,7 @@ to try to read passphrases from the user by opening C</dev/tty>. Mount the named partition or logical volume on the given mountpoint. -If the mountpoint is omitted, it defaults to C</>. +If the mountpoint is omitted, it defaults to F</>. Specifying any mountpoint disables the inspection of the guest and the mount of its root and all of its mountpoints, so make sure @@ -299,7 +299,7 @@ file): =head1 WINDOWS PATHS C<virt-edit> has a limited ability to understand Windows drive letters -and paths (eg. C<E:\foo\bar.txt>). +and paths (eg. F<E:\foo\bar.txt>). If and only if the guest is running Windows then: @@ -345,7 +345,7 @@ 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 +where C<domname> is the name of the libvirt guest, and F</file> is the full path to the file. The command above uses libguestfs's guest inspection feature and so @@ -355,8 +355,8 @@ 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 +where F<disk.img> is the disk image, F</dev/sda1> is the filesystem +within the disk image to edit, and F</file> is the full path to the file. C<virt-edit> cannot create new files. Use the guestfish commands diff --git a/examples/guestfs-faq.pod b/examples/guestfs-faq.pod index 4862f65..af99d39 100644 --- a/examples/guestfs-faq.pod +++ b/examples/guestfs-faq.pod @@ -202,7 +202,7 @@ can access them. =item * -(Nasty) Edit C</etc/libvirt/qemu.conf> and change the C<user> setting. +(Nasty) Edit F</etc/libvirt/qemu.conf> and change the C<user> setting. =back @@ -223,15 +223,15 @@ appliance: [...followed by a lot of debug output...] This is a complicated bug related to L<supermin(1)> appliances. The -appliance is constructed by copying files like C</bin/bash> and many +appliance is constructed by copying files like F</bin/bash> and many libraries from the host. The file C<hostfiles> lists the files that should be copied from the host into the appliance. If some files don't exist on the host then they are missed out, but if these files -are needed in order to (eg) run C</bin/bash> then you'll see the above +are needed in order to (eg) run F</bin/bash> then you'll see the above error. Diagnosing the problem involves studying the libraries needed by -C</bin/bash>, ie: +F</bin/bash>, ie: ldd /bin/bash @@ -240,7 +240,7 @@ the host filesystem, and with the debug output printed in the error message. Once you've worked out which file is missing, install that file using your package manager and try again. -You should also check that files like C</init> and C</bin/bash> (in +You should also check that files like F</init> and F</bin/bash> (in the appliance) are executable. The debug output shows file modes. =head1 DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS @@ -468,7 +468,7 @@ There is one known shortcoming: L<virt-rescue(1)> will not use libvirt currently get the benefit of sVirt protection when using virt-rescue. You can check if sVirt is being used by enabling libvirtd logging (see -C</etc/libvirt/libvirtd.log>), killing and restarting libvirtd, and +F</etc/libvirt/libvirtd.log>), killing and restarting libvirtd, and checking the log files for S<"Setting SELinux context on ..."> messages. In theory sVirt should support AppArmor, but we have not tried it. It @@ -604,7 +604,7 @@ libguestfs caches a large-ish appliance in: /var/tmp/.guestfs-<UID> If the environment variable C<TMPDIR> is defined, then -C<$TMPDIR/.guestfs-E<lt>UIDE<gt>> is used instead. +F<$TMPDIR/.guestfs-E<lt>UIDE<gt>> is used instead. It is safe to delete this directory when you are not using libguestfs. @@ -712,7 +712,7 @@ but in the meantime you have three options: =item 1. If the guest is hosted on a live, reachable ESX server, then locate -and download the disk image called I<somename>C<-flat.vmdk>. Despite +and download the disk image called F<I<somename>-flat.vmdk>. Despite the name, this is a raw disk image, and can be opened by anything. If you have a recent enough version of qemu and libguestfs, then you @@ -960,7 +960,7 @@ calling launch. Use the event API. For examples, see: L<guestfs(3)/SETTING CALLBACKS TO HANDLE EVENTS> and the -C<examples/debug-logging.c> program in the libguestfs sources. +F<examples/debug-logging.c> program in the libguestfs sources. =head2 Digging deeper into the appliance boot process. @@ -976,17 +976,17 @@ of L<libguestfs-test-tool(1)>. =head2 Debugging libvirt If you are using the libvirt backend, and libvirt is failing, then you -can enable debugging by editing C</etc/libvirt/libvirtd.conf>. +can enable debugging by editing F</etc/libvirt/libvirtd.conf>. If you are running as non-root, then you have to edit a different -file. Create C<~/.config/libvirt/libvirtd.conf> containing: +file. Create F<~/.config/libvirt/libvirtd.conf> containing: log_level=1 log_outputs="1:file:/tmp/libvirtd.log" Kill any session (non-root) libvirtd that is running, and next time you run the libguestfs command, you should see a large amount of -useful debugging information from libvirtd in C</tmp/libvirtd.log> +useful debugging information from libvirtd in F</tmp/libvirtd.log> =head1 DESIGN/INTERNALS OF LIBGUESTFS @@ -1096,7 +1096,7 @@ What you have to do is to create a point-in-time snapshot. If it's a logical volume, use an LVM2 snapshot. If the filesystem is located inside something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and then run the fsck on the snapshot. In practice you don't need to use -libguestfs for this -- just run C</sbin/fsck> directly. +libguestfs for this -- just run F</sbin/fsck> directly. Creating point-in-time snapshots of host devices and files is outside the scope of libguestfs, although libguestfs can operate on them once @@ -1179,7 +1179,7 @@ Users expect some tools (like L<virt-cat(1)>) to work with VM paths: virt-cat fedora.img /var/log/messages -How does virt-cat know that C</var> is a separate partition? The +How does virt-cat know that F</var> is a separate partition? The trick is that virt-cat performs inspection on the disk image, and uses that to translate the path correctly. diff --git a/examples/guestfs-performance.pod b/examples/guestfs-performance.pod index abddcc8..7cf10aa 100644 --- a/examples/guestfs-performance.pod +++ b/examples/guestfs-performance.pod @@ -34,7 +34,7 @@ runs, so that you are measuring a typical "hot cache" case. This command starts up the libguestfs appliance on a null disk, and then immediately shuts it down. The first time you run the command, it will create an appliance and cache it (usually under -C</var/tmp/.guestfs-*>). Subsequent runs should reuse the cached +F</var/tmp/.guestfs-*>). Subsequent runs should reuse the cached appliance. =head3 Expected results @@ -70,7 +70,7 @@ L<guestfs(3)/INSPECTION>), mounts the guest's disks, then discards all these results and shuts down. The first time you run the command, it will create an appliance and -cache it (usually under C</var/tmp/.guestfs-*>). Subsequent runs +cache it (usually under F</var/tmp/.guestfs-*>). Subsequent runs should reuse the cached appliance. =head3 Expected results @@ -83,7 +83,7 @@ seconds). =head1 UNDERSTANDING THE APPLIANCE AND WHEN IT IS BUILT/CACHED The first time you use libguestfs, it will build and cache an -appliance. This is usually in C</var/tmp/.guestfs-*>, unless you have +appliance. This is usually in F</var/tmp/.guestfs-*>, unless you have set C<$TMPDIR> or C<$LIBGUESTFS_CACHEDIR> in which case it will be under that temporary directory. @@ -115,7 +115,7 @@ host will cause a one time rebuild of the appliance. =item * -C</var/tmp> (or C<$TMPDIR>, C<$LIBGUESTFS_CACHEDIR>) should be on a +F</var/tmp> (or C<$TMPDIR>, C<$LIBGUESTFS_CACHEDIR>) should be on a fast disk, and have plenty of space for the appliance. =back @@ -131,8 +131,8 @@ To build the appliance, run the command: replacing C<E<lt>directoryE<gt>> with the name of a directory where the appliance will be stored (normally you would name a subdirectory, -for example: C</usr/local/lib/guestfs/appliance> or -C</dev/shm/appliance>). +for example: F</usr/local/lib/guestfs/appliance> or +F</dev/shm/appliance>). Then set C<$LIBGUESTFS_PATH> (and ensure this environment variable is set in your libguestfs program), or modify your program so it calls @@ -151,7 +151,7 @@ L<libguestfs-make-fixed-appliance(1)>). In our testing we did not find that using a fixed appliance gave any measurable performance benefit, even when the appliance was located in -memory (ie. on C</dev/shm>). However there are two points to +memory (ie. on F</dev/shm>). However there are two points to consider: =over 4 @@ -399,7 +399,7 @@ L<http://rwmj.wordpress.com/2013/08/14/performance-of-user-mode-linux-as-a-li… =head2 ENSURE HARDWARE VIRTUALIZATION IS AVAILABLE -Use C</proc/cpuinfo> and this page: +Use F</proc/cpuinfo> and this page: http://virt-tools.org/learning/check-hardware-virt/ @@ -414,7 +414,7 @@ no substitute for running libguestfs on baremetal. =head2 ENSURE KVM IS AVAILABLE Ensure that KVM is enabled and available to the user that will run -libguestfs. It should be safe to set 0666 permissions on C</dev/kvm> +libguestfs. It should be safe to set 0666 permissions on F</dev/kvm> and most distributions now do this. =head2 PROCESSORS TO AVOID @@ -449,7 +449,7 @@ The timestamps are seconds (incrementally since the previous line). You can use SystemTap (L<stap(1)>) to get detailed timings from libguestfs programs. -Save the following script as C<time.stap>: +Save the following script as F<time.stap>: global last; diff --git a/examples/guestfs-recipes.pod b/examples/guestfs-recipes.pod index 2b253e6..2491c25 100644 --- a/examples/guestfs-recipes.pod +++ b/examples/guestfs-recipes.pod @@ -49,7 +49,7 @@ To checksum a whole device, or a partition, LV etc within a disk image: Replace C<md5> with the type of checksum you want. See L<guestfs(3)/guestfs_checksum_device> for a list of supported types. -C</dev/sda1> means "the first partition". You could use C</dev/sda> +F</dev/sda1> means "the first partition". You could use F</dev/sda> to checksum the whole disk image, or the name of a logical volume or RAID device. @@ -72,11 +72,11 @@ For more details, see: L<virt-sysprep(1)/COPYING AND CLONING>. =head1 Convert a CD-ROM / DVD / ISO to a tarball -This converts input C<cd.iso> to output C<cd.tar.gz>: +This converts input F<cd.iso> to output F<cd.tar.gz>: guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz -To export just a subdirectory, eg. C</files>, do: +To export just a subdirectory, eg. F</files>, do: guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz @@ -251,7 +251,7 @@ like this: =head1 Export any directory from a VM -To export C</home> from a VM into a local directory use +To export F</home> from a VM into a local directory use L<virt-copy-out(1)>: virt-copy-out -d Guest /home . @@ -332,11 +332,11 @@ getting the last assigned DHCP address of a virtual machine. L<https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-fro…> In the libguestfs source examples directory you will find the latest -version of the C<virt-dhcp-address.c> program. +version of the F<virt-dhcp-address.c> program. =head1 Get the operating system product name string -Save the following script into a file called C<product-name.sh>: +Save the following script into a file called F<product-name.sh>: #!/bin/sh - set -e @@ -480,12 +480,12 @@ SYSLINUX bootloader using either the guestfish commands C<syslinux> (for FAT-based guests) or C<extlinux> (for ext2/3/4 and btrfs-based guests). -This guide assumes a Linux guest where C</dev/sda1> is C</boot>, -C</boot/vmlinuz> is the guest kernel, and C</dev/sda3> is the root +This guide assumes a Linux guest where F</dev/sda1> is F</boot>, +F</boot/vmlinuz> is the guest kernel, and F</dev/sda3> is the root partition. For a Windows guest you would need a FAT-formatted boot partition and you would need to use the C<syslinux> command instead. -Create a C<syslinux.cfg> configuration file. You should check the +Create a F<syslinux.cfg> configuration file. You should check the SYSLINUX documentation at L<http://www.syslinux.org> but it may look something like this: @@ -497,7 +497,7 @@ something like this: APPEND ro root=/dev/sda3 Locate the syslinux master boot record (a file called something like -C</usr/share/syslinux/mbr.bin>). +F</usr/share/syslinux/mbr.bin>). guestfish -a disk.img -i # Upload the master boot record and configuration file: @@ -515,7 +515,7 @@ L<http://rwmj.wordpress.com/2013/04/04/new-in-libguestfs-use-syslinux-or-extl… =head1 List applications installed in a VM -Save the following to a file C<list-apps.sh>: +Save the following to a file F<list-apps.sh>: #!/bin/sh - set -e diff --git a/examples/guestfs-testing.pod b/examples/guestfs-testing.pod index 2186ed3..2528604 100644 --- a/examples/guestfs-testing.pod +++ b/examples/guestfs-testing.pod @@ -170,7 +170,7 @@ into a guest or disk image. virt-copy-in -d Guest /etc /tmp -This should copy local directory C</etc> to C</tmp/etc> in the guest +This should copy local directory F</etc> to F</tmp/etc> in the guest (recursively). If you boot the guest, can you see all of the copied files and directories? @@ -187,7 +187,7 @@ out of a guest or disk image. Note the final space and period in the command is not a typo. -This should copy C</home> from the guest into the current directory. +This should copy F</home> from the guest into the current directory. =head2 Run virt-df. @@ -349,7 +349,7 @@ Using L<virt-sparsify(1)>, make a disk image more sparse: virt-sparsify /path/to/olddisk.img newdisk.img -Is C<newdisk.img> still bootable after sparsifying? Is the resulting +Is F<newdisk.img> still bootable after sparsifying? Is the resulting disk image smaller (use C<du> to check)? =head2 B<*> "sysprep" a B<shut off> Linux guest. diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 20c3544..8d6e0fa 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -64,7 +64,7 @@ L<virt-rescue(1)> command. =head2 From shell scripts -Create a new C</etc/motd> file in a guest or disk image: +Create a new F</etc/motd> file in a guest or disk image: guestfish <<_EOF_ add disk.img @@ -89,13 +89,13 @@ List all the filesystems in a disk image: =head2 On one command line -Update C</etc/resolv.conf> in a guest: +Update F</etc/resolv.conf> in a guest: guestfish \ add disk.img : run : mount /dev/vg_guest/lv_root / : \ write /etc/resolv.conf "nameserver 1.2.3.4" -Edit C</boot/grub/grub.conf> interactively: +Edit F</boot/grub/grub.conf> interactively: guestfish --rw --add disk.img \ --mount /dev/vg_guest/lv_root \ @@ -111,7 +111,7 @@ disks from a virtual machine: guestfish --ro -d libvirt-domain -i cat /etc/group -Another way to edit C</boot/grub/grub.conf> interactively is: +Another way to edit F</boot/grub/grub.conf> interactively is: guestfish --rw -a disk.img -i edit /boot/grub/grub.conf @@ -127,7 +127,7 @@ Create a 100MB disk containing an ext2-formatted partition: =head2 Start with a prepared disk -An alternate way to create a 100MB disk called C<test1.img> containing +An alternate way to create a 100MB disk called F<test1.img> containing a single ext2-formatted partition: guestfish -N fs @@ -244,12 +244,12 @@ For example: guestfish --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. guestfish --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -290,7 +290,7 @@ were found. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<--listen> @@ -308,9 +308,9 @@ Connect to a live virtual machine. Mount the named partition or logical volume on the given mountpoint. -If the mountpoint is omitted, it defaults to C</>. +If the mountpoint is omitted, it defaults to F</>. -You have to mount something on C</> before most commands will work. +You have to mount something on F</> before most commands will work. If any I<-m> or I<--mount> options are given, the guest is automatically launched. @@ -736,7 +736,7 @@ following will not do what you expect: rm-rf /home/* -Assuming you don't have a directory called literally C</home/*> +Assuming you don't have a directory called literally F</home/*> then the above command will return an error. To perform wildcard expansion, use the C<glob> command. @@ -770,15 +770,15 @@ Blank lines are also ignored. =head1 RUNNING COMMANDS LOCALLY Any line which starts with a I<!> character is treated as a command -sent to the local shell (C</bin/sh> or whatever L<system(3)> uses). +sent to the local shell (F</bin/sh> or whatever L<system(3)> uses). For example: !mkdir local tgz-out /remote local/remote-data.tar.gz will create a directory C<local> on the host, and then export -the contents of C</remote> on the mounted filesystem to -C<local/remote-data.tar.gz>. (See C<tgz-out>). +the contents of F</remote> on the mounted filesystem to +F<local/remote-data.tar.gz>. (See C<tgz-out>). To change the local directory, use the C<lcd> command. C<!cd> will have no effect, due to the way that subprocesses work in Unix. @@ -793,13 +793,13 @@ Thus you can use shell script to construct arbitrary guestfish commands which are then parsed by guestfish. For example it is tedious to create a sequence of files -(eg. C</foo.1> through C</foo.100>) using guestfish commands +(eg. F</foo.1> through F</foo.100>) using guestfish commands alone. However this is simple if we use a shell script to create the guestfish commands for us: <! for n in `seq 1 100`; do echo write /foo.$n $n; done -or with names like C</foo.001>: +or with names like F</foo.001>: <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done @@ -863,7 +863,7 @@ Identify encrypted block devices and partitions using L</vfs-type>: crypto_LUKS Then open those devices using L</luks-open>. This creates a -device-mapper device called C</dev/mapper/luksdev>. +device-mapper device called F</dev/mapper/luksdev>. ><fs> luks-open /dev/sda2 luksdev Enter key or passphrase ("key"): <enter the passphrase> @@ -899,7 +899,7 @@ The parameter is rewritten "behind the scenes" by looking up the position where the drive is mounted, prepending that to the path, changing all backslash characters to forward slash, then resolving the result using L</case-sensitive-path>. For example if the E: drive -was mounted on C</e> then the parameter might be rewritten like this: +was mounted on F</e> then the parameter might be rewritten like this: win:e:\foo\bar => /e/FOO/bar @@ -913,7 +913,7 @@ special filename C<-> to mean "from stdin" or "to stdout". For example: upload - /foo -reads stdin and creates from that a file C</foo> in the disk image, +reads stdin and creates from that a file F</foo> in the disk image, and: tar-out /etc - | tar tf - @@ -996,7 +996,7 @@ I<--csh> option: =head2 REMOTE CONTROL DETAILS Remote control happens over a Unix domain socket called -C</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective +F</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective user ID of the process, and C<$PID> is the process ID of the server. Guestfish client and server versions must match exactly. @@ -1074,7 +1074,7 @@ make for you to save typing. This is particularly useful for testing purposes. This option is used instead of the I<-a> option, and like I<-a> can appear multiple times (and can be mixed with I<-a>). -The new disk is called C<test1.img> for the first I<-N>, C<test2.img> +The new disk is called F<test1.img> for the first I<-N>, F<test2.img> for the second and so on. Existing files in the current directory are I<overwritten>. You can use a different filename by specifying C<filename=> before the type (see examples below). @@ -1097,7 +1097,7 @@ is automatically launched. =head2 EXAMPLES Create a 100MB disk with an ext4-formatted partition, called -C<test1.img> in the current directory: +F<test1.img> in the current directory: guestfish -N fs:ext4 @@ -1109,8 +1109,8 @@ Create a blank 200MB disk: guestfish -N disk:200M -Create a blank 200MB disk called C<blankdisk.img> (instead of -C<test1.img>): +Create a blank 200MB disk called F<blankdisk.img> (instead of +F<test1.img>): guestfish -N blankdisk.img=disk:200M @@ -1138,7 +1138,7 @@ The possible I<-a URI> formats are described below. =head2 B<-a file:///path/to/disk.img> -Add the local disk image (or device) called C<disk.img>. +Add the local disk image (or device) called F<disk.img>. =head2 B<-a ftp://[user@]example.com[:port]/disk.img> @@ -1454,7 +1454,7 @@ using a supermin appliance. The appliance is cached and shared between all handles which have the same effective user ID. If C<LIBGUESTFS_CACHEDIR> is not set, then C<TMPDIR> is used. If -C<TMPDIR> is not set, then C</var/tmp> is used. +C<TMPDIR> is not set, then F</var/tmp> is used. See also L</LIBGUESTFS_TMPDIR>, L</set-cachedir>. @@ -1491,7 +1491,7 @@ The location where libguestfs will store temporary files used by each handle. If C<LIBGUESTFS_TMPDIR> is not set, then C<TMPDIR> is used. If -C<TMPDIR> is not set, then C</tmp> is used. +C<TMPDIR> is not set, then F</tmp> is used. See also L</LIBGUESTFS_CACHEDIR>, L</set-tmpdir>. @@ -1585,8 +1585,8 @@ to make guestfish case sensitive. =item test2.img (etc) When using the I<-N> or I<--new> option, the prepared disk or -filesystem will be created in the file C<test1.img> in the current -directory. The second use of I<-N> will use C<test2.img> and so on. +filesystem will be created in the file F<test1.img> in the current +directory. The second use of I<-N> will use F<test2.img> and so on. Any existing file with the same name will be overwritten. You can use a different filename by using the C<filename=> prefix. diff --git a/fish/libguestfs-tools.conf.pod b/fish/libguestfs-tools.conf.pod index d3555ec..bae3f30 100644 --- a/fish/libguestfs-tools.conf.pod +++ b/fish/libguestfs-tools.conf.pod @@ -14,7 +14,7 @@ libguestfs-tools.conf - configuration file for guestfish, guestmount, virt-rescu =head1 DESCRIPTION -C<libguestfs-tools.conf> (or C<$HOME/.libguestfs-tools.rc>) changes the +F<libguestfs-tools.conf> (or F<$HOME/.libguestfs-tools.rc>) changes the defaults for the following programs only: =over 4 @@ -60,7 +60,7 @@ The order of the configuration files being read is, by importance: =item * $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf (C<$XDG_CONFIG_HOME> is -C<$HOME/.config> if not set). +F<$HOME/.config> if not set). =item * @@ -69,7 +69,7 @@ $HOME/.libguestfs-tools.rc =item * $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf (where C<$XDG_CONFIG_DIRS> -means any of the directories in that environment variable, or just C</etc/xdg> +means any of the directories in that environment variable, or just F</etc/xdg> if not set) =item * @@ -80,9 +80,9 @@ if not set) This means local users can override the system configuration by copying the configuration file (or creating it anew) into -C<$XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf>. +F<$XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf>. -C</etc/libguestfs-tools.conf> and C<$HOME/.libguestfs-tools.rc> are the old +F</etc/libguestfs-tools.conf> and F<$HOME/.libguestfs-tools.rc> are the old non-XDG paths which are read for compatibility. =head1 SEE ALSO diff --git a/fish/virt-copy-in.pod b/fish/virt-copy-in.pod index 3891ce5..37d96df 100644 --- a/fish/virt-copy-in.pod +++ b/fish/virt-copy-in.pod @@ -22,11 +22,11 @@ a virtual machine disk image or named libvirt domain. You can give one of more filenames and directories on the command line. Directories are copied in recursively. The final parameter must be the destination directory in the disk image which must be an -absolute path starting with a C</> character. +absolute path starting with a F</> character. =head1 EXAMPLES -Update C</etc/resolv.conf> in a guest: +Update F</etc/resolv.conf> in a guest: virt-copy-in -d MyGuest resolv.conf /etc diff --git a/format/virt-format.pod b/format/virt-format.pod index caec411..2f83203 100644 --- a/format/virt-format.pod +++ b/format/virt-format.pod @@ -25,7 +25,7 @@ or this: virt-format -a /dev/VG/LV -C<disk.qcow> or C</dev/VG/LV> must exist already. B<Any data on these +F<disk.qcow> or F</dev/VG/LV> must exist already. B<Any data on these disks will be erased by these commands>. These commands will create a single empty partition covering the whole disk, with no filesystem inside it. @@ -101,12 +101,12 @@ For example: virt-format --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-format --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -118,13 +118,13 @@ Set the filesystem label. =item B<--lvm=/dev/I<VG>/I<LV>> -Create a Linux LVM2 logical volume called C</dev/I<VG>/I<LV>>. You +Create a Linux LVM2 logical volume called F</dev/I<VG>/I<LV>>. You can change the name of the volume group and logical volume. =item B<--lvm> Create a Linux LVM2 logical volume with the default name -(C</dev/VG/LV>). +(F</dev/VG/LV>). =item B<--lvm=none> diff --git a/fuse/guestmount.pod b/fuse/guestmount.pod index 0db5c6c..6dedf70 100644 --- a/fuse/guestmount.pod +++ b/fuse/guestmount.pod @@ -31,7 +31,7 @@ manual page, or by looking at the examples below. FUSE lets you mount filesystems as non-root. The mountpoint must be owned by you, and the filesystem will not be visible to any other users unless you make certain global configuration changes to -C</etc/fuse.conf>. To unmount the filesystem, use the +F</etc/fuse.conf>. To unmount the filesystem, use the L<guestunmount(1)> command. =head1 EXAMPLES @@ -252,7 +252,7 @@ mounted on the real virtual machine. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<--live> @@ -266,8 +266,8 @@ Connect to a live virtual machine. Mount the named partition or logical volume on the given mountpoint B<in the guest> (this has nothing to do with mountpoints in the host). -If the mountpoint is omitted, it defaults to C</>. You have to mount -something on C</>. +If the mountpoint is omitted, it defaults to F</>. You have to mount +something on F</>. The third (and rarely used) part of the mount parameter is the list of mount options used to mount the underlying filesystem. If this is not diff --git a/generator/actions.ml b/generator/actions.ml index 7252295..d5e5ccf 100644 --- a/generator/actions.ml +++ b/generator/actions.ml @@ -615,7 +615,7 @@ against. Note that because of dynamic linking this is not necessarily the version of libguestfs that you compiled against. You can compile the program, and then at runtime dynamically link -against a completely different C<libguestfs.so> library. +against a completely different F<libguestfs.so> library. This call was added in version C<1.0.58>. In previous versions of libguestfs there was no way to get the version @@ -830,7 +830,7 @@ to specify the QEMU interface emulation to use at run time." }; ]; shortdesc = "detect the architecture of a binary file"; longdesc = "\ -This detects the architecture of the binary C<filename>, +This detects the architecture of the binary F<filename>, and returns it if known. Currently defined architectures are: @@ -1234,23 +1234,23 @@ Please read L<guestfs(3)/INSPECTION> for more details." }; This returns a hash of where we think the filesystems associated with this operating system should be mounted. Callers should note that this is at best an educated guess -made by reading configuration files such as C</etc/fstab>. +made by reading configuration files such as F</etc/fstab>. I<In particular note> that this may return filesystems which are non-existent or not mountable and callers should be prepared to handle or ignore failures if they try to mount them. Each element in the returned hashtable has a key which -is the path of the mountpoint (eg. C</boot>) and a value +is the path of the mountpoint (eg. F</boot>) and a value which is the filesystem that would be mounted there -(eg. C</dev/sda1>). +(eg. F</dev/sda1>). Non-mounted devices such as swap devices are I<not> returned in this list. For operating systems like Windows which still use drive letters, this call will only return an entry for the first -drive \"mounted on\" C</>. For information about the +drive \"mounted on\" F</>. For information about the mapping of drive letters to partitions, see C<guestfs_inspect_get_drive_mappings>. @@ -1342,13 +1342,13 @@ not all belong to a single logical operating system fish_alias = ["add"]; shortdesc = "add an image to examine or modify"; longdesc = "\ -This function adds a disk image called C<filename> to the handle. -C<filename> may be a regular host file or a host device. +This function adds a disk image called F<filename> to the handle. +F<filename> may be a regular host file or a host device. When this function is called before C<guestfs_launch> (the usual case) then the first time you call this function, -the disk appears in the API as C</dev/sda>, the second time -as C</dev/sdb>, and so on. +the disk appears in the API as F</dev/sda>, the second time +as F</dev/sdb>, and so on. In libguestfs E<ge> 1.20 you can also call this function after launch (with some restrictions). This is called @@ -1362,9 +1362,9 @@ for whatever operations you want to perform (ie. read access if you just want to read the image or write access if you want to modify the image). -This call checks that C<filename> exists. +This call checks that F<filename> exists. -C<filename> may be the special string C<\"/dev/null\">. +F<filename> may be the special string C<\"/dev/null\">. See L<guestfs(3)/NULL DISKS>. The optional arguments are: @@ -1395,7 +1395,7 @@ deprecated C<guestfs_add_drive_with_if> call (q.v.) =item C<name> -The name the drive had in the original guest, e.g. C</dev/sdb>. +The name the drive had in the original guest, e.g. F</dev/sdb>. This is used as a hint to the guest inspection process if it is available. @@ -1403,8 +1403,8 @@ it is available. Give the disk a label. The label should be a unique, short string using I<only> ASCII characters C<[a-zA-Z]>. -As well as its usual name in the API (such as C</dev/sda>), -the drive will also be named C</dev/disk/guestfs/I<label>>. +As well as its usual name in the API (such as F</dev/sda>), +the drive will also be named F</dev/disk/guestfs/I<label>>. See L<guestfs(3)/DISK LABELS>. @@ -1419,7 +1419,7 @@ See also: L<guestfs(3)/REMOTE STORAGE>. =item C<protocol = \"file\"> -C<filename> is interpreted as a local file or device. +F<filename> is interpreted as a local file or device. This is the default if the optional protocol parameter is omitted. @@ -1504,7 +1504,7 @@ in one of the following formats: unix:/path/to/socket If the port number is omitted, then the standard port number -for the protocol is used (see C</etc/services>). +for the protocol is used (see F</etc/services>). =item C<username> @@ -1601,7 +1601,7 @@ The default is false. shortdesc = "get Windows systemroot of inspected operating system"; longdesc = "\ This returns the Windows systemroot of the inspected guest. -The systemroot is a directory path such as C</WINDOWS>. +The systemroot is a directory path such as F</WINDOWS>. This call assumes that the guest is Windows and that the systemroot could be determined by inspection. If this is not @@ -2192,7 +2192,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." }; shortdesc = "get drive letter mappings"; longdesc = "\ This call is useful for Windows which uses a primitive system -of assigning drive letters (like \"C:\") to partitions. +of assigning drive letters (like F<C:\\>) to partitions. This inspection API examines the Windows Registry to find out how disks/partitions are mapped to drive letters, and returns a hash table as in the example below: @@ -2233,7 +2233,7 @@ If it was not possible to get an icon this function returns a zero-length (non-NULL) buffer. I<Callers must check for this case>. Libguestfs will start by looking for a file called -C</etc/favicon.png> or C<C:\\etc\\favicon.png> +F</etc/favicon.png> or F<C:\\etc\\favicon.png> and if it has the correct format, the contents of this file will be returned. You can disable favicons by passing the optional C<favicon> boolean as false (default is true). @@ -2421,19 +2421,19 @@ returns them in a consistent format: =over 4 -=item C</dev/hdX> +=item F</dev/hdX> -=item C</dev/vdX> +=item F</dev/vdX> -These are returned as C</dev/sdX>. Note this works for device +These are returned as F</dev/sdX>. Note this works for device names and partition names. This is approximately the reverse of the algorithm described in L<guestfs(3)/BLOCK DEVICE NAMING>. -=item C</dev/mapper/VG-LV> +=item F</dev/mapper/VG-LV> -=item C</dev/dm-N> +=item F</dev/dm-N> -Converted to C</dev/VG/LV> form using C<guestfs_lvm_canonical_lv_name>. +Converted to F</dev/VG/LV> form using C<guestfs_lvm_canonical_lv_name>. =back @@ -2498,7 +2498,7 @@ or C<guestfs_download> functions." }; shortdesc = "find all files and directories"; longdesc = "\ This command lists out all files and directories, recursively, -starting at C<directory>. It is essentially equivalent to +starting at F<directory>. It is essentially equivalent to running the shell command C<find directory -print> but some post-processing happens on the output, described below. @@ -2509,7 +2509,7 @@ if the directory structure was: /tmp/b /tmp/c/d -then the returned list from C<guestfs_find> C</tmp> would be +then the returned list from C<guestfs_find> F</tmp> would be 4 elements: a @@ -2517,7 +2517,7 @@ then the returned list from C<guestfs_find> C</tmp> would be c c/d -If C<directory> is not a directory, then this command returns +If F<directory> is not a directory, then this command returns an error. The returned list is sorted." }; @@ -2742,7 +2742,7 @@ list a directory contents without making many round-trips." }; ]; shortdesc = "list the files in a directory"; longdesc = "\ -List the files in C<directory> (relative to the root directory, +List the files in F<directory> (relative to the root directory, there is no cwd). The '.' and '..' entries are not returned, but hidden files are shown." }; @@ -2783,8 +2783,8 @@ data." }; ]; shortdesc = "detect the disk format of a disk image"; longdesc = "\ -Detect and return the format of the disk image called C<filename>. -C<filename> can also be a host device, etc. If the format of the +Detect and return the format of the disk image called F<filename>. +F<filename> can also be a host device, etc. If the format of the image could not be detected, then C<\"unknown\"> is returned. Note that detecting the disk format can be insecure under some @@ -2814,7 +2814,7 @@ See also: L<guestfs(3)/DISK IMAGE FORMATS>" }; shortdesc = "return virtual size of a disk"; longdesc = "\ Detect and return the virtual size in bytes of the disk image -called C<filename>. +called F<filename>. Note that detecting disk features can be insecure under some circumstances. See L<guestfs(3)/CVE-2010-3851>." }; @@ -2840,7 +2840,7 @@ circumstances. See L<guestfs(3)/CVE-2010-3851>." }; ]; shortdesc = "return whether disk has a backing file"; longdesc = "\ -Detect and return whether the disk image C<filename> has a +Detect and return whether the disk image F<filename> has a backing file. Note that detecting disk features can be insecure under some @@ -3011,7 +3011,7 @@ Set the directory used by the handle to store temporary files. The environment variables C<LIBGUESTFS_TMPDIR> and C<TMPDIR> control the default value: If C<LIBGUESTFS_TMPDIR> is set, then that is the default. Else if C<TMPDIR> is set, then that is -the default. Else C</tmp> is the default." }; +the default. Else F</tmp> is the default." }; { defaults with name = "get_tmpdir"; added = (1, 19, 58); @@ -3036,7 +3036,7 @@ effective user ID. The environment variables C<LIBGUESTFS_CACHEDIR> and C<TMPDIR> control the default value: If C<LIBGUESTFS_CACHEDIR> is set, then that is the default. Else if C<TMPDIR> is set, then that is -the default. Else C</var/tmp> is the default." }; +the default. Else F</var/tmp> is the default." }; { defaults with name = "get_cachedir"; added = (1, 19, 58); @@ -3149,7 +3149,7 @@ the libguestfs protocol." }; test_excuse = "tests in tests/create subdirectory"; shortdesc = "create a blank disk image"; longdesc = "\ -Create a blank disk image called C<filename> (a host file) +Create a blank disk image called F<filename> (a host file) with format C<format> (usually C<raw> or C<qcow2>). The size is C<size> bytes. @@ -3160,7 +3160,7 @@ size of the backing file, which is discovered automatically. You are encouraged to also pass C<backingformat> to describe the format of C<backingfile>. -If C<filename> refers to a block device, then the device is +If F<filename> refers to a block device, then the device is formatted. The C<size> is ignored since block devices have an intrinsic size. @@ -3378,14 +3378,14 @@ let daemon_functions = [ shortdesc = "mount a guest disk at a position in the filesystem"; longdesc = "\ Mount a guest disk at a position in the filesystem. Block devices -are named C</dev/sda>, C</dev/sdb> and so on, as they were added to +are named F</dev/sda>, F</dev/sdb> and so on, as they were added to the guest. If those block devices contain partitions, they will have -the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style +the usual names (eg. F</dev/sda1>). Also LVM F</dev/VG/LV>-style names can be used, or 'mountable' strings returned by C<guestfs_list_filesystems> or C<guestfs_inspect_get_mountpoints>. The rules are the same as for L<mount(2)>: A filesystem must -first be mounted on C</> before others can be mounted. Other +first be mounted on F</> before others can be mounted. Other filesystems can only be mounted on directories which already exist. @@ -3439,7 +3439,7 @@ file types such as directories, symbolic links, block special etc." }; test_excuse = "tricky to test because it depends on the exact format of the 'ls -l' command, which changed between Fedora 10 and Fedora 11"; shortdesc = "list the files in a directory (long format)"; longdesc = "\ -List the files in C<directory> (relative to the root directory, +List the files in F<directory> (relative to the root directory, there is no cwd) in the format of 'ls -la'. This command is mostly useful for interactive sessions. It @@ -3458,7 +3458,7 @@ is I<not> intended that you try to parse the output string." }; longdesc = "\ List all the block devices. -The full block device names are returned, eg. C</dev/sda>. +The full block device names are returned, eg. F</dev/sda>. See also C<guestfs_list_filesystems>." }; @@ -3482,7 +3482,7 @@ See also C<guestfs_list_filesystems>." }; longdesc = "\ List all the partitions detected on all block devices. -The full partition device names are returned, eg. C</dev/sda1> +The full partition device names are returned, eg. F</dev/sda1> This does not return logical volumes. For that you will need to call C<guestfs_lvs>. @@ -3514,7 +3514,7 @@ List all the physical volumes detected. This is the equivalent of the L<pvs(8)> command. This returns a list of just the device names that contain -PVs (eg. C</dev/sda2>). +PVs (eg. F</dev/sda2>). See also C<guestfs_pvs_full>." }; @@ -3580,7 +3580,7 @@ List all the logical volumes detected. This is the equivalent of the L<lvs(8)> command. This returns a list of the logical volume device names -(eg. C</dev/VolGroup00/LogVol00>). +(eg. F</dev/VolGroup00/LogVol00>). See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>." }; @@ -3635,7 +3635,7 @@ You must call this before using any other C<guestfs_aug_*> commands. C<root> is the filesystem root. C<root> must not be NULL, -use C</> instead. +use F</> instead. The flags are the same as the flags defined in E<lt>augeas.hE<gt>, the logical I<or> of the following @@ -3774,7 +3774,7 @@ the tree before or after C<path> (depending on the boolean flag C<before>). C<path> must match exactly one existing node in the tree, and -C<label> must be a label, ie. not contain C</>, C<*> or end +C<label> must be a label, ie. not contain F</>, C<*> or end with a bracketed index C<[N]>." }; { defaults with @@ -4056,7 +4056,7 @@ See also C<guestfs_stat>." }; longdesc = "\ This creates an LVM physical volume on the named C<device>, where C<device> should usually be a partition name such -as C</dev/sda1>." }; +as F</dev/sda1>." }; { defaults with name = "vgcreate"; added = (0, 0, 8); @@ -4132,7 +4132,7 @@ on the volume group C<volgroup>, with C<size> megabytes." }; This is a direct interface to the L<sfdisk(8)> program for creating partitions on block devices. -C<device> should be a block device, for example C</dev/sda>. +C<device> should be a block device, for example F</dev/sda>. C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads and sectors on the device, which are passed directly to sfdisk as @@ -4211,7 +4211,7 @@ contains the filesystem." }; shortdesc = "show mounted filesystems"; longdesc = "\ This returns the list of currently mounted filesystems. It returns -the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>). +the list of devices (eg. F</dev/sda1>, F</dev/VG/LV>). Some internal mounts are not shown. @@ -4389,7 +4389,7 @@ this function returns an error message. The error message string is the content of I<stderr> from the command. The C<$PATH> environment variable will contain at least -C</usr/bin> and C</bin>. If you require a program from +F</usr/bin> and F</bin>. If you require a program from another location, you should provide the full path in the first parameter. @@ -4688,10 +4688,10 @@ This uses the L<blockdev(8)> command." }; ]; shortdesc = "upload a file from the local machine"; longdesc = "\ -Upload local file C<filename> to C<remotefilename> on the +Upload local file F<filename> to F<remotefilename> on the filesystem. -C<filename> can also be a named pipe. +F<filename> can also be a named pipe. See also C<guestfs_download>." }; @@ -4712,10 +4712,10 @@ See also C<guestfs_download>." }; ]; shortdesc = "download a file to the local machine"; longdesc = "\ -Download file C<remotefilename> and save it as C<filename> +Download file F<remotefilename> and save it as F<filename> on the local machine. -C<filename> can also be a named pipe. +F<filename> can also be a named pipe. See also C<guestfs_upload>, C<guestfs_cat>." }; @@ -4813,7 +4813,7 @@ To get the checksums for many files, use C<guestfs_checksums_out>." }; ]; shortdesc = "unpack tarfile to directory"; longdesc = "\ -This command uploads and unpacks local file C<tarfile> into C<directory>. +This command uploads and unpacks local file C<tarfile> into F<directory>. The optional C<compress> flag controls compression. If not given, then the input should be an uncompressed tar file. Otherwise one @@ -4830,7 +4830,7 @@ compression types)." }; cancellable = true; shortdesc = "pack directory into tarfile"; longdesc = "\ -This command packs the contents of C<directory> and downloads +This command packs the contents of F<directory> and downloads it to local file C<tarfile>. The optional C<compress> flag controls compression. If not given, @@ -4871,7 +4871,7 @@ instead of user/group names. shortdesc = "unpack compressed tarball to directory"; longdesc = "\ This command uploads and unpacks local file C<tarball> (a -I<gzip compressed> tar file) into C<directory>." }; +I<gzip compressed> tar file) into F<directory>." }; { defaults with name = "tgz_out"; added = (1, 0, 3); @@ -4881,7 +4881,7 @@ I<gzip compressed> tar file) into C<directory>." }; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ -This command packs the contents of C<directory> and downloads +This command packs the contents of F<directory> and downloads it to local file C<tarball>." }; { defaults with @@ -4940,7 +4940,7 @@ C<guestfsd> (the guestfs daemon) that runs inside the hypervisor. There is no comprehensive help for this command. You have -to look at the file C<daemon/debug.c> in the libguestfs source +to look at the file F<daemon/debug.c> in the libguestfs source to find out what you can do." }; { defaults with @@ -4980,10 +4980,10 @@ to find out what you can do." }; shortdesc = "remove an LVM logical volume"; longdesc = "\ Remove an LVM logical volume C<device>, where C<device> is -the path to the LV, such as C</dev/VG/LV>. +the path to the LV, such as F</dev/VG/LV>. You can also remove all LVs in a volume group by specifying -the VG name, C</dev/VG>." }; +the VG name, F</dev/VG>." }; { defaults with name = "vgremove"; added = (1, 0, 13); @@ -5252,14 +5252,14 @@ is advisable. If grub-install reports the error \"No suitable drive was found in the generated device map.\" -it may be that you need to create a C</boot/grub/device.map> +it may be that you need to create a F</boot/grub/device.map> file first that contains the mapping between grub device names and Linux device names. It is usually sufficient to create a file containing: (hd0) /dev/vda -replacing C</dev/vda> with the name of the installation device. +replacing F</dev/vda> with the name of the installation device. =back" }; @@ -5405,7 +5405,7 @@ or attached block device(s) in any other way." }; ]; shortdesc = "test if two files have equal contents"; longdesc = "\ -This compares the two files C<file1> and C<file2> and returns +This compares the two files F<file1> and F<file2> and returns true if their content is exactly equal, or false otherwise. The external L<cmp(1)> program is used for the comparison." }; @@ -5743,7 +5743,7 @@ L<ntfs-3g.probe(8)> manual page." }; shortdesc = "run a command via the shell"; longdesc = "\ This call runs a command from the guest filesystem via the -guest's C</bin/sh>. +guest's F</bin/sh>. This is like C<guestfs_command>, but passes the command to: @@ -5809,7 +5809,7 @@ with flags C<GLOB_MARK|GLOB_BRACE>. See that manual page for more details. Notice that there is no equivalent command for expanding a device -name (eg. C</dev/sd*>). Use C<guestfs_list_devices>, +name (eg. F</dev/sd*>). Use C<guestfs_list_devices>, C<guestfs_list_partitions> etc functions instead." }; { defaults with @@ -6096,7 +6096,7 @@ The result is the estimated size in I<kilobytes> longdesc = "\ This command lists out files contained in an initrd. -The files are listed without any initial C</> character. The +The files are listed without any initial F</> character. The files are listed in the order they appear (not necessarily alphabetical). Directory names are listed as separate items. @@ -6110,7 +6110,7 @@ format (compressed cpio files)." }; proc_nr = Some 129; shortdesc = "mount a file using the loop device"; longdesc = "\ -This command lets you mount C<file> (a filesystem image +This command lets you mount F<file> (a filesystem image in a file) on a mount point. It is entirely equivalent to the command C<mount -o loop file mountpoint>." }; @@ -6155,7 +6155,7 @@ label and/or UUID of the new swap partition." }; Create a swap partition on C<device> with label C<label>. Note that you cannot attach a swap label to a block device -(eg. C</dev/sda>), just to a partition. This appears to be +(eg. F</dev/sda>), just to a partition. This appears to be a limitation of the kernel or swap tools." }; { defaults with @@ -6394,7 +6394,7 @@ and C<guestfs_part_disk>" }; deprecated_by = Some "file"; shortdesc = "determine file type inside a compressed file"; longdesc = "\ -This command runs C<file> after first decompressing C<path> +This command runs F<file> after first decompressing C<path> using C<method>. C<method> must be one of C<gzip>, C<compress> or C<bzip2>. @@ -7110,7 +7110,7 @@ directory are watched, but this does I<not> happen recursively Note for non-C or non-Linux callers: the inotify events are defined by the Linux kernel ABI and are listed in -C</usr/include/sys/inotify.h>." }; +F</usr/include/sys/inotify.h>." }; { defaults with name = "inotify_rm_watch"; added = (1, 0, 66); @@ -7366,8 +7366,8 @@ See also C<guestfs_ping_daemon>." }; shortdesc = "find all files and directories, returning NUL-separated list"; longdesc = "\ This command lists out all files and directories, recursively, -starting at C<directory>, placing the resulting list in the -external file called C<files>. +starting at F<directory>, placing the resulting list in the +external file called F<files>. This command works the same way as C<guestfs_find> with the following exceptions: @@ -7434,7 +7434,7 @@ the underlying filesystem is case-insensitive, the driver exports the filesystem to Linux as case-sensitive. One consequence of this is that special directories such -as C<c:\\windows> may appear as C</WINDOWS> or C</windows> +as F<C:\\windows> may appear as F</WINDOWS> or F</windows> (or other things) depending on the precise details of how they were created. In Windows itself this would not be a problem. @@ -8052,7 +8052,7 @@ This command cannot do partial copies ]; shortdesc = "return the size of the file in bytes"; longdesc = "\ -This command returns the size of C<file> in bytes. +This command returns the size of F<file> in bytes. To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>, C<guestfs_is_dir>, C<guestfs_is_file> etc. @@ -8102,12 +8102,12 @@ Rename a volume group C<volgroup> with the new name C<newvolgroup>." }; ]; shortdesc = "list the contents of a single file in an initrd"; longdesc = "\ -This command unpacks the file C<filename> from the initrd file -called C<initrdpath>. The filename must be given I<without> the -initial C</> character. +This command unpacks the file F<filename> from the initrd file +called F<initrdpath>. The filename must be given I<without> the +initial F</> character. For example, in guestfish you could use the following command -to examine the boot script (usually called C</init>) +to examine the boot script (usually called F</init>) contained in a Linux initrd or initramfs image: initrd-cat /boot/initrd-<version>.img init @@ -8221,7 +8221,7 @@ or growing unnecessarily." }; shortdesc = "unpack compressed tarball to directory"; longdesc = "\ This command uploads and unpacks local file C<tarball> (an -I<xz compressed> tar file) into C<directory>." }; +I<xz compressed> tar file) into F<directory>." }; { defaults with name = "txz_out"; added = (1, 3, 2); @@ -8231,7 +8231,7 @@ I<xz compressed> tar file) into C<directory>." }; optional = Some "xz"; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ -This command packs the contents of C<directory> and downloads +This command packs the contents of F<directory> and downloads it to local file C<tarball> (as an xz compressed tar archive)." }; { defaults with @@ -8391,7 +8391,7 @@ The C<guestfs_debug_upload> command uploads a file to the libguestfs appliance. There is no comprehensive help for this command. You have -to look at the file C<daemon/debug.c> in the libguestfs source +to look at the file F<daemon/debug.c> in the libguestfs source to find out what it is for." }; { defaults with @@ -8407,7 +8407,7 @@ to find out what it is for." }; shortdesc = "upload base64-encoded data to file"; longdesc = "\ This command uploads base64-encoded data from C<base64file> -to C<filename>." }; +to F<filename>." }; { defaults with name = "base64_out"; added = (1, 3, 5); @@ -8416,7 +8416,7 @@ to C<filename>." }; cancellable = true; shortdesc = "download file and encode as base64"; longdesc = "\ -This command downloads the contents of C<filename>, writing +This command downloads the contents of F<filename>, writing it out to local file C<base64file> encoded as base64." }; { defaults with @@ -8427,7 +8427,7 @@ it out to local file C<base64file> encoded as base64." }; shortdesc = "compute MD5, SHAx or CRC checksum of files in a directory"; longdesc = "\ This command computes the checksums of all regular files in -C<directory> and then emits a list of those checksums to +F<directory> and then emits a list of those checksums to the local output file C<sumsfile>. This can be used for verifying the integrity of a virtual @@ -8701,7 +8701,7 @@ C<device> is the encrypted block device or partition. The caller must supply one of the keys associated with the LUKS block device, in the C<key> parameter. -This creates a new block device called C</dev/mapper/mapname>. +This creates a new block device called F</dev/mapper/mapname>. Reads and writes to this block device are decrypted from and encrypted to the underlying C<device> respectively. @@ -8732,7 +8732,7 @@ mapping is created." }; This closes a LUKS device that was created earlier by C<guestfs_luks_open> or C<guestfs_luks_open_ro>. The C<device> parameter must be the name of the LUKS mapping -device (ie. C</dev/mapper/mapname>) and I<not> the name +device (ie. F</dev/mapper/mapname>) and I<not> the name of the underlying block device." }; { defaults with @@ -8868,7 +8868,7 @@ If the optional flag C<followsymlinks> is true, then a symlink function to return true. This call only looks at files within the guest filesystem. Libguestfs -partitions and block devices (eg. C</dev/sda>) cannot be used as the +partitions and block devices (eg. F</dev/sda>) cannot be used as the C<path> parameter of this call. See also C<guestfs_stat>." }; @@ -8968,15 +8968,15 @@ See also C<guestfs_part_to_partnum>, C<guestfs_device_index>." }; ]); shortdesc = "upload a file from the local machine with offset"; longdesc = "\ -Upload local file C<filename> to C<remotefilename> on the +Upload local file F<filename> to F<remotefilename> on the filesystem. -C<remotefilename> is overwritten starting at the byte C<offset> +F<remotefilename> is overwritten starting at the byte C<offset> specified. The intention is to overwrite parts of existing files or devices, although if a non-existent file is specified then it is created with a \"hole\" before C<offset>. The size of the data written is implicit in the size of the -source C<filename>. +source F<filename>. Note that there is no limit on the amount of data that can be uploaded with this call, unlike with C<guestfs_pwrite>, @@ -9005,10 +9005,10 @@ See also C<guestfs_upload>, C<guestfs_pwrite>." }; ]); shortdesc = "download a file to the local machine with offset and size"; longdesc = "\ -Download file C<remotefilename> and save it as C<filename> +Download file F<remotefilename> and save it as F<filename> on the local machine. -C<remotefilename> is read for C<size> bytes starting at C<offset> +F<remotefilename> is read for C<size> bytes starting at C<offset> (this region must be within the file or device). Note that there is no limit on the amount of data that @@ -9075,8 +9075,8 @@ See also C<guestfs_pread>." }; shortdesc = "get canonical name of an LV"; longdesc = "\ This converts alternative naming schemes for LVs that you -might find to the canonical name. For example, C</dev/mapper/VG-LV> -is converted to C</dev/VG/LV>. +might find to the canonical name. For example, F</dev/mapper/VG-LV> +is converted to F</dev/VG/LV>. This command returns an error if the C<lvname> parameter does not refer to a logical volume. @@ -9279,7 +9279,7 @@ parameter." }; longdesc = "\ List all device mapper devices. -The returned list contains C</dev/mapper/*> devices, eg. ones created +The returned list contains F</dev/mapper/*> devices, eg. ones created by a previous call to C<guestfs_luks_open>. Device mapper devices which correspond to logical volumes are I<not> @@ -9376,8 +9376,8 @@ See also C<guestfs_write>." }; cancellable = true; shortdesc = "output compressed file"; longdesc = "\ -This command compresses C<file> and writes it out to the local -file C<zfile>. +This command compresses F<file> and writes it out to the local +file F<zfile>. The compression program used is controlled by the C<ctype> parameter. Currently this includes: C<compress>, C<gzip>, C<bzip2>, C<xz> or C<lzop>. @@ -9798,7 +9798,7 @@ This option may not be specified at the same time as the C<correct> option. proc_nr = Some 305; shortdesc = "list the files in a directory (long format with SELinux contexts)"; longdesc = "\ -List the files in C<directory> in the format of 'ls -laZ'. +List the files in F<directory> in the format of 'ls -laZ'. This command is mostly useful for interactive sessions. It is I<not> intended that you try to parse the output string." }; @@ -9941,7 +9941,7 @@ To read the label on a filesystem, call C<guestfs_vfs_label>." }; ]; shortdesc = "zero free space in a filesystem"; longdesc = "\ -Zero the free space in the filesystem mounted on C<directory>. +Zero the free space in the filesystem mounted on F<directory>. The filesystem must be mounted read-write. The filesystem contents are not affected, but any free space @@ -9970,7 +9970,7 @@ or after calling this, depending on your requirements." }; ]; shortdesc = "create an LVM logical volume in % remaining free space"; longdesc = "\ -Create an LVM logical volume called C</dev/volgroup/logvol>, +Create an LVM logical volume called F</dev/volgroup/logvol>, using approximately C<percent> % of the free space remaining in the volume group. Most usefully, when C<percent> is C<100> this will create the largest possible LV." }; @@ -10140,7 +10140,7 @@ To create general filesystems, use C<guestfs_mkfs>." }; ]; shortdesc = "get ext2 file attributes of a file"; longdesc = "\ -This returns the file attributes associated with C<file>. +This returns the file attributes associated with F<file>. The attributes are a set of bits associated with each inode which affect the behaviour of the file. The attributes @@ -10255,7 +10255,7 @@ Don't confuse these attributes with extended attributes shortdesc = "set ext2 file attributes of a file"; longdesc = "\ This sets or clears the file attributes C<attrs> -associated with the inode C<file>. +associated with the inode F<file>. C<attrs> is a string of characters representing file attributes. See C<guestfs_get_e2attrs> for a list of @@ -10327,7 +10327,7 @@ See C<guestfs_get_e2generation>." }; longdesc = "\ Create a snapshot of the btrfs subvolume C<source>. The C<dest> argument is the destination directory and the name -of the snapshot, in the form C</path/to/dest/name>. By default +of the snapshot, in the form F</path/to/dest/name>. By default the newly created snapshot is writable, if the value of optional parameter C<ro> is true, then a readonly snapshot is created. The optional parameter C<qgroupid> represents the qgroup which the @@ -10358,7 +10358,7 @@ Delete the named btrfs subvolume or snapshot." }; shortdesc = "create a btrfs subvolume"; longdesc = "\ Create a btrfs subvolume. The C<dest> argument is the destination -directory and the name of the subvolume, in the form C</path/to/dest/name>. +directory and the name of the subvolume, in the form F</path/to/dest/name>. The optional parameter C<qgroupid> represents the qgroup which the newly created subvolume will be added to." }; @@ -10768,7 +10768,7 @@ command (see L<guestfish(1)/glob>), for example: longdesc = "\ This specialized command is used to get a listing of the filenames in the directory C<dir>. The list of filenames -is written to the local file C<filenames> (on the host). +is written to the local file F<filenames> (on the host). In the output file, the filenames are separated by C<\\0> characters. @@ -10826,7 +10826,7 @@ C<guestfs_xfs_growfs> calls." }; ]; shortdesc = "open a Windows Registry hive file"; longdesc = "\ -Open the Windows Registry hive file named C<filename>. +Open the Windows Registry hive file named F<filename>. If there was any previous hivex handle associated with this guestfs session, then it is closed. @@ -10978,7 +10978,7 @@ See also: C<guestfs_hivex_value_utf8>." }; longdesc = "\ Commit (write) changes to the hive. -If the optional C<filename> parameter is null, then the changes +If the optional F<filename> parameter is null, then the changes are written back to the same hive that was opened. If this is not null then they are written to the alternate filename given and the original hive is left untouched. @@ -11171,12 +11171,12 @@ silently create an ext2 filesystem instead." }; If you add drives using the optional C<label> parameter of C<guestfs_add_drive_opts>, you can use this call to map between disk labels, and raw block device and partition -names (like C</dev/sda> and C</dev/sda1>). +names (like F</dev/sda> and F</dev/sda1>). This returns a hashtable, where keys are the disk labels -(I<without> the C</dev/disk/guestfs> prefix), and the values +(I<without> the F</dev/disk/guestfs> prefix), and the values are the full raw block device and partition names -(eg. C</dev/sda> and C</dev/sda1>)." }; +(eg. F</dev/sda> and F</dev/sda1>)." }; { defaults with name = "internal_hot_add_drive"; added = (1, 19, 49); @@ -11678,7 +11678,7 @@ The optional arguments are: =over 4 -=item C<directory> +=item F<directory> Install SYSLINUX in the named subdirectory, instead of in the root directory of the FAT filesystem. @@ -11686,8 +11686,8 @@ root directory of the FAT filesystem. =back Additional configuration can be supplied to SYSLINUX by -placing a file called C<syslinux.cfg> on the FAT filesystem, -either in the root directory, or under C<directory> if that +placing a file called F<syslinux.cfg> on the FAT filesystem, +either in the root directory, or under F<directory> if that optional argument is being used. For further information about the contents of this file, see L<syslinux(1)>. @@ -11700,11 +11700,11 @@ See also C<guestfs_extlinux>." }; optional = Some "extlinux"; shortdesc = "install the SYSLINUX bootloader on an ext2/3/4 or btrfs filesystem"; longdesc = "\ -Install the SYSLINUX bootloader on the device mounted at C<directory>. +Install the SYSLINUX bootloader on the device mounted at F<directory>. Unlike C<guestfs_syslinux> which requires a FAT filesystem, this can be used on an ext2/3/4 or btrfs filesystem. -The C<directory> parameter can be either a mountpoint, or a +The F<directory> parameter can be either a mountpoint, or a directory within the mountpoint. You also have to mark the partition as \"active\" @@ -11715,8 +11715,8 @@ The SYSLINUX package comes with some suitable Master Boot Records. See the L<extlinux(1)> man page for further information. Additional configuration can be supplied to SYSLINUX by -placing a file called C<extlinux.conf> on the filesystem -under C<directory>. For further information +placing a file called F<extlinux.conf> on the filesystem +under F<directory>. For further information about the contents of this file, see L<extlinux(1)>. See also C<guestfs_syslinux>." }; @@ -11791,7 +11791,7 @@ To read the UUID on a filesystem, call C<guestfs_vfs_uuid>." }; test_excuse = "tests in tests/journal subdirectory"; shortdesc = "open the systemd journal"; longdesc = "\ -Open the systemd journal located in C<directory>. Any previously +Open the systemd journal located in F<directory>. Any previously opened journal handle is closed. The contents of the journal can be read using C<guestfs_journal_next> @@ -12032,7 +12032,7 @@ read as stale or random data." }; cancellable = true; shortdesc = "pack directory into cpio file"; longdesc = "\ -This command packs the contents of C<directory> and downloads +This command packs the contents of F<directory> and downloads it to local file C<cpiofile>. The optional C<format> parameter can be used to select the format. @@ -12627,7 +12627,7 @@ prepared disk image, see L</PREPARED DISK IMAGES>." }; longdesc = " copy-in local [local ...] /remotedir C<copy-in> copies local files or directories recursively into the disk -image, placing them in the directory called C</remotedir> (which must +image, placing them in the directory called F</remotedir> (which must exist). This guestfish meta-command turns into a sequence of L</tar-in> and other commands as necessary. @@ -12724,7 +12724,7 @@ special value C<*> means all events. The third and final parameter is the shell script fragment (or any external command) that is executed when any of the events in the eventset occurs. It is executed using -C<$SHELL -c>, or if C<$SHELL> is not set then C</bin/sh -c>. +C<$SHELL -c>, or if C<$SHELL> is not set then F</bin/sh -c>. The shell script fragment receives callback parameters as arguments C<$1>, C<$2> etc. The actual event that was @@ -12772,7 +12772,7 @@ might do: which would allow you to edit anywhere within the first megabyte of the disk. -To edit the superblock of an ext2 filesystem on C</dev/sda1>, do: +To edit the superblock of an ext2 filesystem on F</dev/sda1>, do: hexedit /dev/sda1 0x400 0x400 diff --git a/guestfs-release-notes.pod b/guestfs-release-notes.pod index 60f5271..3bfdb92 100644 --- a/guestfs-release-notes.pod +++ b/guestfs-release-notes.pod @@ -84,7 +84,7 @@ The Java bindings are now compatible with OpenJDK 8 (Pino Toscano). Oracle Linux is returned as C<oraclelinux> (Nikos Skalkotos). -Linux guests which do not have C</etc/fstab> can now be handled +Linux guests which do not have F</etc/fstab> can now be handled (Pino Toscano). Minix is returned as C<minix> (Pino Toscano). @@ -187,11 +187,11 @@ Several places that used large arrays and structures on the stack have been fixed. There is now a test for booting the appliance repeatedly. Useful for -finding kernel leaks. See: C<tests/qemu/qemu-boot.c> +finding kernel leaks. See: F<tests/qemu/qemu-boot.c> There is a test for testing the speed of various qemu features such as virtio-serial uploads and block device writes. See: -C<tests/qemu/qemu-speed-test.c> +F<tests/qemu/qemu-speed-test.c> GCC warnings are now enabled for OCaml-C bindings in the OCaml virt tools. @@ -203,7 +203,7 @@ shared between all these utilities (thanks Pino Toscano). The FUSE tests were rewritten in C to ensure finer control over how system calls are tested. -The C<update-bugs.sh> script has been fixed so it should no longer +The F<update-bugs.sh> script has been fixed so it should no longer create an empty C<BUGS> file if the Bugzilla server is unavailable. The L<virt-resize(1)> tests now use a stochastic method to ensure much @@ -612,7 +612,7 @@ Earlier versions of libguestfs are not vulnerable. When generating random root passwords and random seeds, two bugs were fixed which are possibly security related. Firstly we no longer read -excessive bytes from C</dev/urandom> (most of which were just thrown +excessive bytes from F</dev/urandom> (most of which were just thrown away). Secondly we changed the code to avoid modulo bias. These issues were not thought to be exploitable. (Both changes suggested by Edwin Török) @@ -742,7 +742,7 @@ done on physical machines. =item * The libguestfs appliance does not write an empty string to -C</proc/sys/kernel/hotplug> when starting up. +F</proc/sys/kernel/hotplug> when starting up. Note that you B<must> configure your kernel to have C<CONFIG_UEVENT_HELPER_PATH=""> otherwise you will get strange LVM @@ -906,7 +906,7 @@ L<virt-builder(1)> is a new tool for building virtual machine images. It lets you rapidly and securely create guests and customize them. New L<virt-sysprep(1)> operations: -Remove files in C</tmp> and C</var/tmp>. +Remove files in F</tmp> and F</var/tmp>. Remove RPM database files. Change root and user passwords. More log files are removed. @@ -919,7 +919,7 @@ L<virt-resize(1)> and virt-sysprep can now use URIs to specify a remote disk. Use C<guestfish -N filename=type> to create a named disk image -(instead of the default C<test1.img> etc). +(instead of the default F<test1.img> etc). L<virt-sparsify(1)> now tests if there is enough disk space to complete the operation, instead of possibly running out of space half @@ -1383,7 +1383,7 @@ Library code internally uses GCC C<__attribute__((cleanup))> (if available) to simplify memory allocation. Internal header files have been reorganized. See the comments in -C<src/guestfs-internal*.h> +F<src/guestfs-internal*.h> Internal code shared between the library and certain tools is now located in a static C<libutils> library. @@ -1399,7 +1399,7 @@ Force use of C<serial-tests> with automake E<ge> 1.12. Use of sockets in the library protocol layer is abstracted, allowing other non-POSIX layers to be added in future (see -C<src/conn-socket.c>). +F<src/conn-socket.c>). C<qemu-img info --output json> is used if available, for more secure parsing of the output of this command. @@ -1408,7 +1408,7 @@ Distros can now use C<make INSTALLDIRS=vendor install> to place Ruby bindings in vendordir. This eliminates a non-upstream patch carried by both Fedora and Debian. -Valgrind log files are now written to C<tmp/valgrind-I<DATE>-I<PID>.log> +Valgrind log files are now written to F<tmp/valgrind-I<DATE>-I<PID>.log> C<make clean> cleans the local C<tmp/> directory. @@ -1596,8 +1596,8 @@ You can now hotplug drives (add and remove drives after launch). Libguestfs can now handle E<gt> 25 disks, in all APIs, tools and tests. You can label drives when adding them, then refer to them by label -(C</dev/disk/guestfs/LABEL>) instead of having to use device names -(C</dev/sda>). +(F</dev/disk/guestfs/LABEL>) instead of having to use device names +(F</dev/sda>). =head3 new library features @@ -1744,7 +1744,7 @@ A man page for the daemon (L<guestfsd(8)>) is included. =head3 guestfish history file -The C<$HOME/.guestfish> history file is now created with 0600 +The F<$HOME/.guestfish> history file is now created with 0600 permissions (instead of 0644 before) so it is no longer world readable. @@ -1754,7 +1754,7 @@ Old versions of both C<virt-edit> and the C<guestfish> C<edit> command created a new file containing the changes but did not set the permissions, etc of the new file to match the old one. The result of this was that if you edited a security sensitive file such as -C</etc/shadow> then it would be left world-readable after the edit. +F</etc/shadow> then it would be left world-readable after the edit. This issue was assigned CVE-2012-2690, and is fixed in libguestfs E<ge> 1.16. @@ -1874,16 +1874,16 @@ Separation of the library code into more files: =item * Launch backends are now located in separate files -eg. C<src/launch-appliance.c>, C<src/launch-libvirt.c>. +eg. F<src/launch-appliance.c>, C<src/launch-libvirt.c>. =item * -Generated action code is now split over several C<src/action*.c> +Generated action code is now split over several F<src/action*.c> files, for faster compilation. =item * -The huge C<src/guestfs.c> file is now split into smaller logical +The huge F<src/guestfs.c> file is now split into smaller logical units. =back @@ -1944,7 +1944,7 @@ in the main code that were found by syntax-check have been fixed Emacs mode (-*- foo -*-) has been added to generated files. -Progress bar output is now sent to C</dev/tty> so it doesn't end up in +Progress bar output is now sent to F</dev/tty> so it doesn't end up in the regular output of the program. virt-resize and virt-sparsify now suppress progress bars if stdout is not a tty. diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod index 1282608..fa909e9 100644 --- a/inspector/virt-inspector.pod +++ b/inspector/virt-inspector.pod @@ -29,7 +29,7 @@ You can also run virt-inspector directly on disk images from a single virtual machine. Use C<virt-inspector -a disk.img>. In rare cases a domain has several block devices, in which case you should list several I<-a> options one after another, with the first corresponding -to the guest's C</dev/sda>, the second to the guest's C</dev/sdb> and +to the guest's F</dev/sda>, the second to the guest's F</dev/sdb> and so on. You can also run virt-inspector on install disks, live CDs, bootable @@ -117,7 +117,7 @@ ensure the format is always specified. =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>. +to try to read passphrases from the user by opening F</dev/tty>. =item B<-v> @@ -163,7 +163,7 @@ For compatibility the old style is still supported. =head1 XML FORMAT The virt-inspector XML is described precisely in a RELAX NG schema -file C<virt-inspector.rng> which is supplied with libguestfs. This +file F<virt-inspector.rng> which is supplied with libguestfs. This section is just an overview. The top-level element is E<lt>operatingsystemsE<gt>, and it contains @@ -384,11 +384,11 @@ that libguestfs supports, and from guestfish. For a description of the C inspection API, read L<guestfs(3)/INSPECTION>. -For example code using the C inspection API, look for C<inspect-vm.c> +For example code using the C inspection API, look for F<inspect-vm.c> which ships with libguestfs. -C<inspect-vm.c> has also been translated into other languages. For -example, C<inspect_vm.pl> is the Perl translation, and there are other +F<inspect-vm.c> has also been translated into other languages. For +example, F<inspect_vm.pl> is the Perl translation, and there are other translations for OCaml, Python, etc. See L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES> for a list of man pages which contain this example code. diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod index 5ea2e84..53276e8 100644 --- a/java/examples/guestfs-java.pod +++ b/java/examples/guestfs-java.pod @@ -112,22 +112,22 @@ supplied in three parts: =over 4 -=item C<libguestfs.jar> +=item F<libguestfs.jar> -=item C<libguestfs-I<VERSION>.jar> +=item F<libguestfs-I<VERSION>.jar> The pure Java JAR file which contains several classes, the primary one being C<com.redhat.et.libguestfs.GuestFS>. Upstream, the JAR file contains a version number in the filename, but some Linux distros may rename it without the version number. -=item C<libguestfs_jni.so> +=item F<libguestfs_jni.so> The JNI code (written in C). This contains private native functions that interface between Java code and the regular libguestfs C library. You should B<not> call these directly. -=item C<libguestfs.so> +=item F<libguestfs.so> The regular libguestfs C library. diff --git a/make-fs/virt-make-fs.pod b/make-fs/virt-make-fs.pod index 83425a1..917550d 100644 --- a/make-fs/virt-make-fs.pod +++ b/make-fs/virt-make-fs.pod @@ -29,7 +29,7 @@ Basic usage is: where C<input> is either a directory containing files that you want to add, or a tar archive (either uncompressed tar or gzip-compressed -tar); and C<output.img> is a disk image. The input type is detected +tar); and F<output.img> is a disk image. The input type is detected automatically. The output disk image defaults to a raw ext2 sparse image unless you specify extra flags (see L</OPTIONS> below). diff --git a/p2v/virt-p2v-make-disk.pod b/p2v/virt-p2v-make-disk.pod index 35bba1a..ac7b812 100644 --- a/p2v/virt-p2v-make-disk.pod +++ b/p2v/virt-p2v-make-disk.pod @@ -31,7 +31,7 @@ combinations, do: =head2 EXAMPLES -Write a virt-p2v bootable USB key on C</dev/sdX> (and existing content +Write a virt-p2v bootable USB key on F</dev/sdX> (and existing content is erased), using Fedora 20 as the base distribution: virt-p2v-make-disk -o /dev/sdX fedora-20 @@ -43,7 +43,7 @@ Write a virt-p2v bootable virtual disk image, and boot it under qemu: -drive file=/var/tmp/p2v.img,if=virtio,index=0 \ -drive file=/var/tmp/guest.img,if=virtio,index=1 -where C</var/tmp/guest.img> would be the disk image of some guest that +where F</var/tmp/guest.img> would be the disk image of some guest that you want to convert (for testing only). =head1 OPTIONS @@ -81,9 +81,9 @@ C<VIRT_P2V_DATA_DIR> environment variable. =item C<$datadir/issue> -=item C<$datadir/launch-virt-p2v.in> +=item F<$datadir/launch-virt-p2v.in> -=item C<$datadir/p2v.service> +=item F<$datadir/p2v.service> Various data files that are copied into the bootable disk image. diff --git a/p2v/virt-p2v-make-kickstart.pod b/p2v/virt-p2v-make-kickstart.pod index 78c60fe..4f1ce1f 100644 --- a/p2v/virt-p2v-make-kickstart.pod +++ b/p2v/virt-p2v-make-kickstart.pod @@ -30,7 +30,7 @@ Using virt-p2v-make-kickstart is very simple: virt-p2v-make-kickstart fedora will build a kickstart file for Fedora. The kickstart file will be -called C<p2v.ks> and located in the current directory. +called F<p2v.ks> and located in the current directory. The parameters are a list of one or more repositories. Some built-in repositories are available: C<fedora>, C<rawhide> or C<koji>. You can @@ -140,17 +140,17 @@ L<virt-v2v(1)>, including Windows or Red Hat Enterprise Linux. =item * -Unpack the tftpboot directory into C</tmp> (so it appears as -C</tmp/tftpboot>). +Unpack the tftpboot directory into F</tmp> (so it appears as +F</tmp/tftpboot>). =item * -Copy C<pxelinux.0> and C<ldlinux.c32> from syslinux (usually from -C</usr/share/syslinux>) into C</tmp/tftpboot>. +Copy F<pxelinux.0> and F<ldlinux.c32> from syslinux (usually from +F</usr/share/syslinux>) into F</tmp/tftpboot>. =item * -Adjust the C<APPEND> line in C</tmp/tftpboot/pxelinux.cfg/default> if +Adjust the C<APPEND> line in F</tmp/tftpboot/pxelinux.cfg/default> if required. See L<virt-p2v(1)/KERNEL COMMAND LINE CONFIGURATION>. =item * @@ -185,7 +185,7 @@ Display help. =item B<--output> OUTPUT Write kickstart to C<OUTPUT>. If not specified, the default is -C<p2v.ks> in the current directory. +F<p2v.ks> in the current directory. =item B<--proxy> URL @@ -209,11 +209,11 @@ The L<virt-p2v(1)> binary which is copied into the kickstart file. =item C<$datadir/issue> -=item C<$datadir/launch-virt-p2v.in> +=item F<$datadir/launch-virt-p2v.in> -=item C<$datadir/p2v.ks.in> +=item F<$datadir/p2v.ks.in> -=item C<$datadir/p2v.service> +=item F<$datadir/p2v.service> Various data files that are used to make the kickstart. diff --git a/p2v/virt-p2v.pod b/p2v/virt-p2v.pod index 5978078..e37e654 100644 --- a/p2v/virt-p2v.pod +++ b/p2v/virt-p2v.pod @@ -152,7 +152,7 @@ The second panel on the left controls the virt-v2v output options. To understand these options it is a really good idea to read the L<virt-v2v(1)> manual page. You can leave the options at the default to create a guest as a disk image plus libvirt XML file located in -C</var/tmp> on the conversion host. This is a good idea if you are a +F</var/tmp> on the conversion host. This is a good idea if you are a first-time virt-p2v user. │ @@ -282,7 +282,7 @@ which are booted using PXE. Where exactly you set command line arguments depends on your PXE implementation, but for pxelinux you put them in the C<APPEND> field -in the C<pxelinux.cfg> file. For example: +in the F<pxelinux.cfg> file. For example: DEFAULT p2v TIMEOUT 20 @@ -355,7 +355,7 @@ Use this to enable full debugging of virt-v2v. If asked to diagnose a problem with virt-p2v, you should add C<p2v.debug> to the kernel command line, and examine the log file -which is left in C</tmp> on the conversion server. +which is left in F</tmp> on the conversion server. =item B<p2v.disks=sdX,sdY,..> @@ -400,7 +400,7 @@ Set the output mode. This is the same as the virt-v2v I<-o> option. See L<virt-v2v(1)/OPTIONS>. If not specified, the default is C<local>, and the converted guest is -written to C</var/tmp>. +written to F</var/tmp>. =item B<p2v.oa=sparse|preallocated> @@ -423,7 +423,7 @@ option. See L<virt-v2v(1)/OPTIONS>. Set the output storage. This is the same as the virt-v2v I<-os> option. See L<virt-v2v(1)/OPTIONS>. -If not specified, the default is C</var/tmp> (on the conversion server). +If not specified, the default is F</var/tmp> (on the conversion server). =item B<p2v.pre=COMMAND> @@ -447,7 +447,7 @@ This can be any command or script. If the command contains spaces, you must quote the whole command with double quotes. I<If> virt-p2v is running as root, I<and> the command line was set -from C</proc/cmdline> (not I<--cmdline>), then the default is to run +from F</proc/cmdline> (not I<--cmdline>), then the default is to run the L<poweroff(8)> command. Otherwise the default is not to run any command. @@ -485,7 +485,7 @@ Display help. =item B<--cmdline=CMDLINE> This is used for debugging. Instead of parsing the kernel command line -from C</proc/cmdline>, parse the string parameter C<CMDLINE>. +from F</proc/cmdline>, parse the string parameter C<CMDLINE>. =item B<-v> @@ -538,13 +538,13 @@ Into this directory are written various files which include: =over 4 -=item C<name> +=item F<name> I<before conversion> The name (usually the hostname) of the physical machine. -=item C<physical.xml> +=item F<physical.xml> I<before conversion> @@ -556,20 +556,20 @@ Note this is not "real" libvirt XML (and must B<never> be loaded into libvirt, which would reject it anyhow). Also it is not the same as the libvirt XML which virt-v2v generates in certain output modes. -=item C<status> +=item F<status> I<after conversion> The final status of the conversion. C<0> if the conversion was successful. Non-zero if the conversion failed. -=item C<time> +=item F<time> I<before conversion> The start date/time of conversion. -=item C<virt-v2v-conversion-log.txt> +=item F<virt-v2v-conversion-log.txt> I<during/after conversion> @@ -616,7 +616,7 @@ file. The final step is to send the S<C<virt-v2v -i libvirtxml physical.xml ...>> command to the conversion server over the control connection. This -references the C<physical.xml> file (see above), which in turn +references the F<physical.xml> file (see above), which in turn references the NBD listening port(s) of the data connection(s). Output from the virt-v2v command (messages, debugging etc) is saved diff --git a/rescue/virt-rescue.pod b/rescue/virt-rescue.pod index d5c729f..a8bbbd7 100644 --- a/rescue/virt-rescue.pod +++ b/rescue/virt-rescue.pod @@ -46,9 +46,9 @@ For live VMs you I<must> use the --ro option. When you run virt-rescue on a virtual machine or disk image, you are placed in an interactive bash shell where you can use many ordinary -Linux commands. What you see in C</> (C</bin>, C</lib> etc) is the +Linux commands. What you see in F</> (F</bin>, F</lib> etc) is the rescue appliance. You must mount the virtual machine's filesystems by -hand. There is an empty directory called C</sysroot> where you can +hand. There is an empty directory called F</sysroot> where you can mount filesystems. You can get virt-rescue to suggest mount commands for you by using the @@ -169,12 +169,12 @@ For example: virt-rescue --format=raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-rescue --format=raw -a disk.img --format -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -304,7 +304,7 @@ QEMU user networking cannot receive incoming connections. The virt-rescue appliance needs to be small and so does not include many network tools. In particular there is no L<telnet(1)> command. You can make TCP connections from the shell using the magical -C</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax: +F</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax: exec 3<>/dev/tcp/redhat.com/80 echo "GET /" >&3 @@ -338,13 +338,13 @@ When starting virt-rescue, attach the core files disk last: virt-rescue --rw [-a ...] -a /tmp/corefiles B<NB.> If you use the I<--ro> option, then virt-rescue will silently -not write any core files to C</tmp/corefiles>. +not write any core files to F</tmp/corefiles>. =item 3. Inside virt-rescue, mount the core files disk. Note replace -C</dev/sdb1> with the last disk index. For example if the core files -disk is the last of four disks, you would use C</dev/sdd1>. +F</dev/sdb1> with the last disk index. For example if the core files +disk is the last of four disks, you would use F</dev/sdd1>. ><rescue> mkdir /tmp/mnt ><rescue> mount /dev/sdb1 /tmp/mnt @@ -360,7 +360,7 @@ Enable core dumps in the rescue kernel: =item 5. Run the tool that caused the core dump. The core dump will be written -to C</tmp/mnt/core.I<PID>>. +to F</tmp/mnt/core.I<PID>>. ><rescue> ls -l /tmp/mnt total 1628 diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod index d8da02f..a7620e0 100644 --- a/resize/virt-resize.pod +++ b/resize/virt-resize.pod @@ -244,11 +244,11 @@ C<dd if=/dev/zero of=outdisk bs=1M count=..>) =head2 LOGICAL PARTITIONS -Logical partitions (a.k.a. C</dev/sda5+> on disks using DOS partition +Logical partitions (a.k.a. F</dev/sda5+> on disks using DOS partition tables) cannot be resized. To understand what is going on, firstly one of the four partitions -C</dev/sda1-4> will have MBR partition type C<05> or C<0f>. This is +F</dev/sda1-4> will have MBR partition type C<05> or C<0f>. This is called the B<extended partition>. Use L<virt-filesystems(1)> to see the MBR partition type. @@ -260,7 +260,7 @@ copied across, all the logical partitions contained inside are copied over implicitly. Virt-resize does not look inside the extended partition, so it copies the logical partitions blindly. -You cannot specify a logical partition (C</dev/sda5+>) at all on the +You cannot specify a logical partition (F</dev/sda5+>) at all on the command line. Doing so will give an error. =head1 OPTIONS @@ -423,8 +423,8 @@ You can give this option multiple times. This takes the logical volume and, as a final step, expands it to fill all the space available in its volume group. A typical usage, -assuming a Linux guest with a single PV C</dev/sda2> and a root device -called C</dev/vg_guest/lv_root> would be: +assuming a Linux guest with a single PV F</dev/sda2> and a root device +called F</dev/vg_guest/lv_root> would be: virt-resize indisk outdisk \ --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root @@ -677,8 +677,8 @@ specify other parameters to grub-install, use L<virt-rescue(1)>. =head2 RESIZING WINDOWS BOOT PARTITIONS In Windows Vista and later versions, Microsoft switched to using a -separate boot partition. In these VMs, typically C</dev/sda1> is the -boot partition and C</dev/sda2> is the main (C:) drive. Resizing the +separate boot partition. In these VMs, typically F</dev/sda1> is the +boot partition and F</dev/sda2> is the main (C:) drive. Resizing the first (boot) partition causes the bootloader to fail with C<0xC0000225> error. Resizing the second partition (ie. C: drive) should work. diff --git a/sparsify/virt-sparsify.pod b/sparsify/virt-sparsify.pod index 9ddedc6..36063ca 100644 --- a/sparsify/virt-sparsify.pod +++ b/sparsify/virt-sparsify.pod @@ -211,7 +211,7 @@ zeroed, but existing blocks of zeroes will still be sparsified. When using I<--in-place>, the filesystem is ignored completely. In the second form, this ignores the named volume group. Use the -volume group name without the C</dev/> prefix, eg. I<--ignore vg_foo> +volume group name without the F</dev/> prefix, eg. I<--ignore vg_foo> You can give this option multiple times. @@ -408,9 +408,9 @@ You should ensure there is enough free space in the worst case for a full copy of the source disk (I<virtual> size), or else set C<$TMPDIR> to point to another directory that has enough space. -This defaults to C</tmp>. +This defaults to F</tmp>. -Note that if C<$TMPDIR> is a tmpfs (eg. if C</tmp> is on tmpfs, or if +Note that if C<$TMPDIR> is a tmpfs (eg. if F</tmp> is on tmpfs, or if you use C<TMPDIR=/dev/shm>), tmpfs defaults to a maximum size of I<half> of physical RAM. If virt-sparsify exceeds this, it will hang. The solution is either to use a real disk, or to increase the maximum diff --git a/src/guestfs.pod b/src/guestfs.pod index e2ee1b5..0068183 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -140,8 +140,8 @@ cause disk corruption, but adding it read-only is safe. You should usually add at least one disk image, and you may add multiple disk images. If adding multiple disk images, they usually have to be "related", ie. from the same guest. In the API, the disk -images are usually referred to as C</dev/sda> (for the first one you -added), C</dev/sdb> (for the second one you added), etc. +images are usually referred to as F</dev/sda> (for the first one you +added), F</dev/sdb> (for the second one you added), etc. Once L</guestfs_launch> has been called you cannot add any more images. You can call L</guestfs_list_devices> to get a list of the device @@ -162,10 +162,10 @@ directly: guestfs_mount (g, "/dev/sda1", "/"); -where C</dev/sda1> means literally the first partition (C<1>) of the -first disk image that we added (C</dev/sda>). If the disk contains +where F</dev/sda1> means literally the first partition (C<1>) of the +first disk image that we added (F</dev/sda>). If the disk contains Linux LVM2 logical volumes you could refer to those instead -(eg. C</dev/VG/LV>). Note that these are libguestfs virtual devices, +(eg. F</dev/VG/LV>). Note that these are libguestfs virtual devices, and are nothing to do with host devices. If you are given a disk image and you don't know what it contains then @@ -328,8 +328,8 @@ Example: duplicate the contents of an LV: /* -1 marks the end of the list of optional parameters */ -1); -The destination (C</dev/VG/Copy>) must be at least as large as the -source (C</dev/VG/Original>). To copy less than the whole source +The destination (F</dev/VG/Copy>) must be at least as large as the +source (F</dev/VG/Original>). To copy less than the whole source device, use the optional C<size> parameter: guestfs_copy_device_to_device (g, @@ -353,7 +353,7 @@ Calls like L</guestfs_upload>, L</guestfs_download>, L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take filenames as arguments, so it appears you can only upload and download to files. However many Un*x-like hosts let you use the special device -files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N> +files F</dev/stdin>, F</dev/stdout>, F</dev/stderr> and F</dev/fd/N> to read and write from stdin, stdout, stderr, and arbitrary file descriptor N. @@ -575,7 +575,7 @@ Then open these devices by calling L</guestfs_luks_open>. Obviously you will require the passphrase! Opening a LUKS device creates a new device mapper device -called C</dev/mapper/mapname> (where C<mapname> is the +called F</dev/mapper/mapname> (where C<mapname> is the string you supply to L</guestfs_luks_open>). Reads and writes to this mapper device are decrypted from and encrypted to the underlying block device respectively. @@ -588,7 +588,7 @@ Use the reverse process to close a LUKS device. Unmount any logical volumes on it, deactivate the volume groups by caling C<guestfs_vg_activate (g, 0, ["/dev/VG"])>. Then close the mapper device by calling -L</guestfs_luks_close> on the C</dev/mapper/mapname> +L</guestfs_luks_close> on the F</dev/mapper/mapname> device (I<not> the underlying encrypted block device). =head2 MOUNT LOCAL @@ -882,7 +882,7 @@ respectively. Un*x-like and Linux-based operating systems usually consist of several filesystems which are mounted at boot time (for example, a separate -boot partition mounted on C</boot>). The inspection rules are able to +boot partition mounted on F</boot>). The inspection rules are able to detect how filesystems correspond to mount points. Call C<guestfs_inspect_get_mountpoints> to get this mapping. It might return a hash table like this example: @@ -894,8 +894,8 @@ return a hash table like this example: The caller can then make calls to L</guestfs_mount> to mount the filesystems as suggested. -Be careful to mount filesystems in the right order (eg. C</> before -C</usr>). Sorting the keys of the hash by length, shortest first, +Be careful to mount filesystems in the right order (eg. F</> before +F</usr>). Sorting the keys of the hash by length, shortest first, should work. Inspection currently only works for some common operating systems. @@ -945,7 +945,7 @@ DOS and Windows still use drive letters, and the filesystems are always treated as case insensitive by Windows itself, and therefore you might find a Windows configuration file referring to a path like C<c:\windows\system32>. When the filesystem is mounted in libguestfs, -that directory might be referred to as C</WINDOWS/System32>. +that directory might be referred to as F</WINDOWS/System32>. Drive letter mappings can be found using inspection (see L</INSPECTION> and L</guestfs_inspect_get_drive_mappings>) @@ -1113,7 +1113,7 @@ used. =item B<C#> The C# bindings are highly experimental. Please read the warnings -at the top of C<csharp/Libguestfs.cs>. +at the top of F<csharp/Libguestfs.cs>. =item B<Erlang> @@ -1238,8 +1238,8 @@ L</guestfs_add_drive_ro> to guarantee that the disk is not changed. =item guestfish command line is hard to use. -C<guestfish disk.img> doesn't do what people expect (open C<disk.img> -for examination). It tries to run a guestfish command C<disk.img> +F<guestfish disk.img> doesn't do what people expect (open F<disk.img> +for examination). It tries to run a guestfish command F<disk.img> which doesn't exist, so it fails. In earlier versions of guestfish the error message was also unintuitive, but we have corrected this since. Like the Bourne shell, we should have used C<guestfish -c @@ -1269,15 +1269,15 @@ and return values which take bytes or other units. =item Ambiguity between devices and paths There is a subtle ambiguity in the API between a device name -(eg. C</dev/sdb2>) and a similar pathname. A file might just happen -to be called C<sdb2> in the directory C</dev> (consider some non-Unix +(eg. F</dev/sdb2>) and a similar pathname. A file might just happen +to be called C<sdb2> in the directory F</dev> (consider some non-Unix VM image). In the current API we usually resolve this ambiguity by having two separate calls, for example L</guestfs_checksum> and L</guestfs_checksum_device>. Some API calls are ambiguous and (incorrectly) resolve the problem by detecting if the path supplied -begins with C</dev/>. +begins with F</dev/>. To avoid both the ambiguity and the need to duplicate some calls, we could make paths/devices into structured names. One way to do this @@ -1334,14 +1334,14 @@ Libguestfs needs a supermin appliance, which it finds by looking along an internal path. By default it looks for these in the directory C<$libdir/guestfs> -(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>). +(eg. F</usr/local/lib/guestfs> or F</usr/lib64/guestfs>). Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> to change the directories that libguestfs will search in. The value is a colon-separated list of paths. The current directory is I<not> searched unless the path contains an empty element or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would -search the current directory and then C</usr/lib/guestfs>. +search the current directory and then F</usr/lib/guestfs>. =head2 QEMU WRAPPERS @@ -1361,7 +1361,7 @@ qemu from source: qemudir=/home/rjones/d/qemu exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@" -Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, +Save this script as F</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and then use it by setting the LIBGUESTFS_HV environment variable. For example: @@ -1576,7 +1576,7 @@ looking for a virtio-serial channel to connect to: </devices> </domain> -L</guestfs_add_domain> extracts C</path/to/socket> and sets the +L</guestfs_add_domain> extracts F</path/to/socket> and sets the backend to C<unix:/path/to/socket>. Some of the libguestfs tools (including guestfish) support a I<--live> @@ -1678,13 +1678,13 @@ developer to program in confidence against the libguestfs API. In the kernel there is now quite a profusion of schemata for naming block devices (in this context, by I<block device> I mean a physical or virtual hard drive). The original Linux IDE driver used names -starting with C</dev/hd*>. SCSI devices have historically used a -different naming scheme, C</dev/sd*>. When the Linux kernel I<libata> +starting with F</dev/hd*>. SCSI devices have historically used a +different naming scheme, F</dev/sd*>. When the Linux kernel I<libata> driver became a popular replacement for the old IDE driver (particularly for SATA devices) those devices also used the -C</dev/sd*> scheme. Additionally we now have virtual machines with +F</dev/sd*> scheme. Additionally we now have virtual machines with paravirtualized drivers. This has created several different naming -systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen +systems, such as F</dev/vd*> for virtio disks and F</dev/xvd*> for Xen PV disks. As discussed above, libguestfs uses a qemu appliance running an @@ -1696,11 +1696,11 @@ or partition names. Working scripts and the recipe (example) scripts that we make available over the internet could fail if the naming scheme changes. -Therefore libguestfs defines C</dev/sd*> as the I<standard naming -scheme>. Internally C</dev/sd*> names are translated, if necessary, +Therefore libguestfs defines F</dev/sd*> as the I<standard naming +scheme>. Internally F</dev/sd*> names are translated, if necessary, to other names as required. For example, under RHEL 5 which uses the -C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to -C</dev/hda2> transparently. +F</dev/hd*> scheme, any device parameter F</dev/sda2> is translated to +F</dev/hda2> transparently. Note that this I<only> applies to parameters. The L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls @@ -1718,9 +1718,9 @@ Not all versions of libguestfs support setting a disk label, and when it is supported, it is limited to 20 ASCII characters C<[a-zA-Z]>. When you add a disk with a label, it can either be addressed -using C</dev/sd*>, or using C</dev/disk/guestfs/I<label>>. +using F</dev/sd*>, or using F</dev/disk/guestfs/I<label>>. Partitions on the disk can be addressed using -C</dev/disk/guestfs/I<label>I<partnum>>. +F</dev/disk/guestfs/I<label>I<partnum>>. Listing devices (L</guestfs_list_devices>) and partitions (L</guestfs_list_partitions>) returns the raw block device name. @@ -1732,8 +1732,8 @@ to raw block device and partition names. Usually this translation is transparent. However in some (very rare) cases you may need to know the exact algorithm. Such cases include where you use L</guestfs_config> to add a mixture of virtio and IDE -devices to the qemu-based appliance, so have a mixture of C</dev/sd*> -and C</dev/vd*> devices. +devices to the qemu-based appliance, so have a mixture of F</dev/sd*> +and F</dev/vd*> devices. The algorithm is applied only to I<parameters> which are known to be either device or partition names. Return values from functions such @@ -1747,7 +1747,7 @@ Is the string a parameter which is a device or partition name? =item * -Does the string begin with C</dev/sd>? +Does the string begin with F</dev/sd>? =item * @@ -1756,15 +1756,15 @@ However if I<not> then we continue with this algorithm. =item * -Replace initial C</dev/sd> string with C</dev/hd>. +Replace initial F</dev/sd> string with F</dev/hd>. -For example, change C</dev/sda2> to C</dev/hda2>. +For example, change F</dev/sda2> to F</dev/hda2>. If that named device exists, use it. If not, continue. =item * -Replace initial C</dev/sd> string with C</dev/vd>. +Replace initial F</dev/sd> string with F</dev/vd>. If that named device exists, use it. If not, return an error. @@ -1905,7 +1905,7 @@ Modern qemu (hence libguestfs) supports most variations, but you should be aware that older versions of qemu had some very bad data-corrupting bugs in this area. -Note that VMware ESX exposes files with the name C<guest-flat.vmdk>. +Note that VMware ESX exposes files with the name F<guest-flat.vmdk>. These are not VMDK. They are raw format files which happen to have a C<.vmdk> extension. @@ -2050,7 +2050,7 @@ Guest configuration may be altered in unusual ways by the administrator of the virtual machine, and may not reflect reality (particularly for untrusted or actively malicious guests). For example we parse the hostname from configuration files like -C</etc/sysconfig/network> that we find in the guest, but the guest +F</etc/sysconfig/network> that we find in the guest, but the guest administrator can easily manipulate these files to provide the wrong hostname. @@ -2140,7 +2140,7 @@ Old versions of both virt-edit and the guestfish C<edit> command created a new file containing the changes but did not set the permissions, etc of the new file to match the old one. The result of this was that if you edited a security sensitive file such as -C</etc/shadow> then it would be left world-readable after the edit. +F</etc/shadow> then it would be left world-readable after the edit. It is sufficient to update libguestfs to any version E<ge> 1.16. @@ -2161,11 +2161,11 @@ L<https://bugzilla.redhat.com/1016960> When using the L<guestfish(1)> I<--remote> or guestfish I<--listen> options, guestfish would create a socket in a known location -(C</tmp/.guestfish-$UID/socket-$PID>). +(F</tmp/.guestfish-$UID/socket-$PID>). The location has to be a known one in order for both ends to communicate. However no checking was done that the containing -directory (C</tmp/.guestfish-$UID>) is owned by the user. Thus +directory (F</tmp/.guestfish-$UID>) is owned by the user. Thus another user could create this directory and potentially hijack sockets owned by another user's guestfish client or server. @@ -3056,7 +3056,7 @@ the moment this is only used for progress messages. =head2 EXAMPLE: CAPTURING LOG MESSAGES A working program demonstrating this can be found in -C<examples/debug-logging.c> in the source of libguestfs. +F<examples/debug-logging.c> in the source of libguestfs. One motivation for the generic event API was to allow GUI programs to capture debug and other messages. In libguestfs E<le> 1.8 these were @@ -3137,7 +3137,7 @@ L</guestfs_get_libvirt_requested_credential_defresult>. The example program below should make this clearer. There is also a more substantial working example program supplied with -the libguestfs sources, called C<libvirt-auth.c>. +the libguestfs sources, called F<libvirt-auth.c>. main () { @@ -3415,7 +3415,7 @@ and some ordinary C entry points: printf ("\t%s %s\n", probefunc(), $$parms); } -The script above can be saved to C<test.stap> and run using the +The script above can be saved to F<test.stap> and run using the L<stap(1)> program. Note that you either have to be root, or you have to add yourself to several special stap groups. Consult the systemtap documentation for more information. @@ -3558,7 +3558,7 @@ debugging (set the environment variable C<LIBGUESTFS_DEBUG=1>). C<supermin --build> is invoked to create the kernel, a small initrd and the appliance. -The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in +The appliance is cached in F</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in another directory if C<LIBGUESTFS_CACHEDIR> or C<TMPDIR> are set). For a complete description of how the appliance is created and cached, @@ -3575,7 +3575,7 @@ appliance. The purpose of the initrd is to load enough kernel modules in order that the appliance itself can be mounted and started. The initrd is a cpio archive called -C</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/initrd>. +F</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/initrd>. When the initrd has started you will see messages showing that kernel modules are being loaded, similar to this: @@ -3590,16 +3590,16 @@ modules are being loaded, similar to this: The appliance is a sparse file containing an ext2 filesystem which contains a familiar (although reduced in size) Linux operating system. It would normally be called -C</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/root>. +F</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/root>. The regular disks being inspected by libguestfs are the first -devices exposed by qemu (eg. as C</dev/vda>). +devices exposed by qemu (eg. as F</dev/vda>). -The last disk added to qemu is the appliance itself (eg. C</dev/vdb> +The last disk added to qemu is the appliance itself (eg. F</dev/vdb> if there was only one regular disk). Thus the final job of the initrd is to locate the appliance disk, -mount it, and switch root into the appliance, and run C</init> from +mount it, and switch root into the appliance, and run F</init> from the appliance. If this works successfully you will see messages such as: @@ -3644,7 +3644,7 @@ The protocol used to talk between the library and the daemon running inside the qemu virtual machine is a simple RPC mechanism built on top of XDR (RFC 1014, RFC 1832, RFC 4506). -The detailed format of structures is in C<src/guestfs_protocol.x> +The detailed format of structures is in F<src/guestfs_protocol.x> (note: this file is automatically generated). There are two broad cases, ordinary functions that don't have any @@ -3874,10 +3874,10 @@ run the generator (C<./autogen.sh && make -C generator>) in order to create those files. Libguestfs uses an autotools-based build system, with the main files -being C<configure.ac> and C<Makefile.am>. The C<generator> +being F<configure.ac> and F<Makefile.am>. The F<generator> subdirectory contains the generator, plus files describing the API. -The C<src> subdirectory contains source for the library. The -C<appliance> and C<daemon> subdirectories contain the source for the +The F<src> subdirectory contains source for the library. The +F<appliance> and F<daemon> subdirectories contain the source for the code that builds the appliance, and the code that runs in the appliance respectively. Other directories are covered in the section L<SOURCE CODE SUBDIRECTORIES> below. @@ -3886,20 +3886,20 @@ Apart from the fact that all API entry points go via some generated code, the library is straightforward. (In fact, even the generated code is designed to be readable, and should be read as ordinary code). Some actions run entirely in the library, and are written as C -functions in files under C<src>. Others are forwarded to the daemon +functions in files under F<src>. Others are forwarded to the daemon where (after some generated RPC marshalling) they appear as C -functions in files under C<daemon>. +functions in files under F<daemon>. To build from source, first read the C<README> file. -=head2 C<local*> FILES +=head2 F<local*> FILES -Files in the top source directory that begin with the prefix C<local*> +Files in the top source directory that begin with the prefix F<local*> are ignored by git. These files can contain local configuration or scripts that you need to build libguestfs. -By convention, I have a file called C<localconfigure> which is a -simple wrapper around C<autogen.sh> containing local configure +By convention, I have a file called F<localconfigure> which is a +simple wrapper around F<autogen.sh> containing local configure customizations that I need: . localenv @@ -3914,7 +3914,7 @@ So I can use this to build libguestfs: ./localconfigure && make -If there is a file in the top build directory called C<localenv>, then +If there is a file in the top build directory called F<localenv>, then it will be sourced by C<make>. This file can contain any local environment variables needed, eg. for skipping tests: @@ -3923,9 +3923,9 @@ environment variables needed, eg. for skipping tests: # Skip this test, it is broken. export SKIP_TEST_BTRFS_FSCK=1 -Note that C<localenv> is included by the top Makefile (so it's a +Note that F<localenv> is included by the top Makefile (so it's a Makefile fragment). But if it is also sourced by your -C<localconfigure> script then it is used as a shell script. +F<localconfigure> script then it is used as a shell script. =head2 ADDING A NEW API ACTION @@ -3939,7 +3939,7 @@ To add a new API action there are two changes: =item 1. You need to add a description of the call (name, parameters, return -type, tests, documentation) to C<generator/actions.ml>. +type, tests, documentation) to F<generator/actions.ml>. There are two sorts of API action, depending on whether the call goes through to the daemon in the appliance, or is serviced entirely by the @@ -3985,33 +3985,33 @@ the OCaml description. You can supply zero or as many tests as you want per API call. The tests can either be added as part of the API description -(C<generator/actions.ml>), or in some rarer cases you may want to drop +(F<generator/actions.ml>), or in some rarer cases you may want to drop a script into C<tests/*/>. Note that adding a script to C<tests/*/> is slower, so if possible use the first method. The following describes the test environment used when you add an API -test in C<actions.ml>. +test in F<actions.ml>. The test environment has 4 block devices: =over 4 -=item C</dev/sda> 500MB +=item F</dev/sda> 500MB General block device for testing. -=item C</dev/sdb> 500MB +=item F</dev/sdb> 500MB -C</dev/sdb1> is an ext2 filesystem used for testing +F</dev/sdb1> is an ext2 filesystem used for testing filesystem write operations. -=item C</dev/sdc> 10MB +=item F</dev/sdc> 10MB Used in a few tests where two block devices are needed. -=item C</dev/sdd> +=item F</dev/sdd> -ISO with fixed content (see C<images/test.iso>). +ISO with fixed content (see F<images/test.iso>). =back @@ -4020,9 +4020,9 @@ libguestfs appliance and block devices are reused between tests. So don't try testing L</guestfs_kill_subprocess> :-x Each test starts with an initial scenario, selected using one of the -C<Init*> expressions, described in C<generator/types.ml>. These +C<Init*> expressions, described in F<generator/types.ml>. These initialize the disks mentioned above in a particular way as documented -in C<types.ml>. You should not assume anything about the previous +in F<types.ml>. You should not assume anything about the previous contents of other disks that are not initialized. You can add a prerequisite clause to any individual test. This is a @@ -4048,7 +4048,7 @@ Packagers can run only certain tests by setting for example: TEST_ONLY="vfs_type zerofree" -See C<tests/c-api/tests.c> for more details of how these environment +See F<tests/c-api/tests.c> for more details of how these environment variables work. =head2 DEBUGGING NEW API ACTIONS @@ -4064,11 +4064,11 @@ stderr, and they will show up if you use C<guestfish -v>. =head2 ADDING A NEW LANGUAGE BINDING All language bindings must be generated by the generator -(see the C<generator> subdirectory). +(see the F<generator> subdirectory). There is no documentation for this yet. We suggest you look -at an existing binding, eg. C<generator/ocaml.ml> or -C<generator/perl.ml>. +at an existing binding, eg. F<generator/ocaml.ml> or +F<generator/perl.ml>. =head2 ADDING TESTS FOR LANGUAGE BINDINGS @@ -4162,7 +4162,7 @@ the automake documentation for details. Runs a subset of the test suite under valgrind. -Any C<Makefile.am> in the tree that has a C<check-valgrind:> target +Any F<Makefile.am> in the tree that has a C<check-valgrind:> target will be run by this rule. =item C<make check-valgrind-local-guests> @@ -4199,7 +4199,7 @@ As above, you have to set C<LIBGUESTFS_HV> to point to the kernel. =item C<make check-with-upstream-qemu> Runs all tests using a local qemu binary. It looks for the qemu -binary in QEMUDIR (defaults to C<$HOME/d/qemu>), but you can set this +binary in QEMUDIR (defaults to F<$HOME/d/qemu>), but you can set this to another directory on the command line, eg: make check-with-upstream-qemu QEMUDIR=/usr/src/qemu @@ -4210,7 +4210,7 @@ Runs all tests using a local libvirt. This only has any effect if the libvirt backend was selected using C<./configure --with-default-backend=libvirt> -It looks for libvirt in LIBVIRTDIR (defaults to C<$HOME/d/libvirt>), +It looks for libvirt in LIBVIRTDIR (defaults to F<$HOME/d/libvirt>), but you can set this to another directory on the command line, eg: make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt @@ -4219,7 +4219,7 @@ but you can set this to another directory on the command line, eg: Runs some slow/long-running tests which are not run by default. -Any C<Makefile.am> in the tree that has a C<check-slow:> target will +Any F<Makefile.am> in the tree that has a C<check-slow:> target will be run by this rule. =item C<make check-all> @@ -4311,191 +4311,191 @@ the programmers. =over 4 -=item C<align> +=item F<align> L<virt-alignment-scan(1)> command and documentation. -=item C<appliance> +=item F<appliance> The libguestfs appliance, build scripts and so on. -=item C<bash> +=item F<bash> Bash tab-completion scripts. -=item C<build-aux> +=item F<build-aux> Various build scripts used by autotools. -=item C<builder> +=item F<builder> L<virt-builder(1)> command and documentation. -=item C<cat> +=item F<cat> The L<virt-cat(1)>, L<virt-filesystems(1)>, L<virt-log(1)> and L<virt-ls(1)> commands and documentation. -=item C<contrib> +=item F<contrib> Outside contributions, experimental parts. -=item C<customize> +=item F<customize> L<virt-customize(1)> command and documentation. -=item C<daemon> +=item F<daemon> The daemon that runs inside the libguestfs appliance and carries out actions. -=item C<df> +=item F<df> L<virt-df(1)> command and documentation. -=item C<diff> +=item F<diff> L<virt-diff(1)> command and documentation. -=item C<edit> +=item F<edit> L<virt-edit(1)> command and documentation. -=item C<examples> +=item F<examples> C API example code. -=item C<fish> +=item F<fish> L<guestfish(1)>, the command-line shell, and various shell scripts built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>, L<virt-tar-in(1)>, L<virt-tar-out(1)>. -=item C<format> +=item F<format> L<virt-format(1)> command and documentation. -=item C<fuse> +=item F<fuse> L<guestmount(1)>, FUSE (userspace filesystem) built on top of libguestfs. -=item C<generator> +=item F<generator> The crucially important generator, used to automatically generate large amounts of boilerplate C code for things like RPC and bindings. -=item C<gnulib> +=item F<gnulib> Gnulib is used as a portability library. A copy of gnulib is included under here. -=item C<html> +=item F<html> Generated HTML manual pages. -=item C<inspector> +=item F<inspector> L<virt-inspector(1)>, the virtual machine image inspector. -=item C<logo> +=item F<logo> Logo used on the website. The fish is called Arthur by the way. -=item C<m4> +=item F<m4> M4 macros used by autoconf. -=item C<make-fs> +=item F<make-fs> L<virt-make-fs(1)> command and documentation. -=item C<mllib> +=item F<mllib> Various libraries and common code used by L<virt-resize(1)> and the other tools which are written in OCaml. -=item C<p2v> +=item F<p2v> L<virt-p2v(1)> command, documentation and scripts for building the virt-p2v ISO or disk image. -=item C<po> +=item F<po> Translations of simple gettext strings. -=item C<po-docs> +=item F<po-docs> The build infrastructure and PO files for translations of manpages and -POD files. Eventually this will be combined with the C<po> directory, +POD files. Eventually this will be combined with the F<po> directory, but that is rather complicated. -=item C<rescue> +=item F<rescue> L<virt-rescue(1)> command and documentation. -=item C<resize> +=item F<resize> L<virt-resize(1)> command and documentation. -=item C<sparsify> +=item F<sparsify> L<virt-sparsify(1)> command and documentation. -=item C<src> +=item F<src> Source code to the C library. -=item C<sysprep> +=item F<sysprep> L<virt-sysprep(1)> command and documentation. -=item C<tests> +=item F<tests> Tests. -=item C<test-tool> +=item F<test-tool> Test tool for end users to test if their qemu/kernel combination will work with libguestfs. -=item C<tmp> +=item F<tmp> -Used for temporary files when running the tests (instead of C</tmp> +Used for temporary files when running the tests (instead of F</tmp> etc). The reason is so that you can run multiple parallel tests of libguestfs without having one set of tests overwriting the appliance created by another. -=item C<tools> +=item F<tools> Command line tools written in Perl (L<virt-win-reg(1)> and many others). -=item C<v2v> +=item F<v2v> L<virt-v2v(1)> command and documentation. -=item C<csharp> +=item F<csharp> -=item C<erlang> +=item F<erlang> -=item C<gobject> +=item F<gobject> -=item C<golang> +=item F<golang> -=item C<haskell> +=item F<haskell> -=item C<java> +=item F<java> -=item C<lua> +=item F<lua> -=item C<ocaml> +=item F<ocaml> -=item C<php> +=item F<php> -=item C<perl> +=item F<perl> -=item C<python> +=item F<python> -=item C<ruby> +=item F<ruby> Language bindings. @@ -4516,7 +4516,7 @@ Ubuntu. =item * -Finalize C<guestfs-release-notes.pod> +Finalize F<guestfs-release-notes.pod> =item * @@ -4530,7 +4530,7 @@ to push the latest POT files to Zanata. Then run: ./zanata-pull.sh -which is a wrapper to pull the latest translated C<*.po> files. +which is a wrapper to pull the latest translated F<*.po> files. =item * @@ -4543,7 +4543,7 @@ L<http://libguestfs.org/download>. =item * -Edit C<index.html.in> on website. +Edit F<index.html.in> on website. =item * @@ -4613,7 +4613,7 @@ to 31 slots, but some of these are used for other purposes. One virtual disk is used by libguestfs internally. Before libguestfs 1.19.7, disk names had to be a single character -(eg. C</dev/sda> through C</dev/sdz>), and since one disk is reserved, +(eg. F</dev/sda> through F</dev/sdz>), and since one disk is reserved, that meant the limit was 25. This has been fixed in more recent versions. @@ -4625,7 +4625,7 @@ L</HOTPLUGGING>. Virtio limits the maximum number of partitions per disk to B<15>. This is because it reserves 4 bits for the minor device number (thus -C</dev/vda>, and C</dev/vda1> through C</dev/vda15>). +F</dev/vda>, and F</dev/vda1> through F</dev/vda15>). If you attach a disk with more than 15 partitions, the extra partitions are ignored by libguestfs. @@ -4707,7 +4707,7 @@ using a supermin appliance. The appliance is cached and shared between all handles which have the same effective user ID. If C<LIBGUESTFS_CACHEDIR> is not set, then C<TMPDIR> is used. If -C<TMPDIR> is not set, then C</var/tmp> is used. +C<TMPDIR> is not set, then F</var/tmp> is used. See also L</LIBGUESTFS_TMPDIR>, L</guestfs_set_cachedir>. @@ -4746,7 +4746,7 @@ The location where libguestfs will store temporary files used by each handle. If C<LIBGUESTFS_TMPDIR> is not set, then C<TMPDIR> is used. If -C<TMPDIR> is not set, then C</tmp> is used. +C<TMPDIR> is not set, then F</tmp> is used. See also L</LIBGUESTFS_CACHEDIR>, L</guestfs_set_tmpdir>. diff --git a/sysprep/virt-sysprep.pod b/sysprep/virt-sysprep.pod index 2de46f2..ad24550 100644 --- a/sysprep/virt-sysprep.pod +++ b/sysprep/virt-sysprep.pod @@ -29,7 +29,7 @@ even in this case it would be better to change the permissions on the disk image to be writable as the non-root user running virt-sysprep. "Sysprep" stands for "system preparation" tool. The name comes from -the Microsoft program C<sysprep.exe> which is used to unconfigure +the Microsoft program F<sysprep.exe> which is used to unconfigure Windows machines in preparation for cloning them. Having said that, virt-sysprep does I<not> currently work on Microsoft Windows guests. We plan to support Windows sysprepping in a future version, and we @@ -159,12 +159,12 @@ For example: virt-sysprep --format raw -a disk.img -forces raw format (no auto-detection) for C<disk.img>. +forces raw format (no auto-detection) for F<disk.img>. virt-sysprep --format raw -a disk.img --format auto -a another.img -forces raw format (no auto-detection) for C<disk.img> and reverts to -auto-detection for C<another.img>. +forces raw format (no auto-detection) for F<disk.img> and reverts to +auto-detection for F<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 @@ -209,7 +209,7 @@ will mount the root directory with C<notime>. This example: --mount-options "/:noatime;/var:rw,nodiratime" -will do the same, plus mount C</var> with C<rw,nodiratime>. +will do the same, plus mount F</var> with C<rw,nodiratime>. =item B<-q> @@ -536,13 +536,13 @@ This can point to the directory containing data files used for Windows firstboot installation. Normally you do not need to set this. If not set, a compiled-in -default will be used (something like C</usr/share/virt-tools>). +default will be used (something like F</usr/share/virt-tools>). This directory may contain the following files: =over 4 -=item C<rhsrvany.exe> +=item F<rhsrvany.exe> This is the RHSrvAny Windows binary, used to install a "firstboot" script in Windows guests. It is required if you intend to use the diff --git a/v2v/test-harness/virt-v2v-test-harness.pod b/v2v/test-harness/virt-v2v-test-harness.pod index 965c4e9..77d459d 100644 --- a/v2v/test-harness/virt-v2v-test-harness.pod +++ b/v2v/test-harness/virt-v2v-test-harness.pod @@ -156,7 +156,7 @@ The test itself - see below. =head2 WRITING THE TEST -The test file (C<*.ml>) is used to control the test harness, and +The test file (F<*.ml>) is used to control the test harness, and minimally it would look something like this: open V2v_test_harness @@ -171,7 +171,7 @@ That would instruct the test harness to: =item * -Uncompress C<I<short_name>.img.xz> +Uncompress F<I<short_name>.img.xz> =item * @@ -201,7 +201,7 @@ page. To do that you have to supply a C<~test_plan> parameter: For an even better test, you can supply post-conversion and post-boot test cases which examine the disk image (using libguestfs) to verify that files have been created, modified or deleted as expected within -the disk image. See C<V2v_test_harness.mli> for more information on +the disk image. See F<V2v_test_harness.mli> for more information on how to do that. =head2 FILES GENERATED BY RUNNING THE TEST @@ -243,7 +243,7 @@ disk space. =over 4 -=item C<$ocamllibdir/v2v_test_harness/v2v_test_harness.mli> +=item F<$ocamllibdir/v2v_test_harness/v2v_test_harness.mli> The test library interface. Read this for detailed programming documentation. diff --git a/v2v/virt-v2v.pod b/v2v/virt-v2v.pod index b49de61..f5dfe24 100644 --- a/v2v/virt-v2v.pod +++ b/v2v/virt-v2v.pod @@ -88,7 +88,7 @@ locally under libvirt. In this case you will most likely have to run virt-v2v as C<root>, since it needs to talk to the system libvirt daemon and copy the guest -disks to C</var/lib/libvirt/images>. +disks to F</var/lib/libvirt/images>. For more information see L</INPUT FROM VMWARE VCENTER SERVER> below. @@ -126,8 +126,8 @@ run on KVM, you have two options. The simplest way is to try: virt-v2v -i disk disk.img -o local -os /var/tmp -where virt-v2v guesses everything about the input C<disk.img> and (in -this case) writes the converted result to C</var/tmp>. +where virt-v2v guesses everything about the input F<disk.img> and (in +this case) writes the converted result to F</var/tmp>. A more complex method is to write some L<libvirt XML|http://libvirt.org/formatdomain.html> describing the @@ -136,7 +136,7 @@ libvirt XML, then so much the better). You can then do: virt-v2v -i libvirtxml guest-domain.xml -o local -os /var/tmp -Since C<guest-domain.xml> contains the path(s) to the guest disk +Since F<guest-domain.xml> contains the path(s) to the guest disk image(s) you do not need to specify the name of the disk image on the command line. @@ -463,7 +463,7 @@ Set the output method to I<vdsm>. This mode is similar to I<-o rhev>, but the full path to the data domain must be given: -C</rhev/data-center/E<lt>data-center-uuidE<gt>/E<lt>data-domain-uuidE<gt>>. +F</rhev/data-center/E<lt>data-center-uuidE<gt>/E<lt>data-domain-uuidE<gt>>. This mode is only used when virt-v2v runs under VDSM control. =item B<-oa sparse> @@ -557,7 +557,7 @@ Choose the root filesystem to be converted. In the case where the virtual machine is dual-boot or multi-boot, or where the VM has other filesystems that look like operating systems, this option can be used to select the root filesystem (a.k.a. C<C:> -drive or C</>) of the operating system that is to be converted. The +drive or F</>) of the operating system that is to be converted. The Windows Recovery Console, certain attached DVD drives, and bugs in libguestfs inspection heuristics, can make a guest look like a multi-boot operating system. @@ -582,7 +582,7 @@ device, then virt-v2v will fail. Note that there is a bug in grub which prevents it from successfully booting a multiboot system if VirtIO is enabled. Grub is only able to boot an operating system from the first VirtIO disk. Specifically, -C</boot> must be on the first VirtIO disk, and it cannot chainload an +F</boot> must be on the first VirtIO disk, and it cannot chainload an OS which is not in the first VirtIO disk. =item B<--vdsm-image-uuid> UUID @@ -753,7 +753,7 @@ L<https://bugzilla.redhat.com/show_bug.cgi?id=244636> =head2 Boot failure: 0x0000007B This boot failure is caused by Windows being unable to find or load -the right disk driver (eg. C<viostor.sys>). If you experience this +the right disk driver (eg. F<viostor.sys>). If you experience this error, here are some things to check: =over 4 @@ -766,7 +766,7 @@ conversion. =item * Check you have the Windows virtio drivers available in -C</usr/share/virtio-win>, and that virt-v2v did not print any warning +F</usr/share/virtio-win>, and that virt-v2v did not print any warning about not being able to install virtio drivers. On S<Red Hat Enterprise Linux 7>, you will need to install the signed @@ -799,7 +799,7 @@ Policy-like prohibitions on installing or using new drivers. =item * -Enable boot debugging and check the C<viostor.sys> driver is being +Enable boot debugging and check the F<viostor.sys> driver is being loaded. =back @@ -1078,7 +1078,7 @@ contents. =head2 OVA: IMPORTING A GUEST -To import an OVA file called C<VM.ova>, do; +To import an OVA file called F<VM.ova>, do; $ virt-v2v -i ova VM.ova -o local -os /var/tmp @@ -1102,7 +1102,7 @@ Currently you must enable passwordless SSH access to the remote Xen host from the virt-v2v conversion server. You must also use ssh-agent, and add your ssh public key to -C</root/.ssh/authorized_keys> (on the Xen host). +F</root/.ssh/authorized_keys> (on the Xen host). After doing this, you should check that passwordless access works from the virt-v2v server to the Xen host. For example: @@ -1187,7 +1187,7 @@ metadata into a local temporary directory: virt-v2v [...] -o local -os /var/tmp -This creates two (or more) files in C</var/tmp> called: +This creates two (or more) files in F</var/tmp> called: /var/tmp/NAME.xml # the libvirt XML (metadata) /var/tmp/NAME-sda # the guest's first disk @@ -1204,7 +1204,7 @@ Upload the converted disk(s) into the storage pool called C<POOL>: =item 3. -Edit C</var/tmp/NAME.xml> to change C</var/tmp/NAME-sda> to the pool +Edit F</var/tmp/NAME.xml> to change F</var/tmp/NAME-sda> to the pool name. In other words, locate the following bit of XML: <disk type='file' device='disk'> @@ -1274,7 +1274,7 @@ possible. =head2 Disk space Virt-v2v places potentially large temporary files in C<$TMPDIR> (which -is C</var/tmp> if you don't set it). Using tmpfs is a bad idea. +is F</var/tmp> if you don't set it). Using tmpfs is a bad idea. For each guest disk, an overlay is stored temporarily. This stores the changes made during conversion, and is used as a cache. The @@ -1366,7 +1366,7 @@ to perform the conversion. Currently it checks: Minimum free space: 20 MB -=item Linux C</boot> +=item Linux F</boot> Minimum free space: 50 MB @@ -1412,7 +1412,7 @@ manually change ownership after virt-v2v has finished. When using I<-o libvirt>, you may need to run virt-v2v as root so that it can write to the libvirt system instance (ie. C<qemu:///system>) and to the default location for disk images (usually -C</var/lib/libvirt/images>). +F</var/lib/libvirt/images>). You can avoid this by setting up libvirt connection authentication, see L<http://libvirt.org/auth.html>. Alternatively, use @@ -1437,7 +1437,7 @@ generally hides the true reason for the failure. There are two log files of interest. The first is stored on the RHEV-M server itself, and is called -C</var/log/ovirt-engine/engine.log> +F</var/log/ovirt-engine/engine.log> The second file, which is the most useful, is found on the SPM host (SPM stands for "Storage Pool Manager"). This is a RHEV node that is @@ -1445,7 +1445,7 @@ elected to do all metadata modifications in the data center, such as image or snapshot creation. You can find out which host is the current SPM from the "Hosts" tab "Spm Status" column. Once you have located the SPM, log into it and grab the file -C</var/log/vdsm/vdsm.log> which will contain detailed error messages +F</var/log/vdsm/vdsm.log> which will contain detailed error messages from low-level commands. =head1 MINIMAL XML FOR -i libvirtxml OPTION @@ -1548,7 +1548,7 @@ option at all. The option was added when virt-v2v was rewritten in 2014. =over 4 -=item C</usr/share/virtio-win> +=item F</usr/share/virtio-win> (Optional) @@ -1575,13 +1575,13 @@ This can point to the directory containing data files used for Windows conversion. Normally you do not need to set this. If not set, a compiled-in -default will be used (something like C</usr/share/virt-tools>). +default will be used (something like F</usr/share/virt-tools>). This directory may contain the following files: =over 4 -=item C<rhsrvany.exe> +=item F<rhsrvany.exe> (Required when doing conversions of Windows guests) @@ -1590,7 +1590,7 @@ script in the guest during conversion of Windows guests. See also: C<https://github.com/rwmjones/rhsrvany> -=item C<rhev-apt.exe> +=item F<rhev-apt.exe> (Optional) -- 2.3.1

2 2

[PATCH] New API: btrfs_replace_start
by Pino Tsao 15 Jun '15

15 Jun '15

Signed-off-by: Pino Tsao <caoj.fnst(a)cn.fujitsu.com> --- daemon/btrfs.c | 40 +++++++++++++++++++++++++++++++++++++++ generator/actions.ml | 19 +++++++++++++++++++ tests/btrfs/test-btrfs-devices.sh | 8 ++++++++ 3 files changed, 67 insertions(+) diff --git a/daemon/btrfs.c b/daemon/btrfs.c index 39392f7..acc300d 100644 --- a/daemon/btrfs.c +++ b/daemon/btrfs.c @@ -2083,3 +2083,43 @@ do_btrfs_image (char *const *sources, const char *image, return 0; } + +int +do_btrfs_replace_start (const char *srcdev, const char *targetdev, + const char* mntpoint, int force) +{ + const size_t MAX_ARGS = 64; + const char *argv[MAX_ARGS]; + size_t i = 0; + CLEANUP_FREE char *err = NULL; + CLEANUP_FREE char *path_buf = NULL; + int r; + + path_buf = sysroot_path (mntpoint); + if (path_buf == NULL) { + reply_with_perror ("malloc"); + return -1; + } + + ADD_ARG (argv, i, str_btrfs); + ADD_ARG (argv, i, "replace"); + ADD_ARG (argv, i, "start"); + ADD_ARG (argv, i, srcdev); + ADD_ARG (argv, i, targetdev); + ADD_ARG (argv, i, path_buf); + ADD_ARG (argv, i, "-B"); + + if ((optargs_bitmask & GUESTFS_BTRFS_REPLACE_START_FORCE_BITMASK) && force) + ADD_ARG (argv, i, "-f"); + + ADD_ARG (argv, i, NULL); + + r = commandv (NULL, &err, argv); + if (r == -1) { + reply_with_error ("%s: %s", mntpoint, err); + return -1; + } + + return 0; +} + diff --git a/generator/actions.ml b/generator/actions.ml index 1a89869..4443600 100644 --- a/generator/actions.ml +++ b/generator/actions.ml @@ -12579,6 +12579,25 @@ numbered C<partnum> on device C<device>. It returns C<primary>, C<logical>, or C<extended>." }; + { defaults with + name = "btrfs_replace_start"; added = (1, 29, 46); + style = RErr, [Device "srcdev"; Device "targetdev"; Pathname "mntpoint"], [OBool "force"]; + proc_nr = Some 455; + optional = Some "btrfs"; camel_name = "BTRFSReplaceStart"; + test_excuse = "It is better to have 3+ test disk to do the test, so put the test in 'tests/btrfs' directory"; + shortdesc = "replace a btrfs managed device with another device"; + longdesc = "\ +Replace device of a btrfs filesystem. On a live filesystem, duplicate the data +to the target device which is currently stored on the source device. +After completion of the operation, the source device is wiped out and +removed from the filesystem. + +The <targetdev> needs to be same size or larger than the <srcdev>. Devices +which are currently mounted are never allowed to be used as the <targetdev> + +Option 'force=true' means using and overwriting <targetdev> even if +it looks like containing a valid btrfs filesystem." }; + ] (* Non-API meta-commands available only in guestfish. diff --git a/tests/btrfs/test-btrfs-devices.sh b/tests/btrfs/test-btrfs-devices.sh index 3935c60..463b0a8 100755 --- a/tests/btrfs/test-btrfs-devices.sh +++ b/tests/btrfs/test-btrfs-devices.sh @@ -66,6 +66,8 @@ btrfs-device-add "/dev/sdc1 /dev/sdd1" / btrfs-device-delete "/dev/sdb1" / btrfs-device-add "/dev/sdb1" / btrfs-device-delete "/dev/sdc1 /dev/sdd1" / +btrfs-replace-start "/dev/sda1" "/dev/sdd1" / force:true +btrfs-replace-start "/dev/sdd1" "/dev/sda1" / force:true mkdir /data2 tar-in $srcdir/../data/filesanddirs-10M.tar.xz /data2 compress:xz @@ -74,6 +76,8 @@ btrfs-device-add "/dev/sdc1 /dev/sdd1" / btrfs-device-delete "/dev/sdb1" / btrfs-device-add "/dev/sdb1" / btrfs-device-delete "/dev/sdc1 /dev/sdd1" / +btrfs-replace-start "/dev/sda1" "/dev/sdd1" / force:true +btrfs-replace-start "/dev/sdd1" "/dev/sda1" / force:true mkdir /data3 tar-in $srcdir/../data/filesanddirs-10M.tar.xz /data3 compress:xz @@ -82,6 +86,8 @@ btrfs-device-add "/dev/sdc1 /dev/sdd1" / btrfs-device-delete "/dev/sdb1" / btrfs-device-add "/dev/sdb1" / btrfs-device-delete "/dev/sdc1 /dev/sdd1" / +btrfs-replace-start "/dev/sda1" "/dev/sdd1" / force:true +btrfs-replace-start "/dev/sdd1" "/dev/sda1" / force:true mkdir /data4 tar-in $srcdir/../data/filesanddirs-10M.tar.xz /data4 compress:xz @@ -90,6 +96,8 @@ btrfs-device-add "/dev/sdc1 /dev/sdd1" / btrfs-device-delete "/dev/sdb1" / btrfs-device-add "/dev/sdb1" / btrfs-device-delete "/dev/sdc1 /dev/sdd1" / +btrfs-replace-start "/dev/sda1" "/dev/sdd1" / force:true +btrfs-replace-start "/dev/sdd1" "/dev/sda1" / force:true EOF -- 2.1.0

4 6

[PATCH v2] btrfs: use CLEANUP_FREE_STRING_LIST for list free
by Chen Hanxiao 12 Jun '15

12 Jun '15

As Pino's comment, we should take advantage of macro CLEANUP_FREE_STRING_LIST. Signed-off-by: Chen Hanxiao <chenhanxiao(a)cn.fujitsu.com> --- v2: initialize variable of CLEANUP_FREE_STRING_LIST to null daemon/btrfs.c | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/daemon/btrfs.c b/daemon/btrfs.c index 39392f7..3ca39ab 100644 --- a/daemon/btrfs.c +++ b/daemon/btrfs.c @@ -409,7 +409,7 @@ umount (char *fs_buf, const mountable_t *fs) guestfs_int_btrfssubvolume_list * do_btrfs_subvolume_list (const mountable_t *fs) { - char **lines; + CLEANUP_FREE_STRING_LIST char **lines = NULL; size_t i = 0; const size_t MAX_ARGS = 64; const char *argv[MAX_ARGS]; @@ -534,13 +534,11 @@ do_btrfs_subvolume_list (const mountable_t *fs) this->btrfssubvolume_path = line; } - free (lines); pcre_free (re); return ret; error: - free_stringslen (lines, nr_subvolumes); if (ret) free (ret->guestfs_int_btrfssubvolume_list_val); free (ret); if (re) pcre_free (re); @@ -1253,8 +1251,8 @@ do_btrfs_qgroup_show (const char *path) CLEANUP_FREE char *path_buf = NULL; CLEANUP_FREE char *err = NULL; CLEANUP_FREE char *out = NULL; + CLEANUP_FREE_STRING_LIST char **lines = NULL; int r; - char **lines; path_buf = sysroot_path (path); if (path_buf == NULL) { @@ -1323,11 +1321,9 @@ do_btrfs_qgroup_show (const char *path) this->btrfsqgroup_id = line; } - free (lines); return ret; error: - free_stringslen (lines, nr_qgroups + 2); if (ret) free (ret->guestfs_int_btrfsqgroup_list_val); free (ret); @@ -1704,10 +1700,10 @@ do_btrfs_balance_status (const char *path) size_t i = 0; CLEANUP_FREE char *path_buf = NULL; CLEANUP_FREE char *err = NULL; + CLEANUP_FREE_STRING_LIST char **lines = NULL; char *out; int r; guestfs_int_btrfsbalance *ret; - char **lines; size_t nlines; const char *errptr; int erroffset; @@ -1830,10 +1826,10 @@ do_btrfs_scrub_status (const char *path) size_t i = 0; CLEANUP_FREE char *path_buf = NULL; CLEANUP_FREE char *err = NULL; + CLEANUP_FREE_STRING_LIST char **lines = NULL; char *out; int r; guestfs_int_btrfsscrub *ret; - char **lines; path_buf = sysroot_path (path); if (path_buf == NULL) { -- 2.1.0

2 1

[PATCH] btrfs: use CLEANUP_FREE_STRING_LIST for list free
by Chen Hanxiao 12 Jun '15

12 Jun '15

As Pino's comment, we should take advantage of macro CLEANUP_FREE_STRING_LIST. Signed-off-by: Chen Hanxiao <chenhanxiao(a)cn.fujitsu.com> --- daemon/btrfs.c | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/daemon/btrfs.c b/daemon/btrfs.c index 39392f7..fd93d43 100644 --- a/daemon/btrfs.c +++ b/daemon/btrfs.c @@ -409,7 +409,7 @@ umount (char *fs_buf, const mountable_t *fs) guestfs_int_btrfssubvolume_list * do_btrfs_subvolume_list (const mountable_t *fs) { - char **lines; + CLEANUP_FREE_STRING_LIST char **lines; size_t i = 0; const size_t MAX_ARGS = 64; const char *argv[MAX_ARGS]; @@ -534,13 +534,11 @@ do_btrfs_subvolume_list (const mountable_t *fs) this->btrfssubvolume_path = line; } - free (lines); pcre_free (re); return ret; error: - free_stringslen (lines, nr_subvolumes); if (ret) free (ret->guestfs_int_btrfssubvolume_list_val); free (ret); if (re) pcre_free (re); @@ -1254,7 +1252,7 @@ do_btrfs_qgroup_show (const char *path) CLEANUP_FREE char *err = NULL; CLEANUP_FREE char *out = NULL; int r; - char **lines; + CLEANUP_FREE_STRING_LIST char **lines; path_buf = sysroot_path (path); if (path_buf == NULL) { @@ -1323,11 +1321,9 @@ do_btrfs_qgroup_show (const char *path) this->btrfsqgroup_id = line; } - free (lines); return ret; error: - free_stringslen (lines, nr_qgroups + 2); if (ret) free (ret->guestfs_int_btrfsqgroup_list_val); free (ret); @@ -1707,7 +1703,7 @@ do_btrfs_balance_status (const char *path) char *out; int r; guestfs_int_btrfsbalance *ret; - char **lines; + CLEANUP_FREE_STRING_LIST char **lines; size_t nlines; const char *errptr; int erroffset; @@ -1833,7 +1829,7 @@ do_btrfs_scrub_status (const char *path) char *out; int r; guestfs_int_btrfsscrub *ret; - char **lines; + CLEANUP_FREE_STRING_LIST char **lines; path_buf = sysroot_path (path); if (path_buf == NULL) { -- 2.1.0

2 1

[PATCH] New API: btrfs_filesystem_show_all
by Chen Hanxiao 11 Jun '15

11 Jun '15

Signed-off-by: Chen Hanxiao <chenhanxiao(a)cn.fujitsu.com> --- daemon/btrfs.c | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++ generator/actions.ml | 19 ++++++ generator/structs.ml | 13 ++++ src/MAX_PROC_NR | 2 +- 4 files changed, 209 insertions(+), 1 deletion(-) diff --git a/daemon/btrfs.c b/daemon/btrfs.c index 39392f7..09f7615 100644 --- a/daemon/btrfs.c +++ b/daemon/btrfs.c @@ -2083,3 +2083,179 @@ do_btrfs_image (char *const *sources, const char *image, return 0; } + +guestfs_int_btrfsfsshow_list * +do_btrfs_filesystem_show_all (void) +{ + const size_t MAX_ARGS = 64; + const char *argv[MAX_ARGS]; + size_t i = 0; + size_t nr_filesystem_show = 0; + CLEANUP_FREE char *err = NULL; + char *out = NULL; + char **lines; + int r; + /* Info from Label line will be reused for the following devid line + * make two temp space to hold them */ + char *label_tmp = NULL, *uuid_tmp = NULL; + + ADD_ARG (argv, i, str_btrfs); + ADD_ARG (argv, i, "filesystem"); + ADD_ARG (argv, i, "show"); + ADD_ARG (argv, i, NULL); + + r = commandv (&out, &err, argv); + if (r == -1) { + reply_with_error ("%s", err); + free(out); + return NULL; + } + + lines = split_lines (out); + if (!lines) + return NULL; + + size_t nlines = count_strings (lines); + for (i = 0; i < nlines; i++) + if (strstr(lines[i], "\tdevid")) + nr_filesystem_show++; + + guestfs_int_btrfsfsshow_list *ret = NULL; + ret = malloc(sizeof *ret); + if (ret == NULL) { + reply_with_perror ("malloc"); + return NULL; + } + + /* No btrfs fs found, return directly */ + if (nr_filesystem_show == 0) { + memset (ret, 0, sizeof(*ret)); + return ret; + } + + ret->guestfs_int_btrfsfsshow_list_len = nr_filesystem_show; + ret->guestfs_int_btrfsfsshow_list_val = + calloc (nr_filesystem_show, sizeof (struct guestfs_int_btrfsfsshow)); + if (ret->guestfs_int_btrfsfsshow_list_val == NULL) { + reply_with_perror ("calloc"); + goto error; + } + + /* Output of `btrfs filesystem show' is like: + * + * Label: none uuid: e34452fa-5444-4e7b-9faa-c26fa1b83686 + * Total devices 1 FS bytes used 176.00KiB + * devid 1 size 1.00GiB used 236.00MiB path /dev/sda6 + * + * Label: none uuid: 9cdb73b9-d5b9-46c4-9395-25a952e7922a + * Total devices 5 FS bytes used 112.00KiB + * devid 1 size 10.00GiB used 1.02GiB path /dev/sdb + * devid 2 size 10.00GiB used 2.00GiB path /dev/sdd + * devid 3 size 10.00GiB used 2.00GiB path /dev/sde + * + * Btrfs v3.18.2 + * + * + * If no btrfs device found, output is like: + * + * Btrfs v3.18.2 + * + */ + if (nlines < 1) { + reply_with_perror ("No filesystem show output"); + return NULL; + } + + char *p, *p1; + size_t k; + + for (i = 0, k = 0; i < nlines - 2; i++) { + char *line = lines[i]; + + struct guestfs_int_btrfsfsshow *this = + &ret->guestfs_int_btrfsfsshow_list_val[k]; + if (STRPREFIX(line, "Label")) { + if ((p = strstr (line, "uuid")) == NULL) { + reply_with_error ("No uuid field found"); + return NULL; + } + p1 = lines[i] + strlen("Label: "); + if ((p - p1) < 1) { + reply_with_error ("No Label field found"); + return NULL; + } + + if (label_tmp) { + free (label_tmp); + label_tmp = NULL; + } + if (uuid_tmp) { + free (uuid_tmp); + uuid_tmp = NULL; + } + + p += strlen ("uuid: "); + uuid_tmp = strdup(p); + p -= strlen ("uuid: "); + *p = '\0'; + label_tmp = strdup(p1); + continue; + } + + if (STRPREFIX (line, "\tdevid")) { + if ((this->btrfsfsshow_uuid = strdup (uuid_tmp)) == NULL) + goto error; + if ((this->btrfsfsshow_label = strdup (label_tmp)) == NULL) + goto error; + + if ((p = strstr (lines[i], "path ")) == NULL) { + reply_with_error ("No path field found"); + goto error; + } + p += strlen ("path "); + if ((this->btrfsfsshow_device = strdup (p)) == NULL) + goto error; + if (sscanf (line, "\tdevid %4d size %9s used %9s path", + &this->btrfsfsshow_devid, + this->btrfsfsshow_total_bytes, + this->btrfsfsshow_bytes_used) != 3) { + reply_with_error ("cannot parse output of filesystem show command: %s", line); + goto error; + } + k++; + } + } + + if (label_tmp) + free (label_tmp); + if (uuid_tmp) + free (uuid_tmp); + free (lines); + + return ret; + +error: + free_stringslen (lines, nlines); + if (label_tmp) + free (label_tmp); + if (uuid_tmp) + free (uuid_tmp); + + for (i = 0; i < nr_filesystem_show; i++) { + struct guestfs_int_btrfsfsshow *this_new = + &ret->guestfs_int_btrfsfsshow_list_val[i]; + + if (this_new->btrfsfsshow_label) + free (this_new->btrfsfsshow_label); + if (this_new->btrfsfsshow_uuid) + free (this_new->btrfsfsshow_uuid); + if (this_new->btrfsfsshow_device) + free (this_new->btrfsfsshow_device); + } + + if (ret) + free (ret->guestfs_int_btrfsfsshow_list_val); + free (ret); + + return NULL; +} diff --git a/generator/actions.ml b/generator/actions.ml index 7252295..26f9083 100644 --- a/generator/actions.ml +++ b/generator/actions.ml @@ -12593,6 +12593,25 @@ numbered C<partnum> on device C<device>. It returns C<primary>, C<logical>, or C<extended>." }; + { defaults with + name = "btrfs_filesystem_show_all"; added = (1, 29, 46); + style = RStructList ("fsshow", "btrfsfsshow"), [], []; + (*style = RString "output", [], [OString "device"];*) + proc_nr = Some 455; + tests = [ + InitPartition, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mkfs_btrfs"; "/dev/sda1 /dev/sda2"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mkfs_btrfs"; "/dev/sdb"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_filesystem_show_all"]]), []; + ]; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemShowAll"; + shortdesc = "show all devices run btrfs filesystem with some additional info"; + longdesc = "\ +This show all devices run btrfs filesystem with some additional info." }; + ] (* Non-API meta-commands available only in guestfish. diff --git a/generator/structs.ml b/generator/structs.ml index ea110a1..80f03ae 100644 --- a/generator/structs.ml +++ b/generator/structs.ml @@ -374,6 +374,19 @@ let structs = [ ]; s_camel_name = "BTRFSScrub" }; + (* btrfs filesystem show output *) + { defaults with + s_name = "btrfsfsshow"; + s_cols = [ + "btrfsfsshow_label", FString; + "btrfsfsshow_uuid", FString; + "btrfsfsshow_devid", FUInt32; + "btrfsfsshow_total_bytes", FUUID; + "btrfsfsshow_bytes_used", FUUID; + "btrfsfsshow_device", FString; + ]; + s_camel_name = "BTRFSFilesystemShowAll" }; + (* XFS info descriptor. *) { defaults with s_name = "xfsinfo"; diff --git a/src/MAX_PROC_NR b/src/MAX_PROC_NR index 515f19a..4930863 100644 --- a/src/MAX_PROC_NR +++ b/src/MAX_PROC_NR @@ -1 +1 @@ -454 +455 -- 2.1.0

3 3

[PATCH] podwrapper: simplify external references pointing to self
by Pino Toscano 09 Jun '15

09 Jun '15

When convering a POD documentation, possibily combining various sub-documents together, simplify the L<> links that explicitly point to the very same documentation being generated. For example, when generating the virt-builder documentation, links like L<virt-builder(1)/SECTION> will be turned into L</SECTION> thus not making Pod::Simple parse them as external reference. While it is a slightly crude hack, it seems there's no easy way to process the link parsing with Pod::Simple subclasses. --- podwrapper.pl.in | 3 +++ 1 file changed, 3 insertions(+) diff --git a/podwrapper.pl.in b/podwrapper.pl.in index 0bb7b28..b354db6 100755 --- a/podwrapper.pl.in +++ b/podwrapper.pl.in @@ -278,6 +278,9 @@ foreach (@inserts) { if $content eq $oldcontent; } +# Turn external links to this man page into simple cross-section links. +$content =~ s,\QL<$name($section)/\E,L</,g; + # Perform @verbatims. foreach (@verbatims) { my @a = split /:/, $_, 2; -- 2.1.0

2 3

[PATCH] qemu-sanity-check.in: Use '-display none' instead of '-nographic'
by Kashyap Chamarthy 08 Jun '15

08 Jun '15

Upstream QEMU recommends to use '-display none' as opposed to '-nographic' -- which is a "legacy option that does a whole bunch of confusing stuff" (thanks Peter Maydell). Upstream libguestfs already made the switch [1] in DEC-2013. [1] https://github.com/libguestfs/libguestfs/commit/7a41f5c1 -- "launch: switch from -nographic to -display none " --- qemu-sanity-check.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/qemu-sanity-check.in b/qemu-sanity-check.in index 5bb5b292def5caff5ca63071565bd447cf5f4efd..34cd9385f56b5eedd0ec26abd128232a47e51996 100644 --- a/qemu-sanity-check.in +++ b/qemu-sanity-check.in @@ -140,7 +140,8 @@ test_output="$(mktemp --suff=.out)" declare -a argv i=0 argv[$((i++))]="$qemu" -argv[$((i++))]="-nographic" +argv[$((i++))]="-display" +argv[$((i++))]="none" argv[$((i++))]="-nodefconfig" argv[$((i++))]="-nodefaults" argv[$((i++))]="-machine" -- 2.1.0

1 1

[PATCH] Use safe_realloc() in favor of realloc overall.
by Nikos Skalkotos 06 Jun '15

06 Jun '15

--- src/inspect-fs-unix.c | 22 +++++++--------------- src/inspect-fs.c | 21 ++++++--------------- 2 files changed, 13 insertions(+), 30 deletions(-) diff --git a/src/inspect-fs-unix.c b/src/inspect-fs-unix.c index 8ffd85d..c9bbad9 100644 --- a/src/inspect-fs-unix.c +++ b/src/inspect-fs-unix.c @@ -90,8 +90,8 @@ static int check_hostname_unix (guestfs_h *g, struct inspect_fs *fs); static int check_hostname_redhat (guestfs_h *g, struct inspect_fs *fs); static int check_hostname_freebsd (guestfs_h *g, struct inspect_fs *fs); static int check_fstab (guestfs_h *g, struct inspect_fs *fs); -static int add_fstab_entry (guestfs_h *g, struct inspect_fs *fs, - const char *mountable, const char *mp); +static void add_fstab_entry (guestfs_h *g, struct inspect_fs *fs, + const char *mountable, const char *mp); static char *resolve_fstab_device (guestfs_h *g, const char *spec, Hash_table *md_map, enum inspect_os_type os_type); @@ -850,8 +850,7 @@ guestfs_int_check_coreos_root (guestfs_h *g, struct inspect_fs *fs) /* CoreOS does not contain /etc/fstab to determine the mount points. * Associate this filesystem with the "/" mount point. */ - if (add_fstab_entry (g, fs, fs->mountable, "/") == -1) - return -1; + add_fstab_entry (g, fs, fs->mountable, "/"); return 0; } @@ -880,8 +879,7 @@ guestfs_int_check_coreos_usr (guestfs_h *g, struct inspect_fs *fs) /* CoreOS does not contain /etc/fstab to determine the mount points. * Associate this filesystem with the "/usr" mount point. */ - if (add_fstab_entry (g, fs, fs->mountable, "/usr") == -1) - return -1; + add_fstab_entry (g, fs, fs->mountable, "/usr"); return 0; } @@ -1197,7 +1195,7 @@ check_fstab (guestfs_h *g, struct inspect_fs *fs) } } - if (add_fstab_entry (g, fs, mountable, mp) == -1) return -1; + add_fstab_entry (g, fs, mountable, mp); } return 0; @@ -1211,7 +1209,7 @@ check_fstab (guestfs_h *g, struct inspect_fs *fs) * * 'mp' is the mount point, which could also be 'swap' or 'none'. */ -static int +static void add_fstab_entry (guestfs_h *g, struct inspect_fs *fs, const char *mountable, const char *mountpoint) { @@ -1222,11 +1220,7 @@ add_fstab_entry (guestfs_h *g, struct inspect_fs *fs, size_t n = fs->nr_fstab + 1; struct inspect_fstab_entry *p; - p = realloc (fs->fstab, n * sizeof (struct inspect_fstab_entry)); - if (p == NULL) { - perrorf (g, "realloc"); - return -1; - } + p = safe_realloc (g, fs->fstab, n * sizeof (struct inspect_fstab_entry)); fs->fstab = p; fs->nr_fstab = n; @@ -1236,8 +1230,6 @@ add_fstab_entry (guestfs_h *g, struct inspect_fs *fs, fs->fstab[n-1].mountpoint = safe_strdup (g, mountpoint); debug (g, "fstab: mountable=%s mountpoint=%s", mountable, mountpoint); - - return 0; } /* Compute a uuid hash as a simple xor of of its 4 32bit components */ diff --git a/src/inspect-fs.c b/src/inspect-fs.c index 09a7005..073ae57 100644 --- a/src/inspect-fs.c +++ b/src/inspect-fs.c @@ -47,7 +47,7 @@ COMPILE_REGEXP (re_major_minor, "(\\d+)\\.(\\d+)", 0) static int check_filesystem (guestfs_h *g, const char *mountable, const struct guestfs_internal_mountable *m, int whole_device); -static int extend_fses (guestfs_h *g); +static void extend_fses (guestfs_h *g); static int get_partition_context (guestfs_h *g, const char *partition, int *partnum_ret, int *nr_partitions_ret); /* Find out if 'device' contains a filesystem. If it does, add @@ -75,8 +75,7 @@ guestfs_int_check_for_filesystem_on (guestfs_h *g, const char *mountable) mountable, vfs_type ? vfs_type : "failed to get vfs type"); if (is_swap) { - if (extend_fses (g) == -1) - return -1; + extend_fses (g); fs = &g->fses[g->nr_fses-1]; fs->mountable = safe_strdup (g, mountable); return 0; @@ -95,8 +94,7 @@ guestfs_int_check_for_filesystem_on (guestfs_h *g, const char *mountable) } if (whole_device) { - if (extend_fses (g) == -1) - return -1; + extend_fses (g); fs = &g->fses[g->nr_fses-1]; r = guestfs_int_check_installer_iso (g, fs, m->im_device); @@ -145,8 +143,7 @@ check_filesystem (guestfs_h *g, const char *mountable, /* Not CLEANUP_FREE, as it will be cleaned up with inspection info */ char *windows_systemroot = NULL; - if (extend_fses (g) == -1) - return -1; + extend_fses (g); if (!whole_device && m->im_type == MOUNTABLE_DEVICE && guestfs_int_is_partition (g, m->im_device)) { @@ -331,24 +328,18 @@ check_filesystem (guestfs_h *g, const char *mountable, return 0; } -static int +static void extend_fses (guestfs_h *g) { size_t n = g->nr_fses + 1; struct inspect_fs *p; - p = realloc (g->fses, n * sizeof (struct inspect_fs)); - if (p == NULL) { - perrorf (g, "realloc"); - return -1; - } + p = safe_realloc (g, g->fses, n * sizeof (struct inspect_fs)); g->fses = p; g->nr_fses = n; memset (&g->fses[n-1], 0, sizeof (struct inspect_fs)); - - return 0; } /* Given a partition (eg. /dev/sda2) then return the partition number -- 2.1.0

3 3

[PATCH] sysprep_operation: fix a typo
by Chen Hanxiao 06 Jun '15

06 Jun '15

s/rathern/rather Signed-off-by: Chen Hanxiao <chenhanxiao(a)cn.fujitsu.com> --- sysprep/sysprep_operation.ml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sysprep/sysprep_operation.ml b/sysprep/sysprep_operation.ml index 5bc1efa..af2004e 100644 --- a/sysprep/sysprep_operation.ml +++ b/sysprep/sysprep_operation.ml @@ -279,7 +279,7 @@ let perform_operations_on_filesystems ?operations g root | Some opset -> (* just the operation names listed *) OperationSet.elements opset in - (* Perform the operations in alphabetical, rathern than random order. *) + (* Perform the operations in alphabetical, rather than random order. *) let ops = List.sort compare_operations ops in List.iter ( @@ -300,7 +300,7 @@ let perform_operations_on_devices ?operations g root | Some opset -> (* just the operation names listed *) OperationSet.elements opset in - (* Perform the operations in alphabetical, rathern than random order. *) + (* Perform the operations in alphabetical, rather than random order. *) let ops = List.sort compare_operations ops in List.iter ( -- 2.1.0

2 1