/libguestfs-1.19.22/generator/generator_actions.ml
OCaml | 9342 lines | 8738 code | 454 blank | 150 comment | 1 complexity | e6a678e96285aaeab3f4f9d219dc8f30 MD5 | raw file
Possible License(s): LGPL-2.0, GPL-3.0, GPL-2.0
Large files files are truncated, but you can click here to view the full file
- (* libguestfs
- * Copyright (C) 2009-2012 Red Hat Inc.
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
- *)
- (* Please read generator/README first. *)
- open Generator_types
- open Generator_utils
- (* Default settings for all action fields. So we copy and override
- * this struct by writing '{ defaults with name = &c }'
- *)
- let defaults = { name = ""; style = RErr, [], []; proc_nr = None;
- tests = []; shortdesc = ""; longdesc = "";
- protocol_limit_warning = false; fish_alias = [];
- fish_output = None; in_fish = true; in_docs = true;
- deprecated_by = None; optional = None;
- progress = false; camel_name = "";
- cancellable = false; config_only = false;
- once_had_no_optargs = false;
- c_name = ""; c_function = ""; c_optarg_prefix = "";
- non_c_aliases = [] }
- (* These test functions are used in the language binding tests. *)
- let test_all_args = [
- String "str";
- OptString "optstr";
- StringList "strlist";
- Bool "b";
- Int "integer";
- Int64 "integer64";
- FileIn "filein";
- FileOut "fileout";
- BufferIn "bufferin";
- ]
- let test_all_optargs = [
- OBool "obool";
- OInt "oint";
- OInt64 "oint64";
- OString "ostring"
- ]
- let test_all_rets = [
- (* except for RErr, which is tested thoroughly elsewhere *)
- "internal_test_rint", RInt "valout";
- "internal_test_rint64", RInt64 "valout";
- "internal_test_rbool", RBool "valout";
- "internal_test_rconststring", RConstString "valout";
- "internal_test_rconstoptstring", RConstOptString "valout";
- "internal_test_rstring", RString "valout";
- "internal_test_rstringlist", RStringList "valout";
- "internal_test_rstruct", RStruct ("valout", "lvm_pv");
- "internal_test_rstructlist", RStructList ("valout", "lvm_pv");
- "internal_test_rhashtable", RHashtable "valout";
- "internal_test_rbufferout", RBufferOut "valout";
- ]
- let test_functions = [
- { defaults with
- name = "internal_test";
- style = RErr, test_all_args, test_all_optargs;
- in_fish = false; in_docs = false; cancellable = true;
- shortdesc = "internal test function - do not use";
- longdesc = "\
- This is an internal test function which is used to test whether
- the automatically generated bindings can handle every possible
- parameter type correctly.
- It echos the contents of each parameter to stdout.
- You probably don't want to call this function." }
- ] @ List.flatten (
- List.map (
- fun (name, ret) -> [
- { defaults with
- name = name;
- style = ret, [String "val"], [];
- in_fish = false; in_docs = false;
- shortdesc = "internal test function - do not use";
- longdesc = "\
- This is an internal test function which is used to test whether
- the automatically generated bindings can handle every possible
- return type correctly.
- It converts string C<val> to the return type.
- You probably don't want to call this function." };
- { defaults with
- name = name ^ "err";
- style = ret, [], [];
- in_fish = false; in_docs = false;
- shortdesc = "internal test function - do not use";
- longdesc = "\
- This is an internal test function which is used to test whether
- the automatically generated bindings can handle every possible
- return type correctly.
- This function always returns an error.
- You probably don't want to call this function." }
- ]
- ) test_all_rets
- )
- (* non_daemon_functions are any functions which don't get processed
- * in the daemon, eg. functions for setting and getting local
- * configuration values.
- *)
- let non_daemon_functions = test_functions @ [
- { defaults with
- name = "launch";
- style = RErr, [], [];
- fish_alias = ["run"]; progress = true; config_only = true;
- shortdesc = "launch the qemu subprocess";
- longdesc = "\
- Internally libguestfs is implemented by running a virtual machine
- using L<qemu(1)>.
- You should call this after configuring the handle
- (eg. adding drives) but before performing any actions." };
- { defaults with
- name = "wait_ready";
- style = RErr, [], [];
- in_fish = false; deprecated_by = Some "launch";
- shortdesc = "wait until the qemu subprocess launches (no op)";
- longdesc = "\
- This function is a no op.
- In versions of the API E<lt> 1.0.71 you had to call this function
- just after calling C<guestfs_launch> to wait for the launch
- to complete. However this is no longer necessary because
- C<guestfs_launch> now does the waiting.
- If you see any calls to this function in code then you can just
- remove them, unless you want to retain compatibility with older
- versions of the API." };
- { defaults with
- name = "kill_subprocess";
- style = RErr, [], [];
- deprecated_by = Some "shutdown";
- shortdesc = "kill the qemu subprocess";
- longdesc = "\
- This kills the qemu subprocess.
- Do not call this. See: C<guestfs_shutdown> instead." };
- { defaults with
- name = "add_cdrom";
- style = RErr, [String "filename"], [];
- deprecated_by = Some "add_drive"; config_only = true;
- shortdesc = "add a CD-ROM disk image to examine";
- longdesc = "\
- This function adds a virtual CD-ROM disk image to the guest.
- This is equivalent to the qemu parameter I<-cdrom filename>.
- Notes:
- =over 4
- =item *
- This call checks for the existence of C<filename>. This
- stops you from specifying other types of drive which are supported
- by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
- the general C<guestfs_config> call instead.
- =item *
- If you just want to add an ISO file (often you use this as an
- efficient way to transfer large files into the guest), then you
- should probably use C<guestfs_add_drive_ro> instead.
- =back" };
- { defaults with
- name = "add_drive_ro";
- style = RErr, [String "filename"], [];
- fish_alias = ["add-ro"]; config_only = true;
- shortdesc = "add a drive in snapshot mode (read-only)";
- longdesc = "\
- This function is the equivalent of calling C<guestfs_add_drive_opts>
- with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> set to 1,
- so the disk is added read-only, with the format being detected
- automatically." };
- { defaults with
- name = "config";
- style = RErr, [String "qemuparam"; OptString "qemuvalue"], [];
- config_only = true;
- shortdesc = "add qemu parameters";
- longdesc = "\
- This can be used to add arbitrary qemu command line parameters
- of the form I<-param value>. Actually it's not quite arbitrary - we
- prevent you from setting some parameters which would interfere with
- parameters that we use.
- The first character of C<param> string must be a C<-> (dash).
- C<value> can be NULL." };
- { defaults with
- name = "set_qemu";
- style = RErr, [OptString "qemu"], [];
- fish_alias = ["qemu"]; config_only = true;
- shortdesc = "set the qemu binary";
- longdesc = "\
- Set the qemu binary that we will use.
- The default is chosen when the library was compiled by the
- configure script.
- You can also override this by setting the C<LIBGUESTFS_QEMU>
- environment variable.
- Setting C<qemu> to C<NULL> restores the default qemu binary.
- Note that you should call this function as early as possible
- after creating the handle. This is because some pre-launch
- operations depend on testing qemu features (by running C<qemu -help>).
- If the qemu binary changes, we don't retest features, and
- so you might see inconsistent results. Using the environment
- variable C<LIBGUESTFS_QEMU> is safest of all since that picks
- the qemu binary at the same time as the handle is created." };
- { defaults with
- name = "get_qemu";
- style = RConstString "qemu", [], [];
- tests = [
- InitNone, Always, TestRun (
- [["get_qemu"]])
- ];
- shortdesc = "get the qemu binary";
- longdesc = "\
- Return the current qemu binary.
- This is always non-NULL. If it wasn't set already, then this will
- return the default qemu binary name." };
- { defaults with
- name = "set_path";
- style = RErr, [OptString "searchpath"], [];
- fish_alias = ["path"]; config_only = true;
- shortdesc = "set the search path";
- longdesc = "\
- Set the path that libguestfs searches for kernel and initrd.img.
- The default is C<$libdir/guestfs> unless overridden by setting
- C<LIBGUESTFS_PATH> environment variable.
- Setting C<path> to C<NULL> restores the default path." };
- { defaults with
- name = "get_path";
- style = RConstString "path", [], [];
- tests = [
- InitNone, Always, TestRun (
- [["get_path"]])
- ];
- shortdesc = "get the search path";
- longdesc = "\
- Return the current search path.
- This is always non-NULL. If it wasn't set already, then this will
- return the default path." };
- { defaults with
- name = "set_append";
- style = RErr, [OptString "append"], [];
- fish_alias = ["append"]; config_only = true;
- shortdesc = "add options to kernel command line";
- longdesc = "\
- This function is used to add additional options to the
- guest kernel command line.
- The default is C<NULL> unless overridden by setting
- C<LIBGUESTFS_APPEND> environment variable.
- Setting C<append> to C<NULL> means I<no> additional options
- are passed (libguestfs always adds a few of its own)." };
- { defaults with
- name = "get_append";
- style = RConstOptString "append", [], [];
- (* This cannot be tested with the current framework. The
- * function can return NULL in normal operations, which the
- * test framework interprets as an error.
- *)
- tests = [];
- shortdesc = "get the additional kernel options";
- longdesc = "\
- Return the additional kernel options which are added to the
- guest kernel command line.
- If C<NULL> then no options are added." };
- { defaults with
- name = "set_autosync";
- style = RErr, [Bool "autosync"], [];
- fish_alias = ["autosync"];
- shortdesc = "set autosync mode";
- longdesc = "\
- If C<autosync> is true, this enables autosync. Libguestfs will make a
- best effort attempt to make filesystems consistent and synchronized
- when the handle is closed
- (also if the program exits without closing handles).
- This is enabled by default (since libguestfs 1.5.24, previously it was
- disabled by default)." };
- { defaults with
- name = "get_autosync";
- style = RBool "autosync", [], [];
- tests = [
- InitNone, Always, TestOutputTrue (
- [["get_autosync"]])
- ];
- shortdesc = "get autosync mode";
- longdesc = "\
- Get the autosync flag." };
- { defaults with
- name = "set_verbose";
- style = RErr, [Bool "verbose"], [];
- fish_alias = ["verbose"];
- shortdesc = "set verbose mode";
- longdesc = "\
- If C<verbose> is true, this turns on verbose messages.
- Verbose messages are disabled unless the environment variable
- C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
- Verbose messages are normally sent to C<stderr>, unless you
- register a callback to send them somewhere else (see
- C<guestfs_set_event_callback>)." };
- { defaults with
- name = "get_verbose";
- style = RBool "verbose", [], [];
- shortdesc = "get verbose mode";
- longdesc = "\
- This returns the verbose messages flag." };
- { defaults with
- name = "is_ready";
- style = RBool "ready", [], [];
- tests = [
- InitNone, Always, TestOutputTrue (
- [["is_ready"]])
- ];
- shortdesc = "is ready to accept commands";
- longdesc = "\
- This returns true iff this handle is ready to accept commands
- (in the C<READY> state).
- For more information on states, see L<guestfs(3)>." };
- { defaults with
- name = "is_config";
- style = RBool "config", [], [];
- tests = [
- InitNone, Always, TestOutputFalse (
- [["is_config"]])
- ];
- shortdesc = "is in configuration state";
- longdesc = "\
- This returns true iff this handle is being configured
- (in the C<CONFIG> state).
- For more information on states, see L<guestfs(3)>." };
- { defaults with
- name = "is_launching";
- style = RBool "launching", [], [];
- tests = [
- InitNone, Always, TestOutputFalse (
- [["is_launching"]])
- ];
- shortdesc = "is launching subprocess";
- longdesc = "\
- This returns true iff this handle is launching the subprocess
- (in the C<LAUNCHING> state).
- For more information on states, see L<guestfs(3)>." };
- { defaults with
- name = "is_busy";
- style = RBool "busy", [], [];
- in_docs = false;
- tests = [
- InitNone, Always, TestOutputFalse (
- [["is_busy"]])
- ];
- shortdesc = "is busy processing a command";
- longdesc = "\
- This always returns false. Do not use this function.
- For more information on states, see L<guestfs(3)>." };
- { defaults with
- name = "get_state";
- style = RInt "state", [], [];
- shortdesc = "get the current state";
- longdesc = "\
- This returns the current state as an opaque integer. This is
- only useful for printing debug and internal error messages.
- For more information on states, see L<guestfs(3)>." };
- { defaults with
- name = "set_memsize";
- style = RErr, [Int "memsize"], [];
- fish_alias = ["memsize"]; config_only = true;
- shortdesc = "set memory allocated to the qemu subprocess";
- longdesc = "\
- This sets the memory size in megabytes allocated to the
- qemu subprocess. This only has any effect if called before
- C<guestfs_launch>.
- You can also change this by setting the environment
- variable C<LIBGUESTFS_MEMSIZE> before the handle is
- created.
- For more information on the architecture of libguestfs,
- see L<guestfs(3)>." };
- { defaults with
- name = "get_memsize";
- style = RInt "memsize", [], [];
- tests = [
- InitNone, Always, TestOutputIntOp (
- [["get_memsize"]], ">=", 256)
- ];
- shortdesc = "get memory allocated to the qemu subprocess";
- longdesc = "\
- This gets the memory size in megabytes allocated to the
- qemu subprocess.
- If C<guestfs_set_memsize> was not called
- on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
- then this returns the compiled-in default value for memsize.
- For more information on the architecture of libguestfs,
- see L<guestfs(3)>." };
- { defaults with
- name = "get_pid";
- style = RInt "pid", [], [];
- fish_alias = ["pid"];
- tests = [
- InitNone, Always, TestOutputIntOp (
- [["get_pid"]], ">=", 1)
- ];
- shortdesc = "get PID of qemu subprocess";
- longdesc = "\
- Return the process ID of the qemu subprocess. If there is no
- qemu subprocess, then this will return an error.
- This is an internal call used for debugging and testing." };
- { defaults with
- name = "version";
- style = RStruct ("version", "version"), [], [];
- tests = [
- InitNone, Always, TestOutputStruct (
- [["version"]], [CompareWithInt ("major", 1)])
- ];
- shortdesc = "get the library version number";
- longdesc = "\
- Return the libguestfs version number that the program is linked
- against.
- Note that because of dynamic linking this is not necessarily
- the version of libguestfs that you compiled against. You can
- compile the program, and then at runtime dynamically link
- against a completely different C<libguestfs.so> library.
- This call was added in version C<1.0.58>. In previous
- versions of libguestfs there was no way to get the version
- number. From C code you can use dynamic linker functions
- to find out if this symbol exists (if it doesn't, then
- it's an earlier version).
- The call returns a structure with four elements. The first
- three (C<major>, C<minor> and C<release>) are numbers and
- correspond to the usual version triplet. The fourth element
- (C<extra>) is a string and is normally empty, but may be
- used for distro-specific information.
- To construct the original version string:
- C<$major.$minor.$release$extra>
- See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
- I<Note:> Don't use this call to test for availability
- of features. In enterprise distributions we backport
- features from later versions into earlier versions,
- making this an unreliable way to test for features.
- Use C<guestfs_available> instead." };
- { defaults with
- name = "set_selinux";
- style = RErr, [Bool "selinux"], [];
- fish_alias = ["selinux"]; config_only = true;
- shortdesc = "set SELinux enabled or disabled at appliance boot";
- longdesc = "\
- This sets the selinux flag that is passed to the appliance
- at boot time. The default is C<selinux=0> (disabled).
- Note that if SELinux is enabled, it is always in
- Permissive mode (C<enforcing=0>).
- For more information on the architecture of libguestfs,
- see L<guestfs(3)>." };
- { defaults with
- name = "get_selinux";
- style = RBool "selinux", [], [];
- shortdesc = "get SELinux enabled flag";
- longdesc = "\
- This returns the current setting of the selinux flag which
- is passed to the appliance at boot time. See C<guestfs_set_selinux>.
- For more information on the architecture of libguestfs,
- see L<guestfs(3)>." };
- { defaults with
- name = "set_trace";
- style = RErr, [Bool "trace"], [];
- fish_alias = ["trace"];
- tests = [
- InitNone, Always, TestOutputFalse (
- [["set_trace"; "false"];
- ["get_trace"]])
- ];
- shortdesc = "enable or disable command traces";
- longdesc = "\
- If the command trace flag is set to 1, then libguestfs
- calls, parameters and return values are traced.
- If you want to trace C API calls into libguestfs (and
- other libraries) then possibly a better way is to use
- the external ltrace(1) command.
- Command traces are disabled unless the environment variable
- C<LIBGUESTFS_TRACE> is defined and set to C<1>.
- Trace messages are normally sent to C<stderr>, unless you
- register a callback to send them somewhere else (see
- C<guestfs_set_event_callback>)." };
- { defaults with
- name = "get_trace";
- style = RBool "trace", [], [];
- shortdesc = "get command trace enabled flag";
- longdesc = "\
- Return the command trace flag." };
- { defaults with
- name = "set_direct";
- style = RErr, [Bool "direct"], [];
- fish_alias = ["direct"]; config_only = true;
- shortdesc = "enable or disable direct appliance mode";
- longdesc = "\
- If the direct appliance mode flag is enabled, then stdin and
- stdout are passed directly through to the appliance once it
- is launched.
- One consequence of this is that log messages aren't caught
- by the library and handled by C<guestfs_set_log_message_callback>,
- but go straight to stdout.
- You probably don't want to use this unless you know what you
- are doing.
- The default is disabled." };
- { defaults with
- name = "get_direct";
- style = RBool "direct", [], [];
- shortdesc = "get direct appliance mode flag";
- longdesc = "\
- Return the direct appliance mode flag." };
- { defaults with
- name = "set_recovery_proc";
- style = RErr, [Bool "recoveryproc"], [];
- fish_alias = ["recovery-proc"]; config_only = true;
- shortdesc = "enable or disable the recovery process";
- longdesc = "\
- If this is called with the parameter C<false> then
- C<guestfs_launch> does not create a recovery process. The
- purpose of the recovery process is to stop runaway qemu
- processes in the case where the main program aborts abruptly.
- This only has any effect if called before C<guestfs_launch>,
- and the default is true.
- About the only time when you would want to disable this is
- if the main process will fork itself into the background
- (\"daemonize\" itself). In this case the recovery process
- thinks that the main program has disappeared and so kills
- qemu, which is not very helpful." };
- { defaults with
- name = "get_recovery_proc";
- style = RBool "recoveryproc", [], [];
- shortdesc = "get recovery process enabled flag";
- longdesc = "\
- Return the recovery process enabled flag." };
- { defaults with
- name = "add_drive_with_if";
- style = RErr, [String "filename"; String "iface"], [];
- deprecated_by = Some "add_drive"; config_only = true;
- shortdesc = "add a drive specifying the QEMU block emulation to use";
- longdesc = "\
- This is the same as C<guestfs_add_drive> but it allows you
- to specify the QEMU interface emulation to use at run time." };
- { defaults with
- name = "add_drive_ro_with_if";
- style = RErr, [String "filename"; String "iface"], [];
- deprecated_by = Some "add_drive"; config_only = true;
- shortdesc = "add a drive read-only specifying the QEMU block emulation to use";
- longdesc = "\
- This is the same as C<guestfs_add_drive_ro> but it allows you
- to specify the QEMU interface emulation to use at run time." };
- { defaults with
- name = "file_architecture";
- style = RString "arch", [Pathname "filename"], [];
- tests = [
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/bin-i586-dynamic"]], "i386");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/bin-sparc-dynamic"]], "sparc");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/bin-win32.exe"]], "i386");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/bin-win64.exe"]], "x86_64");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/lib-i586.so"]], "i386");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/lib-sparc.so"]], "sparc");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/lib-win32.dll"]], "i386");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/lib-win64.dll"]], "x86_64");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/lib-x86_64.so"]], "x86_64");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/initrd-x86_64.img"]], "x86_64");
- InitISOFS, Always, TestOutput (
- [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");
- ];
- shortdesc = "detect the architecture of a binary file";
- longdesc = "\
- This detects the architecture of the binary C<filename>,
- and returns it if known.
- Currently defined architectures are:
- =over 4
- =item \"i386\"
- This string is returned for all 32 bit i386, i486, i586, i686 binaries
- irrespective of the precise processor requirements of the binary.
- =item \"x86_64\"
- 64 bit x86-64.
- =item \"sparc\"
- 32 bit SPARC.
- =item \"sparc64\"
- 64 bit SPARC V9 and above.
- =item \"ia64\"
- Intel Itanium.
- =item \"ppc\"
- 32 bit Power PC.
- =item \"ppc64\"
- 64 bit Power PC.
- =back
- Libguestfs may return other architecture strings in future.
- The function works on at least the following types of files:
- =over 4
- =item *
- many types of Un*x and Linux binary
- =item *
- many types of Un*x and Linux shared library
- =item *
- Windows Win32 and Win64 binaries
- =item *
- Windows Win32 and Win64 DLLs
- Win32 binaries and DLLs return C<i386>.
- Win64 binaries and DLLs return C<x86_64>.
- =item *
- Linux kernel modules
- =item *
- Linux new-style initrd images
- =item *
- some non-x86 Linux vmlinuz kernels
- =back
- What it can't do currently:
- =over 4
- =item *
- static libraries (libfoo.a)
- =item *
- Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
- =item *
- x86 Linux vmlinuz kernels
- x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and
- compressed code, and are horribly hard to unpack. If you want to find
- the architecture of a kernel, use the architecture of the associated
- initrd or kernel module(s) instead.
- =back" };
- { defaults with
- name = "inspect_os";
- style = RStringList "roots", [], [];
- shortdesc = "inspect disk and return list of operating systems found";
- longdesc = "\
- This function uses other libguestfs functions and certain
- heuristics to inspect the disk(s) (usually disks belonging to
- a virtual machine), looking for operating systems.
- The list returned is empty if no operating systems were found.
- If one operating system was found, then this returns a list with
- a single element, which is the name of the root filesystem of
- this operating system. It is also possible for this function
- to return a list containing more than one element, indicating
- a dual-boot or multi-boot virtual machine, with each element being
- the root filesystem of one of the operating systems.
- You can pass the root string(s) returned to other
- C<guestfs_inspect_get_*> functions in order to query further
- information about each operating system, such as the name
- and version.
- This function uses other libguestfs features such as
- C<guestfs_mount_ro> and C<guestfs_umount_all> in order to mount
- and unmount filesystems and look at the contents. This should
- be called with no disks currently mounted. The function may also
- use Augeas, so any existing Augeas handle will be closed.
- This function cannot decrypt encrypted disks. The caller
- must do that first (supplying the necessary keys) if the
- disk is encrypted.
- Please read L<guestfs(3)/INSPECTION> for more details.
- See also C<guestfs_list_filesystems>." };
- { defaults with
- name = "inspect_get_type";
- style = RString "name", [Device "root"], [];
- shortdesc = "get type of inspected operating system";
- longdesc = "\
- This returns the type of the inspected operating system.
- Currently defined types are:
- =over 4
- =item \"linux\"
- Any Linux-based operating system.
- =item \"windows\"
- Any Microsoft Windows operating system.
- =item \"freebsd\"
- FreeBSD.
- =item \"netbsd\"
- NetBSD.
- =item \"hurd\"
- GNU/Hurd.
- =item \"dos\"
- MS-DOS, FreeDOS and others.
- =item \"unknown\"
- The operating system type could not be determined.
- =back
- Future versions of libguestfs may return other strings here.
- The caller should be prepared to handle any string.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_arch";
- style = RString "arch", [Device "root"], [];
- shortdesc = "get architecture of inspected operating system";
- longdesc = "\
- This returns the architecture of the inspected operating system.
- The possible return values are listed under
- C<guestfs_file_architecture>.
- If the architecture could not be determined, then the
- string C<unknown> is returned.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_distro";
- style = RString "distro", [Device "root"], [];
- shortdesc = "get distro of inspected operating system";
- longdesc = "\
- This returns the distro (distribution) of the inspected operating
- system.
- Currently defined distros are:
- =over 4
- =item \"archlinux\"
- Arch Linux.
- =item \"buildroot\"
- Buildroot-derived distro, but not one we specifically recognize.
- =item \"centos\"
- CentOS.
- =item \"cirros\"
- Cirros.
- =item \"debian\"
- Debian.
- =item \"fedora\"
- Fedora.
- =item \"freedos\"
- FreeDOS.
- =item \"gentoo\"
- Gentoo.
- =item \"linuxmint\"
- Linux Mint.
- =item \"mageia\"
- Mageia.
- =item \"mandriva\"
- Mandriva.
- =item \"meego\"
- MeeGo.
- =item \"opensuse\"
- OpenSUSE.
- =item \"pardus\"
- Pardus.
- =item \"redhat-based\"
- Some Red Hat-derived distro.
- =item \"rhel\"
- Red Hat Enterprise Linux.
- =item \"scientificlinux\"
- Scientific Linux.
- =item \"slackware\"
- Slackware.
- =item \"ttylinux\"
- ttylinux.
- =item \"ubuntu\"
- Ubuntu.
- =item \"unknown\"
- The distro could not be determined.
- =item \"windows\"
- Windows does not have distributions. This string is
- returned if the OS type is Windows.
- =back
- Future versions of libguestfs may return other strings here.
- The caller should be prepared to handle any string.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_major_version";
- style = RInt "major", [Device "root"], [];
- shortdesc = "get major version of inspected operating system";
- longdesc = "\
- This returns the major version number of the inspected operating
- system.
- Windows uses a consistent versioning scheme which is I<not>
- reflected in the popular public names used by the operating system.
- Notably the operating system known as \"Windows 7\" is really
- version 6.1 (ie. major = 6, minor = 1). You can find out the
- real versions corresponding to releases of Windows by consulting
- Wikipedia or MSDN.
- If the version could not be determined, then C<0> is returned.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_minor_version";
- style = RInt "minor", [Device "root"], [];
- shortdesc = "get minor version of inspected operating system";
- longdesc = "\
- This returns the minor version number of the inspected operating
- system.
- If the version could not be determined, then C<0> is returned.
- Please read L<guestfs(3)/INSPECTION> for more details.
- See also C<guestfs_inspect_get_major_version>." };
- { defaults with
- name = "inspect_get_product_name";
- style = RString "product", [Device "root"], [];
- shortdesc = "get product name of inspected operating system";
- longdesc = "\
- This returns the product name of the inspected operating
- system. The product name is generally some freeform string
- which can be displayed to the user, but should not be
- parsed by programs.
- If the product name could not be determined, then the
- string C<unknown> is returned.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_mountpoints";
- style = RHashtable "mountpoints", [Device "root"], [];
- shortdesc = "get mountpoints of inspected operating system";
- longdesc = "\
- This returns a hash of where we think the filesystems
- associated with this operating system should be mounted.
- Callers should note that this is at best an educated guess
- made by reading configuration files such as C</etc/fstab>.
- I<In particular note> that this may return filesystems
- which are non-existent or not mountable and callers should
- be prepared to handle or ignore failures if they try to
- mount them.
- Each element in the returned hashtable has a key which
- is the path of the mountpoint (eg. C</boot>) and a value
- which is the filesystem that would be mounted there
- (eg. C</dev/sda1>).
- Non-mounted devices such as swap devices are I<not>
- returned in this list.
- For operating systems like Windows which still use drive
- letters, this call will only return an entry for the first
- drive \"mounted on\" C</>. For information about the
- mapping of drive letters to partitions, see
- C<guestfs_inspect_get_drive_mappings>.
- Please read L<guestfs(3)/INSPECTION> for more details.
- See also C<guestfs_inspect_get_filesystems>." };
- { defaults with
- name = "inspect_get_filesystems";
- style = RStringList "filesystems", [Device "root"], [];
- shortdesc = "get filesystems associated with inspected operating system";
- longdesc = "\
- This returns a list of all the filesystems that we think
- are associated with this operating system. This includes
- the root filesystem, other ordinary filesystems, and
- non-mounted devices like swap partitions.
- In the case of a multi-boot virtual machine, it is possible
- for a filesystem to be shared between operating systems.
- Please read L<guestfs(3)/INSPECTION> for more details.
- See also C<guestfs_inspect_get_mountpoints>." };
- { defaults with
- name = "set_network";
- style = RErr, [Bool "network"], [];
- fish_alias = ["network"]; config_only = true;
- shortdesc = "set enable network flag";
- longdesc = "\
- If C<network> is true, then the network is enabled in the
- libguestfs appliance. The default is false.
- This affects whether commands are able to access the network
- (see L<guestfs(3)/RUNNING COMMANDS>).
- You must call this before calling C<guestfs_launch>, otherwise
- it has no effect." };
- { defaults with
- name = "get_network";
- style = RBool "network", [], [];
- shortdesc = "get enable network flag";
- longdesc = "\
- This returns the enable network flag." };
- { defaults with
- name = "list_filesystems";
- style = RHashtable "fses", [], [];
- shortdesc = "list filesystems";
- longdesc = "\
- This inspection command looks for filesystems on partitions,
- block devices and logical volumes, returning a list of devices
- containing filesystems and their type.
- The return value is a hash, where the keys are the devices
- containing filesystems, and the values are the filesystem types.
- For example:
- \"/dev/sda1\" => \"ntfs\"
- \"/dev/sda2\" => \"ext2\"
- \"/dev/vg_guest/lv_root\" => \"ext4\"
- \"/dev/vg_guest/lv_swap\" => \"swap\"
- The value can have the special value \"unknown\", meaning the
- content of the device is undetermined or empty.
- \"swap\" means a Linux swap partition.
- This command runs other libguestfs commands, which might include
- C<guestfs_mount> and C<guestfs_umount>, and therefore you should
- use this soon after launch and only when nothing is mounted.
- Not all of the filesystems returned will be mountable. In
- particular, swap partitions are returned in the list. Also
- this command does not check that each filesystem
- found is valid and mountable, and some filesystems might
- be mountable but require special options. Filesystems may
- not all belong to a single logical operating system
- (use C<guestfs_inspect_os> to look for OSes)." };
- { defaults with
- name = "add_drive";
- style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"];
- once_had_no_optargs = true;
- fish_alias = ["add"]; config_only = true;
- shortdesc = "add an image to examine or modify";
- longdesc = "\
- This function adds a virtual machine disk image C<filename> to
- libguestfs. The first time you call this function, the disk
- appears as C</dev/sda>, the second time as C</dev/sdb>, and
- so on.
- You don't necessarily need to be root when using libguestfs. However
- you obviously do need sufficient permissions to access the filename
- for whatever operations you want to perform (ie. read access if you
- just want to read the image or write access if you want to modify the
- image).
- This call checks that C<filename> exists.
- The optional arguments are:
- =over 4
- =item C<readonly>
- If true then the image is treated as read-only. Writes are still
- allowed, but they are stored in a temporary snapshot overlay which
- is discarded at the end. The disk that you add is not modified.
- =item C<format>
- This forces the image format. If you omit this (or use C<guestfs_add_drive>
- or C<guestfs_add_drive_ro>) then the format is automatically detected.
- Possible formats include C<raw> and C<qcow2>.
- Automatic detection of the format opens you up to a potential
- security hole when dealing with untrusted raw-format images.
- See CVE-2010-3851 and RHBZ#642934. Specifying the format closes
- this security hole.
- =item C<iface>
- This rarely-used option lets you emulate the behaviour of the
- deprecated C<guestfs_add_drive_with_if> call (q.v.)
- =item C<name>
- The name the drive had in the original guest, e.g. /dev/sdb. This is used as a
- hint to the guest inspection process if it is available.
- =back
- C<filename> can have the special value C</dev/null>, which means
- to add a null (zero length) raw format device. You can add C</dev/null>
- multiple times." };
- { defaults with
- name = "inspect_get_windows_systemroot";
- style = RString "systemroot", [Device "root"], [];
- shortdesc = "get Windows systemroot of inspected operating system";
- longdesc = "\
- This returns the Windows systemroot of the inspected guest.
- The systemroot is a directory path such as C</WINDOWS>.
- This call assumes that the guest is Windows and that the
- systemroot could be determined by inspection. If this is not
- the case then an error is returned.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_roots";
- style = RStringList "roots", [], [];
- shortdesc = "return list of operating systems found by last inspection";
- longdesc = "\
- This function is a convenient way to get the list of root
- devices, as returned from a previous call to C<guestfs_inspect_os>,
- but without redoing the whole inspection process.
- This returns an empty list if either no root devices were
- found or the caller has not called C<guestfs_inspect_os>.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "debug_cmdline";
- style = RStringList "cmdline", [], [];
- in_docs = false;
- shortdesc = "debug the QEMU command line (internal use only)";
- longdesc = "\
- This returns the internal QEMU command line. 'debug' commands are
- not part of the formal API and can be removed or changed at any time." };
- { defaults with
- name = "debug_drives";
- style = RStringList "cmdline", [], [];
- in_docs = false;
- shortdesc = "debug the drives (internal use only)";
- longdesc = "\
- This returns the internal list of drives. 'debug' commands are
- not part of the formal API and can be removed or changed at any time." };
- { defaults with
- name = "add_domain";
- style = RInt "nrdisks", [String "dom"], [OString "libvirturi"; OBool "readonly"; OString "iface"; OBool "live"; OBool "allowuuid"; OString "readonlydisk"];
- fish_alias = ["domain"]; config_only = true;
- shortdesc = "add the disk(s) from a named libvirt domain";
- longdesc = "\
- This function adds the disk(s) attached to the named libvirt
- domain C<dom>. It works by connecting to libvirt, requesting
- the domain and domain XML from libvirt, parsing it for disks,
- and calling C<guestfs_add_drive_opts> on each one.
- The number of disks added is returned. This operation is atomic:
- if an error is returned, then no disks are added.
- This function does some minimal checks to make sure the libvirt
- domain is not running (unless C<readonly> is true). In a future
- version we will try to acquire the libvirt lock on each disk.
- Disks must be accessible locally. This often means that adding disks
- from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
- will fail unless those disks are accessible via the same device path
- locally too.
- The optional C<libvirturi> parameter sets the libvirt URI
- (see L<http://libvirt.org/uri.html>). If this is not set then
- we connect to the default libvirt URI (or one set through an
- environment variable, see the libvirt documentation for full
- details).
- The optional C<live> flag controls whether this call will try
- to connect to a running virtual machine C<guestfsd> process if
- it sees a suitable E<lt>channelE<gt> element in the libvirt
- XML definition. The default (if the flag is omitted) is never
- to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
- information.
- If the C<allowuuid> flag is true (default is false) then a UUID
- I<may> be passed instead of the domain name. The C<dom> string is
- treated as a UUID first and looked up, and if that lookup fails
- then we treat C<dom> as a name as usual.
- The optional C<readonlydisk> parameter controls what we do for
- disks which are marked E<lt>readonly/E<gt> in the libvirt XML.
- Possible values are:
- =over 4
- =item readonlydisk = \"error\"
- If C<readonly> is false:
- The whole call is aborted with an error if any disk with
- the E<lt>readonly/E<gt> flag is found.
- If C<readonly> is true:
- Disks with the E<lt>readonly/E<gt> flag are added read-only.
- =item readonlydisk = \"read\"
- If C<readonly> is false:
- Disks with the E<lt>readonly/E<gt> flag are added read-only.
- Other disks are added read/write.
- If C<readonly> is true:
- Disks with the E<lt>readonly/E<gt> flag are added read-only.
- =item readonlydisk = \"write\" (default)
- If C<readonly> is false:
- Disks with the E<lt>readonly/E<gt> flag are added read/write.
- If C<readonly> is true:
- Disks with the E<lt>readonly/E<gt> flag are added read-only.
- =item readonlydisk = \"ignore\"
- If C<readonly> is true or false:
- Disks with the E<lt>readonly/E<gt> flag are skipped.
- =back
- The other optional parameters are passed directly through to
- C<guestfs_add_drive_opts>." };
- (*
- This interface is not quite baked yet. -- RWMJ 2010-11-11
- { defaults with
- name = "add_libvirt_dom";
- style = RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"; String "readonlydisk"];
- in_fish = false;
- shortdesc = "add the disk(s) from a libvirt domain";
- longdesc = "\
- This function adds the disk(s) attached to the libvirt domain C<dom>.
- It works by requesting the domain XML from libvirt, parsing it for
- disks, and calling C<guestfs_add_drive_opts> on each one.
- In the C API we declare C<void *dom>, but really it has type
- C<virDomainPtr dom>. This is so we don't need E<lt>libvirt.hE<gt>.
- The number of disks added is returned. This operation is atomic:
- if an error is returned, then no disks are added.
- This function does some minimal checks to make sure the libvirt
- domain is not running (unless C<readonly> is true). In a future
- version we will try to acquire the libvirt lock on each disk.
- Disks must be accessible locally. This often means that adding disks
- from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
- will fail unless those disks are accessible via the same device path
- locally too.
- The optional C<live> flag controls whether this call will try
- to connect to a running virtual machine C<guestfsd> process if
- it sees a suitable E<lt>channelE<gt> element in the libvirt
- XML definition. The default (if the flag is omitted) is never
- to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
- information.
- The optional C<readonlydisk> parameter controls what we do for
- disks which are marked E<lt>readonly/E<gt> in the libvirt XML.
- See C<guestfs_add_domain> for possible values.
- The other optional parameters are passed directly through to
- C<guestfs_add_drive_opts>." };
- *)
- { defaults with
- name = "inspect_get_package_format";
- style = RString "packageformat", [Device "root"], [];
- shortdesc = "get package format used by the operating system";
- longdesc = "\
- This function and C<guestfs_inspect_get_package_management> return
- the package format and package management tool used by the
- inspected operating system. For example for Fedora these
- functions would return C<rpm> (package format) and
- C<yum> (package management).
- This returns the string C<unknown> if we could not determine the
- package format I<or> if the operating system does not have
- a real packaging system (eg. Windows).
- Possible strings include:
- C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>.
- Future versions of libguestfs may return other strings.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_package_management";
- style = RString "packagemanagement", [Device "root"], [];
- shortdesc = "get package management tool used by the operating system";
- longdesc = "\
- C<guestfs_inspect_get_package_format> and this function return
- the package format and package management tool used by the
- inspected operating system. For example for Fedora these
- functions would return C<rpm> (package format) and
- C<yum> (package management).
- This returns the string C<unknown> if we could not determine the
- package management tool I<or> if the operating system does not have
- a real packaging system (eg. Windows).
- Possible strings include: C<yum>, C<up2date>,
- C<apt> (for all Debian derivatives),
- C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>.
- Future versions of libguestfs may return other strings.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_list_applications";
- style = RStructList ("applications", "application"), [Device "root"], [];
- shortdesc = "get list of applications installed in the operating system";
- longdesc = "\
- Return the list of applications installed in the operating system.
- I<Note:> This call works differently from other parts of the
- inspection API. You have to call C<guestfs_inspect_os>, then
- C<guestfs_inspect_get_mountpoints>, then mount up the disks,
- before calling this. Listing applications is a significantly
- more difficult operation which requires access to the full
- filesystem. Also note that unlike the other
- C<guestfs_inspect_get_*> calls which are just returning
- data cached in the libguestfs handle, this call actually reads
- parts of the mounted filesystems during the call.
- This returns an empty list if the inspection code was not able
- to determine the list of applications.
- The application structure contains the following fields:
- =over 4
- =item C<app_name>
- The name of the application. For Red Hat-derived and Debian-derived
- Linux guests, this is the package name.
- =item C<app_display_name>
- The display name of the application, sometimes localized to the
- install language of the guest operating system.
- If unavailable this is returned as an empty string C<\"\">.
- Callers needing to display something can use C<app_name> instead.
- =item C<app_epoch>
- For package managers which use epochs, this contains the epoch of
- the package (an integer). If unavailable, this is returned as C<0>.
- =item C<app_version>
- The version string of the application or package. If unavailable
- this is returned as an empty string C<\"\">.
- =item C<app_release>
- The release string of the application or package, for package
- managers that use this. If unavailable this is returned as an
- empty string C<\"\">.
- =item C<app_install_path>
- The installation path of the application (on operating systems
- such as Windows which use installation paths). This path is
- in the format used by the guest operating system, it is not
- a libguestfs path.
- If unavailable this is returned as an empty string C<\"\">.
- =item C<app_trans_path>
- The install path translated into a libguestfs path.
- If unavailable this is returned as an empty string C<\"\">.
- =item C<app_publisher>
- The name of the publisher of the application, for package
- managers that use this. If unavailable this is returned
- as an empty string C<\"\">.
- =item C<app_url>
- The URL (eg. upstream URL) of the application.
- If unavailable this is returned as an empty string C<\"\">.
- =item C<app_source_package>
- For packaging systems which support this, the name of the source
- package. If unavailable this is returned as an empty string C<\"\">.
- =item C<app_summary>
- A short (usually one line) description of the application or package.
- If unavailable this is returned as an empty string C<\"\">.
- =item C<app_description>
- A longer description of the application or package.
- If unavailable this is returned as an empty string C<\"\">.
- =back
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_hostname";
- style = RString "hostname", [Device "root"], [];
- shortdesc = "get hostname of the operating system";
- longdesc = "\
- This function returns the hostname of the operating system
- as found by inspection of the guest's configuration files.
- If the hostname could not be determined, then the
- string C<unknown> is returned.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_get_format";
- style = RString "format", [Device "root"], [];
- shortdesc = "get format of inspected operating system";
- longdesc = "\
- This returns the format of the inspected operating system. You
- can use it to detect install images, live CDs and similar.
- Currently defined formats are:
- =over 4
- =item \"installed\"
- This is an installed operating system.
- =item \"installer\"
- The disk image being inspected is not an installed operating system,
- but a I<bootable> install disk, live CD, or similar.
- =item \"unknown\"
- The format of this disk image is not known.
- =back
- Future versions of libguestfs may return other strings here.
- The caller should be prepared to handle any string.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_is_live";
- style = RBool "live", [Device "root"], [];
- shortdesc = "get live flag for install disk";
- longdesc = "\
- If C<guestfs_inspect_get_format> returns C<installer> (this
- is an install disk), then this returns true if a live image
- was detected on the disk.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_is_netinst";
- style = RBool "netinst", [Device "root"], [];
- shortdesc = "get netinst (network installer) flag for install disk";
- longdesc = "\
- If C<guestfs_inspect_get_format> returns C<installer> (this
- is an install disk), then this returns true if the disk is
- a network installer, ie. not a self-contained install CD but
- one which is likely to require network access to complete
- the install.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "inspect_is_multipart";
- style = RBool "multipart", [Device "root"], [];
- shortdesc = "get multipart flag for install disk";
- longdesc = "\
- If C<guestfs_inspect_get_format> returns C<installer> (this
- is an install disk), then this returns true if the disk is
- part of a set.
- Please read L<guestfs(3)/INSPECTION> for more details." };
- { defaults with
- name = "set_attach_method";
- style = RErr, [String "attachmethod"], [];
- fish_alias = ["attach-method"]; config_only = true;
- shortdesc = "set the attach method";
- longdesc = "\
- Set the method that libguestfs uses to connect to the back end
- guestfsd daemon. Possible methods are:
- =over 4
- =item C<appliance>
- Launch an appliance and connect to it. This is the ordinary method
- and the default.
- =item C<unix:I<path>>
- Connect to the Unix domain socket I<path>.
- This method lets you connect to an existing daemon or (using
- virtio-serial) to a live guest. For more information, see
- L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
- =back" };
- { def…
Large files files are truncated, but you can click here to view the full file