mirror of
https://github.com/coder/coder.git
synced 2026-06-04 05:28:20 +00:00
Yevhenii Shcherbina
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# nsjail on Docker
|
|
|
|
This page describes the runtime and permission requirements for running Agent
|
|
Boundaries with the **nsjail** jail type on **Docker**.
|
|
|
|
For an overview of nsjail, see [nsjail](./index.md).
|
|
|
|
## Runtime & Permission Requirements for Running Boundary in Docker
|
|
|
|
This section describes the Linux capabilities and runtime configurations
|
|
required to run Agent Boundaries with nsjail inside a Docker container.
|
|
Requirements vary depending on the OCI runtime and the seccomp profile in use.
|
|
|
|
### 1. Default `runc` runtime with `CAP_NET_ADMIN`
|
|
|
|
When using Docker's default `runc` runtime, Agent Boundaries requires the
|
|
container to have `CAP_NET_ADMIN`. This is the minimal capability needed for
|
|
configuring virtual networking inside the container.
|
|
|
|
Docker's default seccomp profile may also block certain syscalls (such as
|
|
`clone`) required for creating unprivileged network namespaces. If you encounter
|
|
these restrictions, you may need to update or override the seccomp profile to
|
|
allow these syscalls.
|
|
|
|
[see Docker Seccomp Profile Considerations](#docker-seccomp-profile-considerations)
|
|
|
|
### 2. Default `runc` runtime with `CAP_SYS_ADMIN` (testing only)
|
|
|
|
For development or testing environments, you may grant the container
|
|
`CAP_SYS_ADMIN`, which implicitly bypasses many of the restrictions in Docker's
|
|
default seccomp profile.
|
|
|
|
- Agent Boundaries does not require `CAP_SYS_ADMIN` itself.
|
|
- However, Docker's default seccomp policy commonly blocks namespace-related
|
|
syscalls unless `CAP_SYS_ADMIN` is present.
|
|
- Granting `CAP_SYS_ADMIN` enables Agent Boundaries to run without modifying the
|
|
seccomp profile.
|
|
|
|
⚠️ Warning: `CAP_SYS_ADMIN` is extremely powerful and should not be used in
|
|
production unless absolutely necessary.
|
|
|
|
### 3. `sysbox-runc` runtime with `CAP_NET_ADMIN`
|
|
|
|
When using the `sysbox-runc` runtime (from Nestybox), Agent Boundaries can run
|
|
with only:
|
|
|
|
- `CAP_NET_ADMIN`
|
|
|
|
The sysbox-runc runtime provides more complete support for unprivileged user
|
|
namespaces and nested containerization, which typically eliminates the need for
|
|
seccomp profile modifications.
|
|
|
|
## Docker Seccomp Profile Considerations
|
|
|
|
Docker's default seccomp profile frequently blocks the `clone` syscall, which is
|
|
required by Agent Boundaries when creating unprivileged network namespaces. If
|
|
the `clone` syscall is denied, Agent Boundaries will fail to start.
|
|
|
|
To address this, you may need to modify or override the seccomp profile used by
|
|
your container to explicitly allow the required `clone` variants.
|
|
|
|
You can find the default Docker seccomp profile for your Docker version here
|
|
(specify your docker version):
|
|
|
|
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
|
|
|
If the profile blocks the necessary `clone` syscall arguments, you can provide a
|
|
custom seccomp profile that adds an allow rule like the following:
|
|
|
|
```json
|
|
{
|
|
"names": ["clone"],
|
|
"action": "SCMP_ACT_ALLOW"
|
|
}
|
|
```
|
|
|
|
This example unblocks the clone syscall entirely.
|
|
|
|
### Example: Overriding the Docker Seccomp Profile
|
|
|
|
To use a custom seccomp profile, start by downloading the default profile for
|
|
your Docker version:
|
|
|
|
https://github.com/moby/moby/blob/v25.0.13/profiles/seccomp/default.json#L628-L635
|
|
|
|
Save it locally as seccomp-v25.0.13.json, then insert the clone allow rule shown
|
|
above (or add "clone" to the list of allowed syscalls).
|
|
|
|
Once updated, you can run the container with the custom seccomp profile:
|
|
|
|
```bash
|
|
docker run -it \
|
|
--cap-add=NET_ADMIN \
|
|
--security-opt seccomp=seccomp-v25.0.13.json \
|
|
test bash
|
|
```
|
|
|
|
This instructs Docker to load your modified seccomp profile while granting only
|
|
the minimal required capability (`CAP_NET_ADMIN`).
|