A native Resource Abstraction Layer
Libral is a systems management library that makes it possible to query and modify system resources (files, packages, services, etc.) through a desired-state API. Its goals are to:
libral
in
resource-constrained environments such as devices or containersirc.freenode.net:#libral
If you just want to quickly try out libral
, you can download a
precompiled tarball
(GPG signature)
that should work on any Linux machine that has glibc 2.12 or later. (It
might actually work with glibc 2.8 or later.) If you succeed in that, please
let us know.
We have reports of the precompiled binaries working on 64-bit Fedora 21-25, RHEL 5-7 (and related distributions like CentOS), Debian 6-9, Ubuntu 10.04-16.10, and SLES 11-12. The binaries will not work on 32-bit and pre-glibc 2.8 systems: RHEL 4, SLES 10, ...
In case you do need to build from source, which is not required for
provider development, only if you want to work on the core libral library,
this document contains instructions on building libral
.
You can also try out libral
in the context of a Docker container. The
Dockerfile in the repository allows for building an image quickly based
on the above mentioned precompiled tarball.
docker build -t puppet/libral .
Running this can then be done with Docker, for instance the following
invocation will launch ralsh
in the context of the container.
docker run --rm -t puppet/libral
This is intended for exploring the CLI and experimenting with providers.
After you build libral
, or after you download and unpack the
precompiled tarball,
you can try things out by running ralsh
:
# If you downloaded the precompiled tarball
alias ralsh=$TARBALL_LOCATION/ral/bin/ralsh
# Only if you built libral from source
export RALSH_DATA_DIR=$LIBRAL_CHECKOUT/data
alias ralsh=$LIBRAL_CHECKOUT/bin/ralsh
# list available types
ralsh
# list all instances of a type
ralsh mount
# list a specific instance
ralsh service crond
# make a change for the better
ralsh service crond ensure=stopped
# Do the same against a remote system to which you have ssh access
ralsh -t ahost
ralsh -t ahost package sudo
The default output from ralsh
is meant for human consumption and looks a
lot like Puppet. It is also possible to have ralsh
produce
JSON output by passing the --json
flag.
Many of the providers that libral
knows about are separate
scripts. ralsh
searches them in the following order. In each case, the
providers must be executable scripts in a subdirectory providers
in the
mentioned directory ending in .prov
:
RALSH_DATA_DIR
is set, look in the
directory this variable is set to--include
option to ralsh
is given, look in that directory
(the option can be given multiple times)/usr/share/libral/data
The
precompiled tarball
contains a statically linked ralsh
and all supporting files. After
unpacking the tarball, you can copy it into a container and run it like
this:
CONTAINER=<some_container>
docker cp $TARBALL_LOCATION/ral $CONTAINER:/tmp
docker exec $CONTAINER /bin/sh -c /tmp/ral/bin/ralsh
docker exec $CONTAINER /bin/sh -c '/tmp/ral/bin/ralsh user root'
What resources libral
can manage is determined by what providers are
available. Some providers are built in and implemented in C++, but doing
that is of course labor intensive and should only be done for good
reason. It is much simpler, and recommended, that new providers first be
implemented as external providers. External providers are nothing more than
scripts or other executables that follow one of libral
's calling
conventions. The different calling conventions trade off implementation
complexity for expressive power.
The following calling conventions are available. If you are just getting
started with libral
, you should write your first providers using the
simple
or json
calling convention:
json_batch
(planned,maybe): input/output via JSON, can operate on multiple resources at onceFor all of these, you will also want to read up on the metadata that each provider needs to produce to describe itself.
To start a new provider, follow these steps:
DIR
, run mkdir $DIR/providers
, and$DIR/providers/myprovider.prov
and make it executablemyprovider.prov ral_action=describe
returns
valid provider metadata, especially a valid type. For
now it doesn't matter what the type is, let's call it MYTYPE
ralsh -I $DIR $MYTYPE
. This will ask the provider to list all
instances of the type using the list
action. Get that workingralsh -I $DIR $MYTYPE NAME
. This will ask the provider to find a
resource with name NAME
using the find
action. Get that working,
too.ralsh -I $DIR $MYTYPE NAME ATTR=VALUE...
. This will ask the
provider to update the resource NAME
using the update
action.Naming things is hard; here's the terms libral uses:
user*
commands, or how to manage mounts on LinuxFIXME: we need some conventions around some special resource properties; especially, namevar should always be 'name' and the primary key for all resources from this provider, and 'ensure' should have a special meaning (or should it?)