Installation

Sarus can be installed in three alternative ways:

When installing from source or with Spack, make sure that the required dependencies are available on the system.

Whichever procedure you choose, please also read the page about Post-installation actions to ensure everything is set to run Sarus.

Installing with Spack

Sarus provides Spack packages for itself and its dependencies which are not yet covered by Spack’s builtin repository. Installing with Spack is convenient because detection and installation of dependencies are handled automatically.

As explained in the execution requirements, Sarus must be installed as a root-owned SUID binary in a directory hierarchy which belongs to the root user at all levels. The straightforward way to achieve this is to use a root-owned Spack and run the installation procedure with super-user privileges. An alternative procedure for test/development installations with a non-root Spack is discussed in this subsection.

Note

A static version of glibc is required to build the Dropbear software for the SSH hook. On CentOS 7, Fedora and and OpenSUSE Leap systems, such library is provided separately from common development tools:

# CentOS 7
yum install glibc-static

# Fedora
dnf install glibc-static

# OpenSUSE Leap
zypper install glibc-devel-static

Note

On CentOS 7, the default GCC 4.8.5 compiler is not suitable for building Sarus. We advise to use a more recent compiler, for example one from Developer Toolset 7, 8 or 9:

# Install GCC 8.3.1 through devtoolset-8
yum install centos-release-scl-rh
yum install devtoolset-8-gcc-c++

# Enable devtoolset-8 to set gcc 8.3.1 as default compiler
source /opt/rh/devtoolset-8/enable

# Detect the new compiler with Spack
spack compiler find

The installation procedure with Spack follows below. If you are not performing these actions as the root user, prefix each spack command with sudo:

# Setup Spack bash integration (if you haven't already done so)
. ${SPACK_ROOT}/share/spack/setup-env.sh

# Create a local Spack repository for Sarus-specific dependencies
export SPACK_LOCAL_REPO=${SPACK_ROOT}/var/spack/repos/cscs
spack repo create ${SPACK_LOCAL_REPO}
spack repo add ${SPACK_LOCAL_REPO}

# Import Spack packages for Cpprestsdk, RapidJSON and Sarus
cp -r <Sarus project root dir>/spack/packages/* ${SPACK_LOCAL_REPO}/packages/

# Install Sarus
spack install --verbose sarus

By default, the latest tagged release will be installed. To get the bleeding edge, use the @develop version specifier.

The Spack package for Sarus supports the following variants to customize the installation:

  • ssh: Build and install the SSH hook and custom SSH software to enable connections inside containers [True].

  • configure_installation: Run the script to setup a starting Sarus configuration as part of the installation phase. Running the script requires super-user privileges [True].

  • unit_tests: Build unit test executables in the build directory. Also downloads and builds internally the CppUTest framework [False].

For example, in order to perform a quick installation without SSH we could use:

spack install --verbose sarus ssh=False

Using Spack as a non-root user (for test and development only)

By default, the Spack package for Sarus will run a configuration script as part of the installation phase to setup a minimal working configuration. The script needs to run with root privileges, which in turn means the spack install command must be issued with root powers.

The configure_installation variant of the Spack package allows to control the execution of the script. By negating the variant, Sarus can be installed as a user different than root. It is then necessary to access the installation path and run the configuration script directly. While doing so still requires sudo, it can be performed with a user’s personal Spack software and the amount of root-owned files in the Sarus installation is kept to a minimum.

Installing as non-root likely means that Sarus is located in a directory hierarchy which is not root-owned all the way up to /. This is not allowed by the program’s security checks, so they have to be disabled.

Important

The ability to disable security checks is only meant as a convenience feature when rapidly iterating over test and development installations. It is strongly recommended to keep the checks enabled for production deployments.

Sarus can then be loaded and used normally. The procedure is summed up in the following example:

# Setup Spack bash integration (if you haven't already done so)
. ${SPACK_ROOT}/share/spack/setup-env.sh

# Create a local Spack repository for Sarus-specific dependencies
export SPACK_LOCAL_REPO=${SPACK_ROOT}/var/spack/repos/cscs
spack repo create ${SPACK_LOCAL_REPO}
spack repo add ${SPACK_LOCAL_REPO}

# Import Spack packages for Cpprestsdk, RapidJSON and Sarus
cp -r <Sarus project root dir>/spack/packages/* ${SPACK_LOCAL_REPO}/packages/

 # Install Sarus skipping the configure_installation script
 $ spack install --verbose sarus@develop ~configure_installation

 # Use 'spack find' to get the installation directory
 $ spack find -p sarus@develop
 ==> 1 installed package
 -- linux-ubuntu18.04-sandybridge / gcc@7.5.0 --------------------
 sarus@develop  /home/ubuntu/spack/opt/spack/linux-ubuntu18.04-sandybridge/gcc-7.5.0/sarus-develop-dy4f6tlhx3vwf6zmqityvgdhpnc6clg5

 # cd into the installation directory
 $ cd /home/ubuntu/spack/opt/spack/linux-ubuntu18.04-sandybridge/gcc-7.5.0/sarus-develop-dy4f6tlhx3vwf6zmqityvgdhpnc6clg5

 # Run configure_installation script
 $ sudo ./configure_installation.sh

 # Disable security checks
 $ sudo sed -i -e 's/"securityChecks": true/"securityChecks": false/' etc/sarus.json

 # Return to home folder and test Sarus
 $ cd
 $ spack load sarus@develop
 $ sarus pull alpine
 [...]
 $ sarus run alpine cat /etc/os-release
 NAME="Alpine Linux"
 ID=alpine
 VERSION_ID=3.11.5
 PRETTY_NAME="Alpine Linux v3.11"
 HOME_URL="https://alpinelinux.org/"
 BUG_REPORT_URL="https://bugs.alpinelinux.org/"

Installing from source

Build and install

Get Sarus source code:

git clone git@github.com:eth-cscs/sarus.git
cd sarus

Create a new folder ${build_dir}} to build Sarus from source. e.g. build-Release:

    mkdir -p ${build_dir} && cd ${build_dir}

Configure and build (in this example ${build_type} = Release and ${toolchain_file} = gcc.cmake:

    cmake -DCMAKE_TOOLCHAIN_FILE=${build_dir}/../cmake/toolchain_files/${toolchain_file} \
        -DCMAKE_PREFIX_PATH="/usr/local/include/rapidjson" \
        -DCMAKE_BUILD_TYPE=${build_type} \
        -DCMAKE_INSTALL_PREFIX=${install_dir} \
        ..

    make -j$(nproc)

Note

CMake should automatically find the dependencies (include directories, shared objects, and binaries). However, should CMake not find a dependency, its location can be manually specified through the command line. E.g.:

cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchain_files/gcc.cmake \
      -DCMAKE_INSTALL_PREFIX=${prefix_dir} \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_PREFIX_PATH="<boost install dir>;<cpprestsdk install dir>;<libarchive install dir>;<rapidjson install dir>" \
      -Dcpprestsdk_INCLUDE_DIR=<cpprestsdk include dir> \
      ..

Note

Old versions of CMake might have problems finding Boost 1.65.0. We recommend to use at least CMake 3.10 in order to avoid compatibility issues.

Below are listed the Sarus-specific options that can be passed to CMake in order to customize your build:

  • CMAKE_INSTALL_PREFIX: installation directory of Sarus [/usr/local].

  • ENABLE_SSH: build and install the SSH hook and custom SSH software to enable connections inside containers [TRUE].

  • ENABLE_UNIT_TESTS: build unit tests. Also downloads and builds internally the CppUTest framework [TRUE].

  • ENABLE_TESTS_WITH_VALGRIND: run each unit test through valgrind [FALSE].

Copy files to the installation directory:

    sudo make install

Create the directory in which Sarus will create the OCI bundle for containers. The location of this directory is configurable at any time, as described in the next section. As an example, taking default values:

    sudo mkdir -p ${install_dir}/var/OCIBundleDir

Finalize the installation

To complete the installation, run the configuration script located in the installation path. This script needs to run with root privileges in order to set Sarus as a root-owned SUID program:

    sudo cp /usr/local/bin/tini-static-amd64 ${install_dir}/bin || true
    sudo cp /usr/local/bin/runc.amd64 ${install_dir}/bin || true

    sudo ${install_dir}/configure_installation.sh
    export PATH=${install_dir}/bin:${PATH}

Note

The configuration script will create a minimal working configuration. For enabling additional features, please refer to the Configuration file reference.

As suggested by the output of the script, you should also add Sarus to your PATH. Add a line like export PATH=/opt/sarus/bin:${PATH} to your .bashrc in order to make the addition persistent.