From 22f1890a9beab11d8cfdceba3a4d66f8bbbb468c Mon Sep 17 00:00:00 2001 From: Ian Lewis Date: Fri, 29 Mar 2019 22:40:11 -0400 Subject: Initial commit --- content/docs/user_guide/FAQ.md | 36 ++ content/docs/user_guide/_index.md | 8 + content/docs/user_guide/checkpoint_restore.md | 107 ++++ content/docs/user_guide/compatibility/_index.md | 43 ++ content/docs/user_guide/compatibility/amd64.md | 710 ++++++++++++++++++++++++ content/docs/user_guide/debugging.md | 33 ++ content/docs/user_guide/docker.md | 81 +++ content/docs/user_guide/filesystem.md | 1 + content/docs/user_guide/kubernetes.md | 16 + content/docs/user_guide/networking.md | 36 ++ content/docs/user_guide/oci.md | 53 ++ content/docs/user_guide/platforms.md | 108 ++++ 12 files changed, 1232 insertions(+) create mode 100644 content/docs/user_guide/FAQ.md create mode 100644 content/docs/user_guide/_index.md create mode 100644 content/docs/user_guide/checkpoint_restore.md create mode 100644 content/docs/user_guide/compatibility/_index.md create mode 100644 content/docs/user_guide/compatibility/amd64.md create mode 100644 content/docs/user_guide/debugging.md create mode 100644 content/docs/user_guide/docker.md create mode 100644 content/docs/user_guide/filesystem.md create mode 100644 content/docs/user_guide/kubernetes.md create mode 100644 content/docs/user_guide/networking.md create mode 100644 content/docs/user_guide/oci.md create mode 100644 content/docs/user_guide/platforms.md (limited to 'content/docs/user_guide') diff --git a/content/docs/user_guide/FAQ.md b/content/docs/user_guide/FAQ.md new file mode 100644 index 000000000..b94b93b1f --- /dev/null +++ b/content/docs/user_guide/FAQ.md @@ -0,0 +1,36 @@ ++++ +title = "FAQ" +weight = 1000 ++++ +## My container runs fine with `runc` but fails with `runsc` + +If you’re having problems running a container with `runsc` it’s most likely due +to a compatibility issue or a missing feature in gVisor. See +[Debugging](../debugging/). + +## When I run my container, docker fails with: `flag provided but not defined: -console` + +You're using an old version of Docker. See [Docker Quick Start](../docker/). + +## I can’t see a file copied with: `docker cp` + +For performance reasons, gVisor caches directory contents, and therefore it may +not realize a new file was copied to a given directory. To invalidate the cache +and force a refresh, create a file under the directory in question and list the +contents again. + +This bug is tracked in [bug #4](https://github.com/google/gvisor/issues/4). + +Note that `kubectl cp` works because it does the copy by exec'ing inside the +sandbox, and thus gVisor cache is aware of the new files and dirs. + +There are also different filesystem modes that can be used to avoid this issue. +See [Filesystem](../filesystem/). + +## What's the security model? + +See the [Security Model](../../architecture_guide/security/). + +## What's the expected performance? + +See the [Performance Guide](../../architecture_guide/performance/). diff --git a/content/docs/user_guide/_index.md b/content/docs/user_guide/_index.md new file mode 100644 index 000000000..82b4cf845 --- /dev/null +++ b/content/docs/user_guide/_index.md @@ -0,0 +1,8 @@ ++++ +title = "User Guide" +weight = 10 ++++ + +Using gVisor for the first time? To get started, use either the [Docker Quick +Start](./docker/), the [OCI Quick Start](./oci/) or select a specific topic via +the menu. diff --git a/content/docs/user_guide/checkpoint_restore.md b/content/docs/user_guide/checkpoint_restore.md new file mode 100644 index 000000000..fdecb2d08 --- /dev/null +++ b/content/docs/user_guide/checkpoint_restore.md @@ -0,0 +1,107 @@ ++++ +title = "Checkpoint/Restore" +weight = 90 ++++ +gVisor has the ability to checkpoint a process, save its current state in a +state file, and restore into a new container using the state file. + +## How to use checkpoint/restore + +Checkpoint/restore functionality is currently available via raw `runsc` +commands. To use the checkpoint command, first run a container. + +```bash +runsc run +``` + +To checkpoint the container, the `--image-path` flag must be provided. This is +the directory path within which the checkpoint state-file will be created. The +file will be called `checkpoint.img` and necessary directories will be created +if they do not yet exist. + +> Note: Two checkpoints cannot be saved to the save directory; every image-path +provided must be unique. + +```bash +runsc checkpoint --image-path= +``` + +There is also an optional `--leave-running` flag that allows the container to +continue to run after the checkpoint has been made. (By default, containers stop +their processes after committing a checkpoint.) + +> Note: All top-level runsc flags needed when calling run must be provided to +checkpoint if --leave-running is used. + +> Note: --leave-running functions by causing an immediate restore so the +container, although will maintain its given container id, may have a different +process id. + +```bash +runsc checkpoint --image-path= --leave-running +``` + +To restore, provide the image path to the `checkpoint.img` file created during +the checkpoint. Because containers stop by default after checkpointing, restore +needs to happen in a new container (restore is a command which parallels start). + +```bash +runsc create + +runsc restore --image-path= +``` + +## How to use checkpoint/restore in Docker: + +Currently checkpoint/restore through `runsc` is not entirely compatible with +Docker, although there has been progress made from both gVisor and Docker to +enable compatibility. Here, we document the ideal workflow. + +Run a container: + +```bash +docker run [options] --runtime=runsc ` +``` + +Checkpoint a container: + +```bash +docker checkpoint create ` +``` + +Create a new container into which to restore: + +```bash +docker create [options] --runtime=runsc +``` + +Restore a container: + +```bash +docker start --checkpoint --checkpoint-dir= +``` + +### Issues Preventing Compatibility with Docker + +#### [Moby #37360][leave-running] + +Docker version 18.03.0-ce and earlier hangs when checkpointing and does not +create the checkpoint. To successfully use this feature, install a custom +version of docker-ce from the moby repository. This issue is caused by an +improper implementation of the `--leave-running` flag. This issue is fixed in +newer releases. + +#### Docker does not support restoration into new containers. + +Docker currently expects the container which created the checkpoint to be the +same container used to restore which is not possible in runsc. When Docker +supports container migration and therefore restoration into new containers, this +will be the flow. + +#### [Moby #37344][checkpoint-dir] + +Docker does not currently support the `--checkpoint-dir` flag but this will be +required when restoring from a checkpoint made in another container. + +[leave-running]: https://github.com/moby/moby/pull/37360 +[checkpoint-dir]: https://github.com/moby/moby/issues/37344 diff --git a/content/docs/user_guide/compatibility/_index.md b/content/docs/user_guide/compatibility/_index.md new file mode 100644 index 000000000..cbde08fdb --- /dev/null +++ b/content/docs/user_guide/compatibility/_index.md @@ -0,0 +1,43 @@ ++++ +title = "Compatibility" +weight = 100 ++++ +gVisor implements a large portion of the Linux surface and while we strive to +make it broadly compatible, there are (and always will be) unimplemented +features and bugs. The only real way to know if it will work is to try. If you +find a container that doesn’t work and there is no known issue, please [file a +bug][bug] indicating the full command you used to run the image. + +If you're able to provide the [debug logs](../debugging/), the +problem likely to be fixed much faster. + +## What works? + +The following applications/images have been tested: + +* elasticsearch +* golang +* httpd +* java8 +* jenkins +* mariadb +* memcached +* mongo +* mysql +* nginx +* node +* php +* postgres +* prometheus +* python +* redis +* registry +* tomcat +* wordpress + +[bug]: https://github.com/google/gvisor/issues + +## Syscall Reference + +This section contains an architecture-specific syscall reference guide. These +tables are automatically generated from source-level annotations. diff --git a/content/docs/user_guide/compatibility/amd64.md b/content/docs/user_guide/compatibility/amd64.md new file mode 100644 index 000000000..8a0bf2385 --- /dev/null +++ b/content/docs/user_guide/compatibility/amd64.md @@ -0,0 +1,710 @@ ++++ +title = "AMD64" +weight = 10 ++++ +This table is a reference of Linux syscalls for AMD64 and their compatibility +status in gVisor. gVisor does not support all syscalls and some syscalls may +have a partial implementation. + +Of 329 syscalls, 47 syscalls have a full or partial implementation. There are +currently 51 unimplemented syscalls. 231 syscalls are not yet documented. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#NameSupportGitHub IssueNotes
68msggetUnimplementedReturns ENOSYS
69msgsndUnimplementedReturns ENOSYS
70msgrcvUnimplementedReturns ENOSYS
71msgctlUnimplementedReturns ENOSYS
122setfsuidUnimplementedReturns ENOSYS
123setfsgidUnimplementedReturns ENOSYS
134uselibUnimplementedReturns ENOSYS; Obsolete
135setpersonalityPartialReturns EINVAL; Unable to change personality
136ustatUnimplementedReturns ENOSYS; Needs filesystem support
139sysfsUnimplementedReturns ENOSYS
142schedsetparamPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_nice; ENOSYS otherwise
148schedrrgetintervalPartialReturns EPERM
153vhangupPartialReturns EPERM
154modifyldtPartialReturns EPERM
155pivotrootPartialReturns EPERM
156sysctlPartialReturns EPERM
159adjtimexPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_time; ENOSYS otherwise
163acctPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_pacct; ENOSYS otherwise
164settimeofdayPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_time; ENOSYS otherwise
167swaponPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
168swapoffPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
169rebootPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_boot; ENOSYS otherwise
172ioplPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_rawio; ENOSYS otherwise
173iopermPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_rawio; ENOSYS otherwise
174createmodulePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_module; ENOSYS otherwise
175initmodulePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_module; ENOSYS otherwise
176deletemodulePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_module; ENOSYS otherwise
177getkernelsymsUnimplementedReturns ENOSYS; Not supported in > 2.6
178querymoduleUnimplementedReturns ENOSYS; Not supported in > 2.6
179quotactlPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
180nfsservctlUnimplementedReturns ENOSYS; Does not exist > 3.1
181getpmsgUnimplementedReturns ENOSYS; Not implemented in Linux
182putpmsgUnimplementedReturns ENOSYS; Not implemented in Linux
183afssyscallUnimplementedReturns ENOSYS; Not implemented in Linux
184tuxcallUnimplementedReturns ENOSYS; Not implemented in Linux
185securityUnimplementedReturns ENOSYS; Not implemented in Linux
187readaheadUnimplementedReturns ENOSYS
188setxattrPartialReturns ENOTSUP; Requires filesystem support
189lsetxattrPartialReturns ENOTSUP; Requires filesystem support
190fsetxattrPartialReturns ENOTSUP; Requires filesystem support
191getxattrPartialReturns ENOTSUP; Requires filesystem support
192lgetxattrPartialReturns ENOTSUP; Requires filesystem support
193fgetxattrPartialReturns ENOTSUP; Requires filesystem support
194listxattrPartialReturns ENOTSUP; Requires filesystem support
195llistxattrPartialReturns ENOTSUP; Requires filesystem support
196flistxattrPartialReturns ENOTSUP; Requires filesystem support
197removexattrPartialReturns ENOTSUP; Requires filesystem support
198lremovexattrPartialReturns ENOTSUP; Requires filesystem support
199fremovexattrPartialReturns ENOTSUP; Requires filesystem support
205setthreadareaUnimplementedReturns ENOSYS; Expected to return ENOSYS on 64-bit
211getthreadareaUnimplementedReturns ENOSYS; Expected to return ENOSYS on 64-bit
212lookupdcookiePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
214epollctloldUnimplementedReturns ENOSYS; Deprecated
215epollwaitoldUnimplementedReturns ENOSYS; Deprecated
216remapfilepagesUnimplementedReturns ENOSYS; Deprecated
220semtimedopUnimplementedReturns ENOSYS
236vserverUnimplementedReturns ENOSYS; Not implemented by Linux
237mbindPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_nice; ENOSYS otherwise
240mqopenUnimplementedReturns ENOSYS
241mqunlinkUnimplementedReturns ENOSYS
242mqtimedsendUnimplementedReturns ENOSYS
243mqtimedreceiveUnimplementedReturns ENOSYS
244mqnotifyUnimplementedReturns ENOSYS
245mqgetsetattrUnimplementedReturns ENOSYS
248addkeyPartialReturns EACCES; Not available to user
249requestkeyPartialReturns EACCES; Not available to user
250keyctlPartialReturns EACCES; Not available to user
251iopriosetPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
252iopriogetPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_admin; ENOSYS otherwise
256migratepagesPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_nice; ENOSYS otherwise
273setrobustlistUnimplementedReturns ENOSYS; Obsolete
274getrobustlistUnimplementedReturns ENOSYS; Obsolete
275spliceUnimplementedReturns ENOSYS
276teeUnimplementedReturns ENOSYS
278vmspliceUnimplementedReturns ENOSYS
279movepagesPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_nice; ENOSYS otherwise
282signalfdUnimplementedReturns ENOSYS
289signalfd4UnimplementedReturns ENOSYS
298perfeventopenPartialReturns ENODEV; No support for perf counters
300fanotifyinitUnimplementedReturns ENOSYS; Needs CONFIG_FANOTIFY
301fanotifymarkUnimplementedReturns ENOSYS; Needs CONFIG_FANOTIFY
303nametohandleatPartialReturns EOPNOTSUPP; Needs filesystem support
304openbyhandleatPartialReturns EOPNOTSUPP; Needs filesystem support
305clockadjtimePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_module; ENOSYS otherwise
308setnsUnimplementedReturns ENOSYS
310processvmreadvUnimplementedReturns ENOSYS
311processvmwritevUnimplementedReturns ENOSYS
312kcmpPartialReturns EPERM or ENOSYS; Requires cap_sys_ptrace
313finitmodulePartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_module; ENOSYS otherwise
314schedsetattrUnimplementedReturns ENOSYS
315schedgetattrUnimplementedReturns ENOSYS
316renameat2UnimplementedReturns ENOSYS
319memfdcreateUnimplementedReturns ENOSYS
321bpfPartialReturns EPERM or ENOSYS; Returns EPERM if the process does not have cap_sys_boot; ENOSYS otherwise
322execveatUnimplementedReturns ENOSYS
323userfaultfdUnimplementedReturns ENOSYS
324membarrierUnimplementedReturns ENOSYS
326copyfilerangeUnimplementedReturns ENOSYS
diff --git a/content/docs/user_guide/debugging.md b/content/docs/user_guide/debugging.md new file mode 100644 index 000000000..561aeb8d7 --- /dev/null +++ b/content/docs/user_guide/debugging.md @@ -0,0 +1,33 @@ ++++ +title = "Debugging" +weight = 120 ++++ + +To enable debug and system call logging, add the `runtimeArgs` below to your +[Docker](../docker/) configuration (`/etc/docker/daemon.json`): + +```json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc", + "runtimeArgs": [ + "--debug-log=/tmp/runsc/", + "--debug", + "--strace" + ] + } + } +} +``` + +You may also want to pass `--log-packets` to troubleshoot network problems. Then +restart the Docker daemon: + +```bash +sudo systemctl restart docker +``` + +Run your container again, and inspect the files under `/tmp/runsc`. The log file +with name `boot` will contain the strace logs from your application, which can +be useful for identifying missing or broken system calls in gVisor. diff --git a/content/docs/user_guide/docker.md b/content/docs/user_guide/docker.md new file mode 100644 index 000000000..3123785a7 --- /dev/null +++ b/content/docs/user_guide/docker.md @@ -0,0 +1,81 @@ ++++ +title = "Docker Quick Start" +weight = 10 ++++ +This guide will help you quickly get started running Docker containers using +gVisor with the default platform. + +## Install gVisor + +{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}} + +## Configuring Docker + +> Note: This guide requires Docker. Refer to the [Docker documentation][docker] 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][storage-driver]. + +In the end, the file should look something like: + +```json +{ + "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`: + +```bash +sudo systemctl restart docker +``` + +## Running a container + +Now run your container using the `runsc` runtime: + +```bash +docker run --runtime=runsc hello-world +``` + +You can also run a terminal to explore the container. + +```bash +docker run --runtime=runsc -it ubuntu /bin/bash +``` + +## Verify the runtime + +You can verify that you are running in gVisor using the `dmesg` command. + +```text +$ 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, try running gVisor using the [KVM platform](../platforms/). + +[docker]: https://docs.docker.com/install/ +[storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver diff --git a/content/docs/user_guide/filesystem.md b/content/docs/user_guide/filesystem.md new file mode 100644 index 000000000..314040804 --- /dev/null +++ b/content/docs/user_guide/filesystem.md @@ -0,0 +1 @@ +TODO: Add information about shared/exclusive modes? diff --git a/content/docs/user_guide/kubernetes.md b/content/docs/user_guide/kubernetes.md new file mode 100644 index 000000000..a1150622f --- /dev/null +++ b/content/docs/user_guide/kubernetes.md @@ -0,0 +1,16 @@ ++++ +title = "Kubernetes" +weight = 30 ++++ +gVisor can run sandboxed containers in a Kubernetes cluster with Minikube. After +the gVisor addon is enabled, pods with `io.kubernetes.cri.untrusted-workload` +set to true will execute with `runsc`. Follow [these instructions][minikube] to +enable gVisor addon. + +You can also setup Kubernetes nodes to run pods in gvisor using the `containerd` +CRI runtime and the `gvisor-containerd-shim`. Pods with the +`io.kubernetes.cri.untrusted-workload` annotation will execute with `runsc`. You +can find instructions [here][gvisor-containerd-shim]. + +[minikube]: https://github.com/kubernetes/minikube/blob/master/deploy/addons/gvisor/README.md +[gvisor-containerd-shim]: https://github.com/google/gvisor-containerd-shim diff --git a/content/docs/user_guide/networking.md b/content/docs/user_guide/networking.md new file mode 100644 index 000000000..09d4b9789 --- /dev/null +++ b/content/docs/user_guide/networking.md @@ -0,0 +1,36 @@ ++++ +title = "Networking" +weight = 50 ++++ +gVisor implements its own network stack called [netstack][netstack]. All aspects +of the network stack are handled inside the Sentry — including TCP connection +state, control messages, and packet assembly — keeping it isolated from the host +network stack. Data link layer packets are written directly to the virtual +device inside the network namespace setup by Docker or Kubernetes. + +A network passthrough mode is also supported, but comes at the cost of reduced +isolation. + +## Enabling network passthrough + +For high-performance networking applications, you may choose to disable the user +space network stack and instead use the host network stack. Note that this mode +decreases the isolation to the host. + +Add the following `runtimeArgs` to your Docker configuration +(`/etc/docker/daemon.json`) and restart the Docker daemon: + +```json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc", + "runtimeArgs": [ + "--network=host" + ] + } + } +} +``` + +[netstack]: https://github.com/google/netstack diff --git a/content/docs/user_guide/oci.md b/content/docs/user_guide/oci.md new file mode 100644 index 000000000..49b94bdd3 --- /dev/null +++ b/content/docs/user_guide/oci.md @@ -0,0 +1,53 @@ ++++ +title = "OCI Quick Start" +weight = 20 ++++ +This guide will quickly get you started running your first gVisor sandbox +container using the runtime directly with the default platform. + +## Install gVisor + +{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}} + +## Run an OCI compatible container + +Now we will create an [OCI][oci] container bundle to run our container. First we +will create a root directory for our bundle. + +```bash +{ + mkdir bundle + cd bundle +} +``` + +Create a root file system for the container. We will use the Docker hello-world +image as the basis for our container. + +```bash +{ + mkdir rootfs + docker export $(docker create hello-world) | tar -xf - -C rootfs +} +``` + +Next, create an specification file called `config.json` that contains our +container specification. We will update the default command it runs to `/hello` +in the `hello-world` container. + +```bash +{ + runsc spec + sed -i 's;"sh";"/hello";' config.json +} +``` + +Finally run the container. + +```bash +sudo runsc run hello +``` + +Next try [running gVisor using Docker](../docker/). + +[oci]: https://opencontainers.org/ diff --git a/content/docs/user_guide/platforms.md b/content/docs/user_guide/platforms.md new file mode 100644 index 000000000..755dadf75 --- /dev/null +++ b/content/docs/user_guide/platforms.md @@ -0,0 +1,108 @@ ++++ +title = "Platforms (KVM)" +weight = 30 ++++ + +This document will help you set up your system to use a different gVisor +platform. + +## What is a Platform? + +gVisor requires a *platform* to implement basic context switching and memory +mapping functionality. These are described in more depth in the [Architecture +Guide](../../architecture_guide/). + +## Selecting a Platform + +The platform is selected by a `--platform` command line flag passed to `runsc`. +To select a different platform, modify your Docker configuration +(`/etc/docker/daemon.json`) to pass this argument: + +```json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc", + "runtimeArgs": [ + "--platform=kvm" + ] + } + } +} +``` + +Then restart the Docker daemon. + +## Example: Using the KVM Platform + +The KVM platform is currently experimental; however, it provides several +benefits over the default ptrace platform. + +### Prerequisites + +You will also to have KVM installed on your system. If you are running a Debian +based system like Debian or Ubuntu you can usually do this by installing the +`qemu-kvm` package. + +```bash +sudo apt-get install qemu-kvm +``` + +If you are using a virtual machine you will need to make sure that nested +virtualization is configured. Here are links to documents on how to set up +nested virtualization in several popular environments. + + * Google Cloud: [Enabling Nested Virtualization for VM Instances][nested-gcp] + * Microsoft Azure: [How to enable nested virtualization in an Azure VM][nested-azure] + * VirtualBox: [Nested Virtualization][nested-virtualbox] + * KVM: [Nested Guests][nested-kvm] + +### Configuring Docker + +Per above, you will need to configure Docker to use `runsc` with the KVM +platform. You will remember from the Docker Quick Start that you configured +Docker to use `runsc` as the runtime. Docker allows you to add multiple +runtimes to the Docker configuration. + +Add a new entry for the KVM platform entry to your Docker configuration +(`/etc/docker/daemon.json`) in order to provide the `--platform=kvm` runtime +argument. + +In the end, the file should look something like: + +```json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc" + }, + "runsc-kvm": { + "path": "/usr/local/bin/runsc", + "runtimeArgs": [ + "--platform=kvm" + ] + } + } +} +``` + +You must restart the Docker daemon after making changes to this file, typically +this is done via `systemd`: + +```bash +sudo systemctl restart docker +``` + +## Running a container + +Now run your container using the `runsc-kvm` runtime. This will run the +container using the KVM platform: + +```bash +docker run --runtime=runsc-kvm hello-world +``` + +[nested-azure]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization +[nested-gcp]: https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances +[nested-virtualbox]: https://www.virtualbox.org/manual/UserManual.html#nested-virt +[nested-kvm]: https://www.linux-kvm.org/page/Nested_Guests -- cgit v1.2.3