b9: A tool and library for building virtual machine images.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Build virtual machine images for vm-deployments; resize, un-partition, create from scratch or convert disk image files in a variety of formats; assemble and generate all associated files from templates and regular files. VM images can further be modifed through scripts, which are executed in LXC containers into which the vm-images as well as arbitrary directories from the host are mounted. All assembled files can also be accessed by vm build scripts through a special directory mounted in the build container, and/or can be written to directories, ISO- or VFAT-images. The ISO/VFAT images that B9 creates are compatible to 'cloud-init's NoCloud data source; B9 is also very well suited for compiling in a containerized environment. For these applications, the images can be marked as Transient to indicate no further interest in the VM-image itself, and B9 will discard them after the build. B9 will never over-write source files, not even large vm-image files - there is no intended way to modify a source vm-image file 'in-place'. B9 operates in random build directories, which are discarded when the build exists.


[Skip to Readme]

Properties

Versions 0.2.0, 0.2.1, 0.2.3, 0.2.4, 0.2.5, 0.3.0, 0.3.1, 0.4.0, 0.4.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.7, 0.5.8, 0.5.9, 0.5.10, 0.5.13, 0.5.14, 0.5.15, 0.5.16, 0.5.17, 0.5.18, 0.5.19, 0.5.20, 0.5.21, 0.5.30, 0.5.31, 0.5.32, 0.5.34, 0.5.35, 0.5.41, 0.5.42, 0.5.43, 0.5.44, 0.5.46, 0.5.47, 0.5.48, 0.5.49, 0.5.50, 0.5.51, 0.5.52, 0.5.60, 0.5.61, 0.5.62, 0.5.63, 0.5.65, 0.5.66, 0.5.67, 0.5.68, 0.5.68.1, 0.5.68.2, 0.5.68.3, 0.5.68.4, 0.5.69.0, 1.0.0, 1.0.1, 1.0.1, 1.1.0, 1.1.1, 2.0.0, 2.1.0, 3.1.0, 3.2.0, 3.2.3
Change log CHANGELOG.md
Dependencies aeson (>=1.0), async (>=2.1), b9, base (>=4.12 && <5), base64-bytestring, bifunctors (>=5.4), binary (>=0.8.3), boxes (>=0.1.4), bytestring (>=0.10.8), conduit (>=1.2), conduit-extra (>=1.1), ConfigFile (>=1.1.4), directory (>=1.3), exceptions (>=0.10), extensible-effects (>=5 && <6), filepath (>=1.4), free (>=4.12), hashable (>=1.2), hspec, hspec-expectations, lens (>=4), monad-control (>=1.0 && <1.1), mtl (>=2.2), optparse-applicative (>=0.14), parallel (>=3.2), parsec (>=3.1), pretty (>=1.1), pretty-show (>=1.6), process (>=1.4), QuickCheck (>=2.5), random (>=1.1), shake (>=0.17.6 && <0.19), syb (>=0.6), tagged (>=0.8 && <0.9), template (>=0.2), text (>=1.2), time (>=1.6), transformers (>=0.5), unordered-containers (>=0.2.8), vector (>=0.11), yaml (>=0.8) [details]
License MIT
Copyright 2015, 2016, 2017, 2018, 2019, 2020 Sven Heyll <svh@posteo.de>
Author Sven Heyll <svh@posteo.de>
Maintainer svh@posteo.de
Category Development
Home page https://github.com/sheyll/b9-vm-image-builder
Bug tracker https://github.com/sheyll/b9-vm-image-builder/issues
Source repo head: git clone git://github.com/sheyll/b9-vm-image-builder.git
Uploaded by SvenHeyll at 2020-06-29T02:52:51Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for b9-1.0.1

[back to package description]

B9 - A Benign VM-Build Tool changelog

Build Status Hackage

NOTE: The feature list is not completely implemented yet!

When version 2 is released of b9, all features listed here can be expected to work.

Quick-Start

Mission Statement

B9 is an executable and a Haskell library, that consumes a Haskell term describing the generation of VM-Images.

A few core data types form an EDSL, and B9 contains functions to read and show then.

Such a term can then be stored into a text file and is interpreted by a command line invokation.

Installation

Installation on NixOS

Runtime dependencies

To be able to use B9 install:

LibVirtLXC support

B9 has been tested with libvirt version 1.2.12.

Make sure that all neccessary daemons, e.g. libvirtd.service, lxc.service,.. are active, that SELinux is configured correctly and that the nbd kernel module is loaded.

If neccessary create a libvirt network configuration, e.g. by using the GUI front-endvirt-manager.

Depending upon the libvirt and lxc configuration of the system it might be nessary to allow the user, that will execute b9c, password-less sudo for these commands:

For SystemdNspawn support

For Podman support (TODO)

For Docker support (TODO)

After installing B9 (either from a binary package or by building from source) all its glory is availbe through a single executable called b9c.

When b9c is started for the first time, it creates a configuration file in the users home directory called ~/.b9/b9.conf. The path to that file can be changed using command line arguments. Execute:

b9c -h

for a list of command line parameters and commands.

b9c command line arguments always follow this pattern:

b9c <global-options> <command> <command-options> -- <build-script-extra-args>

To enable B9 to work correctly on your machine edit the config file and make necessary adaptions.

General Overview

Use B9 to compile your software into a deployable set of Linux-VM- or configuration images, from a set of scripts and input files and templates.

The main goal of this tool is to provide a build tool to increase automation and reduce redundancy when creating configured, ready-to-run VM-images.

One big thing is that it can produce many machines and cloud-configs from a single build file, because build files can describe concrete as well as parameterized generators. It can create parameterized VM-Images by uploading (e.g. system-)files assembled by syntax aware template application and combination, all statically checked by during the build.

This sets B9 apart from e.g. cloud-init or other configuration management systems that provide configuration through user provided dynamic script-programs, which rely on the user to contain correct error handling.

The general idea is the same as in statically type programming languages: catch errors as early as possible without relying on the user to create a covering set of tests/error checks.

Certain sacrifies were made; there might be a steep laerning curve, but you will eventually get there. The tool at hand works stable and reliable.

All builds happen in isolation, i.e. by default in random build directories, and are cleaned on failure.

Also, B9 does not modify cached images. Work on VM-Images is always done on a copy of an image, and to speed things up, it is possible to explicitly use copy-on-write images.

B9 creates bootable virtual machine images, without necessarily using virtualization itself.

In essence B9 is a tool for creation, configuration and sharing of VM images and all peripheral artifacts, it creates:

Make VM Disk Images

Manage Disk Images

Assemble Cloud-init Configuration

Input files

The input files can be in:

Usage as Library

Configuration

B9 uses a .ini - style configuration file.

Incremental Builds

B9 uses shake so some degree of incremental build is available.

B9 build files

If you really need to write these file, you are basically f'ed.

For now, look at existing config files and read the sources, if anything, make sure to read at least the chapter Anger-Management before throwing stuff around.

More documentation is comming soon!

General Structure

A B9 configuration describes a single ArtifactGenerator. It generates files belonging to a VM, such as qcow2/raw/vmdk-image file(s) and e.g. cloud-init ISO image files.

Just to recap: a something.b9 build file is always ever only a mere ArtifactGenerator literal, no matter how many Let, Each, Artifacts, etc... you see flying around there.

Creating artifacts

To get any real artifact out of an artifact generator use the Artifact constructor. It takes 2 parameters an arbitrary id and a describtion of what the artifact consists of:

 Artifact (IID "some_instance_id")
          (VmImages ... | CloudInit ...)

An artifact can either be a (set of) VM-disk-image(s) likely in combination with some shell script to install software, etc or a static collection of files put on a cloud-init image(VFAT or ISO or directory).

Defining artifact generators that produce vm image files

To produce vm image files, e.g. with some software installed use the VmImages artifact generator. It has only 2 parameters:

 VmImages
    [ ... disk image targets ... ]
    ( ... installation script ...)

Of course it must be wrapped in an Artifact definition, so we get this structure:

 Artifact (IID "my_first_image")
   (VmImages [...] (...))
ImageTargets

The first argument to VmImages is a list of ImageTarget. Each describes a single VM-disk-image. The syntax is:

ImageTarget
  ImageDestination
  ImageSource
  MountPoint

Parameterized artifact generators

B9 supports $varnam variable interpolation in all strings anywhere in an ArtifactGenerator:

Parameters can be defined using Let, Each and special command line arguments.

To pass parameters via the command line, append them after the argument delimiter option -- which ends the list of regular b9c arguments:

b9c -v build -f file1.b9 .. -- arg_1 arg_2 ...

The parameters are bound to ${arg_1}, ${arg_2}, that is variables indicating the corresponding position on the command line.

To define variables using Let, write:

Let [key-value-pairs, ...]
    [artifactgenerators, ...]

All key-value bindings defined in the first list are available in every artifact generator contained in the second list (body).

A key-value binding, e.g. ("hostname", "www.acme.org"), consist of two strings on parens seperated by a , (comma). The left string is the key, and the right string is the value.

This ("webserver", "www.${domainname}") is an example to show that the value may also contain a variable reference. (Of course, only to variabled defined before)

Anger-Management

B9 build files contain a single literal ArtifactGenerator value in Haskell syntax. B9 currently 'parses' the config file without any error checking, so writing config files is VERY frustrating without some tricks:

Trick 1

Start with a working file and run

b9c reformat -f <filename>

after each modification. The reformat command only parses and - hence the name - (re-) formats/pretty-prints the files passed with -f options.

You will immediately know if a modification broke the file.

NOTE: If your build file refers to any ${arg_...} positional arguments pass them to reformat using -- followed by the argument list.

Trick 2

Obtain and build the sources of B9, start an interactive haskell shell with the B9 code loaded and try to paste the contents of the config file to see if ghci accepts it. Use the ghci macros :{ and :} to begin and end a multi-line input and paste the raw contents of the config file in question in between.

$ cabal install
$ cabal repl

... (many lines omitted) ...

*B9> :{
*B9| Artifact (IID "filer")
*B9|   (VmImages [ ImageTarget
*B9|                 (LocalFile (Image "EXPORT/machines/filer/disks/0.vmdk" Vmdk Ext4)
*B9|                             KeepSize)
*B9|                 (From "fedora-20-prod" KeepSize)
*B9|                 (MountPoint "/")
*B9|             , ImageTarget
*B9|                 (LocalFile (Image "EXPORT/machines/filer/disks/1.vmdk" Vmdk Ext4)
*B9|                             KeepSize)
*B9|                 (EmptyImage "audio_files" Ext4 Raw (ImageSize 64 GB))
*B9|                 (MountPoint "/export/lb/audio")
*B9|             ]
*B9|             (VmScript X86_64
*B9|               [ SharedDirectoryRO "./filer" (MountPoint "/mnt/build_root")
*B9|               , SharedDirectoryRO "../_common/upload" (MountPoint "/mnt/common")]
*B9|               (Begin
*B9|                  [ Run "dhclient" []
*B9|                  , In "/mnt/build_root" [ Run "./machine-" [] ]
*B9|                  , In "/mnt/common" [ Run "./post_export.sh" [] ]
*B9|                  ])))
*B9| :}

Artifact (IID "filer") (VmImages
[ImageTarget (LocalFile (Image "EXPORT/machines/filer/disks/0.vmdk" Vmdk Ext4) KeepSize)
(From "fedora-20-prod" KeepSize) (MountPoint "/"),ImageTarget
(LocalFile (Image "EXPORT/machines/filer/disks/1.vmdk" Vmdk Ext4) KeepSize)
(EmptyImage "audio_files" Ext4 Raw (ImageSize 64 GB)) (MountPoint "/export/lb/audio")]
(VmScript X86_64
[SharedDirectoryRO "./filer" (MountPoint "/mnt/build_root"),
SharedDirectoryRO "../_common/upload" (MountPoint "/mnt/common")]
(Begin [Run "dhclient" [],In "/mnt/build_root" [Run "./machine-" []],In
"/mnt/common" [Run "./post_export.sh" []]])))

B9 Config File Reference

This is an example of a B9 configuration file, by default found in ~/.b9/b9.conf and uses the ini-file format.

Some of the options can also be specified on the command line and in environment variables.

A path to an alternative config file can given on the command lines.

When the default config file does not exist, b9c will create it from default values.

This example is the current default configuration:

[global]
build_dir_root: Nothing
keep_temp_dirs: False
log_file: Nothing
max_cached_shared_images: Just 2
repository: Nothing
repository_cache: Just (InB9UserDir "repo-cache")
unique_build_dirs: True
verbosity: Just LogInfo

[libvirt-lxc]
connection: lxc:///
emulator_path: Just "/usr/lib/libvirt/libvirt_lxc"
guest_capabilities: [CAP_MKNOD,CAP_SYS_ADMIN,CAP_SYS_CHROOT,CAP_SETGID,CAP_SETUID,CAP_NET_BIND_SERVICE,CAP_SETPCAP,CAP_SYS_PTRACE,CAP_SYS_MODULE]
guest_ram_size: RamSize 1 GB
network: Nothing
use_sudo: True

[podman]
guest_capabilities: [CAP_MKNOD,CAP_SYS_ADMIN,CAP_SYS_CHROOT,CAP_SETGID,CAP_SETUID,CAP_NET_BIND_SERVICE,CAP_SETPCAP,CAP_SYS_PTRACE,CAP_SYS_MODULE]
network: Nothing

[systemdNspawn]
console: read-only
executable: Nothing
extra_args: Nothing
guest_capabilities: [CAP_MKNOD,CAP_SYS_ADMIN,CAP_SYS_CHROOT,CAP_SETGID,CAP_SETUID,CAP_NET_BIND_SERVICE,CAP_SETPCAP,CAP_SYS_PTRACE,CAP_SYS_MODULE]
max_lifetime_seconds: Just 14400
use_sudo: True

[docker]
guest_capabilities: [CAP_MKNOD,CAP_SYS_ADMIN,CAP_SYS_CHROOT,CAP_SETGID,CAP_SETUID,CAP_NET_BIND_SERVICE,CAP_SETPCAP,CAP_SYS_PTRACE,CAP_SYS_MODULE]
network: Nothing

The [global] Section

build_dir_root:

TODO document this option.

keep_temp_dirs:

TODO document this option.

log_file:

TODO document this option.

max_cached_shared_images:

TODO document this option.

repository:

TODO document this option.

repository_cache:

TODO document this option.

unique_build_dirs:

TODO document this option.

verbosity:

TODO document this option.

The [libvirt-lxc] Section

connection

TODO document this option.

emulator_path

TODO document this option.

guest_capabilities

TODO document this option.

guest_ram_size

TODO document this option.

network

TODO document this option.

use_sudo

TODO document this option.

The [podman] Section

Since: 1.0.0

guest_capabilities

TODO document this option.

network

TODO document this option.

The [systemdNspawn] Section

Since: 1.0.0

console

This corresponds to the --console=<...> parameter to systemd-nspawn.

If the value is set to interactive the execution of any VmScripts through systemd-nspawn will be interactive by using stdin, stdout and stderr of the b9c process.

executable

TODO document this option.

extra_args

TODO document this option.

guest_capabilities

TODO document this option.

max_lifetime_seconds

TODO document this option.

use_sudo

TODO document this option.

The [docker] Section

Since: 1.0.0

guest_capabilities

TODO document this option.

network

TODO document this option.