Docker Quick Start

This guide will help you quickly get started running Docker containers using gVisor.

Install gVisor

Note: gVisor supports only x86_64 and requires Linux 4.14.77+ (older Linux).

The easiest way to get runsc is from the latest nightly build. After you download the binary, check it against the SHA512 checksum file.

Older builds can also be found here: https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc

With corresponding SHA512 checksums here: https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc.sha512

It is important to copy this binary to a location that is accessible to all users, and ensure it is executable by all users, since runsc executes itself as user nobody to avoid unnecessary privileges. The /usr/local/bin directory is a good place to put the runsc binary.

(
  set -e 
  wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
  wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
  sha512sum -c runsc.sha512
  sudo mv runsc /usr/local/bin
  sudo chown root:root /usr/local/bin/runsc
  chmod 0755 /usr/local/bin/runsc
)

Configuring Docker

Note: This guide requires Docker version 17.09.0 or greater. Refer to the Docker documentation for how to install it.

First you will need to configure Docker to use runsc by adding a runtime entry to your Docker configuration (/etc/docker/daemon.json). You may have to create this file if it does not exist. Also, some Docker versions also require you to specify the storage-driver field.

In the end, the file should look something like:

{
    "runtimes": {
        "runsc": {
            "path": "/usr/local/bin/runsc"
        }
    }
}

You must restart the Docker daemon after making changes to this file, typically this is done via systemd:

sudo systemctl restart docker

Running a container

Now run your container using the runsc runtime:

docker run --runtime=runsc --rm hello-world

You can also run a terminal to explore the container.

docker run --runtime=runsc --rm -it ubuntu /bin/bash

Many docker options are compatible with gVisor, try them out. Here is an example:

docker run --runtime=runsc --rm --link backend:database -v ~/bin:/tools:ro -p 8080:80 --cpus=0.5 -it busybox telnet towel.blinkenlights.nl

Verify the runtime

You can verify that you are running in gVisor using the dmesg command.

$ docker run --runtime=runsc -it ubuntu dmesg
[    0.000000] Starting gVisor...
[    0.354495] Daemonizing children...
[    0.564053] Constructing home...
[    0.976710] Preparing for the zombie uprising...
[    1.299083] Creating process schedule...
[    1.479987] Committing treasure map to memory...
[    1.704109] Searching for socket adapter...
[    1.748935] Generating random numbers by fair dice roll...
[    2.059747] Digging up root...
[    2.259327] Checking naughty and nice process list...
[    2.610538] Rewriting operating system in Javascript...
[    2.613217] Ready!

Note that this is easily replicated by an attacker so applications should never use dmesg to verify the runtime in a security sensitive context.

Next, look at the different options available for gVisor: platform, network, filesystem.