diff --git a/g3doc/architecture_guide/platforms.md b/g3doc/architecture_guide/platforms.md index 68518e6ba..bdd009f06 100644 --- a/g3doc/architecture_guide/platforms.md +++ b/g3doc/architecture_guide/platforms.md @@ -44,14 +44,27 @@ allowing it to execute host system calls. This platform can run anywhere that 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 -to act as both guest OS and VMM. The KVM platform can run on bare-metal, or in a -VM with nested virtualization enabled. While there is no virtualized hardware -layer -- the sandbox retains a process model -- gVisor leverages virtualization -extensions available on modern processors in order to improve isolation and -performance of address space switches. +to act as both guest OS and VMM. The KVM platform runs best on bare-metal +setups. While there is no virtualized hardware layer -- the sandbox retains a +process model -- gVisor leverages virtualization extensions available on modern +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 diff --git a/g3doc/user_guide/platforms.md b/g3doc/user_guide/platforms.md index 6e8b2651e..0791835fd 100644 --- a/g3doc/user_guide/platforms.md +++ b/g3doc/user_guide/platforms.md @@ -45,6 +45,11 @@ 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). + ## Configuring Docker The platform is selected by the `--platform` command line flag passed to @@ -90,6 +95,12 @@ for the KVM platform: "runtimeArgs": [ "--platform=kvm" ] + }, + "runsc-systrap": { + "path": "/usr/local/bin/runsc", + "runtimeArgs": [ + "--platform=systrap" + ] } } } diff --git a/pkg/sentry/platform/systrap/README.md b/pkg/sentry/platform/systrap/README.md index 540c33c4b..05e761d92 100644 --- a/pkg/sentry/platform/systrap/README.md +++ b/pkg/sentry/platform/systrap/README.md @@ -1,33 +1,34 @@ # The systrap platform -This platform is similar with the ptrace platform with the difference how system -calls, page-faults and other exceptions handled. +This platform is similar with the ptrace platform but differs on how system +calls, page-faults and other exceptions are handled. -The kernel allows setting seccomp filters (SECCOMP_RET_TRAP), so that each time -when a thread tries to call a filtered system call, it will receive the SIGSYS -signal. +Linux allows setting seccomp filters with `SECCOMP_RET_TRAP`, such that when a +thread tries to call a system call caught by the seccomp filter, this thread +will receive the `SIGSYS` signal. -With this kernel feature, all stub thread events what have to be handled in the -sentry triggers signals. This means that they can be handled from a signal -handler. +gVisor's systrap platform uses this kernel feature to have all thread events +that have to be handled in the sentry trigger signals. -The systrap platform includes the sysmsg module which implements a stub signal -handler and a protocol of communications of stub threads and the Sentry. +The systrap platform implements a stub signal handler (as part of the `sysmsg` +module), and communication protocol between this stub signal handler and the +Sentry. -The initializations of a new stub thread includes next steps: +The initialization of a new stub thread involves: -* installing seccomp filters to trap all user system calls. -* setting an alternate signal stack which is shared with the Sentry. -* setting the sysmsg signal handler for SIGSYS, SIGSEGV, SIGBUS, SIGFPE, - SIGTRAP, SIGILL. +* Installing seccomp filters to trap all user system calls. +* Setting up an alternate signal stack which is shared with the Sentry. +* Setting up the sysmsg signal handler for `SIGSYS`, `SIGSEGV`, `SIGBUS`, + `SIGFPE`, `SIGTRAP`, and `SIGILL`. -User code is executed in context of a stub thread. When it calls a system call -or triggers page-fault, the signal handler is started. It notifies the Sentry -about a new signal, then the Sentry handles this event and notifies the system -thread back that it can continue running. +User code is executed in the context of a stub thread. When it calls a system +call or triggers a page-fault, the stub signal handler code executes. It +notifies the Sentry of this new signal. The Sentry handles this, and calls back +the system thread so that it can resume running. When the kernel prepares to execute the signal handler, it generates a signal -frame which contains a process state (registers, FPU state, etc). Then when the -kernel resumes a process, the process state is restored from this frame. The -signal frame is saved on a signal handler stack which is shared with the Sentry. -This allows us to read and modify the thread state from the Sentry. +frame which contains the process state (registers, FPU state, etc). Then, when +the kernel resumes the process, the process state is restored from this frame. +The signal frame is saved on the signal handler stack. This memory region is +shared with the Sentry process. This allows gVisor to read and modify the thread +state from the Sentry.