Tyler King
e7fc9fa5e1
Observability: Structured JSON logging via BASCULE_LOG_FORMAT=json Tracing spans on auth (method, principal, peer) Tracing spans on session lifecycle (id, principal, backend, source_ip) Tracing spans on exec requests (session_id, command) Config: [telemetry] and [metrics] sections (OTel export planned) Documentation (8 files, 489 lines): docs/quickstart.md — three-path getting started docs/configuration.md — full config reference with examples docs/authentication.md — all auth modes with setup guides docs/architecture.md — backends, traits, extension model, security docs/observability.md — logging, tracing, metrics docs/comparison.md — vs Teleport, Boundary, StrongDM images/README.md — curated image catalog README.md — features, comparison, quickstart, extension example 1557 lines Rust, 489 lines docs, 0 substrate deps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
128 lines
3.8 KiB
Markdown
128 lines
3.8 KiB
Markdown
# Configuration Reference
|
|
|
|
Bascule uses a TOML configuration file. Pass it with `--config path/to/config.toml`.
|
|
|
|
## Top-Level
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `listen_addr` | string | `0.0.0.0:2222` | Address to listen on |
|
|
| `host_key_path` | string | (generated) | Path to SSH host key |
|
|
| `shell_command` | string | `/bin/bash` | Shell to spawn (local PTY mode) |
|
|
| `shell_args` | list | `[]` | Arguments for shell_command |
|
|
| `banner` | string | `Welcome, {name}.` | Session banner |
|
|
| `max_sessions` | int | `0` | Max concurrent sessions (0 = unlimited) |
|
|
|
|
## `[auth]`
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `mode` | string | `accept-all` | Auth mode: `accept-all`, `authorized-keys` |
|
|
| `authorized_keys_path` | string | — | Path to authorized_keys file |
|
|
|
|
### `[auth.agent_id]` (Entra Agent ID)
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `tenant_id` | string | — | Entra tenant ID |
|
|
| `audiences` | list | `[]` | Expected token audiences |
|
|
| `multi_tenant` | bool | `false` | Accept agents from any tenant |
|
|
|
|
## `[proxy]`
|
|
|
|
When set, sessions are forwarded to a target SSH host.
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `target_host` | string | — | Target SSH host |
|
|
| `target_port` | int | `22` | Target SSH port |
|
|
| `target_user` | string | (principal) | Username on target |
|
|
| `target_key_path` | string | — | Private key for target auth |
|
|
| `accept_target_host_key` | bool | `false` | Accept any target host key (dev only) |
|
|
|
|
## `[container]`
|
|
|
|
When set, sessions spawn an ephemeral container.
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `runtime` | string | `auto` | `docker`, `podman`, `nerdctl`, `auto` |
|
|
| `image` | string | — | Container image |
|
|
| `pull_policy` | string | `if-not-present` | `always`, `if-not-present`, `never` |
|
|
| `mounts` | list | `[]` | Volume mounts |
|
|
| `env` | map | `{}` | Extra environment variables |
|
|
| `memory_limit` | string | — | Memory limit (e.g. `512m`) |
|
|
| `cpu_limit` | string | — | CPU limit (e.g. `1.0`) |
|
|
| `shell` | string | (image default) | Shell command in container |
|
|
| `user` | string | — | User to run as |
|
|
| `ephemeral` | bool | `true` | Destroy container on disconnect |
|
|
| `hardened` | bool | `true` | Drop all caps, add minimal set |
|
|
| `read_only_rootfs` | bool | `false` | Read-only root filesystem |
|
|
| `network` | string | — | Network mode (`none`, `bridge`, `host`) |
|
|
|
|
### Mount format
|
|
|
|
```toml
|
|
[[container.mounts]]
|
|
source = "/host/path"
|
|
target = "/container/path"
|
|
readonly = true
|
|
```
|
|
|
|
## `[telemetry]`
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `otlp_endpoint` | string | — | OTLP endpoint for trace export |
|
|
| `service_name` | string | `bascule` | OTel service name |
|
|
|
|
## `[metrics]`
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `enabled` | bool | `false` | Enable Prometheus `/metrics` endpoint |
|
|
| `port` | int | `9090` | Metrics server port |
|
|
|
|
## Example Configs
|
|
|
|
### Development
|
|
|
|
```toml
|
|
listen_addr = "127.0.0.1:2222"
|
|
[auth]
|
|
mode = "accept-all"
|
|
```
|
|
|
|
### Production (containers + SSH keys)
|
|
|
|
```toml
|
|
listen_addr = "0.0.0.0:2222"
|
|
host_key_path = "/etc/bascule/host_key"
|
|
|
|
[auth]
|
|
mode = "authorized-keys"
|
|
authorized_keys_path = "/etc/bascule/authorized_keys"
|
|
|
|
[container]
|
|
image = "bascule-shell:k8s-ops"
|
|
ephemeral = true
|
|
hardened = true
|
|
memory_limit = "512m"
|
|
network = "none"
|
|
```
|
|
|
|
### Jumphost (proxy)
|
|
|
|
```toml
|
|
listen_addr = "0.0.0.0:2222"
|
|
host_key_path = "/etc/bascule/host_key"
|
|
|
|
[auth]
|
|
mode = "authorized-keys"
|
|
authorized_keys_path = "/etc/bascule/authorized_keys"
|
|
|
|
[proxy]
|
|
target_host = "10.0.1.50"
|
|
target_port = 22
|
|
target_key_path = "/etc/bascule/target_key"
|
|
```
|