osbuilder - Clear Containers guest O/S building scripts
- Building a guest image
- Build guest kernel
- Using the newly generated custom rootfs and kernel images
- Using osbuilder scripts with Docker*
- Environment Variables
The Clear Containers hypervisor creates a virtual machine (VM) in which to run the workload. To do this, the hypervisor requires a root filesystem (rootfs) image and a guest kernel image in order to create the guest environment in which the container runs.
The scripts in this repository are called by running
particular targets. The scripts use a work directory for storing all files. By
default this will be created automatically as
./workdir however this can be
changed by setting the
WORKDIR environment variable. See Environment Variables.
Building a guest image
A guest image is a rootfs that has been converted into a disk image.
Build a rootfs
rootfs target will generate a directory called
overwriting duplicate files:
$ sudo -E make rootfs
(optional) Customise the rootfs
It is possible to customise the rootfs; simply modify the files below
workdir/rootfs as desired.
Create a rootfs image
image target will create a disk image called
container.img from the
workload/rootfs directory. This image file is compatible with the official Clear Containers images provided with a Clear Containers installation.
image target will not create or populate the
so it is necessary to build a rootfs first.
IMG_SIZE environment variable to change the size of the image if
desired. See Environment Variables.
$ sudo -E make image
By default, the rootfs image is based on
Clear Linux for Intel* Architecture, but the
workdir/rootfs directory can be
populated with any other source.
Packages are installed inside the generated image. You can install extra
packages using the environment variable
See Environment Variables.
Clear Linux based packages security limitations
Although the Clear Linux rootfs is constructed from
rpm packages, Clear
Linux itself is not an
rpm-based Linux distribution (the software installed
on a Clear Linux system is not managed using
rpm packages used to generate the rootfs are not signed, so there is no
way to ensure that downloaded packages are trustworthy.
If you are willing to use Clear Linux based images, official Clear Containers rootfs images can be obtained from https://download.clearlinux.org/releases.
Build guest kernel
Clear Containers uses the Linux* kernel.
To build a kernel compatible with Clear Containers using the make
kernel target. This
will clone the Clear Container Kernel in the
(which will be created if necessary). On success two new kernel images will be created:
workdir/vmlinuz.container(compressed kernel image)
workdir/vmlinux.container(uncompressed kernel image)
$ # Pull and setup latest kernel for Clear Containers $ sudo -E make kernel-src $ sudo -E make kernel
Using the newly generated custom rootfs and kernel images
Clear Containers 3.x
This section covers using the new resources with
Installing the custom roots image
- Install the image file
$ sudo make install-image
Installing the new kernel
Install the kernel image (run
make helpfor more information)
$ sudo make install-kernel
Verify kernel is configured
$ cc-runtime cc-env
In order to work the osbuilder scripts require the following programs:
To check if these tools are available locally, run:
$ make check-deps
Using osbuilder scripts with Docker*
If you do not want to install all the dependencies on your system to run the osbuilder scripts, you can instead run them under Docker. To run the osbuilder scripts inside a Docker container the following requirements must be met:
Docker 1.12+ installed
runcis configured as the default runtime
To check if
runcis the default runtime:
$ docker info | grep 'Default Runtime: runc'
This requirement is specifically for
docker buildwhich does not work with a hypervisor-based runtime currently (see issue #8 for more information.
$ export USE_DOCKER=true
Use osbuilder makefile targets as described in Build guest image
$ export USE_DOCKER=true $ # Download Clear Containers guest base rootfs $ sudo -E make rootfs $ # Build an image with the conent generated by 'make rootfs' $ sudo -E make image
osbuilder with ubuntu 14.06 fails because of an old version of
However, it is still possible to run the scripts using docker.
make help to see a list of supported environment variables that can be
used to change the tools behaviour.