Project: Sysbox (Runtime / Container Runtime)
File: install-package.md

This document describes how to install Sysbox using the . This is usually the case when installing Sysbox on hosts that have Docker in them. NOTE: If you are installing Sysbox on a Kubernetes cluster, use the daemonset instead. Also, if you need to build and install Sysbox from source (e.g., to get the latest upstream code or because there is no Sysbox package for your Linux distro yet), see the . - - - - - - - - We are currently offering the for Ubuntu and Debian distributions. This means that for other distros you must . We are working on creating packaged versions for the other supported distros, and expect to have them soon (ETA spring 2022). The Linux host on which Sysbox runs must meet the following requirements: It must have one of the . Systemd must be the host's process-manager (the default in the supported distros). NOTE: if you have a prior version of Sysbox already installed, please first and then follow the installation instructions below. Download the latest Sysbox package from the page: ``` $ wget https://downloads.nestybox.com/sysbox/releases/v0.6.4/sysbox-ce0.6.4-0.linuxamd64.deb ``` Verify that the checksum of the downloaded file fully matches the expected/published one. For example: ```console $ sha256sum sysbox-ce0.6.4-0.linuxamd64.deb d034ddd364ee1f226b8b1ce7456ea8a12abc2eb661bdf42d3e603ed2dc741827 sysbox-ce0.6.4-0.linuxamd64.deb ``` If Docker is running on the host, we recommend stopping and removing all Docker containers as follows (if an error is returned, it simply indicates that no existing containers were found): ```console $ docker rm $(docker ps -a -q) -f ``` This is recommended because the Sysbox installer may need to configure and restart Docker (to make Docker aware of Sysbox). For production scenarios, it's possible to avoid the Docker restart; see below for more on this. Install the Sysbox package and follow the installer instructions: ```console $ sudo apt-get install jq $ sudo apt-get install ./sysbox-ce0.6.4-0.linuxamd64.deb ``` NOTE: the `jq` tool is used by the Sysbox installer. Verify that Sysbox's Systemd units have been properly installed, and associated daemons are properly running: ```console $ sudo systemctl status sysbox -n20 sysbox.service - Sysbox container runtime Loaded: loaded (/lib/systemd/system/sysbox.service; enabled; vendor preset: enabled) Active: active (running) since Sat 2024-04-06 09:49:00 PDT; 15s ago Docs: https://github.com/nestybox/sysbox Main PID: 621617 (sh) Tasks: 2 (limit: 38077) Memory: 380.0K CPU: 15ms CGroup: /system.slice/sysbox.service 621617 /bin/sh -c "/usr/bin/sysbox-runc --version && /usr/bin/sysbox-mgr --version && /usr/bin/sysbox-fs --version && /bin/sleep infinity" 621637 /bin/sleep infinity Apr 06 09:49:00 lenovo systemd[1]: Started Sysbox container runtime. Apr 06 09:49:00 lenovo sh[621618]: sysbox-runc Apr 06 09:49:00 lenovo sh[621618]: edition: Community Edition (CE) Apr 06 09:49:00 lenovo sh[621618]: version: 0.6.4 Apr 06 09:49:00 lenovo sh[621618]: commit: 085502643ea5281652c6984eed9797872f22698a Apr 06 09:49:00 lenovo sh[621618]: built at: Sat Apr 6 16:43:31 UTC 2024 Apr 06 09:49:00 lenovo sh[621618]: built by: Cesar Talledo Apr 06 09:49:00 lenovo sh[621618]: oci-specs: 1.1.0+dev Apr 06 09:49:00 lenovo sh[621626]: sysbox-mgr Apr 06 09:49:00 lenovo sh[621626]: edition: Community Edition (CE) Apr 06 09:49:00 lenovo sh[621626]: version:

Apr 06 09:49:00 lenovo sh[621626]: commit: 03f5d7bc584fdcb2319b2c1831bd58581185fc1c Apr 06 09:49:00 lenovo sh[621626]: built at: Sat Apr 6 16:43:43 UTC 2024 Apr 06 09:49:00 lenovo sh[621626]: built by: Cesar Talledo Apr 06 09:49:00 lenovo sh[621631]: sysbox-fs Apr 06 09:49:00 lenovo sh[621631]: edition: Community Edition (CE) Apr 06 09:49:00 lenovo sh[621631]: version: 0.6.4 Apr 06 09:49:00 lenovo sh[621631]: commit: 1a678b72ac430009739fa6596b824f29b1f7fe2e Apr 06 09:49:00 lenovo sh[621631]: built at: Sat Apr 6 16:43:40 UTC 2024 Apr 06 09:49:00 lenovo sh[621631]: built by: Cesar Talledo ``` This indicates all Sysbox components are running properly. If you are curious on what these are, refer to the . After you've installed Sysbox, you can now use it to deploy containers with Docker. See the for examples. If you hit problems during installation, see the . Sysbox Enterprise Edition (Sysbox-EE) is the enterprise version of Sysbox, with improved security, functionality, performance, life-cycle, and Nestybox support. The installation for Sysbox Enterprise Edition (Sysbox-EE) is exactly the same as for Sysbox (see ), except you use the Sysbox-EE installation package found in the . For example, to install Sysbox-EE on a Ubuntu Focal host: ```console $ wget https://github.com/nestybox/sysbox-ee/releases/download/v0.4.0/sysbox-ee0.4.0-0.ubuntu-focalamd64.deb $ sudo apt-get install ./sysbox-ee0.4.0-0.ubuntu-focalamd64.deb $ sudo systemctl status sysbox -n20 sysbox.service - Sysbox container runtime Loaded: loaded (/lib/systemd/system/sysbox.service; enabled; vendor preset: enabled) Active: active (running) since Tue 2021-07-20 19:35:31 UTC; 18s ago Docs: https://github.com/nestybox/sysbox Main PID: 7963 (sh) Tasks: 2 (limit: 4617) Memory: 868.0K CGroup: /system.slice/sysbox.service 7963 /bin/sh -c /usr/bin/sysbox-runc --version && /usr/bin/sysbox-mgr --version && /usr/bin/sysbox-fs --version && /bin/sleep infinity 7986 /bin/sleep infinity Jul 20 19:35:31 focal systemd[1]: Started Sysbox container runtime. Jul 20 19:35:32 focal sh[7965]: sysbox-runc Jul 20 19:35:32 focal sh[7965]: edition: Enterprise Edition (EE) Jul 20 19:35:32 focal sh[7965]: version: 0.4.0 Jul 20 19:35:32 focal sh[7965]: commit: f4daa007da10280095911dde80a8cb95d03c4859 Jul 20 19:35:32 focal sh[7965]: built at: Mon Jul 19 18:55:14 UTC 2021 Jul 20 19:35:32 focal sh[7965]: built by: Rodny Molina Jul 20 19:35:32 focal sh[7965]: oci-specs: 1.0.2-dev Jul 20 19:35:32 focal sh[7972]: sysbox-mgr Jul 20 19:35:32 focal sh[7972]: edition: Enterprise Edition (EE) Jul 20 19:35:32 focal sh[7972]: version: 0.4.0 Jul 20 19:35:32 focal sh[7972]: commit: de7cbb47c9a667d4aaa79e4ca8aeadf6d5124bb2 Jul 20 19:35:32 focal sh[7972]: built at: Mon Jul 19 18:55:51 UTC 2021 Jul 20 19:35:32 focal sh[7972]: built by: Rodny Molina Jul 20 19:35:32 focal sh[7978]: sysbox-fs Jul 20 19:35:32 focal sh[7978]: edition: Enterprise Edition (EE) Jul 20 19:35:32 focal sh[7978]: version: 0.4.0 Jul 20 19:35:32 focal sh[7978]: commit: b0cb35cf449f5c929dba24fc940aef151f4432c5 Jul 20 19:35:32 focal sh[7978]: built at: Mon Jul 19 18:55:37 UTC 2021 Jul 20 19:35:32 focal sh[7978]: built by: Rodny Molina ``` After you've installed Sysbox-EE, you can now use it to deploy containers with Docker. See the for examples. NOTE: either Sysbox or Sysbox Enterprise must be installed on a given host, never both. Shiftfs is a kernel module that Sysbox uses to ensure host volumes mounted into the (rootless) container show up with proper user and group IDs. Installing shiftfs on the host is required when running on hosts with Linux kernel < 5.12. Installing shiftfs on hosts with kernel >= 5.12 is not required, but nonetheless recommended, assuming your Linux distro supports shiftfs (e.g., Ubuntu, Debian, or Flatcar). The shiftfs module is included by default in Ubuntu desktop and server images, but generally not included in Ubuntu-based cloud VMs and other Linux

For Ubuntu/Debian/Flatcar hosts where shiftfs is not included, it's possible (and fairly easy) to build and install it. To build and install shiftfs, follow the instructions here: https://github.com/toby63/shiftfs-dkms For example, to install shiftfs on an Ubuntu-based cloud VM with Linux kernel version 5.8 or 5.10, follow these simple steps: ```console sudo apt-get install -y make dkms git wget git clone -b k5.10 https://github.com/toby63/shiftfs-dkms.git shiftfs-k510 cd shiftfs-k510 ./update1 sudo make -f Makefile.dkms modinfo shiftfs ``` The last command should show that shiftfs is installed on the host. During installation, the Sysbox installer will detect if Docker is running and reconfigure the Docker daemon such that it detects the Sysbox runtime. It does this by adding the following configuration to `/etc/docker/daemon.json` and sending a signal (SIGHUP) to Docker: ```json { "runtimes": { "sysbox-runc": { "path": "/usr/bin/sysbox-runc" } } } ``` If all is well, Docker will recognize the Sysbox runtime: ```console $ docker info | grep -i runtime WARNING: No swap limit support Runtimes: runc sysbox-runc Default Runtime: runc ``` In versions of Sysbox prior to v0.5.0, using Sysbox required either shiftfs be installed on the host or alternatively that Docker be configured in . Starting with Sysbox v0.5.0, configuring Docker in userns-remap mode is no longer required, even if the host has no support for shiftfs. However, without shiftfs, you will need a host with kernel >= 5.12 so that Sysbox can use the kernel's ID-mapped mounts feature. Avoiding Docker userns-remap mode is desirable because that mode places a few on Docker containers. In some cases it's desirable to make Sysbox the default container runtime for Docker (as opposed to the standard runc runtime). If you wish to make Sysbox the default runtime for Docker, you must reconfigure Docker manually (the Sysbox installer won't do this). To do so, add the `default-runtime` config to `/etc/docker/daemon.json`. It should look similar to this: { "default-runtime": "sysbox-runc", "runtimes": { "sysbox-runc": { "path": "/usr/bin/sysbox-runc" } } } Then restart Docker (e.g., `sudo systemctl restart docker`). With this setup, you can omit the `--runtime=sysbox-runc` flag when using `docker run` to create containers with Sysbox. To simplify the Sysbox installation process, we explicitly ask the user to stop and remove the existing containers. However, this may not be a feasible option in production scenarios. This section tackles this problem by enumerating the docker configuration elements that can be preconfigured to allow Sysbox installation to succeed without impacting the existing containers. During Sysbox installation, the installer adds the following attributes into Docker's configuration file if these are not already present. With the exception of the `runtime` attribute, all others require a Docker process restart for changes to be digested by the Docker engine. `runtime` -- sysbox-runc must be added as a new runtime. `bip` -- explicitly sets Docker's interface (docker0) network IP address. `default-address-pools` -- explicitly defines the subnets to be utilized by Docker for custom-networks purposes. To prevent Sysbox installer from restarting Docker daemon during the installation process, the Docker engine must be already aware of these required attributes, and for this to happen, Docker configuration files such as the following ones should be in placed in `/etc/docker/daemon.json`: ```yaml { "bip": "172.24.0.1/16", "default-address-pools": [ { "base":

"size": 24 } ] } ``` Notice that it is up to the user to decide which specific `bip` or `default-address-pools` values/ranges are pre-configured. The Sysbox installer will not restart Docker as long as there's one instance of these "must-have" attributes in Docker's `/etc/docker/daemon.json` configuration file. Ubuntu offers two methods for installing Docker: Via `apt get` (aka native installation) Via `snap install` (aka snappy installation) In recent versions of Ubuntu, (2) is the default approach. For example, while installing Ubuntu Focal on a VM, the installer will ask if you want to install Docker. If you answer "yes", it will use the snappy installation method. You can tell if Docker is installed via a snap by doing: ```console $ which docker /snap/bin/docker ``` Unfortunately, Sysbox does not currently support working with Docker when the latter is installed via a snap package. In the meantime, you must install Docker natively (method (1) above). These are the steps to do so: If Docker is installed via a snap, remove the snap: ```console $ sudo snap remove docker docker removed ``` Install Docker natively. Follow the instructions in this . Confirm Docker is installed natively: ```console $ which docker /usr/bin/docker ``` Make sure you are in the `docker` group: ```console $ sudo usermod -a -G docker $(whoami) ``` You may need to log-out and log-in for the group setting to take effect. If you are not in the `docker` group (or have no sudo privileges), you'll see an error such as: ```console $ docker run -it alpine Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: ... connect: permission denied ``` Verify Docker works: ```console $ docker run -it alpine Unable to find image 'alpine:latest' locally latest: Pulling from library/alpine df20fa9351a1: Pull complete Digest: sha256:185518070891758909c9f839cf4ca393ee977ac378609f700f60a771a2dfe321 Status: Downloaded newer image for alpine:latest / # ``` At this point you have Docker working, and can now . If you want to revert back to the Docker snap, the steps are below, but keep in mind that Sysbox won't work. Uninstall the native Docker See . Re-install the Docker snap: ```console $ sudo snap install docker ``` Prior to uninstalling Sysbox, make sure all Sysbox containers are removed. There is a simple shell script to do this . Non-Sysbox containers can remain untouched. Uninstall Sysbox binaries plus all the associated configuration and Systemd files: ```console $ sudo apt-get purge sysbox-ce -y ``` For Sysbox Enterprise: ```console $ sudo apt-get purge sysbox-ee -y ``` Remove the `sysbox` user from the system: ```console $ sudo userdel sysbox ``` To upgrade Sysbox, first uninstall Sysbox and re-install the updated version. You can find the latest versions of Sysbox here: . . Note that you must stop all Sysbox containers on the host prior to uninstalling Sysbox (see previous section). During the uninstall and re-install process, the Sysbox installer will restart Docker if needed. Sysbox Enterprise Edition (Sysbox-EE) is a drop-in replacement for Sysbox. If you have a host with Sysbox and wish to install Sysbox Enterprise in it, simply and as described above. NOTE: either Sysbox or Sysbox Enterprise must be installed on a given host, never both.