diff options
| -rw-r--r-- | content/docs/user_guide/FAQ.md | 7 | ||||
| -rw-r--r-- | content/docs/user_guide/debugging.md | 12 | ||||
| -rw-r--r-- | content/docs/user_guide/docker.md | 15 | ||||
| -rw-r--r-- | content/docs/user_guide/filesystem.md | 59 | ||||
| -rw-r--r-- | content/docs/user_guide/networking.md | 15 | ||||
| -rw-r--r-- | content/docs/user_guide/platforms.md | 18 |
6 files changed, 105 insertions, 21 deletions
diff --git a/content/docs/user_guide/FAQ.md b/content/docs/user_guide/FAQ.md index 167933f9f..5e166ace3 100644 --- a/content/docs/user_guide/FAQ.md +++ b/content/docs/user_guide/FAQ.md @@ -20,12 +20,13 @@ 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://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. +sandbox, and thus gVisor's internal cache is made aware of the new files and +directories. ### What's the security model? diff --git a/content/docs/user_guide/debugging.md b/content/docs/user_guide/debugging.md index f8a5999fd..c6f5cc772 100644 --- a/content/docs/user_guide/debugging.md +++ b/content/docs/user_guide/debugging.md @@ -21,6 +21,10 @@ To enable debug and system call logging, add the `runtimeArgs` below to your } ``` +> 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: @@ -29,8 +33,10 @@ 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. +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 @@ -46,7 +52,7 @@ docker run --runtime=runsc --rm -d alpine sh -c "while true; do echo running; sl sudo runsc --root /var/run/docker/runtime-runsc/moby debug --stacks 63254c6ab3a6989623fa1fb53616951eed31ac605a2637bb9ddba5d8d404b35b ``` -> Note: `--root` variable is provided by docker and is normally set to +> 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. diff --git a/content/docs/user_guide/docker.md b/content/docs/user_guide/docker.md index c42a320e3..78c1271b1 100644 --- a/content/docs/user_guide/docker.md +++ b/content/docs/user_guide/docker.md @@ -3,7 +3,7 @@ title = "Docker Quick Start" weight = 10 +++ This guide will help you quickly get started running Docker containers using -gVisor with the default platform. +gVisor. ## Install gVisor @@ -43,13 +43,19 @@ sudo systemctl restart docker Now run your container using the `runsc` runtime: ```bash -docker run --runtime=runsc hello-world +docker run --runtime=runsc --rm hello-world ``` You can also run a terminal to explore the container. ```bash -docker run --runtime=runsc -it ubuntu /bin/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 @@ -75,7 +81,8 @@ $ docker run --runtime=runsc -it ubuntu dmesg 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/). +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 diff --git a/content/docs/user_guide/filesystem.md b/content/docs/user_guide/filesystem.md new file mode 100644 index 000000000..e0a038007 --- /dev/null +++ b/content/docs/user_guide/filesystem.md @@ -0,0 +1,59 @@ ++++ +title = "Filesystem" +weight = 45 ++++ +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/overview/#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/content/docs/user_guide/networking.md b/content/docs/user_guide/networking.md index 83e75aaf2..f1aa77625 100644 --- a/content/docs/user_guide/networking.md +++ b/content/docs/user_guide/networking.md @@ -8,14 +8,19 @@ state, control messages, and packet assembly — keeping it isolated from the ho 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. +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: -## Enabling network passthrough +```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. Note that this mode -decreases the isolation to the host. +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: diff --git a/content/docs/user_guide/platforms.md b/content/docs/user_guide/platforms.md index 5a43ad897..e15072068 100644 --- a/content/docs/user_guide/platforms.md +++ b/content/docs/user_guide/platforms.md @@ -14,9 +14,10 @@ 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: +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 { @@ -31,7 +32,12 @@ To select a different platform, modify your Docker configuration } ``` -Then restart the Docker daemon. +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 @@ -50,7 +56,7 @@ 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. +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] @@ -99,7 +105,7 @@ 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 +docker run --runtime=runsc-kvm --rm hello-world ``` [nested-azure]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization |