diff options
Diffstat (limited to 'website/content/docs/user_guide')
-rwxr-xr-x | website/content/docs/user_guide/FAQ.md | 118 | ||||
-rwxr-xr-x | website/content/docs/user_guide/checkpoint_restore.md | 104 | ||||
-rwxr-xr-x | website/content/docs/user_guide/compatibility/.gitignore | 1 | ||||
-rwxr-xr-x | website/content/docs/user_guide/compatibility/index.md | 93 | ||||
-rwxr-xr-x | website/content/docs/user_guide/debugging.md | 135 | ||||
-rwxr-xr-x | website/content/docs/user_guide/filesystem.md | 63 | ||||
-rwxr-xr-x | website/content/docs/user_guide/install.md | 163 | ||||
-rwxr-xr-x | website/content/docs/user_guide/networking.md | 89 | ||||
-rwxr-xr-x | website/content/docs/user_guide/platforms.md | 122 | ||||
-rwxr-xr-x | website/content/docs/user_guide/quick_start/docker.md | 98 | ||||
-rwxr-xr-x | website/content/docs/user_guide/quick_start/kubernetes.md | 43 | ||||
-rwxr-xr-x | website/content/docs/user_guide/quick_start/oci.md | 51 |
12 files changed, 0 insertions, 1080 deletions
diff --git a/website/content/docs/user_guide/FAQ.md b/website/content/docs/user_guide/FAQ.md deleted file mode 100755 index 951192495..000000000 --- a/website/content/docs/user_guide/FAQ.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "FAQ" -permalink: /docs/user_guide/FAQ/ -layout: docs -category: User Guide -weight: 90 ---- - -### What operating systems are supported? {#supported-os} - -Today, gVisor requires Linux. - -### What CPU architectures are supported? {#supported-cpus} - -gVisor currently supports [x86_64/AMD64](https://en.wikipedia.org/wiki/X86-64) -compatible processors. - -### Do I need to modify my Linux application to use gVisor? {#modify-app} - -No. gVisor is capable of running unmodified Linux binaries. - -### What binary formats does gVisor support? {#supported-binaries} - -gVisor supports Linux -[ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) binaries. -Binaries run in gVisor should be built for the -[AMD64](https://en.wikipedia.org/wiki/X86-64) CPU architecture. - -### Can I run Docker images using gVisor? {#docker-images} - -Yes. Please see the [Docker Quick Start][docker]. - -### Can I run Kubernetes pods using gVisor? {#k8s-pods} - -Yes. Please see the [Kubernetes Quick Start][k8s]. - -### What's the security model? {#security-model} - -See the [Security Model][security-model]. - -## Troubleshooting - -### My container runs fine with `runc` but fails with `runsc` {#app-compatibility} - -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: `open /run/containerd/.../<containerid>/log.json: no such file or directory` {#memfd-create} - -You are using an older version of Linux which doesn't support `memfd_create`. - -This is tracked in [bug #268](https://gvisor.dev/issue/268). - -### When I run my container, docker fails with: `flag provided but not defined: -console` {#old-docker} - -You're using an old version of Docker. See [Docker Quick Start][docker]. - -### I can’t see a file copied with: `docker cp` {#fs-cache} - -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. - -As a workaround, shared root filesystem can be enabled. See [Filesystem][filesystem]. - -This bug is tracked in [bug #4](https://gvisor.dev/issue/4). - -Note that `kubectl cp` works because it does the copy by exec'ing inside the -sandbox, and thus gVisor's internal cache is made aware of the new files and -directories. - -### I'm getting an error like: `panic: unable to attach: operation not permitted` or `fork/exec /proc/self/exe: invalid argument: unknown` {#runsc-perms} - -Make sure that permissions and the owner is correct on the `runsc` binary. - -```bash -sudo chown root:root /usr/local/bin/runsc -sudo chmod 0755 /usr/local/bin/runsc -``` - -### I'm getting an error like `mount submount "/etc/hostname": creating mount with source ".../hostname": input/output error: unknown.` {#memlock} - -There is a bug in Linux kernel versions 5.1 to 5.3.15, 5.4.2, and 5.5. Upgrade to a newer kernel or add the following to `/lib/systemd/system/containerd.service` as a workaround. - -``` -LimitMEMLOCK=infinity -``` - -And run `systemctl daemon-reload && systemctl restart containerd` to restart containerd. - -See [issue #1765](https://gvisor.dev/issue/1765) for more details. - -### My container cannot resolve another container's name when using Docker user defined bridge {#docker-bridge} - -This is normally indicated by errors like `bad address 'container-name'` when -trying to communicate to another container in the same network. - -Docker user defined bridge uses an embedded DNS server bound to the loopback -interface on address 127.0.0.10. This requires access to the host network in -order to communicate to the DNS server. runsc network is isolated from the -host and cannot access the DNS server on the host network without breaking the -sandbox isolation. There are a few different workarounds you can try: - -* Use default bridge network with `--link` to connect containers. Default - bridge doesn't use embedded DNS. -* Use [`--network=host`][host-net] option in runsc, however beware that it will - use the host network stack and is less secure. -* Use IPs instead of container names. -* Use [Kubernetes][k8s]. Container name lookup works fine in Kubernetes. - -[security-model]: /docs/architecture_guide/security/ -[host-net]: /docs/user_guide/networking/#network-passthrough -[debugging]: /docs/user_guide/debugging/ -[filesystem]: /docs/user_guide/filesystem/ -[docker]: /docs/user_guide/quick_start/docker/ -[k8s]: /docs/user_guide/quick_start/kubernetes/ diff --git a/website/content/docs/user_guide/checkpoint_restore.md b/website/content/docs/user_guide/checkpoint_restore.md deleted file mode 100755 index c7179b550..000000000 --- a/website/content/docs/user_guide/checkpoint_restore.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Checkpoint/Restore" -permalink: /docs/user_guide/checkpoint_restore/ -layout: docs -category: User Guide -weight: 60 ---- -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 <container id> -``` - -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 same directory; every image-path -> provided must be unique. - -```bash -runsc checkpoint --image-path=<path> <container id> -``` - -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=<path> --leave-running <container id> -``` - -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 <container id> - -runsc restore --image-path=<path> <container id> -``` - -## 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 <image>` -``` - -Checkpoint a container: - -```bash -docker checkpoint create <container> <checkpoint_name>` -``` - -Create a new container into which to restore: - -```bash -docker create [options] --runtime=runsc <image> -``` - -Restore a container: - -```bash -docker start --checkpoint --checkpoint-dir=<directory> <container> -``` - -### 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/website/content/docs/user_guide/compatibility/.gitignore b/website/content/docs/user_guide/compatibility/.gitignore deleted file mode 100755 index a08e1f35e..000000000 --- a/website/content/docs/user_guide/compatibility/.gitignore +++ /dev/null @@ -1 +0,0 @@ -linux diff --git a/website/content/docs/user_guide/compatibility/index.md b/website/content/docs/user_guide/compatibility/index.md deleted file mode 100755 index 374a0992b..000000000 --- a/website/content/docs/user_guide/compatibility/index.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Applications -layout: docs -category: Compatibility -weight: 0 -permalink: /docs/user_guide/compatibility/ ---- - -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. You can view -open issues related to compatibility [here][issues]. - -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 - -## Utilities - -Most common utilities work. Note that: - -* Some tools, such as `tcpdump` and old versions of `ping`, require explicitly - enabling raw sockets via the unsafe `--net-raw` runsc flag. -* Different Docker images can behave differently. For example, Alpine Linux and - Ubuntu have different `ip` binaries. - - Specific tools include: - -| Tool | Status | -| --- | --- | -| apt-get | Working | -| bundle | Working | -| cat | Working | -| curl | Working | -| dd | Working | -| df | Working | -| dig | Working | -| drill | Working | -| env | Working | -| find | Working | -| gdb | Working | -| gosu | Working | -| grep | Working (unless stdin is a pipe and stdout is /dev/null) | -| ifconfig | Works partially, like ip. Full support [in progress](https://gvisor.dev/issue/578) | -| ip | Some subcommands work (e.g. addr, route). Full support [in progress](https://gvisor.dev/issue/578) | -| less | Working | -| ls | Working | -| lsof | Working | -| mount | Works in readonly mode. gVisor doesn't currently support creating new mounts at runtime | -| nc | Working | -| nmap | Not working | -| netstat | [In progress](https://gvisor.dev/issue/2112) | -| nslookup | Working | -| ping | Working | -| ps | Working | -| route | Working | -| ss | [In progress](https://gvisor.dev/issue/2114) | -| sshd | Partially working. Job control [in progress](https://gvisor.dev/issue/154) | -| strace | Working | -| tar | Working | -| tcpdump | [In progress](https://gvisor.dev/issue/173) | -| top | Working | -| uptime | Working | -| vim | Working | -| wget | Working | - -[bug]: https://github.com/google/gvisor/issues/new?title=Compatibility%20Issue: -[issues]: https://github.com/google/gvisor/issues?q=is%3Aissue+is%3Aopen+label%3A%22area%3A+compatibility%22 diff --git a/website/content/docs/user_guide/debugging.md b/website/content/docs/user_guide/debugging.md deleted file mode 100755 index 9353ac907..000000000 --- a/website/content/docs/user_guide/debugging.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Debugging" -permalink: /docs/user_guide/debugging/ -layout: docs -category: User Guide -weight: 70 ---- - -To enable debug and system call logging, add the `runtimeArgs` below to your -[Docker](../quick_start/docker/) configuration (`/etc/docker/daemon.json`): - -```json -{ - "runtimes": { - "runsc": { - "path": "/usr/local/bin/runsc", - "runtimeArgs": [ - "--debug-log=/tmp/runsc/", - "--debug", - "--strace" - ] - } - } -} -``` - -> Note: the last `/` in `--debug-log` is needed to interpret it as a directory. -> Then each `runsc` command executed will create a separate log file. -> Otherwise, log messages from all commands will be appended to the same file. - -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 -ending with `.boot` will contain the strace logs from your application, which can -be useful for identifying missing or broken system calls in gVisor. If you are -having problems starting the container, the log file ending with `.create` may -have the reason for the failure. - -## Stack traces - -The command `runsc debug --stacks` collects stack traces while the sandbox is -running which can be useful to troubleshoot issues or just to learn more about -gVisor. It connects to the sandbox process, collects a stack dump, and writes -it to the console. For example: - -```bash -docker run --runtime=runsc --rm -d alpine sh -c "while true; do echo running; sleep 1; done" -63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b - -sudo runsc --root /var/run/docker/runtime-runsc/moby debug --stacks 63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b -``` - -> Note: `--root` variable is provided by docker and is normally set to -> `/var/run/docker/runtime-[runtime-name]/moby`. If in doubt, `--root` is logged to -> `runsc` logs. - -## Debugger - -You can debug gVisor like any other Golang program. If you're running with Docker, -you'll need to find the sandbox PID and attach the debugger as root. Here is an -example: - -```bash -# Get a runsc with debug symbols (download nightly or build with symbols). -bazel build -c dbg //runsc:runsc - -# Start the container you want to debug. -docker run --runtime=runsc --rm --name=test -d alpine sleep 1000 - -# Find the sandbox PID. -docker inspect test | grep Pid | head -n 1 - -# Attach your favorite debugger. -sudo dlv attach <PID> - -# Set a breakpoint and resume. -break mm.MemoryManager.MMap -continue -``` - -## Profiling - -`runsc` integrates with Go profiling tools and gives you easy commands to profile -CPU and heap usage. First you need to enable `--profile` in the command line options -before starting the container: - -```json -{ - "runtimes": { - "runsc-prof": { - "path": "/usr/local/bin/runsc", - "runtimeArgs": [ - "--profile" - ] - } - } -} -``` - -> Note: Enabling profiling loosens the seccomp protection added to the sandbox, -> and should not be run in production under normal circumstances. - -Then restart docker to refresh the runtime options. While the container is running, -execute `runsc debug` to collect profile information and save to a file. Here are -the options available: - -* **--profile-heap:** Generates heap profile to the speficied file. -* **--profile-cpu:** Enables CPU profiler, waits for `--duration` seconds - and generates CPU profile to the speficied file. - -For example: - -```bash -docker run --runtime=runsc-prof --rm -d alpine sh -c "while true; do echo running; sleep 1; done" -63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b - -sudo runsc --root /var/run/docker/runtime-runsc-prof/moby debug --profile-heap=/tmp/heap.prof 63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b -sudo runsc --root /var/run/docker/runtime-runsc-prof/moby debug --profile-cpu=/tmp/cpu.prof --duration=30s 63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b -``` - -The resulting files can be opened using `go tool pprof` or [pprof][]. The examples -below create image file (`.svg`) with the heap profile and writes the top -functions using CPU to the console: - -```bash -go tool pprof -svg /usr/local/bin/runsc /tmp/heap.prof -go tool pprof -top /usr/local/bin/runsc /tmp/cpu.prof -``` - -[pprof]: https://github.com/google/pprof/blob/master/doc/README.md diff --git a/website/content/docs/user_guide/filesystem.md b/website/content/docs/user_guide/filesystem.md deleted file mode 100755 index a320b95f3..000000000 --- a/website/content/docs/user_guide/filesystem.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Filesystem" -permalink: /docs/user_guide/filesystem/ -layout: docs -category: User Guide -weight: 40 ---- - -gVisor accesses the filesystem through a file proxy, called the Gofer. The gofer -runs as a separate process, that is isolated from the sandbox. Gofer instances -communicate with their respective sentry using the 9P protocol. For a more detailed -explanation see [Overview > Gofer](../../architecture_guide/#gofer). - -## Sandbox overlay - -To isolate the host filesystem from the sandbox, you can set a writable tmpfs overlay -on top of the entire filesystem. All modifications are made to the overlay, keeping -the host filesystem unmodified. - -> Note: All created and modified files are stored in memory inside the sandbox. - -To use the tmpfs overlay, 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": [ - "--overlay" - ] - } - } -} -``` - -## Shared root filesystem - -The root filesystem is where the image is extracted and is not generally modified -from outside the sandbox. This allows for some optimizations, like skipping checks -to determine if a directory has changed since the last time it was cached, thus -missing updates that may have happened. If you need to `docker cp` files inside the -root filesystem, you may want to enable shared mode. Just be aware that file system -access will be slower due to the extra checks that are required. - -> Note: External mounts are always shared. - -To use set the root filesystem shared, 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": [ - "--file-access=shared" - ] - } - } -} -``` diff --git a/website/content/docs/user_guide/install.md b/website/content/docs/user_guide/install.md deleted file mode 100755 index c5d4891bb..000000000 --- a/website/content/docs/user_guide/install.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Installation" -permalink: /docs/user_guide/install/ -layout: docs -category: User Guide -weight: 10 ---- - -{% include required_linux.html %} - -## Versions - -The `runsc` binaries and repositories are available in multiple versions and -release channels. You should pick the version you'd like to install. For -experimentation, the nightly release is recommended. For production use, the -latest release is recommended. - -After selecting an appropriate release channel from the options below, proceed -to the preferred installation mechanism: manual or from an `apt` repository. - -### HEAD - -Binaries are available for every commit on the `master` branch, and are -available at the following URL: - - `https://storage.googleapis.com/gvisor/releases/master/latest/runsc` - -Checksums for the release binary are at: - - `https://storage.googleapis.com/gvisor/releases/master/latest/runsc.sha512` - -For `apt` installation, use the `master` as the `${DIST}` below. - -### Nightly - -Nightly releases are built most nights from the master branch, and are available -at the following URL: - - `https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc` - -Checksums for the release binary are at: - - `https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512` - -Specific nightly releases can be found at: - - `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc` - -Note that a release may not be available for every day. - -For `apt` installation, use the `nightly` as the `${DIST}` below. - -### Latest release - -The latest official release is available at the following URL: - - `https://storage.googleapis.com/gvisor/releases/release/latest` - -For `apt` installation, use the `release` as the `${DIST}` below. - -### Specific release - -A given release release is available at the following URL: - - `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}` - -See the [releases][releases] page for information about specific releases. - -For `apt` installation of a specific release, which may include point updates, -use the date of the release, e.g. `${yyyymmdd}`, as the `${DIST}` below. - -> Note: only newer releases may be available as `apt` repositories. - -### Point release - -A given point release is available at the following URL: - - `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}` - -Note that `apt` installation of a specific point release is not supported. - -## Install from an `apt` repository - -First, appropriate dependencies must be installed to allow `apt` to install -packages via https: - -```bash -sudo apt-get update && \ -sudo apt-get install -y \ - apt-transport-https \ - ca-certificates \ - curl \ - gnupg-agent \ - software-properties-common -``` - -Next, the key used to sign archives should be added to your `apt` keychain: - -```bash -curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add - -``` - -Based on the release type, you will need to substitute `${DIST}` below, using -one of: - -* `master`: For HEAD. -* `nightly`: For nightly releases. -* `release`: For the latest release. -* `${yyyymmdd}`: For a specific releases (see above). - -The repository for the release you wish to install should be added: - -```bash -sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases ${DIST} main" -``` - -For example, to install the latest official release, you can use: - -```bash -sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main" -``` - -Now the runsc package can be installed: - -```bash -sudo apt-get update && sudo apt-get install -y runsc -``` - -If you have Docker installed, it will be automatically configured. - -## Install directly - -The binary URLs provided above can be used to install directly. For example, the -latest nightly binary can be downloaded, validated, and placed in an appropriate -location by running: - -```bash -( - set -e - URL=https://storage.googleapis.com/gvisor/releases/nightly/latest - wget ${URL}/runsc - wget ${URL}/runsc.sha512 - sha512sum -c runsc.sha512 - rm -f runsc.sha512 - sudo mv runsc /usr/local/bin - sudo chown root:root /usr/local/bin/runsc - sudo chmod 0755 /usr/local/bin/runsc -) -``` - -**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. - -After installation, the`runsc` binary comes with an `install` command that can -optionally automatically configure Docker: - -```bash -runsc install -``` - -[releases]: https://github.com/google/gvisor/releases diff --git a/website/content/docs/user_guide/networking.md b/website/content/docs/user_guide/networking.md deleted file mode 100755 index 0971a38ff..000000000 --- a/website/content/docs/user_guide/networking.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Networking" -permalink: /docs/user_guide/networking/ -layout: docs -category: User Guide -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. - -The IP address and routes configured for the device are transferred inside the -sandbox. The loopback device runs exclusively inside the sandbox and does not -use the host. You can inspect them by running: - -```bash -docker run --rm --runtime=runsc alpine ip addr -``` - -## Network passthrough - -For high-performance networking applications, you may choose to disable the user -space network stack and instead use the host network stack, including the loopback. -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" - ] - } - } -} -``` - -## Disabling external networking - -To completely isolate the host and network from the sandbox, external -networking can be disabled. The sandbox will still contain a loopback provided -by netstack. - -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=none" - ] - } - } -} -``` - -### Disable GSO {#gso} - -If your Linux is older than 4.14.17, you can disable Generic Segmentation -Offload (GSO) to run with a kernel that is newer than 3.17. Add the -`--gso=false` flag to your Docker runtime configuration -(`/etc/docker/daemon.json`) and restart the Docker daemon: - -> Note: Network performance, especially for large payloads, will be greatly reduced. - -```json -{ - "runtimes": { - "runsc": { - "path": "/usr/local/bin/runsc", - "runtimeArgs": [ - "--gso=false" - ] - } - } -} -``` - -[netstack]: https://github.com/google/netstack diff --git a/website/content/docs/user_guide/platforms.md b/website/content/docs/user_guide/platforms.md deleted file mode 100755 index b32386bc9..000000000 --- a/website/content/docs/user_guide/platforms.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Platforms (KVM)" -permalink: /docs/user_guide/platforms/ -layout: docs -category: User Guide -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 interception of syscalls, basic -context switching, and memory mapping functionality. These are described in -more depth in the [Platform Design](../../architecture_guide/platforms/). - -## Selecting a Platform - -The platform is selected by the `--platform` command line flag passed to -`runsc`. By default, the ptrace platform is selected. 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" - ] - } - } -} -``` - -You must restart the Docker daemon after making changes to this file, typically -this is done via `systemd`: - -```bash -sudo systemctl restart docker -``` - -## 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] - -***Note: nested virtualization will have poor performance and is historically a -cause of security issues (e.g. -[CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not -recommended for production.*** - -### 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 --rm 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 diff --git a/website/content/docs/user_guide/quick_start/docker.md b/website/content/docs/user_guide/quick_start/docker.md deleted file mode 100755 index 4afeb3e2f..000000000 --- a/website/content/docs/user_guide/quick_start/docker.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "Docker Quick Start" -permalink: /docs/user_guide/quick_start/docker/ -layout: docs -category: User Guide -subcategory: Quick Start -weight: 15 ---- - -> Note: This guide requires Docker version 17.09.0 or greater. Refer to the -> [Docker documentation][docker] for how to install it. - -This guide will help you quickly get started running Docker containers using -gVisor. - -First, follow the [Installation guide][install]. - -If you use the `apt` repository or the `automated` install, then you can skip -the next section and proceed straight to running a container. - -## Configuring Docker - -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 --rm hello-world -``` - -You can also run a terminal to explore the container. - -```bash -docker run --runtime=runsc --rm -it ubuntu /bin/bash -``` - -Many docker options are compatible with gVisor, try them out. Here is an example: - -```bash -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. - -```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, look at the different options available for gVisor: [platform][platforms], -[network][networking], [filesystem][filesystem]. - -[docker]: https://docs.docker.com/install/ -[storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver -[install]: /docs/user_guide/install/ -[filesystem]: /docs/user_guide/filesystem/ -[networking]: /docs/user_guide/networking/ -[platforms]: /docs/user_guide/platforms/ diff --git a/website/content/docs/user_guide/quick_start/kubernetes.md b/website/content/docs/user_guide/quick_start/kubernetes.md deleted file mode 100755 index 689305082..000000000 --- a/website/content/docs/user_guide/quick_start/kubernetes.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Kubernetes" -permalink: /docs/user_guide/quick_start/kubernetes/ -layout: docs -category: User Guide -subcategory: Quick Start -weight: 17 ---- - -gVisor can be used to run Kubernetes pods and has several integration points -with Kubernetes. - -## Using Minikube - -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. - -## Using Containerd - -You can also setup Kubernetes nodes to run pods in gvisor using the -[containerd][containerd] CRI runtime and the `gvisor-containerd-shim`. You can -use either the `io.kubernetes.cri.untrusted-workload` annotation or -[RuntimeClass][runtimeclass] to run Pods with `runsc`. You can find -instructions [here][gvisor-containerd-shim]. - -## Using GKE Sandbox - -[GKE Sandbox][gke-sandbox] is available in [Google Kubernetes Engine][gke]. You -just need to deploy a node pool with gVisor enabled in your cluster, and it will -run pods annotated with `runtimeClassName: gvisor` inside a gVisor sandbox for -you. [Here][wordpress-quick] is a quick example showing how to deploy a -WordPress site. You can view the full documentation [here][gke-sandbox-docs]. - -[containerd]: https://containerd.io/ -[minikube]: https://github.com/kubernetes/minikube/blob/master/deploy/addons/gvisor/README.md -[gke]: https://cloud.google.com/kubernetes-engine/ -[gke-sandbox]: https://cloud.google.com/kubernetes-engine/sandbox/ -[gke-sandbox-docs]: https://cloud.google.com/kubernetes-engine/docs/how-to/sandbox-pods -[gvisor-containerd-shim]: https://github.com/google/gvisor-containerd-shim -[runtimeclass]: https://kubernetes.io/docs/concepts/containers/runtime-class/ -[wordpress-quick]: /docs/tutorials/kubernetes/ diff --git a/website/content/docs/user_guide/quick_start/oci.md b/website/content/docs/user_guide/quick_start/oci.md deleted file mode 100755 index 62e49e409..000000000 --- a/website/content/docs/user_guide/quick_start/oci.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "OCI Quick Start" -permalink: /docs/user_guide/quick_start/oci/ -layout: docs -category: User Guide -subcategory: Quick Start -weight: 19 ---- - -This guide will quickly get you started running your first gVisor sandbox -container using the runtime directly with the default platform. - -First, follow the [Installation guide][install]. - -## 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 [using CNI to set up networking](../../../tutorials/cni/) or [running gVisor using Docker](../docker/). - -[oci]: https://opencontainers.org/ -[install]: /docs/user_guide/install |