The goal of erlxc is to be a simple, safe interface to Linux containers from Erlang.
Status:
-
the liblxc binding is mostly stable
-
the erlxc module is unstable
erlxc currently requires using liblxc 1.0.0:
git clone https://github.com/lxc/lxc.git
cd lxc
./autogen.sh && ./configure && make && sudo make install
You may need to adjust the LXC defaults, for example, to match the bridge device on your system.
vi /usr/local/etc/lxc/default.conf
Set these environment variables to indicate the path to the liblxc install and build:
export ERLXC_LDFLAGS="-L /usr/local/lib"
export ERLXC_CFLAGS="-I /usr/local/include"
git clone https://github.com/msantos/erlxc.git
cd erlxc
make
The erlxc port will require the appropriate permissions to run. This
can be handled by making the port executable setuid, adding the right
file capabilities or by using sudo.
$ visudo -f /etc/sudoers.d/99_lxc
username ALL = NOPASSWD: /path/to/erlxc/priv/erlxc
erlxc is being tested on Ubuntu 12.04/x86_64 and Ubuntu 13.04/arm (beaglebone black).
The high level API models the container as an Erlang process.
spawn(Name) -> Container
spawn(Name, Options) -> Container
Types Container = container()
Name = <<>> | binary()
Options = [
{path, iodata()} |
{verbose, non_neg_integer()} |
{config, [
<<>> |
{load, file:filename_all()} |
{Key, Value} |
Key
]} |
{cgroup, [{Key, Value}]} |
{chroot, [
{dir, [DirSpec]} |
{copy, [CopySpec]} |
{file, [FileSpec]}
]} |
{create, [
{template, iodata()} |
{bdevtype, iodata()} |
{bdevspec, iodata()} |
{flags, non_neg_integer()} |
{argv, [iodata()]}
]} |
{start, [
{useinit, true | false | 0 | 1} |
{argv, list(iodata())}
]} |
temporary | transient | temporary
]
Key = iodata()
Value = iodata()
DirSpec = file:filename_all()
| {file:filename_all(), FileMode}
FileSpec = {file:filename_all(), FileContent}
| {file:filename_all(), FileContent, FileMode}
CopySpec = {file:filename_all(), file:filename_all()}
| {file:filename_all(), file:filename_all(), FileMode}
FileMode = file:file_info() | integer() | 'undefined'
FileContent = iodata()
Spawn a container. If an empty binary is specified as the name,
erlxc will generate a random name.
exit(Container, Reason) -> true
Types Container = container()
Reason = normal | kill
Halt the container. Note: by default, the container is linked
to the creating process. If the process crashes, so will the
container.
send(Container, Data) -> true
Types Container = container()
Data = iodata()
Send data to the container's console.
type(Container) -> Type
type(Container, Type) -> boolean()
Types Container = container()
Type = temporary | transient | permanent
Get or set the container type. The "type" abuses supervisor
terminology to describe the behaviour of the container when the
owning process exits:
* temporary
The container is shutdown and the container filesystem
is deleted.
Unnamed containers (containers spawned using <<>>) are
temporary by default.
* transient
The container is shutdown when the linked process exits.
Named containers are transient by default.
* permanent
The container continues running if the owning process exits.
container(Container) -> port()
Types Container = container()
Retrieve the port for the container for use with the liblxc module.
console(Container) -> port()
Types Container = container()
Retrieve the port for the console.
- tcpvm
This code listens on a TCP port and spawns an Ubuntu system when a client connects.
In a shell:
$ ./start.sh
% If you're bridge is something other than lxcbr0
> tcpvm:start([{config, [{"lxc.network.link", "br0"}]}]).
And in another shell:
nc localhost 31337
Or if you have socat installed, start a session with job control:
socat `tty`,raw,echo=0 tcp:localhost:31337
-module(tcpvm).
-include_lib("erlxc/include/erlxc.hrl").
-export([start/0, start/1]).
start() ->
start([]).
start(Options) ->
Port = proplists:get_value(port, Options, 31337),
{ok, LSock} = gen_tcp:listen(Port, [binary,{active,false},{reuseaddr,true}]),
accept(LSock, Options).
accept(LSock, Options) ->
{ok, Socket} = gen_tcp:accept(LSock),
Pid = spawn(fun() -> create(Socket, Options) end),
ok = gen_tcp:controlling_process(Socket, Pid),
accept(LSock, Options).
create(Socket, Options) ->
Container = erlxc:spawn(<<>>, Options),
shell(Socket, Container).
shell(Socket, #container{console = Console} = Container) ->
inet:setopts(Socket, [{active, once}]),
receive
{tcp, Socket, Data} ->
erlxc:send(Container, Data),
shell(Socket, Container);
{tcp_closed, Socket} ->
error_logger:error_report([{socket, closed}]),
ok;
{tcp_error, Socket, Error} ->
error_logger:error_report([{socket, Error}]),
ok;
{Console, {data, Data}} ->
ok = gen_tcp:send(Socket, Data),
shell(Socket, Container)
end.- imc: run a command inside an "immutable" container
imc makes a chroot, does a read-only bind mount of system directories
and mounts writable directories as tmpfs before running the specified
command as a random, unprivileged user.
By default, a distributed erlang node is run. To start the node, compile the example:
make eg
Then run a node:
./start.sh
% node name will be: imc@192.168.123.45
1> Container = imc:spawn("192.168.123.45").Start up another distributed erlang node and connect:
% Assuming 192.168.123.10 is the IP address of your client
erl -name c@192.168.123.10 -setcookie COOKIE
^G
(c@192.168.123.10)1>
User switch command
--> r 'imc@192.168.123.45'
--> c
Eshell V5.8.5 (abort with ^G)
(imc@192.168.123.45)1>
Any command can be run with these caveats:
-
currently stdout/stderr is discarded
-
if the command is expecting stdin, unexpected things can happen
-
the command must run in the foreground
-
the console does not work so the only way to communicate with the container is over the network (unless there is shared resource like a writeable host directory bind mounted inside the container)
For example, to run a shell inside the container listening on port 2222 with cgroup enforcement disabled:
% <<>> : choose a random name
Container = imc:spawn(
<<>>,
"192.168.123.45",
[
{cgroup, []},
{cmd, "/usr/bin/mkfifo /tmp/sh; /bin/cat /tmp/sh | /bin/bash -i 2>&1 | /bin/nc -l 2222 > /tmp/sh"}
]).The low level API mirrors the liblxc API;
http://qa.linuxcontainers.org/master/current/doc/api/lxccontainer_8h.html
The intent is to create an interface that is more flexible and reliable than shelling out to the lxc commands.
NULL values are represented by the empty binary (<<>>).
list_active_containers(Container, Path) -> List
list_all_containers(Container, Path) -> List
list_defined_containers(Container, Path) -> List
Types Container = pid()
Path = iodata()
List = [binary()]
List the containers in Path (<<>> uses the default path).
clear_config(Container) -> true | false
Types Container = pid()
Empty the container LXC configuration.
clear_config_item(Container, Item) -> true | false
Types Container = pid()
Item = iodata()
Erase Item from the container's configuration.
config_file_name(Container) -> Filename
Types Container = pid()
Filename = binary()
Returns the configuration file for the container.
create(Container, Template, Bdevtype, Bdevspec, Flags, Argv) -> true | false
Types Container = pid()
Template = iodata()
Bdevtype = iodata()
Bdevspec = iodata()
Flags = integer()
Argv = [binary()]
Create a container using the specified LXC template script. Use
<<>> to specify the default backing store ("dir").
An example of creating an Ubuntu container:
{ok, Container} = erlxc_drv:start(<<"testprecise">>),
true = liblxc:create(
Container,
<<"ubuntu">>,
<<>>,
<<>>,
0,
[<<"-r">>, <<"precise">>]
).
defined(Container) -> true | false
Types Container = pid()
Describes whether the container is defined or not.
destroy(Container) -> true | false
Types Container = pid()
Removes all resources associated with the container, including
deleting the container filesystem.
get_config_item(Container, Item) -> binary() | 'false'.
Types Container = pid()
Item = iodata()
Returns the configuration value of the key specified in Item.
get_config_path(Container) -> binary().
Types Container = pid()
Returns the configuration path for the container.
get_keys(Container, Key) -> binary().
Types Container = pid()
Key = iodata()
Retrieves the list of keys from the LXC configuration. A subkey
can be specified or <<>> to retrieve all keys.
The keys are returned as a single binary, with individual keys
separated by '\n'. Use binary:split/3 to convert to a list of keys:
Keys = liblxc:get_keys(Container, <<>>),
binary:split(Keys, <<"\n">>, [global,trim]).
init_pid(Container) -> integer().
Types Container = pid()
Retrieve the PID of the container's init process.
load_config(Container, Path) -> true | false
Types Container = pid()
Path = iodata()
Load the container's configuration. An optional path can be
specified (<<>> to use the default path).
name(Container) -> binary().
Types Container = pid()
Retrieve the container's name.
running(Container) -> true | false
Types Container = pid()
Return the status of the container.
save_config(Container, Path) -> true | false
Types Container = pid()
Save the container configuration to an alternate path.
set_config_item(Container, Key, Val) -> true | false
Types Container = pid()
Key = Val = iodata()
Set the configuration key to the specified value.
set_config_path(Container, Path) -> true | false
Types Container = pid()
Path = iodata()
Set the configuration path to the specified value.
shutdown(Container, Timeout) -> true | false
Types Container = pid()
Timeout = non_neg_integer()
Halt the container by sending a SIGPWR to the container init process.
start(Container, UseInit, Argv) -> {ok, non_neg_integer()} | {error, file:posix()}
Types Container = pid()
UseInit = 0 | 1
Argv = [binary()]
Boot the container. Returns the system PID of the container process.
state(Container) -> binary()
Types Container = pid()
Retrieves the current state of the container.
stop(Container) -> true | false
Types Container = pid()
Halts the container.
wait(Container, State, Timeout) -> true | false
Types Container = pid()
State = iodata()
Timeout = non_neg_integer()
Blocks until the container state equals the value specified in
State. Set Timeout to 0 to return immediately.
- Create an Ubuntu 12.04 container
-module(lxc).
-export([
define/1, define/2,
create/1,
start/1,
shutdown/1,
destroy/1
]).
define(Name) ->
define(Name, <<"lxcbr0">>).
define(Name, Bridge) ->
Container = erlxc_drv:start(Name),
liblxc:set_config_item(Container, <<"lxc.network.type">>, <<"veth">>),
liblxc:set_config_item(Container, <<"lxc.network.link">>, Bridge),
liblxc:set_config_item(Container, <<"lxc.network.flags">>, <<"up">>),
Container.
create(Container) ->
liblxc:create(Container, <<"ubuntu">>, <<>>, <<>>, 0, [<<"-r">>, <<"precise">>]).
start(Container) ->
liblxc:start(Container, 0, []).
shutdown(Container) ->
liblxc:shutdown(Container, 0).
destroy(Container) ->
liblxc:destroy(Container).There are a few options that can be passed to the lxc driver for debugging:
-
nodaemonize : run the container in the foreground
This option will allow you to see the error messages that are redirected to /dev/null after liblxc daemonizes.
-
nocloseallfds : valgrind reserves some file descriptors for its use. This option ensures liblxc doesn't close them.
To run erlxc under valgrind:
Container = erlxc:spawn("foo", [{exec, "sudo valgrind --leak-check=yes --log-file=/tmp/lxc.log"}, nocloseallfds]).
% Or
Port = erlxc_drv:start("foo", [{exec, "sudo valgrind --leak-check=yes --log-file=/tmp/lxc.log"}, nocloseallfds]).- verx provides an interface to libvirt, which has support for Linux containers
https://github.com/msantos/verx
- islet is a high level interface for Linux containers using libvirt
https://github.com/msantos/islet
-
generate C/Erlang bindings from typespecs
-
generate liblxc documentation
-
port to Ubuntu 12.04 (liblxc 0.7.5)