gVisor - Platforms
The core Sentry packages implement system calls, file systems, etc, but do not define how application code is executed or how system calls are intercepted. This behavior is defined by an implementation of the Platform interface.
Think of the Sentry as the "Brain" and the Platform as the "Nerves." The Brain decides what to do, but the Nerves are what physically catch the application's signals and pass them to the Brain.
gVisor Platforms
TL;DR:
- use KVM for bare-metal deployments.
- use systrap for in-VM deployements (e.g. used in GKE).
The KVM Platform (Performance; for bare metal machines)
This platform uses the Linux Kernel-based Virtual Machine (KVM) module. It is used as a way to achieve address space isolation.
- How it works: It treats the Sentry like a Hypervisor and the application like a Virtual Machine. However, it doesn't boot a guest OS; it just uses KVM to switch the CPU into a restricted mode where it can "trap" system calls extremely fast.
- Pros: It is the fastest platform because it uses hardware-assisted virtualization (Intel VT-x or AMD-V).
- Cons: It requires access to
/dev/kvm. This can be difficult to get inside some cloud environments or if you are already running inside a VM (this is called "nested virtualization," which is often disabled or slow).
The Systrap Platform (The "Modern" Default; inside VMs)
Systrap is a newer, more sophisticated platform designed to be faster than Ptrace without requiring KVM hardware.
- How it works:
- It uses a combination of a small "stub" code in the application's memory and shared memory regions. It relies on Linux signals (like
SIGSYS) to trap syscalls. - It is based on the use of Linux's
seccomp-bpfsubsystem for system call interception (as opposed to the typical use-case ofseccomp-bpfbeing for system call filtering). It does not require virtualization support from the host and is therefore well-suited to run inside a virtual machine.
- It uses a combination of a small "stub" code in the application's memory and shared memory regions. It relies on Linux signals (like
- Pros: It is significantly faster than Ptrace and doesn't require
/dev/kvm. It is now the default platform for most gVisor installations because it provides a "best of both worlds" balance. - Cons: It is more complex to implement and debug than Ptrace.
Deprecated: The Ptrace Platform (Universal Compatibility; replaced by systrap)
This platform uses the standard Linux ptrace system call—the same tool used by debuggers like gdb or tracing tools like strace.
- How it works: The Sentry "attaches" to the application as a debugger. Every time the application tries to make a system call, the kernel pauses the application and notifies the Sentry.
- Pros: It works everywhere. It doesn't need special hardware, it doesn't need root privileges, and it works on every cloud provider.
- Cons: It is slow. Every single system call requires multiple context switches between the app, the host kernel, and the Sentry. It has significant performance overhead.
Comparison Table
| Platform | Hardware Req | Speed | Use Case |
|---|---|---|---|
| KVM | Requires VT-x/AMD-V | Fastest | High-performance production workloads where /dev/kvm is available. |
| Systrap | None | Medium | Most standard containers; the default for "runsc". |
| Ptrace | None | Slowest | Environments where security is restricted (like inside another restricted container). |
Why does gVisor need "Platforms" at all?
If you were writing a normal program, you would just talk to the Linux Kernel directly. But gVisor's whole purpose is to stop the application from talking to the Linux Kernel.
To do this, the Sentry must "hook" into the application's execution.
- Intercept: The application says "Open this file."
- Redirect: The Platform stops the request and redirects it to the Sentry.
- Validate: The Sentry checks if the application is allowed to see that file.
- Emulate: The Sentry does the work and gives the result back to the application.
The "Platform" is simply the choice of how you perform that redirection (Step 2). If you have the hardware to do it (KVM), use it. If you don't, use the software methods (Systrap/Ptrace).
Where is the source code?
All can be found under pkg/sentry/platform/ folder:
https://github.com/google/gvisor/tree/master/pkg/sentry/platform