NAME¶
guestfs-ocaml - How to use libguestfs from OCaml
SYNOPSIS¶
Module style:
let g = Guestfs.create () in
Guestfs.add_drive_opts g ~format:"raw" ~readonly:true "disk.img";
Guestfs.launch g;
Object-oriented style:
let g = new Guestfs.guestfs () in
g#add_drive_opts ~format:"raw" ~readonly:true "disk.img";
g#launch ();
ocamlfind opt prog.ml -package guestfs -linkpkg -o prog
or:
ocamlopt -I +guestfs mlguestfs.cmxa prog.ml -o prog
DESCRIPTION¶
This manual page documents how to call libguestfs from the OCaml programming
language. This page just documents the differences from the C API and gives
some examples. If you are not familiar with using libguestfs, you also need to
read
guestfs(3).
PROGRAMMING STYLES¶
There are two different programming styles supported by the OCaml bindings. You
can use a module style, with each C function mapped to an OCaml function:
int guestfs_set_verbose (guestfs_h *g, int flag);
becomes:
val Guestfs.set_verbose : Guestfs.t -> bool -> unit
Alternately you can use an object-oriented style, calling methods on the class
"Guestfs.guestfs":
method set_verbose : bool -> unit
The object-oriented style is usually briefer, and the minor performance penalty
isn't noticeable in the general overhead of performing libguestfs functions.
CLOSING THE HANDLE¶
The handle is closed when it is reaped by the garbage collector. Because
libguestfs handles include a lot of state, it is also possible to close (and
hence free) them explicitly by calling "Guestfs.close" or the
"#close" method.
EXCEPTIONS¶
Errors from libguestfs functions are mapped into the "Guestfs.Error"
exception. This has a single parameter which is the error message (a string).
Calling any function/method on a closed handle raises
"Guestfs.Handle_closed". The single parameter is the name of the
function that you called.
EXAMPLE 1: CREATE A DISK IMAGE¶
(* Example showing how to create a disk image. *)
open Unix
open Printf
let output = "disk.img"
let () =
let g = new Guestfs.guestfs () in
(* Create a raw-format sparse disk image, 512 MB in size. *)
let fd = openfile output [O_WRONLY;O_CREAT;O_TRUNC;O_NOCTTY] 0o666 in
ftruncate fd (512 * 1024 * 1024);
close fd;
(* Set the trace flag so that we can see each libguestfs call. *)
g#set_trace true;
(* Set the autosync flag so that the disk will be synchronized
* automatically when the libguestfs handle is closed.
*)
g#set_autosync true;
(* Attach the disk image to libguestfs. *)
g#add_drive_opts ~format:"raw" ~readonly:false output;
(* Run the libguestfs back-end. *)
g#launch ();
(* Get the list of devices. Because we only added one drive
* above, we expect that this list should contain a single
* element.
*)
let devices = g#list_devices () in
if Array.length devices <> 1 then
failwith "error: expected a single device from list-devices";
(* Partition the disk as one single MBR partition. *)
g#part_disk devices.(0) "mbr";
(* Get the list of partitions. We expect a single element, which
* is the partition we have just created.
*)
let partitions = g#list_partitions () in
if Array.length partitions <> 1 then
failwith "error: expected a single partition from list-partitions";
(* Create a filesystem on the partition. *)
g#mkfs "ext4" partitions.(0);
(* Now mount the filesystem so that we can add files. *)
g#mount_options "" partitions.(0) "/";
(* Create some files and directories. *)
g#touch "/empty";
let message = "Hello, world\n" in
g#write "/hello" message;
g#mkdir "/foo";
(* This one uploads the local file /etc/resolv.conf into
* the disk image.
*)
g#upload "/etc/resolv.conf" "/foo/resolv.conf";
(* Because 'autosync' was set (above) we can just close the handle
* and the disk contents will be synchronized. You can also do
* this manually by calling g#umount_all and g#sync.
*
* Note also that handles are automatically closed if they are
* reaped by the garbage collector. You only need to call close
* if you want to close the handle right away.
*)
g#close ()
EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE¶
(* Example showing how to inspect a virtual machine disk. *)
open Printf
let disk =
if Array.length Sys.argv = 2 then
Sys.argv.(1)
else
failwith "usage: inspect_vm disk.img"
let () =
let g = new Guestfs.guestfs () in
(* Attach the disk image read-only to libguestfs. *)
g#add_drive_opts (*~format:"raw"*) ~readonly:true disk;
(* Run the libguestfs back-end. *)
g#launch ();
(* Ask libguestfs to inspect for operating systems. *)
let roots = g#inspect_os () in
if Array.length roots = 0 then
failwith "inspect_vm: no operating systems found";
Array.iter (
fun root ->
printf "Root device: %s\n" root;
(* Print basic information about the operating system. *)
printf " Product name: %s\n" (g#inspect_get_product_name root);
printf " Version: %d.%d\n"
(g#inspect_get_major_version root)
(g#inspect_get_minor_version root);
printf " Type: %s\n" (g#inspect_get_type root);
printf " Distro: %s\n" (g#inspect_get_distro root);
(* Mount up the disks, like guestfish -i.
*
* Sort keys by length, shortest first, so that we end up
* mounting the filesystems in the correct order.
*)
let mps = g#inspect_get_mountpoints root in
let cmp (a,_) (b,_) =
compare (String.length a) (String.length b) in
let mps = List.sort cmp mps in
List.iter (
fun (mp, dev) ->
try g#mount_ro dev mp
with Guestfs.Error msg -> eprintf "%s (ignored)\n" msg
) mps;
(* If /etc/issue.net file exists, print up to 3 lines. *)
let filename = "/etc/issue.net" in
if g#is_file filename then (
printf "--- %s ---\n" filename;
let lines = g#head_n 3 filename in
Array.iter print_endline lines
);
(* Unmount everything. *)
g#umount_all ()
) roots
SEE ALSO¶
guestfs(3),
guestfs-examples(3),
guestfs-erlang(3),
guestfs-java(3),
guestfs-perl(3),
guestfs-python(3),
guestfs-recipes(1),
guestfs-ruby(3),
<
http://libguestfs.org/>, <
http://caml.inria.fr/>.
AUTHORS¶
Richard W.M. Jones ("rjones at redhat dot com")
COPYRIGHT¶
Copyright (C) 2010 Red Hat Inc. <
http://libguestfs.org/>
The examples in this manual page may be freely copied, modified and distributed
without any restrictions.
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This library 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 Lesser General Public License for more
details.
You should have received a copy of the GNU Lesser General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
