1guestfs-hacking(1) Virtualization Support guestfs-hacking(1)
2
6 guestfs-hacking - extending and contributing to libguestfs
7
9 This manual page is for hackers who want to extend libguestfs itself.
10
12 Libguestfs source is located in the github repository
13 https://github.com/libguestfs/libguestfs
14 Large amounts of boilerplate code in libguestfs (RPC, bindings,
16 documentation) are generated. This means that many source files will
17 appear to be missing from a straightforward git checkout. You have to
18 run the generator ("./autogen.sh && make -C generator") in order to
19 create those files.
20 Libguestfs uses an autotools-based build system, with the main files
22 being configure.ac and Makefile.am. See "THE BUILD SYSTEM".
23 The generator subdirectory contains the generator, plus files
25 describing the API. The lib subdirectory contains source for the
26 library. The appliance and daemon subdirectories contain the source
27 for the code that builds the appliance, and the code that runs in the
28 appliance respectively. Other directories are covered in the section
29 "SOURCE CODE SUBDIRECTORIES" below.
30 Apart from the fact that all API entry points go via some generated
32 code, the library is straightforward. (In fact, even the generated
33 code is designed to be readable, and should be read as ordinary code).
34 Some actions run entirely in the library, and are written as C
35 functions in files under lib. Others are forwarded to the daemon where
36 (after some generated RPC marshalling) they appear as C functions in
37 files under daemon.
38 To build from source, first read the guestfs-building(1).
40 SOURCE CODE SUBDIRECTORIES
42 There are a lot of subdirectories in the source tree! Which ones
43 should you concentrate on first? lib and daemon which contain the
44 source code of the core library. generator is the code generator
45 described above, so that is important. The Makefile.am in the root
46 directory will tell you in which order the subdirectories get built.
47 And then if you are looking at a particular tool (eg. v2v) or language
48 binding (eg. python), go straight to that subdirectory, but remember
49 that if you didn't run the generator yet, then you may find files which
50 appear to be missing.
51 align
53 virt-alignment-scan(1) command and documentation.
54 appliance
56 The libguestfs appliance, build scripts and so on.
57 bash
59 Bash tab-completion scripts.
60 build-aux
62 Various build scripts used by autotools.
63 builder
65 virt-builder(1) command and documentation.
66 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
68 virt-tail(1) commands and documentation.
69 common
71 Various libraries of internal code can be found in the common
72 subdirectory:
73 common/edit
75 Common code for interactively and non-interactively editing
76 files within a libguestfs filesystem.
77 common/errnostring
79 The communication protocol used between the library and the
80 daemon running inside the appliance has to encode errnos as
81 strings, which is handled by this library.
82 common/miniexpect
84 A copy of the miniexpect library from
85 http://git.annexia.org/?p=miniexpect.git;a=summary. This is
86 used in virt-p2v.
87 common/mlaugeas
89 Bindings for the Augeas library. These come from the ocaml-
90 augeas library http://git.annexia.org/?p=ocaml-augeas.git
91 common/mlgettext
93 Small, generated wrapper which allows libguestfs to be compiled
94 with or without ocaml-gettext. This is generated by
95 ./configure.
96 common/mlpcre
98 Lightweight OCaml bindings for Perl Compatible Regular
99 Expressions (PCRE). Note this is not related in any way to
100 Markus Mottl's ocaml-pcre library.
101 common/mlprogress
103 OCaml bindings for the progress bar functions (see
104 common/progress).
105 common/mlstdutils
107 A library of pure OCaml utility functions used in many places.
108 common/mltools
110 OCaml utility functions only used by the OCaml virt tools (like
111 "virt-sysprep", "virt-v2v" etc.)
112 common/mlutils
114 OCaml bindings for C functions in "common/utils", and some
115 POSIX bindings which are missing from the OCaml stdlib.
116 common/mlvisit
118 OCaml bindings for the visit functions (see common/visit).
119 common/mlxml
121 OCaml bindings for the libxml2 library.
122 common/options
124 Common options parsing for guestfish, guestmount and some virt
125 tools.
126 common/parallel
128 A framework used for processing multiple libvirt domains in
129 parallel.
130 common/progress
132 Common code for printing progress bars.
133 common/protocol
135 The XDR-based communication protocol used between the library
136 and the daemon running inside the appliance is defined here.
137 common/qemuopts
139 Mini-library for writing qemu command lines and qemu config
140 files.
141 common/structs
143 Common code for printing and freeing libguestfs structs, used
144 by the library and some tools.
145 common/utils
147 Various utility functions used throughout the library and
148 tools.
149 common/visit
151 Recursively visit a guestfs filesystem hierarchy.
152 common/windows
154 Utility functions for handling Windows drive letters.
155 contrib
157 Outside contributions, experimental parts.
158 customize
160 virt-customize(1) command and documentation.
161 daemon
163 The daemon that runs inside the libguestfs appliance and carries
164 out actions.
165 df virt-df(1) command and documentation.
167 dib virt-dib(1) command and documentation.
169 diff
171 virt-diff(1) command and documentation.
172 docs
174 Miscellaneous manual pages.
175 edit
177 virt-edit(1) command and documentation.
178 examples
180 C API example code.
181 fish
183 guestfish(1), the command-line shell, and various shell scripts
184 built on top such as virt-copy-in(1), virt-copy-out(1),
185 virt-tar-in(1), virt-tar-out(1).
186 format
188 virt-format(1) command and documentation.
189 fuse
191 guestmount(1), FUSE (userspace filesystem) built on top of
192 libguestfs.
193 generator
195 The crucially important generator, used to automatically generate
196 large amounts of boilerplate C code for things like RPC and
197 bindings.
198 get-kernel
200 virt-get-kernel(1) command and documentation.
201 gnulib
203 Gnulib is used as a portability library. A copy of gnulib is
204 included under here.
205 inspector
207 virt-inspector(1), the virtual machine image inspector.
208 lib Source code to the C library.
210 logo
212 Logo used on the website. The fish is called Arthur by the way.
213 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
215 make-fs
217 virt-make-fs(1) command and documentation.
218 p2v virt-p2v(1) command, documentation and scripts for building the
220 virt-p2v ISO or disk image.
221 po Translations of simple gettext strings.
223 po-docs
225 The build infrastructure and PO files for translations of manpages
226 and POD files. Eventually this will be combined with the po
227 directory, but that is rather complicated.
228 rescue
230 virt-rescue(1) command and documentation.
231 resize
233 virt-resize(1) command and documentation.
234 sparsify
236 virt-sparsify(1) command and documentation.
237 sysprep
239 virt-sysprep(1) command and documentation.
240 tests
242 Tests.
243 test-data
245 Files and other test data used by the tests.
246 test-tool
248 Test tool for end users to test if their qemu/kernel combination
249 will work with libguestfs.
250 tmp Used for temporary files when running the tests (instead of /tmp
252 etc). The reason is so that you can run multiple parallel tests of
253 libguestfs without having one set of tests overwriting the
254 appliance created by another.
255 tools
257 Command line tools written in Perl (virt-win-reg(1) and many
258 others).
259 utils
261 Miscellaneous utilities, such as "boot-benchmark".
262 v2v virt-v2v(1) command and documentation.
264 website
266 The http://libguestfs.org website files.
267 csharp
269 erlang
270 gobject
271 golang
272 haskell
273 java
274 lua
275 ocaml
276 php
277 perl
278 python
279 ruby
280 Language bindings.
281 THE BUILD SYSTEM
283 Libguestfs uses the GNU autotools build system (autoconf, automake,
284 libtool).
285 The ./configure script is generated from configure.ac and
287 m4/guestfs-*.m4. Most of the configure script is split over many m4
288 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
289 dependencies of the daemon.
290 The job of the top level Makefile.am is mainly to list the
292 subdirectories ("SUBDIRS") in the order they should be compiled.
293 common-rules.mk is included in every Makefile.am (top level and
295 subdirectories). subdir-rules.mk is included only in subdirectory
296 Makefile.am files.
297 There are many make targets. Use this command to list them all:
299 make help
301
303 ADDING A NEW API
304 Because large amounts of boilerplate code in libguestfs are generated,
305 this makes it easy to extend the libguestfs API.
306 To add a new API action there are two changes:
308 1. You need to add a description of the call (name, parameters, return
310 type, tests, documentation) to generator/actions_*.ml and possibly
311 generator/proc_nr.ml.
312 There are two sorts of API action, depending on whether the call
314 goes through to the daemon in the appliance, or is serviced
315 entirely by the library (see "ARCHITECTURE" in
316 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
317 of the former, since the sync is done in the appliance.
318 "guestfs_set_trace" in guestfs(3) is an example of the latter,
319 since a trace flag is maintained in the handle and all tracing is
320 done on the library side.
321 Most new actions are of the first type, and get added to the
323 "daemon_functions" list. Each function has a unique procedure
324 number used in the RPC protocol which is assigned to that action
325 when we publish libguestfs and cannot be reused. Take the latest
326 procedure number and increment it.
327 For library-only actions of the second type, add to the
329 "non_daemon_functions" list. Since these functions are serviced by
330 the library and do not travel over the RPC mechanism to the daemon,
331 these functions do not need a procedure number, and so the
332 procedure number is set to "-1".
333 2. Implement the action (in C):
335 For daemon actions, implement the function "do_<name>" in the
337 "daemon/" directory.
338 For library actions, implement the function "guestfs_impl_<name>"
340 in the "lib/" directory.
341 In either case, use another function as an example of what to do.
343 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
345 can be implemented in OCaml. You have to set the "impl = OCaml
346 ..." flag in the generator. Take a look at daemon/file.ml for an
347 example.
348 After making these changes, use "make" to compile.
350 Note that you don’t need to implement the RPC, language bindings,
352 manual pages or anything else. It’s all automatically generated from
353 the OCaml description.
354 Adding tests for an API
356 You can supply zero or as many tests as you want per API call. The
358 tests can either be added as part of the API description
359 (generator/actions_*.ml), or in some rarer cases you may want to drop a
360 script into "tests/*/". Note that adding a script to "tests/*/" is
361 slower, so if possible use the first method.
362 The following describes the test environment used when you add an API
364 test in actions_*.ml.
365 The test environment has 4 block devices:
367 /dev/sda 2 GB
369 General block device for testing.
370 /dev/sdb 2 GB
372 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
373 operations.
374 /dev/sdc 10 MB
376 Used in a few tests where two block devices are needed.
377 /dev/sdd
379 ISO with fixed content (see images/test.iso).
380 To be able to run the tests in a reasonable amount of time, the
382 libguestfs appliance and block devices are reused between tests. So
383 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
384 Each test starts with an initial scenario, selected using one of the
386 "Init*" expressions, described in generator/types.ml. These initialize
387 the disks mentioned above in a particular way as documented in
388 types.ml. You should not assume anything about the previous contents
389 of other disks that are not initialized.
390 You can add a prerequisite clause to any individual test. This is a
392 run-time check, which, if it fails, causes the test to be skipped.
393 Useful if testing a command which might not work on all variations of
394 libguestfs builds. A test that has prerequisite of "Always" means to
395 run unconditionally.
396 In addition, packagers can skip individual tests by setting environment
398 variables before running "make check".
399 SKIP_TEST_<CMD>_<NUM>=1
401 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
403 guestfs(3).
404 or:
406 SKIP_TEST_<CMD>=1
408 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
410 tests.
411 Packagers can run only certain tests by setting for example:
413 TEST_ONLY="vfs_type zerofree"
415 See tests/c-api/tests.c for more details of how these environment
417 variables work.
418 Debugging new APIs
420 Test new actions work before submitting them.
422 You can use guestfish to try out new commands.
424 Debugging the daemon is a problem because it runs inside a minimal
426 environment. However you can fprintf messages in the daemon to stderr,
427 and they will show up if you use "guestfish -v".
428 ADDING A NEW LANGUAGE BINDING
430 All language bindings must be generated by the generator (see the
431 generator subdirectory).
432 There is no documentation for this yet. We suggest you look at an
434 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
435 Adding tests for language bindings
437 Language bindings should come with tests. Previously testing of
439 language bindings was rather ad-hoc, but we have been trying to
440 formalize the set of tests that every language binding should use.
441 Currently only the OCaml and Perl bindings actually implement the full
443 set of tests, and the OCaml bindings are canonical, so you should
444 emulate what the OCaml tests do.
445 This is the numbering scheme used by the tests:
447 - 000+ basic tests:
449 010 load the library
451 020 create
452 030 create-flags
453 040 create multiple handles
454 050 test setting and getting config properties
455 060 explicit close
456 065 implicit close (in GC'd languages)
457 070 optargs
458 080 version
459 090 retvalues
460 - 100 launch, create partitions and LVs and filesystems
462 - 400+ events:
464 410 close event
466 420 log messages
467 430 progress messages
468 - 800+ regression tests (specific to the language)
470 - 900+ any other custom tests for the language
472 To save time when running the tests, only 100, 430, 800+, 900+ should
474 launch the handle.
475 FORMATTING CODE
477 Our C source code generally adheres to some basic code-formatting
478 conventions. The existing code base is not totally consistent on this
479 front, but we do prefer that contributed code be formatted similarly.
480 In short, use spaces-not-TABs for indentation, use 2 spaces for each
481 indentation level, and other than that, follow the K&R style.
482 If you use Emacs, add the following to one of your start-up files
484 (e.g., ~/.emacs), to help ensure that you get indentation right:
485 ;;; In libguestfs, indent with spaces everywhere (not TABs).
487 ;;; Exceptions: Makefile and ChangeLog modes.
488 (add-hook 'find-file-hook
489 '(lambda () (if (and buffer-file-name
490 (string-match "/libguestfs\\>"
491 (buffer-file-name))
492 (not (string-equal mode-name "Change Log"))
493 (not (string-equal mode-name "Makefile")))
494 (setq indent-tabs-mode nil))))
495 ;;; When editing C sources in libguestfs, use this style.
497 (defun libguestfs-c-mode ()
498 "C mode with adjusted defaults for use with libguestfs."
499 (interactive)
500 (c-set-style "K&R")
501 (setq c-indent-level 2)
502 (setq c-basic-offset 2))
503 (add-hook 'c-mode-hook
504 '(lambda () (if (string-match "/libguestfs\\>"
505 (buffer-file-name))
506 (libguestfs-c-mode))))
507 TESTING YOUR CHANGES
509 Turn warnings into errors when developing to make warnings hard to
510 ignore:
511 ./configure --enable-werror
513 Useful targets are:
515 "make check"
517 Runs the regular test suite.
518 This is implemented using the regular automake "TESTS" target. See
520 the automake documentation for details.
521 "make check-valgrind"
523 Runs a subset of the test suite under valgrind.
524 See "VALGRIND" below.
526 "make check-valgrind-local-guests"
528 Runs a subset of the test suite under valgrind using locally
529 installed libvirt guests (read-only).
530 "make check-direct"
532 Runs all tests using default appliance back-end. This only has any
533 effect if a non-default backend was selected using "./configure
534 --with-default-backend=..."
535 "make check-valgrind-direct"
537 Run a subset of the test suite under valgrind using the default
538 appliance back-end.
539 "make check-uml"
541 Runs all tests using the User-Mode Linux backend.
542 As there is no standard location for the User-Mode Linux kernel,
544 you have to set "LIBGUESTFS_HV" to point to the kernel image, eg:
545 make check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux
547 "make check-valgrind-uml"
549 Runs all tests using the User-Mode Linux backend, under valgrind.
550 As above, you have to set "LIBGUESTFS_HV" to point to the kernel.
552 "make check-with-upstream-qemu"
554 Runs all tests using a local qemu binary. It looks for the qemu
555 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
556 to another directory on the command line, eg:
557 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
559 "make check-with-upstream-libvirt"
561 Runs all tests using a local libvirt. This only has any effect if
562 the libvirt backend was selected using "./configure
563 --with-default-backend=libvirt"
564 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
566 but you can set this to another directory on the command line, eg:
567 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
569 "make check-slow"
571 Runs some slow/long-running tests which are not run by default.
572 To mark a test as slow/long-running:
574 · Add it to the list of "TESTS" in the Makefile.am, just like a
576 normal test.
577 · Modify the test so it checks if the "SLOW=1" environment
579 variable is set, and if not set it skips (ie. returns with exit
580 code 77). If using $TEST_FUNCTIONS, you can call the function
581 "slow_test" for this.
582 · Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
584 tests.
585 · Add a rule to the Makefile.am:
587 check-slow:
589 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
590 "sudo make check-root"
592 Runs some tests which require root privileges. These are supposed
593 to be safe, but take care. You have to run this as root (eg. using
594 sudo(8) explicitly).
595 To mark a test as requiring root:
597 · Add it to the list of "TESTS" in the Makefile.am, just like a
599 normal test.
600 · Modify the test so it checks if euid == 0, and if not set it
602 skips (ie. returns with exit code 77). If using
603 $TEST_FUNCTIONS, you can call the function "root_test" for
604 this.
605 · Add a variable "ROOT_TESTS" to the Makefile.am listing the root
607 tests.
608 · Add a rule to the Makefile.am:
610 check-root:
612 $(MAKE) check TESTS="$(ROOT_TESTS)"
613 "make check-all"
615 Equivalent to running all "make check*" rules except "check-root".
616 "make check-release"
618 Runs a subset of "make check*" rules that are required to pass
619 before a tarball can be released. Currently this is:
620 · check
622 · check-valgrind
624 · check-direct
626 · check-valgrind-direct
628 · check-slow
630 "make installcheck"
632 Run "make check" on the installed copy of libguestfs.
633 The version of installed libguestfs being tested, and the version
635 of the libguestfs source tree must be the same.
636 Do:
638 ./autogen.sh
640 make clean ||:
641 make
642 make installcheck
643 VALGRIND
645 When you do "make check-valgrind", it searches for any Makefile.am in
646 the tree that has a "check-valgrind:" target and runs it.
647 Writing the Makefile.am and tests correctly to use valgrind and working
649 with automake parallel tests is subtle.
650 If your tests are run via a shell script wrapper, then in the wrapper
652 use:
653 $VG virt-foo
655 and in the Makefile.am use:
657 check-valgrind:
659 make VG="@VG@" check
660 However, if your binaries run directly from the "TESTS" rule, you have
662 to modify the Makefile.am like this:
663 LOG_COMPILER = $(VG)
665 check-valgrind:
667 make VG="@VG@" check
668 In either case, check that the right program is being tested by
670 examining the tmp/valgrind* log files carefully.
671 SUBMITTING PATCHES
673 Submit patches to the mailing list:
674 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
675 rjones@redhat.com.
676 You do not need to subscribe to the mailing list if you don’t want to.
678 There may be a short delay while your message is moderated.
679 DAEMON CUSTOM PRINTF FORMATTERS
681 In the daemon code we have created custom printf formatters %Q and %R,
682 which are used to do shell quoting.
683 %Q Simple shell quoted string. Any spaces or other shell characters
685 are escaped for you.
686 %R Same as %Q except the string is treated as a path which is prefixed
688 by the sysroot.
689 For example:
691 asprintf (&cmd, "cat %R", path);
693 would produce "cat /sysroot/some\ path\ with\ spaces"
695 Note: Do not use these when you are passing parameters to the
697 "command{,r,v,rv}()" functions. These parameters do NOT need to be
698 quoted because they are not passed via the shell (instead, straight to
699 exec). You probably want to use the "sysroot_path()" function however.
700 INTERNATIONALIZATION (I18N) SUPPORT
702 We support i18n (gettext anyhow) in the library.
703 However many messages come from the daemon, and we don’t translate
705 those at the moment. One reason is that the appliance generally has
706 all locale files removed from it, because they take up a lot of space.
707 So we'd have to readd some of those, as well as copying our PO files
708 into the appliance.
709 Debugging messages are never translated, since they are intended for
711 the programmers.
712
714 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
715 Mostly this section is "how we make automake & ocamlopt work together"
716 since OCaml programs themselves are easy to compile.
717 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
719 What we do instead is to treat OCaml programs as C programs which
720 happen to contain these "other objects" ("DEPENDENCIES" in automake-
721 speak) that happen to be the OCaml objects. This works because OCaml
722 programs usually have C files for native bindings etc.
723 So a typical program is described as just its C sources:
725 virt_v2v_SOURCES = ... utils-c.c xml-c.c
727 For programs that have no explicit C sources, we create an empty
729 dummy.c file, and list that instead:
730 virt_resize_SOURCES = dummy.c
732 The OCaml objects which contain most of the code are listed as automake
734 dependencies (other dependencies may also be listed):
735 virt_v2v_DEPENDENCIES = ... cmdline.cmx v2v.cmx
737 The only other special thing we need to do is to provide a custom link
739 command. This is needed because automake won't assemble the ocamlopt
740 command, the list of objects and the "-cclib" libraries in the correct
741 order otherwise.
742 virt_v2v_LINK = \
744 $(top_srcdir)/ocaml-link.sh -cclib '-lutils -lgnu' -- ...
745 The actual rules, which you can examine in v2v/Makefile.am, are a
747 little bit more complicated than this because they have to handle:
748 · Compiling for byte code or native code.
750 · The pattern rules needed to compile the OCaml sources to objects.
752 These are now kept in subdir-rules.mk at the top level, which is
754 included in every subdirectory Makefile.am.
755 · Adding OCaml sources files to "EXTRA_DIST".
757 Automake isn't aware of the complete list of sources for a binary,
759 so it will not add them all automatically.
760 VIRT-V2V
762 First a little history. Virt-v2v has been through at least two
763 complete rewrites, so this is probably about the third version (but we
764 don't intend to rewrite it again). The previous version was written in
765 Perl and can be found here:
766 https://git.fedorahosted.org/git/virt-v2v.git
767 The current version started out as almost a line-for-line rewrite of
769 the Perl code in OCaml + C, and it still has a fairly similar
770 structure. Therefore if there are details of this code that you don't
771 understand (especially in the details of guest conversion), checking
772 the Perl code may help.
773 The files to start with when reading this code are:
775 · types.mli
777 · v2v.ml
779 types.mli defines all the structures used and passed around when
781 communicating between different bits of the program. v2v.ml controls
782 how the program runs in stages.
783 After studying those files, you may want to branch out into the input
785 modules (input_*), the output modules (output_*) or the conversion
786 modules (convert_*). The input and output modules define -i and -o
787 options (see the manual). The conversion modules define what guest
788 types we can handle and the detailed steps involved in converting them.
789 Every other file in this directory is a support module / library of
791 some sort. Some code is written in C, especially where we want to use
792 an external C library such as libxml2.
793 VIRT-P2V
795 Virt-p2v is a front end on virt-v2v. ie. All it does is act as a GUI
796 front end, and it calls out to virt-v2v to perform the actual
797 conversion. Therefore most of the C code in the p2v/ subdirectory is
798 Gtk (GUI) code, or supporting code for talking to the remote conversion
799 server. There is no special support for physical machines in virt-v2v.
800 They are converted in the same way as foreign VMs.
801 Running virt-p2v
803 You can run the p2v/virt-p2v binary directly, but it will try to
805 convert your machine’s real /dev/sda which is unlikely to work well.
806 However virt-p2v also has a test mode in which you can supply a test
807 disk:
808 make -C p2v run-virt-p2v-directly
810 This is a wrapper around the virt-p2v(1) --test-disk option. You can
812 control the "physical machine" disk by setting "PHYSICAL_MACHINE" to
813 point to a disk image.
814 A more realistic test is to run virt-p2v inside a VM on the local
816 machine. To do that, do:
817 make -C p2v run-virt-p2v-in-a-vm
819 This also runs qemu with the "physical machine" disk (which you can set
821 by setting "PHYSICAL_MACHINE"), a virtual CD, and a variety of network
822 cards for testing. You can change the qemu binary and add extra qemu
823 options by setting "QEMU" and/or "QEMU_OPTIONS" on the make
824 commandline.
825 A third way to run virt-p2v simulates fairly accurately the program
827 being downloaded over PXE and then doing an automatic conversion of the
828 source physical machine (the non-GUI path -- see next section below):
829 make -C p2v run-virt-p2v-non-gui-conversion
831 Understanding the virt-p2v code
833 See also: "HOW VIRT-P2V WORKS" in virt-p2v(1)
835 There are two paths through the code, GUI or non-GUI (parsing the
837 kernel command line):
838 main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c
840 │ │
841 │ │
842 └────▶ kernel.c ────┘
843 but both paths call back to the conversion.c function
845 "start_conversion" to run the remote virt-v2v.
846 The main task of gui.c/kernel.c is to populate the virt-v2v
848 configuration (config.c).
849 During conversion, we need to establish ssh connections, and that is
851 done using two libraries:
852 conversion.c ──────▶ ssh.c ──────▶ miniexpect.c
854 where ssh.c is responsible for managing ssh connections overall, and
856 miniexpect.c implements "expect-like" functionality for talking
857 interactively to the remote virt-v2v conversion server.
858 (Note that miniexpect is a separate library with its own upstream, so
860 if you patch miniexpect.c, then please make sure the changes get
861 reflected in miniexpect’s upstream too:
862 http://git.annexia.org/?p=miniexpect.git;a=summary)
863
865 MAINTAINER MAKEFILE TARGETS
866 These "make" targets probably won’t work and aren't useful unless you
867 are a libguestfs maintainer.
868 make maintainer-commit
870 This commits everything in the working directory with the commit
872 message "Version $(VERSION).". You must update configure.ac, clean and
873 rebuild first.
874 make maintainer-tag
876 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
878 the messages:
879 Version $(VERSION) stable
881 Version $(VERSION) development
883 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
885 between a stable and development release.)
886 make maintainer-check-authors
888 Check that all authors (found in git commit messages) are included in
890 the generator/authors.ml file.
891 make maintainer-check-extra-dist
893 This rule must be run after "make dist" (so there is a tarball in the
895 working directory). It compares the contents of the tarball with the
896 contents of git to ensure that no files have been missed from
897 Makefile.am "EXTRA_DIST" rules.
898 make maintainer-upload-website
900 This is used by the software used to automate libguestfs releases to
902 copy the libguestfs website to another git repository before it is
903 uploaded to the web server.
904 MAKING A STABLE RELEASE
906 When we make a stable release, there are several steps documented here.
907 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
908 about the stable branch policy.
909 · Check "make && make check" works on at least:
911 Fedora (x86-64)
913 Debian (x86-64)
914 Ubuntu (x86-64)
915 Fedora (aarch64)
916 Fedora (ppc64)
917 Fedora (ppc64le)
918 · Check "./configure --without-libvirt" works.
919 · Finalize guestfs-release-notes.pod
921 · Push and pull from Zanata.
923 Run:
925 zanata push
927 to push the latest POT files to Zanata. Then run:
929 ./zanata-pull.sh
931 which is a wrapper to pull the latest translated *.po files.
933 · Consider updating gnulib to latest upstream version.
935 · Create new stable and development directories under
937 http://libguestfs.org/download.
938 · Edit website/index.html.in.
940 · Set the version (in configure.ac) to the new stable version, ie.
942 1.XX.0, and commit it:
943 ./localconfigure
945 make distclean -k
946 ./localconfigure
947 make && make dist
948 make maintainer-commit
949 make maintainer-tag
950 · Create the stable branch in git:
952 git branch stable-1.XX
954 git push origin stable-1.XX
955 · Do a full release of the stable branch.
957 · Set the version to the next development version and commit that.
959 Optionally do a full release of the development branch.
960
962 This section documents internal functions inside libguestfs and various
963 utilities. It is intended for libguestfs developers only.
964 This section is autogenerated from "/**" comments in source files,
966 which are marked up in POD format.
967 These functions are not publicly exported, and may change or be removed
969 at any time.
970 Subdirectory lib
972 File lib/actions-support.c
973 Helper functions for the actions code in lib/actions-*.c.
975 File lib/appliance-cpu.c
977 The appliance choice of CPU model.
979 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
981 const char *
983 guestfs_int_get_cpu_model (int kvm)
984 Return the right CPU model to use as the qemu "-cpu" parameter or its
986 equivalent in libvirt. This returns:
987 "host"
989 The literal string "host" means use "-cpu host".
990 some string
992 Some string such as "cortex-a57" means use "-cpu cortex-a57".
993 "NULL"
995 "NULL" means no "-cpu" option at all. Note returning "NULL" does
996 not indicate an error.
997 This is made unnecessarily hard and fragile because of two stupid
999 choices in QEMU:
1000 · The default for "qemu-system-aarch64 -M virt" is to emulate a
1002 "cortex-a15" (WTF?).
1003 · We don't know for sure if KVM will work, but "-cpu host" is broken
1005 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
1006 semi-broken in any way.
1007 File lib/appliance-kcmdline.c
1009 The appliance kernel command line.
1011 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
1013 #define VALID_TERM(term) \
1015 guestfs_int_string_is_valid ((term), 1, 16, \
1016 VALID_FLAG_ALPHA|VALID_FLAG_DIGIT, "-_")
1017 #if defined(__powerpc64__)
1019 #define SERIAL_CONSOLE "console=hvc0 console=ttyS0"
1020 #elif defined(__arm__) || defined(__aarch64__)
1021 #define SERIAL_CONSOLE "console=ttyAMA0"
1022 #elif defined(__s390x__)
1023 #define SERIAL_CONSOLE "console=ttysclp0"
1024 #else
1025 #define SERIAL_CONSOLE "console=ttyS0"
1026 #endif
1027 #if defined(__aarch64__)
1029 #define EARLYPRINTK "earlyprintk=pl011,0x9000000"
1030 #endif
1031 /**
1033 * Construct the Linux command line passed to the appliance. This is
1034 * used by the C<direct> and C<libvirt> backends, and is simply
1035 * located in this file because it's a convenient place for this
1036 * common code.
1037 *
1038 * The C<appliance_dev> parameter must be the full device name of the
1039 * appliance disk and must have already been adjusted to take into
1040 * account virtio-blk or virtio-scsi; eg C</dev/sdb>.
1041 *
1042 * The C<flags> parameter can contain the following flags logically
1043 * or'd together (or 0):
1044 *
1045 * =over 4
1046 *
1047 * =item C<APPLIANCE_COMMAND_LINE_IS_TCG>
1048 *
1049 * If we are launching a qemu TCG guest (ie. KVM is known to be
1050 * disabled or unavailable). If you don't know, don't pass this flag.
1051 *
1052 * =back
1053 *
1054 * Note that this function returns a newly allocated buffer which must
1055 * be freed by the caller.
1056 */
1057 char *
1058 guestfs_int_appliance_command_line (guestfs_h *g, const char *appliance_dev,
1059 int flags)
1060 Check that the $TERM environment variable is reasonable before we pass
1062 it through to the appliance.
1063 File lib/appliance-uefi.c
1065 Find the UEFI firmware needed to boot the appliance.
1067 See also lib/uefi.c (autogenerated file) containing the firmware file
1069 locations.
1070 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
1072 int
1074 guestfs_int_get_uefi (guestfs_h *g, char **code, char **vars, int *flags)
1075 Return the location of firmware needed to boot the appliance. This is
1077 aarch64 only currently, since that's the only architecture where UEFI
1078 is mandatory (and that only for RHEL).
1079 *code is initialized with the path to the read-only UEFI code file.
1081 *vars is initialized with the path to a copy of the UEFI vars file
1082 (which is cleaned up automatically on exit).
1083 If *code == *vars == "NULL" then no UEFI firmware is available.
1085 *code and *vars should be freed by the caller.
1087 If the function returns "-1" then there was a real error which should
1089 cause appliance building to fail (no UEFI firmware is not an error).
1090 See also v2v/utils.ml:find_uefi_firmware
1092 File lib/appliance.c
1094 This file deals with building the libguestfs appliance.
1096 Function "lib/appliance.c:guestfs_int_build_appliance"
1098 int
1100 guestfs_int_build_appliance (guestfs_h *g,
1101 char **kernel_rtn,
1102 char **initrd_rtn,
1103 char **appliance_rtn)
1104 Locate or build the appliance.
1106 This function locates or builds the appliance as necessary, handling
1108 the supermin appliance, caching of supermin-built appliances, or using
1109 either a fixed or old-style appliance.
1110 The return value is 0 = good, "-1" = error. Returned in
1112 "appliance.kernel" will be the name of the kernel to use,
1113 "appliance.initrd" the name of the initrd, "appliance.image" the name
1114 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
1115 that we are using an old-style (non-ext2) appliance. All three strings
1116 must be freed by the caller. However the referenced files themselves
1117 must not be deleted.
1118 The process is as follows:
1120 1. Look in "path" which contains a supermin appliance skeleton. If no
1122 element has this, skip straight to step 3.
1123 2. Call "supermin --build" to build the full appliance (if it needs to
1125 be rebuilt). If this is successful, return the full appliance.
1126 3. Check "path", looking for a fixed appliance. If one is found,
1128 return it.
1129 4. Check "path", looking for an old-style appliance. If one is found,
1131 return it.
1132 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1134 and consists of up to four files:
1135 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1137 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1138 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1139 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1140 Multiple instances of libguestfs with the same UID may be racing to
1142 create an appliance. However (since supermin ≥ 5) supermin provides a
1143 --lock flag and atomic update of the appliance.d subdirectory.
1144 Function "lib/appliance.c:locate_or_build_appliance"
1146 static int
1148 locate_or_build_appliance (guestfs_h *g,
1149 struct appliance_files *appliance,
1150 const char *path)
1151 Check "path", looking for one of appliances: supermin appliance, fixed
1153 appliance or old-style appliance. If one of the fixed appliances is
1154 found, return it. If the supermin appliance skeleton is found, build
1155 and return appliance.
1156 Return values:
1158 1 = appliance is found, returns C<appliance>,
1160 0 = appliance not found,
1161 -1 = error which aborts the launch process.
1162 Function "lib/appliance.c:search_appliance"
1164 static int
1166 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1167 Search elements of "g->path", returning the first "appliance" element
1169 which matches the predicate function "locate_or_build_appliance".
1170 Return values:
1172 1 = a path element matched, returns C<appliance>,
1174 0 = no path element matched,
1175 -1 = error which aborts the launch process.
1176 Function "lib/appliance.c:build_supermin_appliance"
1178 static int
1180 build_supermin_appliance (guestfs_h *g,
1181 const char *supermin_path,
1182 struct appliance_files *appliance)
1183 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1185 Returns: 0 = built or "-1" = error (aborts launch).
1187 Function "lib/appliance.c:run_supermin_build"
1189 static int
1191 run_supermin_build (guestfs_h *g,
1192 const char *lockfile,
1193 const char *appliancedir,
1194 const char *supermin_path)
1195 Run "supermin --build" and tell it to generate the appliance.
1197 Function "lib/appliance.c:dir_contains_file"
1199 static int
1201 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1202 Returns true iff "file" is contained in "dir".
1204 Function "lib/appliance.c:dir_contains_files"
1206 static int
1208 dir_contains_files (guestfs_h *g, const char *dir, ...)
1209 Returns true iff every listed file is contained in "dir".
1211 File lib/command.c
1213 A wrapper for running external commands, loosely based on libvirt's
1215 "virCommand" interface.
1216 In outline to use this interface you must:
1218 1. Create a new command handle:
1220 struct command *cmd;
1222 cmd = guestfs_int_new_command (g);
1223 2. Either add arguments:
1225 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1227 guestfs_int_cmd_add_arg (cmd, "info");
1228 guestfs_int_cmd_add_arg (cmd, filename);
1229 (NB: You don't need to add a "NULL" argument at the end.)
1231 3. Or construct a command using a mix of quoted and unquoted strings.
1233 (This is useful for system(3)/"popen("r")"-style shell commands,
1234 with the added safety of allowing args to be quoted properly).
1235 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1237 guestfs_int_cmd_add_string_quoted (cmd, filename);
1238 4. Set various flags, such as whether you want to capture errors in
1240 the regular libguestfs error log.
1241 5. Run the command. This is what does the fork(2) call, optionally
1243 loops over the output, and then does a waitpid(3) and returns the
1244 exit status of the command.
1245 r = guestfs_int_cmd_run (cmd);
1247 if (r == -1)
1248 // error
1249 // else test r using the WIF* functions
1250 6. Close the handle:
1252 guestfs_int_cmd_close (cmd);
1254 (or use "CLEANUP_CMD_CLOSE").
1256 Function "lib/command.c:guestfs_int_new_command"
1258 struct command *
1260 guestfs_int_new_command (guestfs_h *g)
1261 Create a new command handle.
1263 Function "lib/command.c:guestfs_int_cmd_add_arg"
1265 void
1267 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1268 Add single arg (for "execv"-style command execution).
1270 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1272 void
1274 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1275 Add single arg (for "execv"-style command execution) using a
1277 printf(3)-style format string.
1278 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1280 void
1282 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1283 Add a string (for system(3)-style command execution).
1285 This variant adds the strings without quoting them, which is dangerous
1287 if the string contains untrusted content.
1288 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1290 void
1292 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1293 Add a string (for system(3)-style command execution).
1295 The string is enclosed in double quotes, with any special characters
1297 within the string which need escaping done. This is used to add a
1298 single argument to a system(3)-style command string.
1299 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1301 void
1303 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1304 cmd_stdout_callback stdout_callback,
1305 void *stdout_data, unsigned flags)
1306 Set a callback which will capture stdout.
1308 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1310 callback is called line by line on the output. If there is a trailing
1311 "\n" then it is automatically removed before the callback is called.
1312 The line buffer is "\0"-terminated.
1313 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1315 to the callback as it is received from the command. Note in this case
1316 the buffer is not "\0"-terminated, so you need to may attention to the
1317 length field in the callback.
1318 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1320 called exactly once, with the entire buffer. Note in this case the
1321 buffer is not "\0"-terminated, so you need to may attention to the
1322 length field in the callback.
1323 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1325 void
1327 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1328 Equivalent to adding "2>&1" to the end of the command. This is
1330 incompatible with the "capture_errors" flag, because it doesn't make
1331 sense to combine them.
1332 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1334 void
1336 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1337 Clear the "capture_errors" flag. This means that any errors will go to
1339 stderr, instead of being captured in the event log, and that is usually
1340 undesirable.
1341 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1343 void
1345 guestfs_int_cmd_clear_close_files (struct command *cmd)
1346 Don't close file descriptors after the fork.
1348 XXX Should allow single fds to be sent to child process.
1350 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1352 void
1354 guestfs_int_cmd_set_child_callback (struct command *cmd,
1355 cmd_child_callback child_callback,
1356 void *data)
1357 Set a function to be executed in the child, right before the execution.
1359 Can be used to setup the child, for example changing its current
1360 directory.
1361 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1363 void
1365 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1366 Set up child rlimits, in case the process we are running could consume
1368 lots of space or time.
1369 Function "lib/command.c:finish_command"
1371 static void
1373 finish_command (struct command *cmd)
1374 Finish off the command by either "NULL"-terminating the argv array or
1376 adding a terminating "\0" to the string, or die with an internal error
1377 if no command has been added.
1378 Function "lib/command.c:loop"
1380 static int
1382 loop (struct command *cmd)
1383 The loop which reads errors and output and directs it either to the log
1385 or to the stdout callback as appropriate.
1386 Function "lib/command.c:guestfs_int_cmd_run"
1388 int
1390 guestfs_int_cmd_run (struct command *cmd)
1391 Fork, run the command, loop over the output, and waitpid.
1393 Returns the exit status. Test it using "WIF*" macros.
1395 On error: Calls "error" and returns "-1".
1397 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1399 int
1401 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1402 Fork and run the command, but don't wait. Roughly equivalent to
1404 "popen (..., "r"|"w")".
1405 Returns the file descriptor of the pipe, connected to stdout ("r") or
1407 stdin ("w") of the child process.
1408 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1410 wait for the status of the child.
1411 Errors from the subcommand cannot be captured to the error log using
1413 this interface. Instead the caller should call
1414 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1415 returns an error).
1416 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1418 int
1420 guestfs_int_cmd_pipe_wait (struct command *cmd)
1421 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1423 On error (eg. failed syscall) this returns "-1" and sets the error. If
1424 the subcommand fails, then use "WIF*" macros to check this, and call
1425 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1426 the child.
1427 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1429 char *
1431 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1432 Read the error messages printed by the child. The caller must free the
1434 returned buffer after use.
1435 Function "lib/command.c:guestfs_int_cmd_close"
1437 void
1439 guestfs_int_cmd_close (struct command *cmd)
1440 Close the "cmd" object and free all resources.
1442 Function "lib/command.c:process_line_buffer"
1444 static void
1446 process_line_buffer (struct command *cmd, int closed)
1447 Deal with buffering stdout for the callback.
1449 File lib/conn-socket.c
1451 This file handles connections to the child process where this is done
1453 over regular POSIX sockets.
1454 Function "lib/conn-socket.c:handle_log_message"
1456 static int
1458 handle_log_message (guestfs_h *g,
1459 struct connection_socket *conn)
1460 This is called if "conn->console_sock" becomes ready to read while we
1462 are doing one of the connection operations above. It reads and deals
1463 with the log message.
1464 Returns:
1466 1 log message(s) were handled successfully
1468 0 connection to appliance closed
1470 "-1"
1472 error
1473 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1475 struct connection *
1477 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1478 int daemon_accept_sock,
1479 int console_sock)
1480 Create a new socket connection, listening.
1482 Note that it's OK for "console_sock" to be passed as "-1", meaning
1484 there's no console available for this appliance.
1485 After calling this, "daemon_accept_sock" is owned by the connection,
1487 and will be closed properly either in "accept_connection" or
1488 "free_connection".
1489 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1491 struct connection *
1493 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1494 int daemon_sock,
1495 int console_sock)
1496 Create a new socket connection, connected.
1498 As above, but the caller passes us a connected "daemon_sock" and
1500 promises not to call "accept_connection".
1501 File lib/create.c
1503 APIs for creating empty disks.
1505 Mostly this consists of wrappers around the qemu-img(1) program.
1507 Function "lib/create.c:disk_create_qcow2"
1509 #define VALID_FORMAT(format) \
1511 guestfs_int_string_is_valid ((format), 1, 16, \
1512 VALID_FLAG_ALPHA|VALID_FLAG_DIGIT, "")
1513 static int
1515 disk_create_qcow2 (guestfs_h *g, const char *orig_filename, int64_t size,
1516 const char *backingfile,
1517 const struct guestfs_disk_create_argv *optargs)
1518 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1520 locale), but limit the length to something reasonable.
1521 File lib/drives.c
1523 Drives added are stored in an array in the handle. Code here manages
1525 that array and the individual "struct drive" data.
1526 Function "lib/drives.c:create_overlay"
1528 static int
1530 create_overlay (guestfs_h *g, struct drive *drv)
1531 For readonly drives, create an overlay to protect the original drive
1533 content. Note we never need to clean up these overlays since they are
1534 created in the temporary directory and deleted when the handle is
1535 closed.
1536 Function "lib/drives.c:create_drive_file"
1538 static struct drive *
1540 create_drive_file (guestfs_h *g,
1541 const struct drive_create_data *data)
1542 Create and free the "struct drive".
1544 Function "lib/drives.c:create_drive_dev_null"
1546 static struct drive *
1548 create_drive_dev_null (guestfs_h *g,
1549 struct drive_create_data *data)
1550 Create the special /dev/null drive.
1552 Traditionally you have been able to use /dev/null as a filename, as
1554 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1555 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1556 zero-sized file including /dev/null.
1557 Because of these problems, we replace /dev/null with a non-zero sized
1559 temporary file. This shouldn't make any difference since users are not
1560 supposed to try and access a null drive.
1561 Function "lib/drives.c:drive_to_string"
1563 static char *
1565 drive_to_string (guestfs_h *g, const struct drive *drv)
1566 Convert a "struct drive" to a string for debugging. The caller must
1568 free this string.
1569 Function "lib/drives.c:add_drive_to_handle_at"
1571 static void
1573 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1574 Add "struct drive" to the "g->drives" vector at the given index
1576 "drv_index". If the array isn't large enough it is reallocated. The
1577 index must not contain a drive already.
1578 Function "lib/drives.c:add_drive_to_handle"
1580 static void
1582 add_drive_to_handle (guestfs_h *g, struct drive *d)
1583 Add struct drive to the end of the "g->drives" vector in the handle.
1585 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1587 void
1589 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1590 Called during launch to add a dummy slot to "g->drives".
1592 Function "lib/drives.c:guestfs_int_free_drives"
1594 void
1596 guestfs_int_free_drives (guestfs_h *g)
1597 Free up all the drives in the handle.
1599 Function "lib/drives.c:valid_port"
1601 #define VALID_FORMAT_IFACE(str) \
1603 guestfs_int_string_is_valid ((str), 1, 0, \
1604 VALID_FLAG_ALPHA|VALID_FLAG_DIGIT, "-_")
1605 /**
1607 * Check the disk label is reasonable. It can't contain certain
1608 * characters, eg. C<'/'>, C<','>. However be stricter here and
1609 * ensure it's just alphabetic and E<le> 20 characters in length.
1610 */
1611 #define VALID_DISK_LABEL(str) \
1612 guestfs_int_string_is_valid ((str), 1, 20, VALID_FLAG_ALPHA, NULL)
1613 /**
1615 * Check the server hostname is reasonable.
1616 */
1617 #define VALID_HOSTNAME(str) \
1618 guestfs_int_string_is_valid ((str), 1, 255, \
1619 VALID_FLAG_ALPHA|VALID_FLAG_DIGIT, "-.:[]")
1620 /**
1622 * Check the port number is reasonable.
1623 */
1624 static int
1625 valid_port (int port)
1626 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1628 (in C locale).
1629 Function "lib/drives.c:guestfs_impl_remove_drive"
1631 int
1633 guestfs_impl_remove_drive (guestfs_h *g, const char *label)
1634 This function implements "guestfs_remove_drive" in guestfs(3).
1636 Depending on whether we are hotplugging or not, this function does
1638 slightly different things: If not hotplugging, then the drive just
1639 disappears as if it had never been added. The later drives "move up"
1640 to fill the space. When hotplugging we have to do some complex stuff,
1641 and we usually end up leaving an empty ("NULL") slot in the "g->drives"
1642 vector.
1643 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1645 size_t
1647 guestfs_int_checkpoint_drives (guestfs_h *g)
1648 Checkpoint and roll back drives, so that groups of drives can be added
1650 atomicly. Only used by "guestfs_add_domain" in guestfs(3).
1651 Function "lib/drives.c:guestfs_impl_debug_drives"
1653 char **
1655 guestfs_impl_debug_drives (guestfs_h *g)
1656 Internal function to return the list of drives.
1658 File lib/errors.c
1660 This file handles errors, and also debug, trace and warning messages.
1662 Errors in libguestfs API calls are handled by setting an error message
1664 and optional errno in the handle. The caller has the choice of testing
1665 API calls to find out if they failed and then querying the last error
1666 from the handle, and/or getting a callback.
1667 From the point of view of the library source, generally you should use
1669 the "error" or "perrorf" macros along error paths, eg:
1670 if (something_bad) {
1672 error (g, "something bad happened");
1673 return -1;
1674 }
1675 Make sure to call the "error" or "perrorf" macro exactly once along
1677 each error path, since the handle can only store a single error and the
1678 previous error will be overwritten.
1679 Function "lib/errors.c:guestfs_int_warning"
1681 void
1683 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1684 Print a warning.
1686 Code should not call this function directly. Use the
1688 "warning (g, fs, ...)" macro.
1689 Warnings are printed unconditionally. We try to make these rare:
1691 Generally speaking, a warning should either be an error, or if it's not
1692 important for end users then it should be a debug message.
1693 Function "lib/errors.c:guestfs_int_debug"
1695 void
1697 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1698 Print a debug message.
1700 Code should not call this function directly. To add debug messages in
1702 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1703 "g->verbose" is false and avoids the function call, meaning the macro
1704 is more efficient.
1705 Function "lib/errors.c:guestfs_int_trace"
1707 void
1709 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1710 Print a trace message.
1712 Do not call this function. All calls are generated automatically.
1714 Function "lib/errors.c:guestfs_int_error_errno"
1716 void
1718 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1719 Set the last error and errno in the handle, and optionally raise the
1721 error callback if one is defined.
1722 If you don't need to set errno, use the "error (g, fs, ...)" macro
1724 instead of calling this directly. If you need to set errno then there
1725 is no macro wrapper, so calling this function directly is fine.
1726 Function "lib/errors.c:guestfs_int_perrorf"
1728 void
1730 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1731 Similar to perror(3), but it sets the last error in the handle, raises
1733 the error callback if one is defined, and supports format strings.
1734 You should probably use the "perrorf (g, fs, ...)" macro instead of
1736 calling this directly.
1737 Function "lib/errors.c:guestfs_int_launch_failed_error"
1739 void
1741 guestfs_int_launch_failed_error (guestfs_h *g)
1742 Raise a launch failed error in a standard format.
1744 Since this is the most common error seen by people who have
1746 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1747 describe in this error message what resources are available to debug
1748 launch problems.
1749 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1751 void
1753 guestfs_int_unexpected_close_error (guestfs_h *g)
1754 Raise an error if the appliance unexpectedly crashes after launch.
1756 Function "lib/errors.c:guestfs_int_launch_timeout"
1758 void
1760 guestfs_int_launch_timeout (guestfs_h *g)
1761 Raise an error if the appliance hangs during launch.
1763 Function "lib/errors.c:guestfs_int_external_command_failed"
1765 void
1767 guestfs_int_external_command_failed (guestfs_h *g, int status,
1768 const char *cmd_name, const char *extra)
1769 Raise an error if an external command fails.
1771 "status" is the status code of the command (eg. returned from
1773 waitpid(2) or system(3)). This function turns the status code into an
1774 explanatory string.
1775 File lib/events.c
1777 Function "lib/events.c:replace_old_style_event_callback"
1779 static void
1781 replace_old_style_event_callback (guestfs_h *g,
1782 guestfs_event_callback cb,
1783 uint64_t event_bitmask,
1784 void *opaque,
1785 void *opaque2)
1786 Emulate old-style callback API.
1788 There were no event handles, so multiple callbacks per event were not
1790 supported. Calling the same "guestfs_set_*_callback" function would
1791 replace the existing event. Calling it with "cb == NULL" meant that
1792 the caller wanted to remove the callback.
1793 File lib/guestfs-internal-all.h
1795 This header contains definitions which are shared by all parts of
1797 libguestfs, ie. the daemon, the library, language bindings and virt
1798 tools (ie. all C code).
1799 If you need a definition used by only the library, put it in
1801 lib/guestfs-internal.h instead.
1802 If a definition is used by only a single tool, it should not be in any
1804 shared header file at all.
1805 File lib/guestfs-internal.h
1807 This header file is included in the libguestfs library (lib/) only.
1809 See also lib/guestfs-internal-all.h.
1811 Structure "lib/guestfs-internal.h:event"
1813 struct event {
1815 uint64_t event_bitmask;
1816 guestfs_event_callback cb;
1817 void *opaque;
1818 /* opaque2 is not exposed through the API, but is used internally to
1820 * emulate the old-style callback API.
1821 */
1822 void *opaque2;
1823 };
1824 This struct is used to maintain a list of events registered against the
1826 handle. See "g->events" in the handle.
1827 Structure "lib/guestfs-internal.h:drive"
1829 struct drive {
1831 /* Original source of the drive, eg. file:..., http:... */
1832 struct drive_source src;
1833 /* If the drive is readonly, then an overlay [a local file] is
1835 * created before launch to protect the original drive content, and
1836 * the filename is stored here. Backends should open this file if
1837 * it is non-NULL, else consult the original source above.
1838 *
1839 * Note that the overlay is in a backend-specific format, probably
1840 * different from the source format. eg. qcow2, UML COW.
1841 */
1842 char *overlay;
1843 /* Various per-drive flags. */
1845 bool readonly;
1846 char *iface;
1847 char *name;
1848 char *disk_label;
1849 char *cachemode;
1850 enum discard discard;
1851 bool copyonread;
1852 };
1853 There is one "struct drive" per drive, including hot-plugged drives.
1855 Structure "lib/guestfs-internal.h:backend_ops"
1857 struct backend_ops {
1859 /* Size (in bytes) of the per-handle data structure needed by this
1860 * backend. The data pointer is allocated and freed by libguestfs
1861 * and passed to the functions in the 'void *data' parameter.
1862 * Inside the data structure is opaque to libguestfs. Any strings
1863 * etc pointed to by it must be freed by the backend during
1864 * shutdown.
1865 */
1866 size_t data_size;
1867 /* Create a COW overlay on top of a drive. This must be a local
1869 * file, created in the temporary directory. This is called when
1870 * the drive is added to the handle.
1871 */
1872 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1873 /* Launch and shut down. */
1875 int (*launch) (guestfs_h *g, void *data, const char *arg);
1876 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1877 /* Miscellaneous. */
1879 int (*get_pid) (guestfs_h *g, void *data);
1880 int (*max_disks) (guestfs_h *g, void *data);
1881 /* Hotplugging drives. */
1883 int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1884 int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1885 };
1886 Backend operations.
1888 Each backend (eg. libvirt, direct) defines some functions which get run
1890 at various places in the handle lifecycle (eg. at launch, shutdown).
1891 The backend defines this struct pointing to those functions.
1892 Structure "lib/guestfs-internal.h:connection"
1894 struct connection {
1896 const struct connection_ops *ops;
1897 /* In the real struct, private data used by each connection module
1899 * follows here.
1900 */
1901 };
1902 Connection module.
1904 A "connection" represents the appliance console connection plus the
1906 daemon connection. It hides the underlying representation (POSIX
1907 sockets, "virStreamPtr").
1908 Structure "lib/guestfs-internal.h:cached_feature"
1910 struct cached_feature {
1912 char *group;
1913 int result;
1914 };
1915 Cache of queried features.
1917 Used to cache the appliance features (see lib/available.c).
1919 Structure "lib/guestfs-internal.h:guestfs_h"
1921 struct guestfs_h {
1923 struct guestfs_h *next; /* Linked list of open handles. */
1924 enum state state; /* See the state machine diagram in guestfs(3)*/
1925 /* Lock acquired when entering any public guestfs_* function to
1927 * protect the handle.
1928 */
1929 gl_recursive_lock_define (, lock);
1930 /**** Configuration of the handle. ****/
1932 bool verbose; /* Debugging. */
1933 bool trace; /* Trace calls. */
1934 bool autosync; /* Autosync. */
1935 bool direct_mode; /* Direct mode. */
1936 bool recovery_proc; /* Create a recovery process. */
1937 bool enable_network; /* Enable the network. */
1938 bool selinux; /* selinux enabled? */
1939 bool pgroup; /* Create process group for children? */
1940 bool close_on_exit; /* Is this handle on the atexit list? */
1941 int smp; /* If > 1, -smp flag passed to hv. */
1943 int memsize; /* Size of RAM (megabytes). */
1944 char *path; /* Path to the appliance. */
1946 char *hv; /* Hypervisor (HV) binary. */
1947 char *append; /* Append to kernel command line. */
1948 struct hv_param *hv_params; /* Extra hv parameters. */
1950 char *program; /* Program name. */
1952 char *identifier; /* Handle identifier. */
1953 /* Array of drives added by add-drive* APIs.
1955 *
1956 * Before launch this list can be empty or contain some drives.
1957 *
1958 * During launch, a dummy slot may be added which represents the
1959 * slot taken up by the appliance drive.
1960 *
1961 * When hotplugging is supported by the backend, drives can be
1962 * added to the end of this list after launch. Also hot-removing a
1963 * drive causes a NULL slot to appear in the list.
1964 *
1965 * During shutdown, this list is deleted, so that each launch gets a
1966 * fresh set of drives (however callers: don't do this, create a new
1967 * handle each time).
1968 *
1969 * Always use ITER_DRIVES macro to iterate over this list!
1970 */
1971 struct drive **drives;
1972 size_t nr_drives;
1973 #define ITER_DRIVES(g,i,drv) \
1975 for (i = 0; i < (g)->nr_drives; ++i) \
1976 if (((drv) = (g)->drives[i]) != NULL)
1977 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1979 char *backend; /* The full string, always non-NULL. */
1980 char *backend_arg; /* Pointer to the argument part. */
1981 const struct backend_ops *backend_ops;
1982 void *backend_data; /* Per-handle data. */
1983 char **backend_settings; /* Backend settings (can be NULL). */
1984 /**** Runtime information. ****/
1986 /* Temporary and cache directories. */
1987 /* The actual temporary directory - this is not created with the
1988 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1989 */
1990 char *tmpdir;
1991 char *sockdir;
1992 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1993 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1994 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1995 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1996 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1997 /* Error handler, plus stack of old error handlers. */
1999 gl_tls_key_t error_data;
2000 /* Linked list of error_data structures allocated for this handle,
2002 * plus a mutex to protect the linked list.
2003 */
2004 gl_lock_define (, error_data_list_lock);
2005 struct error_data *error_data_list;
2006 /* Out of memory error handler. */
2008 guestfs_abort_cb abort_cb;
2009 /* Events. */
2011 struct event *events;
2012 size_t nr_events;
2013 /* Private data area. */
2015 struct hash_table *pda;
2016 struct pda_entry *pda_next;
2017 /* User cancelled transfer. Not signal-atomic, but it doesn't
2019 * matter for this case because we only care if it is != 0.
2020 */
2021 int user_cancel;
2022 struct timeval launch_t; /* The time that we called guestfs_launch. */
2024 /* Used by bindtests. */
2026 FILE *test_fp;
2027 /* Used to generate unique numbers, eg for temp files. To use this,
2029 * '++g->unique'. Note these are only unique per-handle, not
2030 * globally unique.
2031 */
2032 int unique;
2033 /*** Protocol. ***/
2035 struct connection *conn; /* Connection to appliance. */
2036 int msg_next_serial;
2037 #if HAVE_FUSE
2039 /**** Used by the mount-local APIs. ****/
2040 char *localmountpoint;
2041 struct fuse *fuse; /* FUSE handle. */
2042 int ml_dir_cache_timeout; /* Directory cache timeout. */
2043 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
2044 int ml_read_only; /* If mounted read-only. */
2045 int ml_debug_calls; /* Extra debug info on each FUSE call. */
2046 #endif
2047 #ifdef HAVE_LIBVIRT_BACKEND
2049 /* Used by lib/libvirt-auth.c. */
2050 #define NR_CREDENTIAL_TYPES 9
2051 unsigned int nr_supported_credentials;
2052 int supported_credentials[NR_CREDENTIAL_TYPES];
2053 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
2054 bool wrapper_warning_done;
2055 unsigned int nr_requested_credentials;
2056 virConnectCredentialPtr requested_credentials;
2057 #endif
2058 /* Cached features. */
2060 struct cached_feature *features;
2061 size_t nr_features;
2062 };
2063 The libguestfs handle.
2065 Structure "lib/guestfs-internal.h:version"
2067 struct version {
2069 int v_major;
2070 int v_minor;
2071 int v_micro;
2072 };
2073 Used for storing major.minor.micro version numbers. See lib/version.c
2075 for more information.
2076 File lib/guid.c
2078 Function "lib/guid.c:guestfs_int_validate_guid"
2080 int
2082 guestfs_int_validate_guid (const char *str)
2083 Check whether a string supposed to contain a GUID actually contains it.
2085 It can recognize strings either as
2086 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
2087 "21EC2020-3AEA-1069-A2DD-08002B30309D".
2088 File lib/handle.c
2090 This file deals with the "guestfs_h" handle, creating it, closing it,
2092 and initializing/setting/getting fields.
2093 Function "lib/handle.c:init_libguestfs"
2095 static void
2097 init_libguestfs (void)
2098 No initialization is required by libguestfs, but libvirt and libxml2
2100 require initialization if they might be called from multiple threads.
2101 Hence this constructor function which is called when libguestfs is
2102 first loaded.
2103 Function "lib/handle.c:shutdown_backend"
2105 static int
2107 shutdown_backend (guestfs_h *g, int check_for_errors)
2108 This function is the common path for shutting down the backend qemu
2110 process.
2111 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
2113 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
2114 "check_for_errors" is a hint to the backend about whether we care about
2116 errors or not. In the libvirt case it can be used to optimize the
2117 shutdown for speed when we don't care.
2118 Function "lib/handle.c:close_handles"
2120 static void
2122 close_handles (void)
2123 Close all open handles (called from atexit(3)).
2125 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
2127 int
2129 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
2130 This is a convenience function, but we might consider exporting it as
2132 an API in future.
2133 File lib/inspect-icon.c
2135 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2137 char *
2139 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2140 const char *extension,
2141 uint64_t max_size)
2142 Download a guest file to a local temporary file.
2144 The name of the temporary (downloaded) file is returned. The caller
2146 must free the pointer, but does not need to delete the temporary file.
2147 It will be deleted when the handle is closed.
2148 The name of the temporary file is randomly generated, but an extension
2150 can be specified using "extension" (or pass "NULL" for none).
2151 Refuse to download the guest file if it is larger than "max_size". On
2153 this and other errors, "NULL" is returned.
2154 File lib/launch-direct.c
2156 Implementation of the "direct" backend.
2158 For more details see "BACKENDS" in guestfs(3).
2160 Function "lib/launch-direct.c:add_drive_standard_params"
2162 static int
2164 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2165 struct qemuopts *qopts,
2166 size_t i, struct drive *drv)
2167 Add the standard elements of the "-drive" parameter.
2169 File lib/launch-libvirt.c
2171 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2173 static char *
2175 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2176 Return "drv->src.format", but if it is "NULL", autodetect the format.
2178 libvirt has disabled the feature of detecting the disk format, unless
2180 the administrator sets "allow_disk_format_probing=1" in
2181 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2182 set, so we have to do format detection here using "qemu-img" and pass
2183 that to libvirt.
2184 This can still be a security issue, so in most cases it is recommended
2186 the users pass the format to libguestfs which will faithfully pass that
2187 straight through to libvirt without doing autodetection.
2188 Caller must free the returned string. On error this function sets the
2190 error in the handle and returns "NULL".
2191 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2193 static char *
2195 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2196 const char *format)
2197 Create a qcow2 format overlay, with the given "backing_drive" (file).
2199 The "format" parameter is the backing file format. The "format"
2200 parameter can be NULL, in this case the backing format will be
2201 determined automatically. This is used to create the appliance
2202 overlay, and also for read-only drives.
2203 File lib/launch.c
2205 This file implements "guestfs_launch" in guestfs(3).
2207 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2209 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2210 so this file mostly passes calls through to the current backend.
2211 Function "lib/launch.c:guestfs_int_launch_send_progress"
2213 void
2215 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2216 This function sends a launch progress message.
2218 Launching the appliance generates approximate progress messages.
2220 Currently these are defined as follows:
2221 0 / 12: launch clock starts
2223 3 / 12: appliance created
2224 6 / 12: detected that guest kernel started
2225 9 / 12: detected that /init script is running
2226 12 / 12: launch completed successfully
2227 Notes:
2229 1. This is not a documented ABI and the behaviour may be changed or
2231 removed in future.
2232 2. Messages are only sent if more than 5 seconds has elapsed since the
2234 launch clock started.
2235 3. There is a hack in lib/proto.c to make this work.
2237 Function "lib/launch.c:guestfs_int_timeval_diff"
2239 int64_t
2241 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2242 Compute "y - x" and return the result in milliseconds.
2244 Approximately the same as this code:
2246 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2247 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2249 void
2251 guestfs_int_unblock_sigterm (void)
2252 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2254 parent process can send "SIGTERM" to the child process in case
2255 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2256 Function "lib/launch.c:guestfs_impl_max_disks"
2258 int
2260 guestfs_impl_max_disks (guestfs_h *g)
2261 Returns the maximum number of disks allowed to be added to the backend
2263 (backend dependent).
2264 Function "lib/launch.c:guestfs_impl_wait_ready"
2266 int
2268 guestfs_impl_wait_ready (guestfs_h *g)
2269 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2271 this function after launch in versions ≤ 1.0.70, but it is now an
2272 (almost) no-op.
2273 Function "lib/launch.c:guestfs_int_create_socketname"
2275 int
2277 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2278 char (*sockpath)[UNIX_PATH_MAX])
2279 Create the path for a socket with the selected filename in the tmpdir.
2281 Function "lib/launch.c:guestfs_int_register_backend"
2283 void
2285 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2286 When the library is loaded, each backend calls this function to
2288 register itself in a global list.
2289 Function "lib/launch.c:guestfs_int_set_backend"
2291 int
2293 guestfs_int_set_backend (guestfs_h *g, const char *method)
2294 Implementation of "guestfs_set_backend" in guestfs(3).
2296 · Callers must ensure this is only called in the config state.
2298 · This shouldn't call "error" since it may be called early in handle
2300 initialization. It can return an error code however.
2301 File lib/private-data.c
2303 Implement a private data area where libguestfs C API users can attach
2305 arbitrary pieces of data to a "guestfs_h" handle.
2306 For more information see "PRIVATE DATA AREA" in guestfs(3).
2308 Language bindings do not generally expose this, largely because in non-
2310 C languages it is easy to associate data with handles in other ways
2311 (using hash tables or maps).
2312 Structure "lib/private-data.c:pda_entry"
2314 struct pda_entry {
2316 char *key; /* key */
2317 void *data; /* opaque user data pointer */
2318 };
2319 The private data area is internally stored as a gnulib hash table
2321 containing "pda_entry" structures.
2322 Note the private data area is allocated lazily, since the vast majority
2324 of callers will never use it. This means "g->pda" is likely to be
2325 "NULL".
2326 File lib/proto.c
2328 This is the code used to send and receive RPC messages and (for certain
2330 types of message) to perform file transfers. This code is driven from
2331 the generated actions (lib/actions-*.c). There are five different
2332 cases to consider:
2333 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2335 There is no RPC involved at all, it's all handled inside the
2336 library.
2337 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2339 request, then read the reply. The sequence of calls is:
2340 guestfs_int_send
2342 guestfs_int_recv
2343 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2345 guestfs(3)). We write the request, then write the file(s), then
2346 read the reply. The sequence of calls is:
2347 guestfs_int_send
2349 guestfs_int_send_file (possibly multiple times)
2350 guestfs_int_recv
2351 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2353 guestfs(3)). We write the request, then read the reply, then read
2354 the file(s). The sequence of calls is:
2355 guestfs_int_send
2357 guestfs_int_recv
2358 guestfs_int_recv_file (possibly multiple times)
2359 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2361 this in the current API, but they would be implemented as a
2362 combination of cases 3 and 4.
2363 All read/write/etc operations are performed using the current
2365 connection module ("g->conn"). During operations the connection module
2366 transparently handles log messages that appear on the console.
2367 Function "lib/proto.c:child_cleanup"
2369 static void
2371 child_cleanup (guestfs_h *g)
2372 This is called if we detect EOF, ie. qemu died.
2374 Function "lib/proto.c:guestfs_int_progress_message_callback"
2376 void
2378 guestfs_int_progress_message_callback (guestfs_h *g,
2379 const guestfs_progress *message)
2380 Convenient wrapper to generate a progress message callback.
2382 Function "lib/proto.c:guestfs_int_log_message_callback"
2384 void
2386 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2387 Connection modules call us back here when they get a log message.
2389 Function "lib/proto.c:check_daemon_socket"
2391 static ssize_t
2393 check_daemon_socket (guestfs_h *g)
2394 Before writing to the daemon socket, check the read side of the daemon
2396 socket for any of these conditions:
2397 error
2399 return -1
2400 daemon cancellation message
2402 return -2
2403 progress message
2405 handle it here
2406 end of input or appliance exited unexpectedly
2408 return 0
2409 anything else
2411 return 1
2412 Function "lib/proto.c:guestfs_int_send_file"
2414 int
2416 guestfs_int_send_file (guestfs_h *g, const char *filename)
2417 Send a file.
2419 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2421 must read the error message).
2422 Function "lib/proto.c:send_file_data"
2424 static int
2426 send_file_data (guestfs_h *g, const char *buf, size_t len)
2427 Send a chunk of file data.
2429 Function "lib/proto.c:send_file_cancellation"
2431 static int
2433 send_file_cancellation (guestfs_h *g)
2434 Send a cancellation message.
2436 Function "lib/proto.c:send_file_complete"
2438 static int
2440 send_file_complete (guestfs_h *g)
2441 Send a file complete chunk.
2443 Function "lib/proto.c:recv_from_daemon"
2445 static int
2447 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2448 This function reads a single message, file chunk, launch flag or
2450 cancellation flag from the daemon. If something was read, it returns
2451 0, otherwise "-1".
2452 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2454 *size_rtn returns the size of the returned message or it may be
2456 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2457 *buf_rtn is returned containing the message (if any) or will be set to
2459 "NULL". *buf_rtn must be freed by the caller.
2460 This checks for EOF (appliance died) and passes that up through the
2462 child_cleanup function above.
2463 Log message, progress messages are handled transparently here.
2465 Function "lib/proto.c:guestfs_int_recv"
2467 int
2469 guestfs_int_recv (guestfs_h *g, const char *fn,
2470 guestfs_message_header *hdr,
2471 guestfs_message_error *err,
2472 xdrproc_t xdrp, char *ret)
2473 Receive a reply.
2475 Function "lib/proto.c:guestfs_int_recv_discard"
2477 int
2479 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2480 Same as "guestfs_int_recv", but it discards the reply message.
2482 Notes (XXX):
2484 · This returns an int, but all current callers ignore it.
2486 · The error string may end up being set twice on error paths.
2488 Function "lib/proto.c:guestfs_int_recv_file"
2490 int
2492 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2493 Returns "-1" = error, 0 = EOF, ">0" = more data
2495 Function "lib/proto.c:receive_file_data"
2497 static ssize_t
2499 receive_file_data (guestfs_h *g, void **buf_r)
2500 Receive a chunk of file data.
2502 Returns "-1" = error, 0 = EOF, ">0" = more data
2504 File lib/qemu.c
2506 Functions to handle qemu versions and features.
2508 Function "lib/qemu.c:guestfs_int_test_qemu"
2510 struct qemu_data *
2512 guestfs_int_test_qemu (guestfs_h *g)
2513 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2515 other commands so we can find out the version of qemu and what options
2516 this qemu supports.
2517 This caches the results in the cachedir so that as long as the qemu
2519 binary does not change, calling this is effectively free.
2520 Function "lib/qemu.c:cache_filename"
2522 static char *
2524 cache_filename (guestfs_h *g, const char *cachedir,
2525 const struct stat *statbuf, const char *suffix)
2526 Generate the filenames, for the stat file and the other cache files.
2528 By including the size and mtime in the filename we also ensure that the
2530 same user can use multiple versions of qemu without conflicts.
2531 Function "lib/qemu.c:parse_qemu_version"
2533 static void
2535 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2536 struct version *qemu_version)
2537 Parse the first line of "qemu_help" into the major and minor version of
2539 qemu, but don't fail if parsing is not possible.
2540 Function "lib/qemu.c:parse_json"
2542 static void
2544 parse_json (guestfs_h *g, const char *json, yajl_val *treep)
2545 Parse the json output from QMP. But don't fail if parsing is not
2547 possible.
2548 Function "lib/qemu.c:generic_read_cache"
2550 static int
2552 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2553 Generic functions for reading and writing the cache files, used where
2555 we are just reading and writing plain text strings.
2556 Function "lib/qemu.c:generic_qmp_test"
2558 static int
2560 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2561 const char *qmp_command,
2562 char **outp)
2563 Run a generic QMP test on the QEMU binary.
2565 Function "lib/qemu.c:guestfs_int_qemu_version"
2567 struct version
2569 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2570 Return the parsed version of qemu.
2572 Function "lib/qemu.c:guestfs_int_qemu_supports"
2574 int
2576 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2577 const char *option)
2578 Test if option is supported by qemu command line (just by grepping the
2580 help text).
2581 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2583 int
2585 guestfs_int_qemu_supports_device (guestfs_h *g,
2586 const struct qemu_data *data,
2587 const char *device_name)
2588 Test if device is supported by qemu (currently just greps the "qemu
2590 -device ?" output).
2591 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2593 int
2595 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2596 const struct qemu_data *data)
2597 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2599 2.10 (but sometimes disabled).
2600 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2602 char *
2604 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2605 Escape a qemu parameter.
2607 Every "," becomes ",,". The caller must free the returned string.
2609 XXX This functionality is now only used when constructing a qemu-img
2611 command in lib/create.c. We should extend the qemuopts library to
2612 cover this use case.
2613 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2615 char *
2617 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2618 const struct drive_source *src)
2619 Useful function to format a drive + protocol for qemu.
2621 Note that the qemu parameter is the bit after "file=". It is not
2623 escaped here, but would usually be escaped if passed to qemu as part of
2624 a full -drive parameter (but not for qemu-img(1)).
2625 Function "lib/qemu.c:guestfs_int_discard_possible"
2627 bool
2629 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2630 const struct version *qemu_version)
2631 Test if discard is both supported by qemu AND possible with the
2633 underlying file or device. This returns 1 if discard is possible. It
2634 returns 0 if not possible and sets the error to the reason why.
2635 This function is called when the user set "discard == "enable"".
2637 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2639 void
2641 guestfs_int_free_qemu_data (struct qemu_data *data)
2642 Free the "struct qemu_data".
2644 File lib/rescue.c
2646 Support for virt-rescue(1).
2648 File lib/stringsbuf.c
2650 An expandable NULL-terminated vector of strings (like "argv").
2652 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2654 Note: Don't confuse this with stringsbuf in the daemon which is a
2656 different type with different methods.
2657 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2659 void
2661 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2662 Add a string to the end of the list.
2664 This doesn't call strdup(3) on the string, so the string itself is
2666 stored inside the vector.
2667 Function "lib/stringsbuf.c:guestfs_int_add_string"
2669 void
2671 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2672 Add a string to the end of the list.
2674 This makes a copy of the string.
2676 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2678 void
2680 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2681 const char *fs, ...)
2682 Add a string to the end of the list.
2684 Uses an sprintf-like format string when creating the string.
2686 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2688 void
2690 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2691 Finish the string buffer.
2693 This adds the terminating NULL to the end of the vector.
2695 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2697 void
2699 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2700 Free the string buffer and the strings.
2702 File lib/tmpdirs.c
2704 Handle temporary directories.
2706 Function "lib/tmpdirs.c:set_abs_path"
2708 static int
2710 set_abs_path (guestfs_h *g, const char *ctxstr,
2711 const char *tmpdir, char **tmpdir_ret)
2712 We need to make all tmpdir paths absolute because lots of places in the
2714 code assume this. Do it at the time we set the path or read the
2715 environment variable (https://bugzilla.redhat.com/882417).
2716 The "ctxstr" parameter is a string displayed in error messages giving
2718 the context of the operation (eg. name of environment variable being
2719 used, or API function being called).
2720 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2722 char *
2724 guestfs_impl_get_tmpdir (guestfs_h *g)
2725 Implements the "guestfs_get_tmpdir" API.
2727 Note this actually calculates the tmpdir, so it never returns "NULL".
2729 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2731 char *
2733 guestfs_impl_get_cachedir (guestfs_h *g)
2734 Implements the "guestfs_get_cachedir" API.
2736 Note this actually calculates the cachedir, so it never returns "NULL".
2738 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2740 char *
2742 guestfs_impl_get_sockdir (guestfs_h *g)
2743 Implements the "guestfs_get_sockdir" API.
2745 Note this actually calculates the sockdir, so it never returns "NULL".
2747 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2749 int
2751 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2752 The "g->tmpdir" (per-handle temporary directory) is not created when
2754 the handle is created. Instead we create it lazily before the first
2755 time it is used, or during launch.
2756 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2758 char *
2760 guestfs_int_make_temp_path (guestfs_h *g,
2761 const char *name, const char *extension)
2762 Generate unique temporary paths for temporary files.
2764 Returns a unique path or NULL on error.
2766 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2768 char *
2770 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2771 Create the supermin appliance directory under cachedir, if it does not
2773 exist.
2774 Sanity-check that the permissions on the cachedir are safe, in case it
2776 has been pre-created maliciously or tampered with.
2777 Returns the directory name which the caller must free.
2779 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2781 void
2783 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2784 Recursively remove a temporary directory. If removal fails, just
2786 return (it's a temporary directory so it'll eventually be cleaned up by
2787 a temp cleaner).
2788 This is implemented using "rm -rf" because that's simpler and safer.
2790 File lib/umask.c
2792 Return current umask in a thread-safe way.
2794 glibc documents, but does not actually implement, a "getumask(3)" call.
2796 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2798 and other Unix, this file implements an expensive but thread-safe way
2799 to get the current process's umask.
2800 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2802 Function "lib/umask.c:guestfs_int_getumask"
2804 int
2806 guestfs_int_getumask (guestfs_h *g)
2807 Returns the current process's umask. On failure, returns "-1" and sets
2809 the error in the guestfs handle.
2810 Function "lib/umask.c:get_umask_from_proc"
2812 static int
2814 get_umask_from_proc (guestfs_h *g)
2815 For Linux ≥ 4.7 get the umask from /proc/self/status.
2817 On failure this returns "-1". However if we could not open the /proc
2819 file or find the "Umask" entry in it, return "-2" which causes the
2820 fallback path to run.
2821 Function "lib/umask.c:get_umask_from_fork"
2823 static int
2825 get_umask_from_fork (guestfs_h *g)
2826 Fallback method of getting the umask using fork.
2828 File lib/unit-tests.c
2830 Unit tests of internal functions.
2832 These tests may use a libguestfs handle, but must not launch the
2834 handle. Also, avoid long-running tests.
2835 Function "lib/unit-tests.c:test_split"
2837 static void
2839 test_split (void)
2840 Test "guestfs_int_split_string".
2842 Function "lib/unit-tests.c:test_concat"
2844 static void
2846 test_concat (void)
2847 Test "guestfs_int_concat_strings".
2849 Function "lib/unit-tests.c:test_join"
2851 static void
2853 test_join (void)
2854 Test "guestfs_int_join_strings".
2856 Function "lib/unit-tests.c:test_validate_guid"
2858 static void
2860 test_validate_guid (void)
2861 Test "guestfs_int_validate_guid".
2863 Function "lib/unit-tests.c:test_drive_name"
2865 static void
2867 test_drive_name (void)
2868 Test "guestfs_int_drive_name".
2870 Function "lib/unit-tests.c:test_drive_index"
2872 static void
2874 test_drive_index (void)
2875 Test "guestfs_int_drive_index".
2877 Function "lib/unit-tests.c:test_getumask"
2879 static void
2881 test_getumask (void)
2882 Test "guestfs_int_getumask".
2884 Function "lib/unit-tests.c:test_command"
2886 static void
2888 test_command (void)
2889 Test "guestfs_int_new_command" etc.
2891 XXX These tests could be made much more thorough. So far we simply
2893 test that it's not obviously broken.
2894 Function "lib/unit-tests.c:test_qemu_escape_param"
2896 static void
2898 test_qemu_escape_param (void)
2899 Test "guestfs_int_qemu_escape_param"
2901 XXX I wanted to make this test run qemu, passing some parameters which
2903 need to be escaped, but I cannot think of a way to do that without
2904 launching a VM.
2905 Function "lib/unit-tests.c:test_timeval_diff"
2907 static void
2909 test_timeval_diff (void)
2910 Test "guestfs_int_timeval_diff".
2912 File lib/version.c
2914 This file provides simple version number management.
2916 Function "lib/version.c:guestfs_int_version_from_x_y"
2918 int
2920 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2921 Parses a version from a string, looking for a "X.Y" pattern.
2923 Returns "-1" on failure (like failed integer parsing), 0 on missing
2925 match, and 1 on match and successful parsing. "v" is changed only on
2926 successful match.
2927 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2929 int
2931 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2932 const char *str, const pcre *re)
2933 Parses a version from a string, using the specified "re" as regular
2935 expression which must provide (at least) two matches.
2936 Returns "-1" on failure (like failed integer parsing), 0 on missing
2938 match, and 1 on match and successful parsing. "v" is changed only on
2939 successful match.
2940 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2942 int
2944 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2945 const char *str)
2946 Parses a version from a string, either looking for a "X.Y" pattern or
2948 considering it as whole integer.
2949 Returns "-1" on failure (like failed integer parsing), 0 on missing
2951 match, and 1 on match and successful parsing. "v" is changed only on
2952 successful match.
2953 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2955 int
2957 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2958 Parse small, unsigned ints, as used in version numbers.
2960 This will fail with an error if trailing characters are found after the
2962 integer.
2963 Returns ≥ 0 on success, or "-1" on failure.
2965 File lib/wait.c
2967 Function "lib/wait.c:guestfs_int_waitpid"
2969 int
2971 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2972 A safe version of waitpid(3) which retries if "EINTR" is returned.
2974 Note: this only needs to be used in the library, or in programs that
2976 install a non-restartable "SIGCHLD" handler (which is not the case for
2977 any current libguestfs virt tools).
2978 If the main program installs a SIGCHLD handler and sets it to be non-
2980 restartable, then what can happen is the library is waiting in a wait
2981 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2982 wait syscall returns "EINTR". Since the library cannot control the
2983 signal handler, we have to instead restart the wait syscall, which is
2984 the purpose of this wrapper.
2985 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2987 void
2989 guestfs_int_waitpid_noerror (pid_t pid)
2990 Like "guestfs_int_waitpid", but ignore errors.
2992 Function "lib/wait.c:guestfs_int_wait4"
2994 int
2996 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2997 struct rusage *rusage, const char *errmsg)
2998 A safe version of wait4(2) which retries if "EINTR" is returned.
3000 File lib/whole-file.c
3002 Function "lib/whole-file.c:guestfs_int_read_whole_file"
3004 int
3006 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
3007 char **data_r, size_t *size_r)
3008 Read the whole file "filename" into a memory buffer.
3010 The memory buffer is initialized and returned in "data_r". The size of
3012 the file in bytes is returned in "size_r". The return buffer must be
3013 freed by the caller.
3014 On error this sets the error in the handle and returns "-1".
3016 For the convenience of callers, the returned buffer is NUL-terminated
3018 (the NUL is not included in the size).
3019 The file must be a regular, local, trusted file. In particular, do not
3021 use this function to read files that might be under control of an
3022 untrusted user since that will lead to a denial-of-service attack.
3023 Subdirectory builder
3025 File builder/index-parser-c.c
3026 This file handles the interface between the C/lex/yacc index file
3028 parser, and the OCaml world. See builder/index_parser.ml for the OCaml
3029 type definition.
3030 Subdirectory common/edit
3032 File common/edit/file-edit.c
3033 This file implements common file editing in a range of utilities
3035 including guestfish(1), virt-edit(1), virt-customize(1) and
3036 virt-builder(1).
3037 It contains the code for both interactive-(editor-)based editing and
3039 non-interactive editing using Perl snippets.
3040 Function "common/edit/file-edit.c:edit_file_editor"
3042 int
3044 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
3045 const char *backup_extension, int verbose)
3046 Edit "filename" using the specified "editor" application.
3048 If "backup_extension" is not null, then a copy of "filename" is saved
3050 with "backup_extension" appended to its file name.
3051 If "editor" is null, then the $EDITOR environment variable will be
3053 queried for the editor application, leaving "vi" as fallback if not
3054 set.
3055 Returns "-1" for failure, 0 on success, 1 if the editor did not change
3057 the file (e.g. the user closed the editor without saving).
3058 Function "common/edit/file-edit.c:edit_file_perl"
3060 int
3062 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
3063 const char *backup_extension, int verbose)
3064 Edit "filename" running the specified "perl_expr" using Perl.
3066 If "backup_extension" is not null, then a copy of "filename" is saved
3068 with "backup_extension" appended to its file name.
3069 Returns "-1" for failure, 0 on success.
3071 Subdirectory common/mlxml
3073 File common/mlxml/xml-c.c
3074 Mini interface to libxml2.
3076 Subdirectory common/options
3078 File common/options/config.c
3079 This file parses the guestfish configuration file, usually
3081 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
3082 Note that "parse_config" is called very early, before command line
3084 parsing, before the "verbose" flag has been set, even before the global
3085 handle "g" is opened.
3086 File common/options/decrypt.c
3088 This file implements the decryption of disk images, usually done before
3090 mounting their partitions.
3091 Function "common/options/decrypt.c:make_mapname"
3093 static void
3095 make_mapname (const char *device, char *mapname, size_t len)
3096 Make a LUKS map name from the partition name, eg. "/dev/vda2" =>
3098 "luksvda2"
3099 Function "common/options/decrypt.c:inspect_do_decrypt"
3101 void
3103 inspect_do_decrypt (guestfs_h *g)
3104 Simple implementation of decryption: look for any "crypto_LUKS"
3106 partitions and decrypt them, then rescan for VGs. This only works for
3107 Fedora whole-disk encryption. WIP to make this work for other
3108 encryption schemes.
3109 File common/options/display-options.c
3111 This file contains common code used to implement --short-options and
3113 --long-options in C virt tools. (The equivalent for OCaml virt tools
3114 is implemented by common/mltools/getopt.ml).
3115 These "hidden" options are used to implement bash tab completion.
3117 Function "common/options/display-options.c:display_short_options"
3119 void
3121 display_short_options (const char *format)
3122 Implements the internal "tool --short-options" flag, which just lists
3124 out the short options available. Used by bash completion.
3125 Function "common/options/display-options.c:display_long_options"
3127 void
3129 display_long_options (const struct option *long_options)
3130 Implements the internal "tool --long-options" flag, which just lists
3132 out the long options available. Used by bash completion.
3133 File common/options/domain.c
3135 Implements the guestfish (and other tools) -d option.
3137 Function "common/options/domain.c:add_libvirt_drives"
3139 int
3141 add_libvirt_drives (guestfs_h *g, const char *guest)
3142 This function is called when a user invokes "guestfish -d guest".
3144 Returns the number of drives added ("> 0"), or "-1" for failure.
3146 File common/options/inspect.c
3148 This file implements inspecting the guest and mounting the filesystems
3150 found in the right places. It is used by the guestfish(1) -i option
3151 and some utilities such as virt-cat(1).
3152 Function "common/options/inspect.c:inspect_mount_handle"
3154 void
3156 inspect_mount_handle (guestfs_h *g)
3157 This function implements the -i option.
3159 Function "common/options/inspect.c:print_inspect_prompt"
3161 void
3163 print_inspect_prompt (void)
3164 This function is called only if "inspect_mount_root" was called, and
3166 only after we've printed the prompt in interactive mode.
3167 File common/options/keys.c
3169 Function "common/options/keys.c:read_key"
3171 char *
3173 read_key (const char *param)
3174 Read a passphrase ('Key') from /dev/tty with echo off.
3176 The caller (fish/cmds.c) will call free on the string afterwards.
3178 Based on the code in cryptsetup file lib/utils.c.
3179 File common/options/options.c
3181 This file contains common options parsing code used by guestfish and
3183 many other tools which share a common options syntax.
3184 For example, guestfish, virt-cat, virt-ls etc all support the -a
3186 option, and that is handled in all of those tools using a macro
3187 "OPTION_a" defined in fish/options.h.
3188 There are a lot of common global variables used, "drvs" accumulates the
3190 list of drives, "verbose" for the -v flag, and many more.
3191 Function "common/options/options.c:option_a"
3193 void
3195 option_a (const char *arg, const char *format, struct drv **drvsp)
3196 Handle the guestfish -a option on the command line.
3198 Function "common/options/options.c:option_d"
3200 void
3202 option_d (const char *arg, struct drv **drvsp)
3203 Handle the -d option when passed on the command line.
3205 Function "common/options/options.c:display_mountpoints_on_failure"
3207 static void
3209 display_mountpoints_on_failure (const char *mp_device,
3210 const char *user_supplied_options)
3211 If the -m option fails on any command, display a useful error message
3213 listing the mountpoints.
3214 File common/options/uri.c
3216 This file implements URI parsing for the -a option, in many utilities
3218 including guestfish(1), virt-cat(1), virt-builder(1),
3219 virt-customize(1), etc.
3220 Subdirectory common/parallel
3222 File common/parallel/domains.c
3223 This file is used by "virt-df" and some of the other tools when they
3225 are implicitly asked to operate over all libvirt domains (VMs), for
3226 example when "virt-df" is called without specifying any particular disk
3227 image.
3228 It hides the complexity of querying the list of domains from libvirt.
3230 Function "common/parallel/domains.c:free_domains"
3232 void
3234 free_domains (void)
3235 Frees up everything allocated by "get_all_libvirt_domains".
3237 Function "common/parallel/domains.c:get_all_libvirt_domains"
3239 void
3241 get_all_libvirt_domains (const char *libvirt_uri)
3242 Read all libguest guests into the global variables "domains" and
3244 "nr_domains". The guests are ordered by name. This exits on any
3245 error.
3246 File common/parallel/estimate-max-threads.c
3248 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3250 size_t
3252 estimate_max_threads (void)
3253 This function uses the output of "free -m" to estimate how many
3255 libguestfs appliances could be safely started in parallel. Note that
3256 it always returns ≥ 1.
3257 Function "common/parallel/estimate-max-threads.c:read_line_from"
3259 static char *
3261 read_line_from (const char *cmd)
3262 Run external command and read the first line of output.
3264 File common/parallel/parallel.c
3266 This file is used by "virt-df" and some of the other tools when they
3268 need to run multiple parallel libguestfs instances to operate on a
3269 large number of libvirt domains efficiently.
3270 It implements a multithreaded work queue. In addition it reorders the
3272 output so the output still appears in the same order as the input (ie.
3273 still ordered alphabetically).
3274 Function "common/parallel/parallel.c:start_threads"
3276 int
3278 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3279 Run the threads and work through the global list of libvirt domains.
3281 "option_P" is whatever the user passed in the -P option, or 0 if the
3283 user didn't use the -P option (in which case the number of threads is
3284 chosen heuristically).
3285 "options_handle" (which may be "NULL") is the global guestfs handle
3287 created by the options mini-library.
3288 The work function ("work") should do the work (inspecting the domain,
3290 etc.) on domain index "i". However it must not print out any result
3291 directly. Instead it prints anything it needs to the supplied "FILE
3292 *". The work function should return 0 on success or "-1" on error.
3293 The "start_threads" function returns 0 if all work items completed
3295 successfully, or "-1" if there was an error.
3296 Subdirectory common/progress
3298 File common/progress/progress.c
3299 This file implements the progress bar in guestfish(1), virt-resize(1)
3301 and virt-sparsify(1).
3302 Function "common/progress/progress.c:progress_bar_init"
3304 struct progress_bar *
3306 progress_bar_init (unsigned flags)
3307 Initialize a progress bar struct.
3309 It is intended that you can reuse the same struct for multiple commands
3311 (but only in a single thread). Call "progress_bar_reset" before each
3312 new command.
3313 Function "common/progress/progress.c:progress_bar_free"
3315 void
3317 progress_bar_free (struct progress_bar *bar)
3318 Free a progress bar struct.
3320 Function "common/progress/progress.c:progress_bar_reset"
3322 void
3324 progress_bar_reset (struct progress_bar *bar)
3325 This function should be called just before you issue any command.
3327 Function "common/progress/progress.c:estimate_remaining_time"
3329 static double
3331 estimate_remaining_time (struct progress_bar *bar, double ratio)
3332 Return remaining time estimate (in seconds) for current call.
3334 This returns the running mean estimate of remaining time, but if the
3336 latest estimate of total time is greater than two s.d.'s from the
3337 running mean then we don't print anything because we're not confident
3338 that the estimate is meaningful. (Returned value is <0.0 when nothing
3339 should be printed).
3340 Function "common/progress/progress.c:progress_bar_set"
3342 void
3344 progress_bar_set (struct progress_bar *bar,
3345 uint64_t position, uint64_t total)
3346 Set the position of the progress bar.
3348 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3350 Subdirectory common/qemuopts
3352 File common/qemuopts/qemuopts-tests.c
3353 Unit tests of internal functions.
3355 These tests may use a libguestfs handle, but must not launch the
3357 handle. Also, avoid long-running tests.
3358 File common/qemuopts/qemuopts.c
3360 Mini-library for writing qemu command lines and qemu config files.
3362 There are some shortcomings with the model used for qemu options which
3364 aren't clear until you try to convert options into a configuration
3365 file. However if we attempted to model the options in more detail then
3366 this library would be both very difficult to use and incompatible with
3367 older versions of qemu. Hopefully the current model is a decent
3368 compromise.
3369 For reference here are the problems:
3371 · There's inconsistency in qemu between options and config file, eg.
3373 "-smp 4" becomes:
3374 [smp-opts]
3376 cpus = "4"
3377 · Similar to the previous point, you can write either "-smp 4" or
3379 "-smp cpus=4" (although this won't work in very old qemu). When
3380 generating a config file you need to know the implicit key name.
3381 · In "-opt key=value,..." the "key" is really a tree/array specifier.
3383 The way this works is complicated but hinted at here:
3384 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3385 · Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3387 "-machine kernel=foo".
3388 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3390 struct qemuopts *
3392 qemuopts_create (void)
3393 Create an empty list of qemu options.
3395 The caller must eventually free the list by calling "qemuopts_free".
3397 Returns "NULL" on error, setting "errno".
3399 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3401 void
3403 qemuopts_free (struct qemuopts *qopts)
3404 Free the list of qemu options.
3406 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3408 int
3410 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3411 Add a command line flag which has no argument. eg:
3413 qemuopts_add_flag (qopts, "-nodefconfig");
3415 Returns 0 on success. Returns "-1" on error, setting "errno".
3417 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3419 int
3421 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3422 Add a command line flag which has a single argument. eg:
3424 qemuopts_add_arg (qopts, "-m", "1024");
3426 Don't use this if the argument is a comma-separated list, since quoting
3428 will not be done properly. See "qemuopts_add_arg_list".
3429 Returns 0 on success. Returns "-1" on error, setting "errno".
3431 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3433 int
3435 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3436 const char *fs, ...)
3437 Add a command line flag which has a single formatted argument. eg:
3439 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3441 Don't use this if the argument is a comma-separated list, since quoting
3443 will not be done properly. See "qemuopts_add_arg_list".
3444 Returns 0 on success. Returns "-1" on error, setting "errno".
3446 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3448 int
3450 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3451 const char *value)
3452 This is like "qemuopts_add_arg" except that no quoting is done on the
3454 value.
3455 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3457 neither shell quoting nor qemu comma quoting is done on the value.
3458 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3460 "qemuopts_to_config*" will fail.
3462 You should use this with great care.
3464 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3466 int
3468 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3469 Start an argument that takes a comma-separated list of fields.
3471 Typical usage is like this (with error handling omitted):
3473 qemuopts_start_arg_list (qopts, "-drive");
3475 qemuopts_append_arg_list (qopts, "file=foo");
3476 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3477 qemuopts_end_arg_list (qopts);
3478 which would construct "-drive file=foo,if=ide"
3480 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3482 call.
3483 Returns 0 on success. Returns "-1" on error, setting "errno".
3485 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3487 int
3489 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3490 const char *elem0, ...)
3491 Add a command line flag which has a list of arguments. eg:
3493 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3495 This is turned into a comma-separated list, like: "-drive
3497 file=foo,if=ide". Note that this handles qemu quoting properly, so
3498 individual elements may contain commas and this will do the right
3499 thing.
3500 Returns 0 on success. Returns "-1" on error, setting "errno".
3502 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3504 int
3506 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3507 Set the qemu binary name.
3509 Returns 0 on success. Returns "-1" on error, setting "errno".
3511 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3513 int
3515 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3516 Set the qemu binary name to "qemu-system-[arch]".
3518 As a special case if "arch" is "NULL", the binary is set to the KVM
3520 binary for the current host architecture:
3521 qemuopts_set_binary_by_arch (qopts, NULL);
3523 Returns 0 on success. Returns "-1" on error, setting "errno".
3525 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3527 int
3529 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3530 Write the qemu options to a script.
3532 "qemuopts_set_binary*" must be called first.
3534 The script file will start with "#!/bin/sh" and will be chmod to mode
3536 0755.
3537 Returns 0 on success. Returns "-1" on error, setting "errno".
3539 Function "common/qemuopts/qemuopts.c:shell_quote"
3541 static void
3543 shell_quote (const char *str, FILE *fp)
3544 Print "str" to "fp", shell-quoting it if necessary.
3546 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3548 static void
3550 shell_and_comma_quote (const char *str, FILE *fp)
3551 Print "str" to "fp" doing both shell and qemu comma quoting.
3553 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3555 int
3557 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3558 Write the qemu options to a "FILE *fp".
3560 "qemuopts_set_binary*" must be called first.
3562 Only the qemu command line is written. The caller may need to add
3564 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3565 Returns 0 on success. Returns "-1" on error, setting "errno".
3567 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3569 char **
3571 qemuopts_to_argv (struct qemuopts *qopts)
3572 Return a NULL-terminated argument list, of the kind that can be passed
3574 directly to execv(3).
3575 "qemuopts_set_binary*" must be called first. It will be returned as
3577 "argv[0]" in the returned list.
3578 The list of strings and the strings themselves must be freed by the
3580 caller.
3581 Returns "NULL" on error, setting "errno".
3583 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3585 int
3587 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3588 Write the qemu options to a qemu config file, suitable for reading in
3590 using "qemu -readconfig filename".
3591 Note that qemu config files have limitations on content and quoting, so
3593 not all qemuopts structs can be written (this function returns an error
3594 in these cases). For more information see
3595 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3596 https://bugs.launchpad.net/qemu/+bug/1686364
3597 Also, command line argument names and config file sections sometimes
3599 have different names. For example the equivalent of "-m 1024" is:
3600 [memory]
3602 size = "1024"
3603 This code does not attempt to convert between the two forms. You just
3605 need to know how to do that yourself.
3606 Returns 0 on success. Returns "-1" on error, setting "errno".
3608 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3610 int
3612 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3613 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3615 Subdirectory common/utils
3617 File common/utils/cleanups.c
3618 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3620 They are implemented using the "__attribute__((cleanup))" feature of
3621 gcc and clang. Typical usage is:
3622 fn ()
3624 {
3625 CLEANUP_FREE char *str = NULL;
3626 str = safe_asprintf (g, "foo");
3627 // str is freed automatically when the function returns
3628 }
3629 There are a few catches to be aware of with the cleanup mechanism:
3631 · If a cleanup variable is not initialized, then you can end up
3633 calling free(3) with an undefined value, resulting in the program
3634 crashing. For this reason, you should usually initialize every
3635 cleanup variable with something, eg. "NULL"
3636 · Don't mark variables holding return values as cleanup variables.
3638 · The "main()" function shouldn't use cleanup variables since it is
3640 normally exited by calling exit(3), and that doesn't call the
3641 cleanup handlers.
3642 The functions in this file are used internally by the "CLEANUP_*"
3644 macros. Don't call them directly.
3645 File common/utils/gnulib-cleanups.c
3647 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3649 They are implemented using the "__attribute__((cleanup))" feature of
3650 gcc and clang. Typical usage is:
3651 fn ()
3653 {
3654 CLEANUP_FREE char *str = NULL;
3655 str = safe_asprintf (g, "foo");
3656 // str is freed automatically when the function returns
3657 }
3658 There are a few catches to be aware of with the cleanup mechanism:
3660 · If a cleanup variable is not initialized, then you can end up
3662 calling free(3) with an undefined value, resulting in the program
3663 crashing. For this reason, you should usually initialize every
3664 cleanup variable with something, eg. "NULL"
3665 · Don't mark variables holding return values as cleanup variables.
3667 · The "main()" function shouldn't use cleanup variables since it is
3669 normally exited by calling exit(3), and that doesn't call the
3670 cleanup handlers.
3671 The functions in this file are used internally by the "CLEANUP_*"
3673 macros. Don't call them directly.
3674 File common/utils/guestfs-utils.h
3676 This header file is included in all "frontend" parts of libguestfs,
3678 namely the library, non-C language bindings, virt tools and tests.
3679 The daemon does not use this header. If you need a place to put
3681 something shared with absolutely everything including the daemon, put
3682 it in lib/guestfs-internal-all.h
3683 If a definition is only needed by a single component of libguestfs (eg.
3685 just the library, or just a single virt tool) then it should not be
3686 here!
3687 File common/utils/utils.c
3689 Utility functions used by the library, tools and language bindings.
3691 These functions must not call internal library functions such as
3693 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3694 Function "common/utils/utils.c:guestfs_int_split_string"
3696 char **
3698 guestfs_int_split_string (char sep, const char *str)
3699 Split string at separator character "sep", returning the list of
3701 strings. Returns "NULL" on memory allocation failure.
3702 Note (assuming "sep" is ":"):
3704 "str == NULL"
3706 aborts
3707 "str == """
3709 returns "[]"
3710 "str == "abc""
3712 returns "["abc"]"
3713 "str == ":""
3715 returns "["", ""]"
3716 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3718 char *
3720 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3721 char *buffer, size_t buflen)
3722 Translate a wait/system exit status into a printable string.
3724 Function "common/utils/utils.c:guestfs_int_random_string"
3726 int
3728 guestfs_int_random_string (char *ret, size_t len)
3729 Return a random string of characters.
3731 Notes:
3733 · The "ret" buffer must have length "len+1" in order to store the
3735 final "\0" character.
3736 · There is about 5 bits of randomness per output character (so about
3738 "5*len" bits of randomness in the resulting string).
3739 Function "common/utils/utils.c:guestfs_int_drive_name"
3741 char *
3743 guestfs_int_drive_name (size_t index, char *ret)
3744 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3746 Drive indexes count from 0. The return buffer has to be large enough
3748 for the resulting string, and the returned pointer points to the *end*
3749 of the string.
3750 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3752 Function "common/utils/utils.c:guestfs_int_drive_index"
3754 ssize_t
3756 guestfs_int_drive_index (const char *name)
3757 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3759 return the index (eg 27).
3760 Note that you must remove any prefix such as "hd", "sd" etc, or any
3762 partition number before calling the function.
3763 Function "common/utils/utils.c:guestfs_int_is_true"
3765 int
3767 guestfs_int_is_true (const char *str)
3768 Similar to "Tcl_GetBoolean".
3770 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3772 bool
3774 guestfs_int_string_is_valid (const char *str,
3775 size_t min_length, size_t max_length,
3776 int flags, const char *extra)
3777 Check a string for validity, that it contains only certain characters,
3779 and minimum and maximum length. This function is usually wrapped in a
3780 VALID_* macro, see lib/drives.c for an example.
3781 "str" is the string to check.
3783 "min_length" and "max_length" are the minimum and maximum length
3785 checks. 0 means no check.
3786 The flags control:
3788 "VALID_FLAG_ALPHA"
3790 7-bit ASCII-only alphabetic characters are permitted.
3791 "VALID_FLAG_DIGIT"
3793 7-bit ASCII-only digits are permitted.
3794 "extra" is a set of extra characters permitted, in addition to
3796 alphabetic and/or digits. ("extra = NULL" for no extra).
3797 Returns boolean "true" if the string is valid (passes all the tests),
3799 or "false" if not.
3800 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3802 void
3804 guestfs_int_fadvise_normal (int fd)
3805 Hint that we will read or write the file descriptor normally.
3807 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3809 and sets the per-file number of readahead pages to equal the block
3810 device readahead setting.
3811 It's OK to call this on a non-file since we ignore failure as it is
3813 only a hint.
3814 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3816 void
3818 guestfs_int_fadvise_sequential (int fd)
3819 Hint that we will read or write the file descriptor sequentially.
3821 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3823 and sets the per-file number of readahead pages to twice the block
3824 device readahead setting.
3825 It's OK to call this on a non-file since we ignore failure as it is
3827 only a hint.
3828 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3830 void
3832 guestfs_int_fadvise_random (int fd)
3833 Hint that we will read or write the file descriptor randomly.
3835 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3837 this flag is to:
3838 · Disable normal sequential file readahead.
3840 · If any read of the file is done which misses in the page cache, 2MB
3842 are read into the page cache. [I think - I'm not sure I totally
3843 understand what this is doing]
3844 It's OK to call this on a non-file since we ignore failure as it is
3846 only a hint.
3847 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3849 void
3851 guestfs_int_fadvise_noreuse (int fd)
3852 Hint that we will access the data only once.
3854 On Linux, this does nothing.
3856 It's OK to call this on a non-file since we ignore failure as it is
3858 only a hint.
3859 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3861 void
3863 guestfs_int_fadvise_dontneed (int fd)
3864 Hint that we will not access the data in the near future.
3866 On Linux, this immediately writes out any dirty pages in the page cache
3868 and then invalidates (drops) all pages associated with this file from
3869 the page cache. Apparently it does this even if the file is opened or
3870 being used by other processes. This setting is not persistent; if you
3871 subsequently read the file it will be cached in the page cache as
3872 normal.
3873 It's OK to call this on a non-file since we ignore failure as it is
3875 only a hint.
3876 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3878 void
3880 guestfs_int_fadvise_willneed (int fd)
3881 Hint that we will access the data in the near future.
3883 On Linux, this immediately reads the whole file into the page cache.
3885 This setting is not persistent; subsequently pages may be dropped from
3886 the page cache as normal.
3887 It's OK to call this on a non-file since we ignore failure as it is
3889 only a hint.
3890 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3892 char *
3894 guestfs_int_shell_unquote (const char *str)
3895 Unquote a shell-quoted string.
3897 Augeas passes strings to us which may be quoted, eg. if they come from
3899 files in /etc/sysconfig. This function can do simple unquoting of
3900 these strings.
3901 Note this function does not do variable substitution, since that is
3903 impossible without knowing the file context and indeed the environment
3904 under which the shell script is run. Configuration files should not
3905 use complex quoting.
3906 "str" is the input string from Augeas, a string that may be single- or
3908 double-quoted or may not be quoted. The returned string is unquoted,
3909 and must be freed by the caller. "NULL" is returned on error and
3910 "errno" is set accordingly.
3911 For information on double-quoting in bash, see
3913 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3914 Function "common/utils/utils.c:guestfs_int_is_reg"
3916 int
3918 guestfs_int_is_reg (int64_t mode)
3919 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3921 field represents a regular file.
3922 Function "common/utils/utils.c:guestfs_int_is_dir"
3924 int
3926 guestfs_int_is_dir (int64_t mode)
3927 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3929 field represents a directory.
3930 Function "common/utils/utils.c:guestfs_int_is_chr"
3932 int
3934 guestfs_int_is_chr (int64_t mode)
3935 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3937 field represents a char device.
3938 Function "common/utils/utils.c:guestfs_int_is_blk"
3940 int
3942 guestfs_int_is_blk (int64_t mode)
3943 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3945 field represents a block device.
3946 Function "common/utils/utils.c:guestfs_int_is_fifo"
3948 int
3950 guestfs_int_is_fifo (int64_t mode)
3951 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3953 field represents a named pipe (FIFO).
3954 Function "common/utils/utils.c:guestfs_int_is_lnk"
3956 int
3958 guestfs_int_is_lnk (int64_t mode)
3959 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3961 field represents a symbolic link.
3962 Function "common/utils/utils.c:guestfs_int_is_sock"
3964 int
3966 guestfs_int_is_sock (int64_t mode)
3967 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3969 field represents a Unix domain socket.
3970 Function "common/utils/utils.c:guestfs_int_full_path"
3972 char *
3974 guestfs_int_full_path (const char *dir, const char *name)
3975 Concatenate "dir" and "name" to create a path. This correctly handles
3977 the case of concatenating "/" + "filename" as well as "/dir" +
3978 "filename". "name" may be "NULL".
3979 The caller must free the returned path.
3981 This function sets "errno" and returns "NULL" on error.
3983 Subdirectory common/visit
3985 File common/visit/visit.c
3986 This file contains a recursive function for visiting all files and
3988 directories in a guestfs filesystem.
3989 Adapted from
3991 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
3992 Function "common/visit/visit.c:visit"
3994 int
3996 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
3997 Visit every file and directory in a guestfs filesystem, starting at
3999 "dir".
4000 "dir" may be "/" to visit the entire filesystem, or may be some
4002 subdirectory. Symbolic links are not followed.
4003 The visitor function "f" is called once for every directory and every
4005 file. The parameters passed to "f" include the current directory name,
4006 the current file name (or "NULL" when we're visiting a directory), the
4007 "guestfs_statns" (file permissions etc), and the list of extended
4008 attributes of the file. The visitor function may return "-1" which
4009 causes the whole recursion to stop with an error.
4010 Also passed to this function is an "opaque" pointer which is passed
4012 through to the visitor function.
4013 Returns 0 if everything went OK, or "-1" if there was an error. Error
4015 handling is not particularly well defined. It will either set an error
4016 in the libguestfs handle or print an error on stderr, but there is no
4017 way for the caller to tell the difference.
4018 Subdirectory common/windows
4020 File common/windows/windows.c
4021 This file implements "win:" Windows file path support in guestfish(1).
4023 Function "common/windows/windows.c:is_windows"
4025 int
4027 is_windows (guestfs_h *g, const char *root)
4028 Checks whether "root" is a Windows installation.
4030 This relies on an already being done introspection.
4032 Function "common/windows/windows.c:windows_path"
4034 char *
4036 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4037 Resolves "path" as possible Windows path according to "root", giving a
4039 new path that can be used in libguestfs API calls.
4040 Notes:
4042 · "root" must be a Windows installation
4044 · relies on an already being done introspection
4046 · will unmount all the existing mount points and mount the Windows
4048 root (according to "readonly")
4049 · calls exit(3) on memory allocation failures
4051 Subdirectory daemon
4053 File daemon/command.c
4054 This file contains a number of useful functions for running external
4056 commands and capturing their output.
4057 Function "daemon/command.c:commandf"
4059 int
4061 commandf (char **stdoutput, char **stderror, unsigned flags,
4062 const char *name, ...)
4063 Run a command. Optionally capture stdout and stderr as strings.
4065 Returns 0 if the command ran successfully, or "-1" if there was any
4067 error.
4068 For a description of the "flags" see "commandrvf".
4070 There is also a macro "command(out,err,name,...)" which calls
4072 "commandf" with "flags=0".
4073 Function "daemon/command.c:commandrf"
4075 int
4077 commandrf (char **stdoutput, char **stderror, unsigned flags,
4078 const char *name, ...)
4079 Same as "command", but we allow the status code from the subcommand to
4081 be non-zero, and return that status code.
4082 We still return "-1" if there was some other error.
4084 There is also a macro "commandr(out,err,name,...)" which calls
4086 "commandrf" with "flags=0".
4087 Function "daemon/command.c:commandvf"
4089 int
4091 commandvf (char **stdoutput, char **stderror, unsigned flags,
4092 char const *const *argv)
4093 Same as "command", but passing in an argv array.
4095 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4097 with "flags=0".
4098 Function "daemon/command.c:commandrvf"
4100 int
4102 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4103 char const* const *argv)
4104 This is a more sane version of system(3) for running external commands.
4106 It uses fork/execvp, so we don't need to worry about quoting of
4107 parameters, and it allows us to capture any error messages in a buffer.
4108 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4110 the command as a string.
4111 If "stderror" is not "NULL", then *stderror will return the stderr of
4113 the command. If there is a final \n character, it is removed so you
4114 can use the error string directly in a call to "reply_with_error".
4115 Flags are:
4117 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4119 For broken external commands that send error messages to stdout
4120 (hello, parted) but that don't have any useful stdout information,
4121 use this flag to capture the error messages in the *stderror
4122 buffer. If using this flag, you should pass "stdoutput=NULL"
4123 because nothing could ever be captured in that buffer.
4124 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4126 For running external commands on chrooted files correctly (see
4127 https://bugzilla.redhat.com/579608) specifying this flag causes
4128 another process to be forked which chroots into sysroot and just
4129 copies the input file to stdin of the specified command. The file
4130 descriptor is ORed with the flags, and that file descriptor is
4131 always closed by this function. See daemon/hexdump.c for an
4132 example of usage.
4133 There is also a macro "commandrv(out,err,argv)" which calls
4135 "commandrvf" with "flags=0".
4136 File daemon/device-name-translation.c
4138 Function "daemon/device-name-translation.c:device_name_translation"
4140 char *
4142 device_name_translation (const char *device)
4143 Perform device name translation.
4145 It returns a newly allocated string which the caller must free.
4147 It returns "NULL" on error. Note it does not call "reply_with_*".
4149 We have to open the device and test for "ENXIO", because the device
4151 nodes may exist in the appliance.
4152 File daemon/guestfsd.c
4154 This is the guestfs daemon which runs inside the guestfs appliance.
4156 This file handles start up and connecting back to the library.
4157 Function "daemon/guestfsd.c:print_shell_quote"
4159 static int
4161 print_shell_quote (FILE *stream,
4162 const struct printf_info *info ATTRIBUTE_UNUSED,
4163 const void *const *args)
4164 printf helper function so we can use %Q ("quoted") and %R to print
4166 shell-quoted strings. See guestfs-hacking(1) for more details.
4167 File daemon/internal.c
4169 Internal functions that are not part of the public API.
4171 File daemon/utils-c.c
4173 Bindings for utility functions.
4175 Note that functions called from OCaml code must never call any of the
4177 "reply*" functions.
4178 File daemon/utils.c
4180 Miscellaneous utility functions used by the daemon.
4182 Function "daemon/utils.c:is_root_device_stat"
4184 static int
4186 is_root_device_stat (struct stat *statbuf)
4187 Return true iff device is the root device (and therefore should be
4189 ignored from the point of view of user calls).
4190 Function "daemon/utils.c:is_device_parameter"
4192 int
4194 is_device_parameter (const char *device)
4195 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4197 device name. This function tests if the parameter is a block device
4198 name.
4199 It can also be used in daemon code to test if the string passed as a
4201 "Dev_or_Path" parameter is a device or path.
4202 Function "daemon/utils.c:sysroot_path"
4204 char *
4206 sysroot_path (const char *path)
4207 Turn "/path" into "/sysroot/path".
4209 Returns "NULL" on failure. The caller must check for this and call
4211 "reply_with_perror ("malloc")". The caller must also free the returned
4212 string.
4213 See also the custom %R printf formatter which does shell quoting too.
4215 Function "daemon/utils.c:sysroot_realpath"
4217 char *
4219 sysroot_realpath (const char *path)
4220 Resolve path within sysroot, calling "sysroot_path" on the resolved
4222 path.
4223 Returns "NULL" on failure. The caller must check for this and call
4225 "reply_with_perror ("malloc")". The caller must also free the returned
4226 string.
4227 See also the custom %R printf formatter which does shell quoting too.
4229 Function "daemon/utils.c:is_power_of_2"
4231 int
4233 is_power_of_2 (unsigned long v)
4234 Returns true if "v" is a power of 2.
4236 Uses the algorithm described at
4238 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4239 Function "daemon/utils.c:split_lines_sb"
4241 struct stringsbuf
4243 split_lines_sb (char *str)
4244 Split an output string into a NULL-terminated list of lines, wrapped
4246 into a stringsbuf.
4247 Typically this is used where we have run an external command which has
4249 printed out a list of things, and we want to return an actual list.
4250 The corner cases here are quite tricky. Note in particular:
4252 "" returns "[]"
4254 "\n"
4256 returns "[""]"
4257 "a\nb"
4259 returns "["a"; "b"]"
4260 "a\nb\n"
4262 returns "["a"; "b"]"
4263 "a\nb\n\n"
4265 returns "["a"; "b"; ""]"
4266 The original string is written over and destroyed by this function
4268 (which is usually OK because it's the 'out' string from "command*()").
4269 You can free the original string, because "add_string()" strdups the
4270 strings.
4271 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4273 Function "daemon/utils.c:trim"
4275 void
4277 trim (char *str)
4278 Skip leading and trailing whitespace, updating the original string in-
4280 place.
4281 Function "daemon/utils.c:parse_btrfsvol"
4283 int
4285 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4286 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4288 directly; it is only used from the stubs.
4289 A btrfs subvolume is given as:
4291 btrfsvol:/dev/sda3/root
4293 where /dev/sda3 is a block device containing a btrfs filesystem, and
4295 root is the name of a subvolume on it. This function is passed the
4296 string following "btrfsvol:".
4297 On success, "mountable->device" and "mountable->volume" must be freed
4299 by the caller.
4300 Function "daemon/utils.c:mountable_to_string"
4302 char *
4304 mountable_to_string (const mountable_t *mountable)
4305 Convert a "mountable_t" back to its string representation
4307 This function can be used in an error path, so must not call
4309 "reply_with_error".
4310 Function "daemon/utils.c:prog_exists"
4312 int
4314 prog_exists (const char *prog)
4315 Check program exists and is executable on $PATH.
4317 Function "daemon/utils.c:random_name"
4319 int
4321 random_name (char *template)
4322 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4324 template to contain a randomly named file. Any 'X' characters after
4325 the final '/' in the template are replaced with random characters.
4326 Notes: You should probably use an 8.3 path, so it's compatible with all
4328 filesystems including basic FAT. Also this only substitutes lowercase
4329 ASCII letters and numbers, again for compatibility with lowest common
4330 denominator filesystems.
4331 This doesn't create a file or check whether or not the file exists (it
4333 would be extremely unlikely to exist as long as the RNG is working).
4334 If there is an error, "-1" is returned.
4336 Function "daemon/utils.c:udev_settle_file"
4338 void
4340 udev_settle_file (const char *file)
4341 LVM and other commands aren't synchronous, especially when udev is
4343 involved. eg. You can create or remove some device, but the "/dev"
4344 device node won't appear until some time later. This means that you
4345 get an error if you run one command followed by another.
4346 Use "udevadm settle" after certain commands, but don't be too fussed if
4348 it fails.
4349 Function "daemon/utils.c:make_exclude_from_file"
4351 char *
4353 make_exclude_from_file (const char *function, char *const *excludes)
4354 Turn list "excludes" into a temporary file, and return a string
4356 containing the temporary file name. Caller must unlink the file and
4357 free the string.
4358 "function" is the function that invoked this helper, and it is used
4360 mainly for errors/debugging.
4361 Subdirectory fish
4363 File fish/alloc.c
4364 This file implements the guestfish "alloc" and "sparse" commands.
4366 Function "fish/alloc.c:alloc_disk"
4368 int
4370 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4371 This is the underlying allocation function. It's called from a few
4373 other places in guestfish.
4374 File fish/copy.c
4376 This file implements the guestfish commands "copy-in" and "copy-out".
4378 File fish/destpaths.c
4380 The file handles tab-completion of filesystem paths in guestfish.
4382 File fish/display.c
4384 The file implements the guestfish "display" command, for displaying
4386 graphical files (icons, images) in disk images.
4387 File fish/echo.c
4389 The file implements the guestfish "echo" command.
4391 File fish/edit.c
4393 guestfish "edit" command, suggested by Ján Ondrej.
4395 File fish/events.c
4397 This file implements the guestfish event-related commands, "event",
4399 "delete-event" and "list-events".
4400 File fish/fish.c
4402 guestfish, the guest filesystem shell. This file contains the main
4404 loop and utilities.
4405 Function "fish/fish.c:parse_command_line"
4407 static struct parsed_command
4409 parse_command_line (char *buf, int *exit_on_error_rtn)
4410 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4412 This destructively updates "buf".
4413 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4415 setting and to return the local setting (eg. if the command begins with
4416 '-').
4417 Returns in "parsed_command.status":
4419 1 got a guestfish command (returned in
4421 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4422 0 no guestfish command, but otherwise OK
4424 "-1"
4426 an error
4427 Function "fish/fish.c:parse_quoted_string"
4429 static ssize_t
4431 parse_quoted_string (char *p)
4432 Parse double-quoted strings, replacing backslash escape sequences with
4434 the true character. Since the string is returned in place, the escapes
4435 must make the string shorter.
4436 Function "fish/fish.c:execute_and_inline"
4438 static int
4440 execute_and_inline (const char *cmd, int global_exit_on_error)
4441 Used to handle "<!" (execute command and inline result).
4443 Function "fish/fish.c:issue_command"
4445 int
4447 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4448 int rc_exit_on_error_flag)
4449 Run a command.
4451 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4453 remote server (when issuing --remote commands). It does not cause
4454 "issue_command" itself to exit on error.
4455 Function "fish/fish.c:extended_help_message"
4457 void
4459 extended_help_message (void)
4460 Print an extended help message when the user types in an unknown
4462 command for the first command issued. A common case is the user doing:
4463 guestfish disk.img
4465 expecting guestfish to open disk.img (in fact, this tried to run a non-
4467 existent command "disk.img").
4468 Function "fish/fish.c:error_cb"
4470 static void
4472 error_cb (guestfs_h *g, void *data, const char *msg)
4473 Error callback. This replaces the standard libguestfs error handler.
4475 Function "fish/fish.c:free_n_strings"
4477 static void
4479 free_n_strings (char **str, size_t len)
4480 Free strings from a non-NULL terminated "char**".
4482 Function "fish/fish.c:decode_ps1"
4484 static char *
4486 decode_ps1 (const char *str)
4487 Decode "str" into the final printable prompt string.
4489 Function "fish/fish.c:win_prefix"
4491 char *
4493 win_prefix (const char *path)
4494 Resolve the special "win:..." form for Windows-specific paths. The
4496 generated code calls this for all device or path arguments.
4497 The function returns a newly allocated string, and the caller must free
4499 this string; else display an error and return "NULL".
4500 Function "fish/fish.c:file_in"
4502 char *
4504 file_in (const char *arg)
4505 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4507 The caller (fish/cmds.c) will call "free_file_in" after the command has
4509 run which should clean up resources.
4510 Function "fish/fish.c:file_out"
4512 char *
4514 file_out (const char *arg)
4515 Resolve the special "FileOut" paths ("-" or filename).
4517 The caller (fish/cmds.c) will call "free (str)" after the command has
4519 run.
4520 Function "fish/fish.c:progress_callback"
4522 void
4524 progress_callback (guestfs_h *g, void *data,
4525 uint64_t event, int event_handle, int flags,
4526 const char *buf, size_t buf_len,
4527 const uint64_t *array, size_t array_len)
4528 Callback which displays a progress bar.
4530 File fish/glob.c
4532 This file implements the guestfish "glob" command.
4534 Function "fish/glob.c:expand_devicename"
4536 static char **
4538 expand_devicename (guestfs_h *g, const char *device)
4539 Glob-expand device patterns, such as "/dev/sd*"
4541 (https://bugzilla.redhat.com/635971).
4542 There is no "guestfs_glob_expand_device" function because the
4544 equivalent can be implemented using functions like
4545 "guestfs_list_devices".
4546 It's not immediately clear what it means to expand a pattern like
4548 "/dev/sd*". Should that include device name translation? Should the
4549 result include partitions as well as devices?
4550 Should "/dev/" + "*" return every possible device and filesystem? How
4552 about VGs? LVs?
4553 To solve this what we do is build up a list of every device, partition,
4555 etc., then glob against that list.
4556 Notes for future work (XXX):
4558 · This doesn't handle device name translation. It wouldn't be too
4560 hard to add.
4561 · Could have an API function for returning all device-like things.
4563 Function "fish/glob.c:add_strings_matching"
4565 static int
4567 add_strings_matching (char **pp, const char *glob,
4568 char ***ret, size_t *size_r)
4569 Using POSIX fnmatch(3), find strings in the list "pp" which match
4571 pattern "glob". Add strings which match to the "ret" array. *size_r
4572 is the current size of the "ret" array, which is updated with the new
4573 size.
4574 Function "fish/glob.c:single_element_list"
4576 static char **
4578 single_element_list (const char *element)
4579 Return a single element list containing "element".
4581 File fish/help.c
4583 The file implements the guestfish "help" command.
4585 Function "fish/help.c:display_help"
4587 int
4589 display_help (const char *cmd, size_t argc, char *argv[])
4590 The "help" command.
4592 This used to just list all commands, but that's not very useful.
4594 Instead display some useful context-sensitive help. This could be
4595 improved if we knew how many drives had been added already, and whether
4596 anything was mounted.
4597 File fish/hexedit.c
4599 This file implements the guestfish "hexedit" command.
4601 File fish/lcd.c
4603 Function "fish/lcd.c:run_lcd"
4605 int
4607 run_lcd (const char *cmd, size_t argc, char *argv[])
4608 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4610 File fish/man.c
4612 Function "fish/man.c:run_man"
4614 int
4616 run_man (const char *cmd, size_t argc, char *argv[])
4617 guestfish "man" command
4619 File fish/more.c
4621 This file implements the guestfish "more" command.
4623 File fish/prep.c
4625 This file implements the guestfish -N option for creating pre-prepared
4627 disk layouts.
4628 File fish/rc.c
4630 This file implements guestfish remote (command) support.
4632 Function "fish/rc.c:rc_listen"
4634 void
4636 rc_listen (void)
4637 The remote control server (ie. "guestfish --listen").
4639 Function "fish/rc.c:rc_remote"
4641 int
4643 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4644 int exit_on_error)
4645 The remote control client (ie. "guestfish --remote").
4647 File fish/reopen.c
4649 This file implements the guestfish "reopen" command.
4651 File fish/setenv.c
4653 This file implements the guestfish "setenv" and "unsetenv" commands.
4655 File fish/supported.c
4657 This file implements the guestfish "supported" command.
4659 File fish/tilde.c
4661 This file implements tilde ("~") expansion of home directories in
4663 guestfish(1).
4664 Function "fish/tilde.c:try_tilde_expansion"
4666 char *
4668 try_tilde_expansion (char *str)
4669 This is called from the script loop if we find a candidate for
4671 "~username" (tilde-expansion).
4672 Function "fish/tilde.c:expand_home"
4674 static char *
4676 expand_home (char *orig, const char *append)
4677 Return $HOME + append string.
4679 Function "fish/tilde.c:find_home_for_username"
4681 static const char *
4683 find_home_for_username (const char *username, size_t ulen)
4684 Lookup "username" (of length "ulen"), return home directory if found,
4686 or "NULL" if not found.
4687 File fish/time.c
4689 This file implements the guestfish "time" command.
4691 Subdirectory p2v
4693 File p2v/config.c
4694 Function "p2v/config.c:print_config"
4696 void
4698 print_config (struct config *config, FILE *fp)
4699 Print the conversion parameters and other important information.
4701 File p2v/conversion.c
4703 This file manages the p2v conversion.
4705 The conversion is actually done by virt-v2v(1) running on the remote
4707 conversion server. This file manages running the remote command and
4708 provides callbacks for displaying the output.
4709 When virt-p2v operates in GUI mode, this code runs in a separate
4711 thread. When virt-p2v operates in kernel mode, this runs synchronously
4712 in the main thread.
4713 Function "p2v/conversion.c:generate_name"
4715 static void
4717 generate_name (struct config *config, const char *filename)
4718 Write the guest name into "filename".
4720 Function "p2v/conversion.c:generate_wrapper_script"
4722 static void
4724 generate_wrapper_script (struct config *config, const char *remote_dir,
4725 const char *filename)
4726 Construct the virt-v2v wrapper script.
4728 This will be sent to the remote server, and is easier than trying to
4730 "type" a long and complex single command line into the ssh connection
4731 when we start the conversion.
4732 Function "p2v/conversion.c:print_quoted"
4734 static void
4736 print_quoted (FILE *fp, const char *s)
4737 Print a shell-quoted string on "fp".
4739 Function "p2v/conversion.c:generate_system_data"
4741 static void
4743 generate_system_data (const char *dmesg_file,
4744 const char *lscpu_file,
4745 const char *lspci_file,
4746 const char *lsscsi_file,
4747 const char *lsusb_file)
4748 Collect data about the system running virt-p2v such as the dmesg output
4750 and lists of PCI devices. This is useful for diagnosis when things go
4751 wrong.
4752 If any command fails, this is non-fatal.
4754 Function "p2v/conversion.c:generate_p2v_version_file"
4756 static void
4758 generate_p2v_version_file (const char *p2v_version_file)
4759 Generate a file containing the version of virt-p2v.
4761 The version of virt-v2v is contained in the conversion log.
4763 File p2v/cpuid.c
4765 Find CPU vendor, topology and some CPU flags.
4767 lscpu (from util-linux) provides CPU vendor, topology and flags.
4769 ACPI can be read by seeing if /sys/firmware/acpi exists.
4771 CPU model is essentially impossible to get without using libvirt, but
4773 we cannot use libvirt for the reasons outlined in this message:
4774 https://www.redhat.com/archives/libvirt-users/2017-March/msg00071.html
4775 Note that #vCPUs and amount of RAM is handled by main.c.
4777 Function "p2v/cpuid.c:get_lscpu"
4779 static char **
4781 get_lscpu (void)
4782 Get the output of lscpu as a list of (key, value) pairs (as a flattened
4784 list of strings).
4785 Function "p2v/cpuid.c:get_field"
4787 static const char *
4789 get_field (char **lscpu, const char *key)
4790 Read a single field from lscpu output.
4792 If the field does not exist, returns "NULL".
4794 Function "p2v/cpuid.c:get_vendor"
4796 static void
4798 get_vendor (char **lscpu, struct cpu_config *cpu)
4799 Read the CPU vendor from lscpu output.
4801 Function "p2v/cpuid.c:get_topology"
4803 static void
4805 get_topology (char **lscpu, struct cpu_config *cpu)
4806 Read the CPU topology from lscpu output.
4808 Function "p2v/cpuid.c:get_flags"
4810 static void
4812 get_flags (char **lscpu, struct cpu_config *cpu)
4813 Read some important flags from lscpu output.
4815 Function "p2v/cpuid.c:get_acpi"
4817 static void
4819 get_acpi (struct cpu_config *cpu)
4820 Find out if the system uses ACPI.
4822 File p2v/gui.c
4824 This file implements almost all of the virt-p2v graphical user
4826 interface (GUI).
4827 The GUI has three main dialogs:
4829 Connection dialog
4831 The connection dialog is the one shown initially. It asks the user
4832 to type in the login details for the remote conversion server and
4833 invites the user to test the ssh connection.
4834 Conversion dialog
4836 The conversion dialog asks for information about the target VM (eg.
4837 the number of vCPUs required), and about what to convert (eg. which
4838 network interfaces should be copied and which should be ignored).
4839 Running dialog
4841 The running dialog is displayed when the P2V process is underway.
4842 It mainly displays the virt-v2v debug messages.
4843 Note that the other major dialog ("Configure network ...") is handled
4845 entirely by NetworkManager's nm-connection-editor(1) program and has
4846 nothing to do with this code.
4847 This file is written in a kind of "pseudo-Gtk" which is backwards
4849 compatible from Gtk 2.10 (RHEL 5) through at least Gtk 3.22. This is
4850 done using a few macros to implement old "gtk_*" functions or map them
4851 to newer functions. Supporting ancient Gtk is important because we
4852 want to provide a virt-p2v binary that can run on very old kernels, to
4853 support 32 bit and proprietary SCSI drivers.
4854 Function "p2v/gui.c:gui_conversion"
4856 void
4858 gui_conversion (struct config *config)
4859 The entry point from the main program.
4861 Note that "gtk_init" etc have already been called in "main".
4863 Function "p2v/gui.c:create_connection_dialog"
4865 static void
4867 create_connection_dialog (struct config *config)
4868 Create the connection dialog.
4870 This creates the dialog, but it is not displayed. See
4872 "show_connection_dialog".
4873 Function "p2v/gui.c:username_changed_callback"
4875 static void
4877 username_changed_callback (GtkWidget *w, gpointer data)
4878 If the username is "root", disable the sudo button.
4880 Function "p2v/gui.c:password_or_identity_changed_callback"
4882 static void
4884 password_or_identity_changed_callback (GtkWidget *w, gpointer data)
4885 The password or SSH identity URL entries are mutually exclusive, so if
4887 one contains text then disable the other. This function is called when
4888 the "changed" signal is received on either.
4889 Function "p2v/gui.c:show_connection_dialog"
4891 static void
4893 show_connection_dialog (void)
4894 Hide all other dialogs and show the connection dialog.
4896 Function "p2v/gui.c:test_connection_clicked"
4898 static void
4900 test_connection_clicked (GtkWidget *w, gpointer data)
4901 Callback from the "Test connection" button.
4903 This initiates a background thread which actually does the ssh to the
4905 conversion server and the rest of the testing (see
4906 "test_connection_thread").
4907 Function "p2v/gui.c:test_connection_thread"
4909 static void *
4911 test_connection_thread (void *data)
4912 Run "test_connection" (in a detached background thread). Once it
4914 finishes stop the spinner and set the spinner message appropriately.
4915 If the test is successful then we enable the "Next" button. If
4916 unsuccessful, an error is shown in the connection dialog.
4917 Function "p2v/gui.c:start_spinner"
4919 static gboolean
4921 start_spinner (gpointer user_data)
4922 Idle task called from "test_connection_thread" (but run on the main
4924 thread) to start the spinner in the connection dialog.
4925 Function "p2v/gui.c:stop_spinner"
4927 static gboolean
4929 stop_spinner (gpointer user_data)
4930 Idle task called from "test_connection_thread" (but run on the main
4932 thread) to stop the spinner in the connection dialog.
4933 Function "p2v/gui.c:test_connection_error"
4935 static gboolean
4937 test_connection_error (gpointer user_data)
4938 Idle task called from "test_connection_thread" (but run on the main
4940 thread) when there is an error. Display the error message and disable
4941 the "Next" button so the user is forced to correct it.
4942 Function "p2v/gui.c:test_connection_ok"
4944 static gboolean
4946 test_connection_ok (gpointer user_data)
4947 Idle task called from "test_connection_thread" (but run on the main
4949 thread) when the connection test was successful.
4950 Function "p2v/gui.c:configure_network_button_clicked"
4952 static void
4954 configure_network_button_clicked (GtkWidget *w, gpointer data)
4955 Callback from the "Configure network ..." button. This dialog is
4957 handled entirely by an external program which is part of
4958 NetworkManager.
4959 Function "p2v/gui.c:xterm_button_clicked"
4961 static void
4963 xterm_button_clicked (GtkWidget *w, gpointer data)
4964 Callback from the "XTerm ..." button.
4966 Function "p2v/gui.c:about_button_clicked"
4968 static void
4970 about_button_clicked (GtkWidget *w, gpointer data)
4971 Callback from the "About virt-p2v ..." button.
4973 See also p2v/about-authors.c and p2v/about-license.c.
4975 Function "p2v/gui.c:connection_next_clicked"
4977 static void
4979 connection_next_clicked (GtkWidget *w, gpointer data)
4980 Callback when the connection dialog "Next" button has been clicked.
4982 Function "p2v/gui.c:create_conversion_dialog"
4984 static void
4986 create_conversion_dialog (struct config *config)
4987 Create the conversion dialog.
4989 This creates the dialog, but it is not displayed. See
4991 "show_conversion_dialog".
4992 Function "p2v/gui.c:show_conversion_dialog"
4994 static void
4996 show_conversion_dialog (void)
4997 Hide all other dialogs and show the conversion dialog.
4999 Function "p2v/gui.c:set_info_label"
5001 static void
5003 set_info_label (void)
5004 Update the "Information" section in the conversion dialog.
5006 Note that "v2v_version" (the remote virt-v2v version) is read from the
5008 remote virt-v2v in the "test_connection" function.
5009 Function "p2v/gui.c:repopulate_output_combo"
5011 static void
5013 repopulate_output_combo (struct config *config)
5014 Repopulate the list of output drivers in the "Output to (-o)" combo.
5016 The list of drivers is read from the remote virt-v2v instance in
5017 "test_connection".
5018 Function "p2v/gui.c:populate_disks"
5020 static void
5022 populate_disks (GtkTreeView *disks_list)
5023 Populate the "Fixed hard disks" treeview.
5025 Function "p2v/gui.c:populate_removable"
5027 static void
5029 populate_removable (GtkTreeView *removable_list)
5030 Populate the "Removable media" treeview.
5032 Function "p2v/gui.c:populate_interfaces"
5034 static void
5036 populate_interfaces (GtkTreeView *interfaces_list)
5037 Populate the "Network interfaces" treeview.
5039 Function "p2v/gui.c:maybe_identify_click"
5041 static gboolean
5043 maybe_identify_click (GtkWidget *interfaces_list, GdkEventButton *event,
5044 gpointer data)
5045 When the user clicks on the interface name on the list of interfaces,
5047 we want to run "ethtool --identify", which usually makes some lights
5048 flash on the physical interface.
5049 We cannot catch clicks on the cell itself, so we have to go via a more
5051 obscure route. See http://stackoverflow.com/a/27207433 and
5052 https://en.wikibooks.org/wiki/GTK%2B_By_Example/Tree_View/Events
5053 Function "p2v/gui.c:conversion_back_clicked"
5055 static void
5057 conversion_back_clicked (GtkWidget *w, gpointer data)
5058 The conversion dialog "Back" button has been clicked.
5060 Function "p2v/gui.c:vcpus_or_memory_check_callback"
5062 static void
5064 vcpus_or_memory_check_callback (GtkWidget *w, gpointer data)
5065 Display a warning if the vCPUs or memory is outside the supported range
5067 (https://bugzilla.redhat.com/823758).
5068 Function "p2v/gui.c:create_running_dialog"
5070 static void
5072 create_running_dialog (void)
5073 Create the running dialog.
5075 This creates the dialog, but it is not displayed. See
5077 "show_running_dialog".
5078 Function "p2v/gui.c:show_running_dialog"
5080 static void
5082 show_running_dialog (void)
5083 Hide all other dialogs and show the running dialog.
5085 Function "p2v/gui.c:set_log_dir"
5087 static gboolean
5089 set_log_dir (gpointer user_data)
5090 Display the remote log directory in the running dialog.
5092 If this isn't called from the main thread, then you must only call it
5094 via an idle task ("g_idle_add").
5095 NB: This frees the remote_dir ("user_data" pointer) which was strdup'd
5097 in "notify_ui_callback".
5098 Function "p2v/gui.c:set_status"
5100 static gboolean
5102 set_status (gpointer user_data)
5103 Display the conversion status in the running dialog.
5105 If this isn't called from the main thread, then you must only call it
5107 via an idle task ("g_idle_add").
5108 NB: This frees the message ("user_data" pointer) which was strdup'd in
5110 "notify_ui_callback".
5111 Function "p2v/gui.c:add_v2v_output"
5113 static gboolean
5115 add_v2v_output (gpointer user_data)
5116 Append output from the virt-v2v process to the buffer, and scroll to
5118 ensure it is visible.
5119 This function is able to parse ANSI colour sequences and more.
5121 If this isn't called from the main thread, then you must only call it
5123 via an idle task ("g_idle_add").
5124 NB: This frees the message ("user_data" pointer) which was strdup'd in
5126 "notify_ui_callback".
5127 Function "p2v/gui.c:start_conversion_clicked"
5129 static void
5131 start_conversion_clicked (GtkWidget *w, gpointer data)
5132 Callback when the "Start conversion" button is clicked.
5134 Function "p2v/gui.c:start_conversion_thread"
5136 static void *
5138 start_conversion_thread (void *data)
5139 This is the background thread which performs the conversion.
5141 Function "p2v/gui.c:conversion_error"
5143 static gboolean
5145 conversion_error (gpointer user_data)
5146 Idle task called from "start_conversion_thread" (but run on the main
5148 thread) when there was an error during the conversion.
5149 Function "p2v/gui.c:conversion_finished"
5151 static gboolean
5153 conversion_finished (gpointer user_data)
5154 Idle task called from "start_conversion_thread" (but run on the main
5156 thread) when the conversion completed without errors.
5157 Function "p2v/gui.c:notify_ui_callback"
5159 static void
5161 notify_ui_callback (int type, const char *data)
5162 This is called from conversion.c:"start_conversion" when there is a
5164 status change or a log message.
5165 Function "p2v/gui.c:cancel_conversion_dialog"
5167 static void
5169 cancel_conversion_dialog (GtkWidget *w, gpointer data)
5170 This is called when the user clicks on the "Cancel conversion" button.
5172 Since conversions can run for a long time, and cancelling the
5173 conversion is non-recoverable, this function displays a confirmation
5174 dialog before cancelling the conversion.
5175 File p2v/inhibit.c
5177 This file is used to inhibit power saving, sleep, suspend etc during
5179 the conversion.
5180 The method it uses is to send a D-Bus message to logind, as described
5182 here:
5183 https://www.freedesktop.org/wiki/Software/systemd/inhibit/
5185 If virt-p2v is compiled without D-Bus support then this does nothing.
5187 Function "p2v/inhibit.c:inhibit_power_saving"
5189 int
5191 inhibit_power_saving (void)
5192 Inhibit all forms of power saving. A file descriptor is returned, and
5194 when the file descriptor is closed the inhibit is stopped.
5195 If the function returns "-1" then "Inhibit" operation could not be
5197 performed (eg. if we are compiled without D-Bus support, or there is
5198 some error contacting logind). This is not usually fatal from the
5199 point of view of the caller, conversion can continue.
5200 File p2v/kernel-cmdline.c
5202 Mini library to read and parse "/proc/cmdline".
5204 Function "p2v/kernel-cmdline.c:parse_cmdline_string"
5206 char **
5208 parse_cmdline_string (const char *cmdline)
5209 Read and parse "/proc/cmdline".
5211 We only support double quoting, consistent with the Linux
5213 documentation.
5214 https://www.kernel.org/doc/Documentation/kernel-parameters.txt
5215 systemd supports single and double quoting and single character
5217 escaping, but we don't support all that.
5218 Returns a list of key, value pairs, terminated by "NULL".
5220 File p2v/kernel.c
5222 Kernel-driven, non-interactive configuration of virt-p2v.
5224 File p2v/main.c
5226 Function "p2v/main.c:partition_parent"
5228 static dev_t
5230 partition_parent (dev_t part_dev)
5231 Get parent device of a partition.
5233 Returns 0 if no parent device could be found.
5235 Function "p2v/main.c:device_contains"
5237 static int
5239 device_contains (const char *dev, dev_t root_device)
5240 Return true if the named device (eg. "dev == "sda"") contains the root
5242 filesystem. "root_device" is the major:minor of the root filesystem
5243 (eg. "8:1" if the root filesystem was /dev/sda1).
5244 This doesn't work for LVs and so on. However we only really care if
5246 this test works on the P2V ISO where the root device is a regular
5247 partition.
5248 Function "p2v/main.c:find_all_disks"
5250 static void
5252 find_all_disks (void)
5253 Enumerate all disks in /sys/block and add them to the global
5255 "all_disks" and "all_removable" arrays.
5256 Function "p2v/main.c:find_all_interfaces"
5258 static void
5260 find_all_interfaces (void)
5261 Enumerate all network interfaces in /sys/class/net and add them to the
5263 global "all_interfaces" array.
5264 File p2v/nbd.c
5266 This file handles the virt-p2v --nbd command line option and running
5268 either qemu-nbd(8) or nbdkit(1).
5269 Function "p2v/nbd.c:set_nbd_option"
5271 void
5273 set_nbd_option (const char *opt)
5274 The main program calls this to set the --nbd option.
5276 Function "p2v/nbd.c:test_nbd_servers"
5278 void
5280 test_nbd_servers (void)
5281 Test the --nbd option (or built-in default list) to see which servers
5283 are actually installed and appear to be working.
5284 Set the "use_server" global accordingly.
5286 Function "p2v/nbd.c:start_nbd_server"
5288 pid_t
5290 start_nbd_server (const char **ipaddr, int *port, const char *device)
5291 Start the NBD server.
5293 We previously tested all NBD servers (see "test_nbd_servers") and
5295 hopefully found one which will work.
5296 Returns the process ID (> 0) or 0 if there is an error.
5298 Function "p2v/nbd.c:socket_activation"
5300 static inline void
5302 socket_activation (int *fds, size_t nr_fds)
5303 Set up file descriptors and environment variables for socket
5305 activation.
5306 Note this function runs in the child between fork and exec.
5308 Function "p2v/nbd.c:start_qemu_nbd"
5310 static pid_t
5312 start_qemu_nbd (const char *device,
5313 const char *ipaddr, int port, int *fds, size_t nr_fds)
5314 Start a local qemu-nbd(1) process.
5316 If we are using socket activation, "fds" and "nr_fds" will contain the
5318 locally pre-opened file descriptors for this. Otherwise if "fds ==
5319 NULL" we pass the port number.
5320 Returns the process ID (> 0) or 0 if there is an error.
5322 Function "p2v/nbd.c:start_nbdkit"
5324 static pid_t
5326 start_nbdkit (const char *device,
5327 const char *ipaddr, int port, int *fds, size_t nr_fds)
5328 Start a local nbdkit(1) process using the nbdkit-file-plugin(1).
5330 If we are using socket activation, "fds" and "nr_fds" will contain the
5332 locally pre-opened file descriptors for this. Otherwise if "fds ==
5333 NULL" we pass the port number.
5334 Returns the process ID (> 0) or 0 if there is an error.
5336 Function "p2v/nbd.c:get_local_port"
5338 static int
5340 get_local_port (void)
5341 This is used when we are starting an NBD server that does not support
5343 socket activation. We have to pass the '-p' option to the NBD server,
5344 but there's no good way to choose a free port, so we have to just
5345 guess.
5346 Returns the port number on success or "-1" on error.
5348 Function "p2v/nbd.c:open_listening_socket"
5350 static int
5352 open_listening_socket (const char *ipaddr, int **fds, size_t *nr_fds)
5353 This is used when we are starting an NBD server which supports socket
5355 activation. We can open a listening socket on an unused local port and
5356 return it.
5357 Returns the port number on success or "-1" on error.
5359 The file descriptor(s) bound are returned in the array *fds, *nr_fds.
5361 The caller must free the array.
5362 Function "p2v/nbd.c:wait_for_nbd_server_to_start"
5364 int
5366 wait_for_nbd_server_to_start (const char *ipaddr, int port)
5367 Wait for a local NBD server to start and be listening for connections.
5369 Function "p2v/nbd.c:connect_with_source_port"
5371 static int
5373 connect_with_source_port (const char *hostname, int dest_port, int source_port)
5374 Connect to "hostname:dest_port", resolving the address using
5376 getaddrinfo(3).
5377 This also sets the source port of the connection to the first free port
5379 number ≥ "source_port".
5380 This may involve multiple connections - to IPv4 and IPv6 for instance.
5382 File p2v/physical-xml.c
5384 Create the physical.xml file, which is a piece of phony libvirt XML
5386 used to communicate the metadata of the physical machine to virt-v2v.
5387 Function "p2v/physical-xml.c:generate_physical_xml"
5389 void
5391 generate_physical_xml (struct config *config, struct data_conn *data_conns,
5392 const char *filename)
5393 Write the libvirt XML for this physical machine.
5395 Note this is not actually input for libvirt. It's input for virt-v2v
5397 on the conversion server. Virt-v2v will (if necessary) generate the
5398 final libvirt XML.
5399 Function "p2v/physical-xml.c:map_interface_to_network"
5401 static const char *
5403 map_interface_to_network (struct config *config, const char *interface)
5404 Using "config->network_map", map the interface to a target network
5406 name. If no map is found, return "default". See virt-p2v(1)
5407 documentation of "p2v.network" for how the network map works.
5408 Note this returns a static string which is only valid as long as
5410 "config->network_map" is not freed.
5411 File p2v/rtc.c
5413 Try to calculate Real Time Clock (RTC) offset from UTC in seconds. For
5415 example if the RTC is 1 hour ahead of UTC, this will return 3600. This
5416 is stored in "config->rtc_offset".
5417 Function "p2v/rtc.c:get_rtc_config"
5419 void
5421 get_rtc_config (struct rtc_config *rtc)
5422 Return RTC offset from UTC in seconds, positive numbers meaning that
5424 the RTC is running ahead of UTC.
5425 In the error case, "rtc>offset" is updated with 0 and "rtc>basis" is
5427 set to "BASIS_UNKNOWN".
5428 File p2v/ssh.c
5430 This file handles the ssh connections to the conversion server.
5432 virt-p2v will open several connections over the lifetime of the
5434 conversion process.
5435 In "test_connection", it will first open a connection (to check it is
5437 possible) and query virt-v2v on the server to ensure it exists, it is
5438 the right version, and so on. This connection is then closed, because
5439 in the GUI case we don't want to deal with keeping it alive in case the
5440 administrator has set up an autologout.
5441 Once we start conversion, we will open a control connection to send the
5443 libvirt configuration data and to start up virt-v2v, and we will open
5444 up one data connection per local hard disk. The data connection(s)
5445 have a reverse port forward to the local NBD server which is serving
5446 the content of that hard disk. The remote port for each data
5447 connection is assigned by ssh. See "open_data_connection" and
5448 "start_remote_conversion".
5449 Function "p2v/ssh.c:curl_download"
5451 static int
5453 curl_download (const char *url, const char *local_file)
5454 Download URL to local file using the external 'curl' command.
5456 Function "p2v/ssh.c:cache_ssh_identity"
5458 static int
5460 cache_ssh_identity (struct config *config)
5461 Re-cache the "config->identity_url" if needed.
5463 Function "p2v/ssh.c:start_ssh"
5465 static mexp_h *
5467 start_ssh (unsigned spawn_flags, struct config *config,
5468 char **extra_args, int wait_prompt)
5469 Start ssh subprocess with the standard arguments and possibly some
5471 optional arguments. Also handles authentication.
5472 Function "p2v/ssh.c:scp_file"
5474 int
5476 scp_file (struct config *config, const char *target, const char *local, ...)
5477 Upload file(s) to remote using scp(1).
5479 Note that the target (directory or file) comes before the list of local
5481 files, because the list of local files is a varargs list.
5482 This is a simplified version of "start_ssh" above.
5484 File p2v/utils.c
5486 Function "p2v/utils.c:get_blockdev_size"
5488 uint64_t
5490 get_blockdev_size (const char *dev)
5491 Return size of a block device, from /sys/block/dev/size.
5493 This function always succeeds, or else exits (since we expect "dev" to
5495 always be valid and the "size" file to always exist).
5496 Function "p2v/utils.c:get_blockdev_model"
5498 char *
5500 get_blockdev_model (const char *dev)
5501 Return model of a block device, from /sys/block/dev/device/model.
5503 Returns "NULL" if the file was not found. The caller must free the
5505 returned string.
5506 Function "p2v/utils.c:get_blockdev_serial"
5508 char *
5510 get_blockdev_serial (const char *dev)
5511 Return the serial number of a block device.
5513 This is found using the lsblk command.
5515 Returns "NULL" if we could not get the serial number. The caller must
5517 free the returned string.
5518 Function "p2v/utils.c:get_if_addr"
5520 char *
5522 get_if_addr (const char *if_name)
5523 Return contents of /sys/class/net/if_name/address (if found).
5525 Function "p2v/utils.c:get_if_vendor"
5527 char *
5529 get_if_vendor (const char *if_name, int truncate)
5530 Return contents of /sys/class/net/if_name/device/vendor (if found),
5532 mapped to the PCI vendor. See:
5533 http://pjwelsh.blogspot.co.uk/2011/11/howto-get-network-card-vendor-device-or.html
5534 Function "p2v/utils.c:wait_network_online"
5536 void
5538 wait_network_online (const struct config *config)
5539 Wait for the network to come online, but don't error out if that fails.
5541 The caller will call "test_connection" immediately after this which
5542 will fail if the network didn't come online.
5543 File p2v/whole-file.c
5545 Function "p2v/whole-file.c:read_whole_file"
5547 int
5549 read_whole_file (const char *filename, char **data_r, size_t *size_r)
5550 Read the whole file into a memory buffer and return it. The file
5552 should be a regular, local, trusted file.
5553 Subdirectory python
5555 File python/handle.c
5556 This file contains a small number of functions that are written by
5558 hand. The majority of the bindings are generated (see
5559 python/actions-*.c).
5560 Subdirectory v2v
5562 File v2v/libvirt_utils-c.c
5563 This module implements various "virsh"-like commands, but with non-
5565 broken authentication handling.
5566
5568 guestfs(3), guestfs-building(1), guestfs-examples(3),
5569 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
5570 guestfs-testing(1), libguestfs-test-tool(1),
5571 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
5572
5574 Richard W.M. Jones ("rjones at redhat dot com")
5575
5577 Copyright (C) 2009-2018 Red Hat Inc.
5578
5580 This library is free software; you can redistribute it and/or modify it
5581 under the terms of the GNU Lesser General Public License as published
5582 by the Free Software Foundation; either version 2 of the License, or
5583 (at your option) any later version.
5584 This library is distributed in the hope that it will be useful, but
5586 WITHOUT ANY WARRANTY; without even the implied warranty of
5587 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5588 Lesser General Public License for more details.
5589 You should have received a copy of the GNU Lesser General Public
5591 License along with this library; if not, write to the Free Software
5592 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
5593 02110-1301 USA
5594
5596 To get a list of bugs against libguestfs, use this link:
5597 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
5598 To report a new bug against libguestfs, use this link:
5600 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
5601 When reporting a bug, please supply:
5603 · The version of libguestfs.
5605 · Where you got libguestfs (eg. which Linux distro, compiled from
5607 source, etc)
5608 · Describe the bug accurately and give a way to reproduce it.
5610 · Run libguestfs-test-tool(1) and paste the complete, unedited output
5612 into the bug report.
5613libguestfs-1.38.2 2018-05-15 guestfs-hacking(1)