This document will walk you through the steps to setup the environment required to use the tools in the CLIP OS project.
Global environment configuration requirements¶
Here is a requirements check-list about your global environment:
You must run a 64-bit x86 system (a.k.a.
About other system architectures…
Cross-compiling to other system architectures is not supported yet. No other host system architecture is supported yet.
You must run Linux. No other operating system is supported. Any relatively recent and stable kernel provided by a major Linux distribution should be compatible with the CLIP OS toolkit.
Supported Linux distributions
The project has been tested and is known to work with the following distributions:
- Arch Linux
- Debian testing (buster) and Debian unstable
- Fedora 28
- Ubuntu 18.04
Similarly, the following kernels are supported:
- 4.16 and above (Arch Linux, Debian unstable, etc.)
- 4.9 (Debian stable (stretch))
The project will likely work on other distributions but we do not plan on supporting any other one yet.
About other Linux distributions…
Provided a kernel can support all the features used within the CLIP OS toolkit (such as namespaces, capabilities, cgroups for containerization, SquashFS, loop devices, OverlayFS, tmpfs, etc.), it is expected to work without issue.
Both your hardware and your kernel must support KVM (through Intel VT-x/VT-d or AMD-V/AMD-Vi technologies) to run CLIP OS virtual machine images.
Super-user privileges are required on punctual occasions through the use of the
Why this requirement?
Super-user privileges are required to permit the CLIP OS toolkit to create and manage Linux containers, such as the CLIP OS SDK ephemeral containers.
However, the CLIP OS toolkit will not run everything as root as it will lower its effective privileges when root privileges are not necessary.
For more information, see the implementation of the class cosmk.privileges.ElevatedPrivileges in cosmk Python API reference.
Make sure to have allocated a consequent size of swap space on your system as it might be required when working on large ephemeral SDK environments. Having a lot of RAM (16GB+) will also help.
Why this requirement?
SDK ephemeral containers make use of “in-memory” tmpfs OverlayFS layers. As a consequence, there are scenarios where memory usage may be large (typically when bootstrapping the CLIP OS SDK image) and may not fit the entire memory of the system.
Make sure to have enough free storage space before getting the source tree as it can take up to several gigabytes of storage, and even more when you will begin building CLIP OS images. 50GB should be a minimum.
Make sure to work in a filesystem without any restricted features such as noexec or nodev as it will cause undefined issues throughout the building process of some parts of the CLIP OS images.
If your are using a distribution supported by the project, you may skip this part of the documentation and jump directly to the section Dependencies installation on supported Linux-distributions. Otherwise (or if you encounter issues with the above method), please continue reading this section.
To get a functional environment, you will need these software dependencies in your userland:
Git as all the source code is versioned through Git repositories.
repo (tool from the Android Open Source Project) is required to fetch the source tree.
Alternative way to install repo
repomight be packaged by your Linux distribution. Otherwise you may have to get it and install it from source. To do so, follow the related instructions on the Android Open Source project page regarding the setup of the environment for AOSP.
Git LFS (Git Large File Storage extension) is required to fetch Git repositories with a lot of large binary files.
Alternative way to install Git LFS
git-lfsis not provided through a package of your Linux distribution, you can follow instructions from the Git LFS project pages to install it.
Python 3.6 (or later) with a working C compiler and some basic development libraries and tools as well as the appropriate CPython C header files.
Why a C compilation infrastructure is needed on the host while all the compilations are done within containers?
These development packages are required to build some external Python packages vendored in the source tree and which embed some CPython code.
sudo (v1.8.21 or above) is required to permit the CLIP OS toolkit to elevate privileges to super-user privileges. The current unprivileged user must be a
sudoerto be able to gain those privileges via the use of
runc (the OCI runtime tool) is required as it is used as the runtime for the CLIP OS SDK Linux containers.
Alternative and more convenient way to get runc on your system
Since runc is a project originated from Docker and used as a container runtime by the Docker engine (since version 1.11 of the Docker Engine), installing the Docker Engine is an alternative to provide the
runcutility to the CLIP OS toolkit (Docker embeds a
runcbinary under the name of
This tip may be useful if your distribution does not provide a standalone
runcpackage but does provide a package for Docker.
squashfs-tools and util-linux system packages for the use of
Why SquashFS and loop devices?
These two utilities are required to create and mount squashfs images used internally by the CLIP OS toolkit as the rootfs images of the ephemeral SDK containers.
Rust language support to build just.
justis a simple command-line utility to launch and abstract sequences of shell commands within
Justfiles. These files follow a Makefile-like syntax and provide an alternative way (in the context of the CLIP OS toolkit) to launch build jobs and other source code management common scripts as the
cosmktool does not implement all the required features yet.
Alternative way to install Rust
If Rust is not provided by any of your Linux distribution packages, you can install it with rustup.
Bash 4.1 (or later) is required for some toolkit helper scripts.
libvirt with QEMU and KVM support are required as the platform to run the CLIP OS virtual machines with QEMU with virtualized networks.
Avoid running QEMU as root if not necessary
On some Linux distributions (e.g., Arch Linux), libvirt is provided with a default configuration which runs QEMU as root. If you intend to use libvirt only for the purpose of running CLIP OS QEMU images, you may want to run the QEMU processes launched by libvirt as your current user.
To do so, edit the file
/etc/libvirt/qemu.confand change the values for the
user = "myusername" # replace with your current username group = "kvm"
Dependencies installation on supported Linux-distributions¶
On Ubuntu or Debian 10 (testing) and unstable (with
contrib sources enabled
$ sudo apt install \ python3.6 python3.6-dev python3-venv \ gnupg2 repo git git-lfs openssh-client \ build-essential pkg-config \ runc sudo squashfs-tools \ qemu libvirt-dev libvirt-daemon \ virt-manager gir1.2-spiceclientglib-2.0 gir1.2-spiceclientgtk-3.0 \ debootstrap \ rustc cargo
On Fedora 28:
$ sudo dnf install \ python2 python3-devel \ gnupg git git-lfs openssh-clients \ @development-tools \ runc sudo squashfs-tools \ qemu libvirt-devel libvirt-daemon \ virt-manager \ debootstrap \ rust cargo
On Arch Linux:
$ sudo pacman -Syu \ python \ gnupg repo git git-lfs openssh \ base-devel \ runc sudo squashfs-tools \ qemu libvirt bridge-utils dnsmasq \ virt-manager ebtables \ debootstrap \ rust \ debian-archive-keyring
How to fetch the entire source tree?¶
The project source tree is split among several distinct repositories that are
managed together using
Make sure the Git LFS filters are enabled
Please ensure to have installed the Git LFS filters hooks for Git either
globally on your system (changes will be made in
the following command:
$ sudo git-lfs install --system --skip-repo
or only for your current user (changes will be made in
$ git-lfs install --skip-repo
This step is required to be done before synchronizing the whole CLIP OS
source tree and allows to automatically download the files stored within the
Git LFS server when
repo checks out the Git LFS-backed repositories of
the source tree.
Watch out for unusual umask values!
Due to the fact that we bind-mount the source tree within SDK containers,
please ensure to fetch and synchronize the entire source tree with a umask
value keeping permissions to read files and traverse directories
(recommended umask value
Failure to do so may lead to undefined issues when using the CLIP OS toolkit as all the file modes of this source tree are left unchanged when they are exposed within SDK containers. As a consequence, some unprivileged programs running in these containers might encounter a “Permission denied” error when trying to read files whose mode deny access for “others”.
Then to get the entire source tree:
$ mkdir clipos $ cd clipos $ umask 0022 $ git lfs install --skip-repo $ repo init -u https://github.com/CLIPOS/manifest $ repo sync
This may take some time (several minutes at least, but this depends on your
network bandwidth) as several Git repositories need to be cloned, including
large Git repositories holding lots of contents and history, such as the Linux
src/external/linux/) or the Gentoo Portage tree
If you are certain to have set everything up correctly and if you are not
intreseted in the output of the
repo sync command, you can instruct
repo to synchronize all the sub-repositories concurrently by using
multiple Git processes:
$ repo sync -j4
This should be significantly faster than the method above but the output of the Git cloning processes might be interlaced and not easily readable.
At this point, you should have successfully set up your environment and fetched the whole source tree of the CLIP OS project.
In case you forgot to install the Git LFS filters before synchronizing the whole source tree
If you forgot to setup the Git LFS filter before running
repo sync, you
can still download the missing contents of the files backed by Git LFS (and
therefore fix your current source tree checkout) by running this command:
$ repo forall -c 'git lfs install && git lfs pull'
Congratulations, you are now ready to launch a build of a CLIP OS image.