|
| 1 | +# Sysbox Distro Compatibility |
| 2 | + |
| 3 | +## Contents |
| 4 | + |
| 5 | +- [Supported Linux Distros](#supported-linux-distros) |
| 6 | +- [Ubuntu Support](#ubuntu-support) |
| 7 | + - [Sysbox on Older Ubuntu Kernels](#sysbox-on-older-ubuntu-kernels) |
| 8 | + - [Distro Compatibility Summary](#distro-compatibility-summary) |
| 9 | + - [Upgrading the Ubuntu Kernel](#upgrading-the-ubuntu-kernel) |
| 10 | + - [Bionic Beaver](#bionic-beaver) |
| 11 | + - [Disco Dingo](#disco-dingo) |
| 12 | + |
| 13 | +## Supported Linux Distros |
| 14 | + |
| 15 | +Sysbox relies on functionality that is currently only present in |
| 16 | +Ubuntu kernels. Thus, Ubuntu is the only distro supported at this |
| 17 | +time. |
| 18 | + |
| 19 | +## Ubuntu Support |
| 20 | + |
| 21 | +Sysbox requires very recent Ubuntu kernels: |
| 22 | + |
| 23 | +- Ubuntu 19.10 "Eoan" |
| 24 | +- Ubuntu 19.04 "Disco" (kernel upgrade >= 5.0.0-21.22) |
| 25 | +- Ubuntu 18.04 "Bionic" (kernel upgrade >= 5.0) |
| 26 | + |
| 27 | +If your kernel is not one of these, you can still use Sysbox |
| 28 | +using the alternative approach described in the next section. |
| 29 | + |
| 30 | +**NOTES:** |
| 31 | + |
| 32 | +1) Canonical generates flavors of these kernels for desktop, server, |
| 33 | +and cloud. The [cloud images](https://cloud-images.ubuntu.com/) do |
| 34 | +not yet include the kernel functionality required by Sysbox |
| 35 | +(unfortunately). Thus, if you want to use Sysbox on a cloud VM, you |
| 36 | +must install the Ubuntu desktop or server flavors on the VM, or use |
| 37 | +the alternative approach described in the next section. |
| 38 | + |
| 39 | +2) If you have a Ubuntu desktop or server image but need to upgrade |
| 40 | +the kernel in order to meet the requirements listed above, see |
| 41 | +[here](#upgrading-the-ubuntu-kernel) for suggestions on how to do this. |
| 42 | + |
| 43 | +3) If you launch a system container with Docker + Sysbox, and you get |
| 44 | +an error such as |
| 45 | + |
| 46 | +```console |
| 47 | +# docker run --runtime=sysbox-runc -it debian:latest |
| 48 | +docker: Error response from daemon: OCI runtime create failed: container requires user-ID shifting but error was found: shiftfs module is not loaded in the kernel. Update your kernel to include shiftfs module or enable Docker with userns-remap. Refer to the Sysbox troubleshooting guide for more info: unknown |
| 49 | +``` |
| 50 | + |
| 51 | +it means that your kernel does not meet the requirements listed above |
| 52 | +(specifically your distro does not have the `shiftfs` module that is |
| 53 | +present in recent Ubuntu desktop and server kernels). In this case you |
| 54 | +must either upgrade your kernel or use the alternative approach |
| 55 | +described in the next section. |
| 56 | + |
| 57 | +### Sysbox on Older Ubuntu Kernels |
| 58 | + |
| 59 | +If your distro is Ubuntu but the kernel version is not as recent as |
| 60 | +those listed in the prior section, it's still possible to use |
| 61 | +Sysbox. However, doing so requires two things: |
| 62 | + |
| 63 | +1) You must have Ubuntu Bionic or later (e.g., Ubuntu Bionic, Disco, |
| 64 | + Cosmic, or Eoan). Any kernel version of these releases will do. |
| 65 | + |
| 66 | +2) You must change the configuration of the Docker daemon: |
| 67 | + |
| 68 | +- After installing Sysbox, add the `userns-remap` line to the |
| 69 | + `/etc/docker/daemon.json` file as shown below: |
| 70 | + |
| 71 | + ```console |
| 72 | + # cat /etc/docker/daemon.json |
| 73 | + { |
| 74 | + "userns-remap": "sysbox", |
| 75 | + "runtimes": { |
| 76 | + "sysbox-runc": { |
| 77 | + "path": "/usr/local/sbin/sysbox-runc" |
| 78 | + } |
| 79 | + } |
| 80 | + } |
| 81 | + ``` |
| 82 | + |
| 83 | + This tells Docker to enable the user namespace in all containers |
| 84 | + and map the root user in the container to the subid range of |
| 85 | + user `sysbox`, as defined in the `/etc/subuid` and `/etc/subgid` files. |
| 86 | + |
| 87 | +- Restart the Docker daemon: |
| 88 | + |
| 89 | + ```console |
| 90 | + # sudo systemctl restart docker.service |
| 91 | + ``` |
| 92 | + |
| 93 | +- Note that both of the actions above require `root` privileges on |
| 94 | + the host. |
| 95 | + |
| 96 | +When Docker is configured this way, Sysbox works in what we call |
| 97 | +"Docker userns-remap mode". It's a mode that offers strong container |
| 98 | +isolation, but not as strong as when using the latest Ubuntu kernels |
| 99 | +with the shiftfs module as described in the prior section (where |
| 100 | +Sysbox works in "Exclusive userns-remap mode". See |
| 101 | +[here](usage.md#system-container-isolation-modes) for more info on |
| 102 | +Sysbox isolation modes. |
| 103 | + |
| 104 | +### Distro Compatibility Summary |
| 105 | + |
| 106 | +Here is a summary of the distro requirements: |
| 107 | + |
| 108 | +| Distro Name | Kernel | Requires Docker in Userns-Remap Mode | |
| 109 | +| ------------------- | ---------------- | ------------------------------------ | |
| 110 | +| Ubuntu 19.10 Eoan | Any | No | |
| 111 | +| Ubuntu 19.04 Disco | >= 5.0.0-21.22 | No | |
| 112 | +| | < 5.0.0-21.22 | Yes | |
| 113 | +| Ubuntu 18.10 Cosmic | Any | Yes | |
| 114 | +| Ubuntu 18.04 Bionic | >= 5.0 | No | |
| 115 | +| | < 5.0 | Yes | |
| 116 | + |
| 117 | +### Upgrading the Ubuntu Kernel |
| 118 | + |
| 119 | +In case you need to upgrade your machine's Linux kernel to meet Sysbox |
| 120 | +kernel version requirements, here are some suggestions. Refer to the |
| 121 | +Ubuntu documentation online for further info. |
| 122 | + |
| 123 | +#### Bionic Beaver |
| 124 | + |
| 125 | +For Bionic Beaver, we recommend using Ubuntu's [LTS-enablement](https://wiki.ubuntu.com/Kernel/LTSEnablementStack) |
| 126 | +package: |
| 127 | + |
| 128 | +```console |
| 129 | +$ sudo apt-get update && sudo apt install --install-recommends linux-generic-hwe-18.04 -y |
| 130 | +``` |
| 131 | + |
| 132 | +#### Disco Dingo |
| 133 | + |
| 134 | +For Disco Dingo, we recommend simply upgrading the distro: |
| 135 | + |
| 136 | +```console |
| 137 | +$ sudo apt-get update |
| 138 | +$ sudo apt-get upgrade |
| 139 | +$ sudo apt-get dist-upgrade |
| 140 | +$ reboot |
| 141 | +``` |
0 commit comments