guestfs-erlang - How to use libguestfs from Erlang
{ok, G} = guestfs:create(),
ok = guestfs:add_drive_opts(G, Disk,
[{format, "raw"}, {readonly, true}]),
ok = guestfs:launch(G),
[Device] = guestfs:list_devices(G),
ok = guestfs:close(G).
This manual page documents how to call libguestfs from the Erlang 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).
The Erlang bindings are implemented using an external program called
erl-guestfs. This program must be on the current PATH, or else you
should specify the full path to the program:
{ok, G} = guestfs:create().
{ok, G} = guestfs:create("/path/to/erl-guestfs").
G is the libguestfs handle which you should pass to other
functions.
To close the handle:
ok = guestfs:close(G).
For functions that take optional arguments, the first arguments are the non-optional ones. The last argument is a list of tuples supplying the remaining optional arguments.
ok = guestfs:add_drive_opts(G, Disk,
[{format, "raw"}, {readonly, true}]).
If the last argument would be an empty list, you can also omit it:
ok = guestfs:add_drive_opts(G, Disk).
On success, most functions return a Result term (which could be a
list, string, tuple etc.). If there is nothing for the function to
return, then the atom ok is returned.
On error, you would see one of the following tuples:
{error, Msg, Errno}This indicates an ordinary error from the function.
Msg is the error message (string) and Errno is the Unix error
(integer).
Errno can be zero. See guestfs(3)/guestfs_last_errno.
{unknown, Function}This indicates that the function you called is not known. Generally
this means you are mixing erl-guestfs from another version of
libguestfs, which you should not do.
Function is the name of the unknown function.
{unknownarg, Arg}This indicates that you called a function with optional arguments, with an unknown argument name.
Arg is the name of the unknown argument.
#!/usr/bin/env escript
%%! -smp enable -sname create_disk debug verbose
% Example showing how to create a disk image.
main(_) ->
Output = "disk.img",
{ok, G} = guestfs:create(),
% Create a raw-format sparse disk image, 512 MB in size.
{ok, File} = file:open(Output, [raw, write, binary]),
{ok, _} = file:position(File, 512 * 1024 * 1024 - 1),
ok = file:write(File, " "),
ok = file:close(File),
% Set the trace flag so that we can see each libguestfs call.
ok = guestfs:set_trace(G, true),
% Set the autosync flag so that the disk will be synchronized
% automatically when the libguestfs handle is closed.
ok = guestfs:set_autosync(G, true),
% Attach the disk image to libguestfs.
ok = guestfs:add_drive_opts(G, Output,
[{format, "raw"}, {readonly, false}]),
% Run the libguestfs back-end.
ok = guestfs:launch(G),
% Get the list of devices. Because we only added one drive
% above, we expect that this list should contain a single
% element.
[Device] = guestfs:list_devices(G),
% Partition the disk as one single MBR partition.
ok = guestfs:part_disk(G, Device, "mbr"),
% Get the list of partitions. We expect a single element, which
% is the partition we have just created.
[Partition] = guestfs:list_partitions(G),
% Create a filesystem on the partition.
ok = guestfs:mkfs(G, "ext4", Partition),
% Now mount the filesystem so that we can add files. *)
ok = guestfs:mount_options(G, "", Partition, "/"),
% Create some files and directories. *)
ok = guestfs:touch(G, "/empty"),
Message = "Hello, world\n",
ok = guestfs:write(G, "/hello", Message),
ok = guestfs:mkdir(G, "/foo"),
% This one uploads the local file /etc/resolv.conf into
% the disk image.
ok = guestfs:upload(G, "/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 guestfs:umount_all and guestfs: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.
ok = guestfs:close(G).
#!/usr/bin/env escript
%%! -smp enable -sname inspect_vm debug verbose
% Example showing how to inspect a virtual machine disk.
main([Disk]) ->
{ok, G} = guestfs:create(),
% Attach the disk image read-only to libguestfs.
ok = guestfs:add_drive_opts(G, Disk, [{readonly, true}]),
% Run the libguestfs back-end.
ok = guestfs:launch(G),
% Ask libguestfs to inspect for operating systems.
case guestfs:inspect_os(G) of
[] ->
io:fwrite("inspect_vm: no operating systems found~n"),
exit(no_operating_system);
Roots ->
list_os(G, Roots)
end.
list_os(_, []) ->
ok;
list_os(G, [Root|Roots]) ->
io:fwrite("Root device: ~s~n", [Root]),
% Print basic information about the operating system.
Product_name = guestfs:inspect_get_product_name(G, Root),
io:fwrite(" Product name: ~s~n", [Product_name]),
Major = guestfs:inspect_get_major_version(G, Root),
Minor = guestfs:inspect_get_minor_version(G, Root),
io:fwrite(" Version: ~w.~w~n", [Major, Minor]),
Type = guestfs:inspect_get_type(G, Root),
io:fwrite(" Type: ~s~n", [Type]),
Distro = guestfs:inspect_get_distro(G, Root),
io:fwrite(" Distro: ~s~n", [Distro]),
% Mount up the disks, like guestfish -i.
Mps = sort_mps(guestfs:inspect_get_mountpoints(G, Root)),
mount_mps(G, Mps),
% If /etc/issue.net file exists, print up to 3 lines. *)
Filename = "/etc/issue.net",
Is_file = guestfs:is_file(G, Filename),
if Is_file ->
io:fwrite("--- ~s ---~n", [Filename]),
Lines = guestfs:head_n(G, 3, Filename),
write_lines(Lines);
true -> ok
end,
% Unmount everything.
ok = guestfs:umount_all(G),
list_os(G, Roots).
% Sort keys by length, shortest first, so that we end up
% mounting the filesystems in the correct order.
sort_mps(Mps) ->
Cmp = fun ({A,_}, {B,_}) ->
length(A) =< length(B) end,
lists:sort(Cmp, Mps).
mount_mps(_, []) ->
ok;
mount_mps(G, [{Mp, Dev}|Mps]) ->
case guestfs:mount_ro(G, Dev, Mp) of
ok -> ok;
{ error, Msg, _ } ->
io:fwrite("~s (ignored)~n", [Msg])
end,
mount_mps(G, Mps).
write_lines([]) ->
ok;
write_lines([Line|Lines]) ->
io:fwrite("~s~n", [Line]),
write_lines(Lines).
guestfs(3), guestfs-examples(3), guestfs-java(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3), guestfs-recipes(1), guestfs-ruby(3), http://www.erlang.org/. http://libguestfs.org/.
Richard W.M. Jones (rjones at redhat dot com)
Copyright (C) 2011 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