diff --git a/g3doc/architecture_guide/platforms.md b/g3doc/architecture_guide/platforms.md index bdd009f06..b003eff3c 100644 --- a/g3doc/architecture_guide/platforms.md +++ b/g3doc/architecture_guide/platforms.md @@ -30,33 +30,11 @@ various trade-offs, generally around performance and hardware requirements. The choice of platform depends on the context in which `runsc` is executing. In general, when running on bare-metal (not inside a VM), the KVM platform will -provide the best performance. The `ptrace` platform is a better choice when +provide the best performance. The `systrap` platform is a better choice when running inside a VM, or on a machine without virtualization support. ![Platforms](platforms.png "Platform examples.") -### ptrace - -The ptrace platform uses [`PTRACE_SYSEMU`][ptrace] to execute user code without -allowing it to execute host system calls. This platform can run anywhere that -`ptrace` works (even VMs without nested virtualization), which is ubiquitous. - -Unfortunately, the ptrace platform has high context switch overhead, so system -call-heavy applications may pay a [performance penalty](./performance.md). - -### systrap - -The systrap platform is an **experimental, non-production-ready** platform aimed -at replacing the ptrace platform (i.e. in VMs without nested virtualization). It -relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to intercept system -calls. This makes the kernel send `SIGSYS` to the triggering thread, which hands -over control to gVisor to handle the system call. For more details, please see -[the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md). - -As of 2023-03, this platform has not been battle-tested as `ptrace`, and is not -recommended for production use. Users are encouraged to try it out in -non-production environments and [report bugs and feedback](../community.md). - ### KVM The KVM platform uses the kernel's [KVM][kvm] functionality to allow the Sentry @@ -67,13 +45,36 @@ processors in order to improve isolation and performance of address space switches. Note that while running within a nested VM is feasible with the KVM platform, -the `ptrace` platform will often provide better performance in such a setup, due -to the overhead of nested virtualization. +the `systrap` platform will often provide better performance in such a setup, +due to the overhead of nested virtualization. -### GKE Sandbox +### systrap -[GKE Sandbox] uses a custom gVisor platform implementation which provides better -performance than `ptrace` and KVM. +The `systrap` platform relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to +intercept system calls. This makes the kernel send `SIGSYS` to the triggering +thread, which hands over control to gVisor to handle the system call. For more +details, please see +[the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md). + +`systrap` replaced `ptrace` as the default gVisor platform in mid-2023. If you +depend on `ptrace`, and `systrap` doesn't fulfill your needs, please +[voice your feedback](../community.md). + +### ptrace + +The ptrace platform uses [`PTRACE_SYSEMU`][ptrace] to execute user code without +allowing it to execute host system calls. This platform can run anywhere that +`ptrace` works (even VMs without nested virtualization), which is ubiquitous. + +Unfortunately, the ptrace platform has high context switch overhead, so system +call-heavy applications may pay a [performance penalty](./performance.md). For +this reason, `systrap` is almost always the better choice. + +`systrap` replaced `ptrace` as the default gVisor platform in mid-2023. While +`ptrace` continues to exist in the codebase, it is no longer supported and is +expected to eventually be removed entirely. If you depend on `ptrace`, and +`systrap` doesn't fulfill your needs, please +[voice your feedback](../community.md). ## Changing Platforms diff --git a/g3doc/user_guide/platforms.md b/g3doc/user_guide/platforms.md index 0791835fd..9d036b906 100644 --- a/g3doc/user_guide/platforms.md +++ b/g3doc/user_guide/platforms.md @@ -14,8 +14,8 @@ more. If you intend to run the KVM platform, 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 ensuring the module is loaded, and your user has -permissions to access the `/dev/kvm` device. Usually, it means that the user is -in the `kvm` group. +permissions to access the `/dev/kvm` device. Usually, this means that your user +is in the `kvm` group. ```shell # Check that /dev/kvm is owned by the kvm group @@ -28,7 +28,7 @@ ok ``` **For best performance, use the KVM platform on bare-metal machines only**. If -you have to run gVisor within a virtual machine, the `ptrace` platform will +you have to run gVisor within a virtual machine, the `systrap` platform will often yield better performance than KVM. If you still want to use KVM within 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 @@ -45,17 +45,20 @@ cause of security issues (e.g. [CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not recommended for production.*** -A third platform, `systrap`, is expected to eventually replace the `ptrace` -platform. As of this writing (2023-03), **this platform is not -production-ready**, but we encourage `ptrace` users to try it out in -non-production settings and [report bugs and feedback](../community.md). +A third platform, `ptrace`, also has the versatility of running on any +environment. However, it has higher performance overhead than `systrap` in +almost all cases. `systrap` replaced `ptrace` as the default platform in +mid-2023. While `ptrace` continues to exist in the codebase, it is no longer +supported and is expected to eventually be removed entirely. If you depend on +`ptrace`, and `systrap` doesn't fulfill your needs, please +[voice your feedback](../community.md). ## Configuring Docker The platform is selected by the `--platform` command line flag passed to -`runsc`. By default, the ptrace platform is selected. For example, to select the -KVM platform, modify your Docker configuration (`/etc/docker/daemon.json`) to -pass the `--platform` argument: +`runsc`. By default, the `systrap` platform is selected. For example, to select +the KVM platform, modify your Docker configuration (`/etc/docker/daemon.json`) +to pass the `--platform` argument: ```json { @@ -78,18 +81,12 @@ $ sudo systemctl restart docker ``` Note that you may configure multiple runtimes using different platforms. For -example, the following configuration has one configuration for ptrace and one +example, the following configuration has one configuration for systrap and one for the KVM platform: ```json { "runtimes": { - "runsc-ptrace": { - "path": "/usr/local/bin/runsc", - "runtimeArgs": [ - "--platform=ptrace" - ] - }, "runsc-kvm": { "path": "/usr/local/bin/runsc", "runtimeArgs": [