mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-21 06:11:31 +08:00
Evan Lezar
e9271cb313
Closes #3502 Resolve trusted OCI runtime images with driver TOML, process environment, and compiled-default precedence across Docker, Podman, and Kubernetes. Signed-off-by: Evan Lezar <elezar@nvidia.com>
250 lines
10 KiB
Markdown
250 lines
10 KiB
Markdown
---
|
|
title: OPENSHELL-GATEWAY
|
|
section: 8
|
|
header: OpenShell Manual
|
|
footer: openshell-gateway
|
|
date: 2025
|
|
---
|
|
|
|
# NAME
|
|
|
|
openshell-gateway - OpenShell gateway server daemon
|
|
|
|
# SYNOPSIS
|
|
|
|
**openshell-gateway** \[*OPTIONS*\]
|
|
|
|
**openshell-gateway** **config preflight** [**--path** *PATH* | **--** *GATEWAY_ARGS*...]
|
|
|
|
# DESCRIPTION
|
|
|
|
**openshell-gateway** is the control-plane server for OpenShell. It
|
|
manages sandbox lifecycle, stores provider credentials, delivers
|
|
network and filesystem policies to sandboxes, manages provider access
|
|
requests, and provides the SSH tunnel endpoint for CLI-to-sandbox
|
|
connections.
|
|
|
|
When installed via a Linux package, the gateway runs as a systemd user
|
|
service. The packaged service starts from built-in defaults and reads
|
|
the default gateway TOML path only when that file exists.
|
|
|
|
The gateway exposes a single port with multiplexed gRPC and HTTP,
|
|
secured by mutual TLS (mTLS) by default unless the TOML config disables
|
|
TLS.
|
|
|
|
# OPTIONS
|
|
|
|
**--bind-address** *IP*
|
|
: IP address to bind all listeners to. Default: **127.0.0.1**.
|
|
Environment: **OPENSHELL_BIND_ADDRESS**.
|
|
|
|
**--port** *PORT*
|
|
: Port for the gRPC/HTTP API. Default: **17670**.
|
|
Environment: **OPENSHELL_SERVER_PORT**.
|
|
|
|
**--health-port** *PORT*
|
|
: Port for unauthenticated health endpoints (/healthz, /readyz).
|
|
Set to 0 to disable. Default: **0**.
|
|
Environment: **OPENSHELL_HEALTH_PORT**.
|
|
|
|
**--metrics-port** *PORT*
|
|
: Port for Prometheus metrics (/metrics). Set to 0 to disable.
|
|
Default: **0**. Environment: **OPENSHELL_METRICS_PORT**.
|
|
|
|
**--log-level** *LEVEL*
|
|
: Log level: trace, debug, info, warn, error. Default: **info**.
|
|
Environment: **OPENSHELL_LOG_LEVEL**.
|
|
|
|
**--db-url** *URL*
|
|
: SQLite database URL for state persistence. When unset, the gateway
|
|
stores SQLite state under *~/.local/state/openshell/gateway/*.
|
|
Environment: **OPENSHELL_DB_URL**.
|
|
|
|
**--compute-driver** *DRIVER*
|
|
: Compute driver. Selects exactly one driver. Options: **podman**,
|
|
**docker**, **kubernetes**, **vm**. When unset, the gateway
|
|
auto-detects Kubernetes, then Podman, then Docker. VM is opt-in.
|
|
Environment: **OPENSHELL_COMPUTE_DRIVER**.
|
|
|
|
**--tls-cert** *PATH*
|
|
: Path to server TLS certificate file. Defaults to the local generated
|
|
TLS bundle when present. Required unless **--disable-tls** is set.
|
|
Environment: **OPENSHELL_TLS_CERT**.
|
|
|
|
**--tls-key** *PATH*
|
|
: Path to server TLS private key file. Defaults to the local generated
|
|
TLS bundle when present. Required unless **--disable-tls** is set.
|
|
Environment: **OPENSHELL_TLS_KEY**.
|
|
|
|
**--tls-client-ca** *PATH*
|
|
: Path to CA certificate for client certificate verification (mTLS).
|
|
When set without **--oidc-issuer**, client certificates are required
|
|
and the TLS handshake rejects unauthenticated connections. When set
|
|
together with **--oidc-issuer**, client certificates are accepted
|
|
but not required. Client certificates can authenticate local
|
|
single-user CLI callers when mTLS auth is enabled; sandbox
|
|
supervisors still authenticate with gateway-minted bearer tokens.
|
|
Environment: **OPENSHELL_TLS_CLIENT_CA**.
|
|
|
|
**--enable-mtls-auth** *BOOL*
|
|
: Enable mTLS client certificate authentication for local single-user
|
|
Docker, Podman, and VM gateways. Defaults on for local gateways with
|
|
client certificate verification and no OIDC issuer. Not supported with
|
|
the Kubernetes compute driver.
|
|
Environment: **OPENSHELL_ENABLE_MTLS_AUTH**.
|
|
|
|
**--disable-tls**
|
|
: Disable TLS entirely and listen on plaintext HTTP. When the bind
|
|
address is **0.0.0.0** (the RPM default), disabling TLS exposes the
|
|
API to the entire network without authentication. Only use when the
|
|
gateway sits behind a TLS-terminating reverse proxy, or restrict
|
|
**--bind-address** to **127.0.0.1**.
|
|
Environment: **OPENSHELL_DISABLE_TLS**.
|
|
|
|
**--server-san** *SAN*
|
|
: Subject Alternative Name configured on the gateway server
|
|
certificate. Repeat or pass a comma-separated value through
|
|
**OPENSHELL_SERVER_SAN**. Wildcard DNS SANs also enable sandbox
|
|
service URLs under that domain.
|
|
Environment: **OPENSHELL_SERVER_SAN**.
|
|
|
|
Compute driver settings such as sandbox image, callback endpoint, image
|
|
pull policy, network name, VM state directory, and guest TLS material are
|
|
configured in the TOML file passed with **--config**.
|
|
|
|
# CONFIGURATION PREFLIGHT
|
|
|
|
Validate a gateway configuration before starting the daemon:
|
|
|
|
openshell-gateway config preflight [--path PATH | -- GATEWAY_ARGS...]
|
|
|
|
With no path, preflight validates a nonempty OPENSHELL_GATEWAY_CONFIG. If that
|
|
variable is unset, it optionally validates an auto-discovered XDG config. The
|
|
absence of either config still validates the effective daemon arguments. An explicit missing path, legacy schema-v1
|
|
file, invalid TOML, symlink, or nonregular file fails with a nonzero status.
|
|
Preflight merges file and environment values and applies read-only startup checks
|
|
for selector and socket normalization, registered compute-driver configuration,
|
|
rate limits, TLS and mTLS, interceptors, and middleware. When a selected file
|
|
omits the selector, it validates configured tables for auto-detectable drivers
|
|
without running socket or process-based detection probes. It does not construct a
|
|
compute driver or connect to a transport. Preflight never changes the file and
|
|
reports that failed input was preserved.
|
|
|
|
Arguments after **--** replace **--path** mode and are parsed as the exact gateway
|
|
daemon invocation. Package wrappers use this form so command-line overrides are
|
|
validated before the same arguments reach startup.
|
|
|
|
An explicitly selected local **vm** driver also checks **mke2fs** or **mkfs.ext4**, **debugfs**, and **e2fsck**. Install e2fsprogs 1.43 or newer with the operating system's package manager, then run preflight with the gateway service's account, working directory, configuration, and environment. The command reports selected executable paths and versions. A restricted service **PATH** can select different tools from an interactive shell; include the installation's bin and sbin directories in that service's environment.
|
|
|
|
Each executable receives only **-V**, with a five-second deadline and an 8 KiB output limit per stream. Missing, non-executable, unsupported, or failing tools return nonzero status with installation or repair guidance. Preflight creates no images or runtime state and does not start the VM driver. Other drivers do not require these tools. A remote driver endpoint reports that host tool checks were not performed; check a local VM configuration on that host in the driver service's environment.
|
|
|
|
The Debian and Ubuntu systemd user unit runs preflight before certificate
|
|
generation, while retaining its EnvironmentFile and bare ExecStart behavior. The
|
|
Snap wrapper replays its effective daemon arguments through preflight. It first
|
|
uses a nonempty OPENSHELL_GATEWAY_CONFIG. Otherwise it passes the canonical
|
|
SNAP_COMMON/gateway.toml path whenever it exists or is a symlink. A broken symlink
|
|
fails preflight before the gateway is started. Correct or manually migrate an
|
|
operator-owned v1 file, then run preflight again before restarting the service.
|
|
|
|
# SYSTEMD INTEGRATION
|
|
|
|
The package installs a systemd user unit at
|
|
*/usr/lib/systemd/user/openshell-gateway.service*. Manage the gateway
|
|
with standard systemd commands:
|
|
|
|
systemctl --user enable --now openshell-gateway
|
|
systemctl --user status openshell-gateway
|
|
systemctl --user restart openshell-gateway
|
|
systemctl --user stop openshell-gateway
|
|
|
|
View logs:
|
|
|
|
journalctl --user -u openshell-gateway
|
|
journalctl --user -u openshell-gateway -f
|
|
|
|
The unit runs **openshell-gateway config preflight** and then
|
|
**openshell-gateway generate-certs** as **ExecStartPre** steps. Certificate
|
|
generation creates a self-signed PKI bundle for mTLS
|
|
and sandbox JWT signing material, adding missing JWT files to older
|
|
TLS-only installs when needed. The packaged unit sets
|
|
**OPENSHELL_LOCAL_TLS_DIR** to *~/.local/state/openshell/tls* and uses that
|
|
same value for certificate generation and gateway startup. Override
|
|
**OPENSHELL_LOCAL_TLS_DIR** in *~/.config/openshell/gateway.env* only if you
|
|
need a custom bundle location.
|
|
|
|
The gateway then starts from built-in defaults and reads
|
|
*~/.config/openshell/gateway.toml* when that file exists.
|
|
|
|
The user service also reads *~/.config/openshell/gateway.env* for both config
|
|
preflight and startup. **OPENSHELL_SANDBOX_RUNTIME_IMAGE** and
|
|
**OPENSHELL_SUPERVISOR_IMAGE** accept complete tagged or digest-pinned OCI
|
|
references for the built-in Docker, Podman, and Kubernetes drivers. These
|
|
variables take precedence over explicit image fields in the selected driver's
|
|
TOML table, which take precedence over compiled release defaults.
|
|
These are trusted gateway inputs and cannot be supplied by sandbox requests.
|
|
Do not embed registry credentials in image references.
|
|
|
|
To persist the service across logouts:
|
|
|
|
sudo loginctl enable-linger $USER
|
|
|
|
# CONFIGURATION
|
|
|
|
The systemd user unit launches the gateway with:
|
|
|
|
openshell-gateway
|
|
|
|
Gateway listener, TLS, database, and compute driver settings have local
|
|
defaults. Create *~/.config/openshell/gateway.toml* when you need to
|
|
override them. The gateway rejects `database_url` in TOML; set
|
|
**OPENSHELL_DB_URL** when you need a different database.
|
|
|
|
To override individual settings without creating TOML:
|
|
|
|
systemctl --user edit openshell-gateway
|
|
|
|
This creates a drop-in override that persists across package upgrades.
|
|
|
|
# FILES
|
|
|
|
*/usr/bin/openshell-gateway*
|
|
: Gateway binary.
|
|
|
|
*/usr/lib/systemd/user/openshell-gateway.service*
|
|
: Systemd user unit file.
|
|
|
|
*~/.config/openshell/gateway.toml*
|
|
: Optional gateway TOML configuration.
|
|
|
|
*~/.local/state/openshell/tls/*
|
|
: Auto-generated TLS certificates and sandbox JWT signing keys.
|
|
|
|
*~/.local/state/openshell/gateway/openshell.db*
|
|
: SQLite database for gateway state.
|
|
|
|
*~/.config/openshell/gateways/openshell/mtls/*
|
|
: Client mTLS certificates for CLI auto-discovery.
|
|
|
|
# EXAMPLES
|
|
|
|
Start the gateway as a systemd user service:
|
|
|
|
systemctl --user enable --now openshell-gateway
|
|
|
|
Check gateway health from the CLI:
|
|
|
|
openshell gateway add --local https://127.0.0.1:17670
|
|
openshell status
|
|
|
|
Override the API port in TOML:
|
|
|
|
$EDITOR ~/.config/openshell/gateway.toml
|
|
systemctl --user restart openshell-gateway
|
|
|
|
# SEE ALSO
|
|
|
|
**openshell**(1), **systemctl**(1), **journalctl**(1), **loginctl**(1),
|
|
**podman**(1)
|
|
|
|
Full documentation: *https://docs.nvidia.com/openshell/*
|