https://github.com/zachcheung/ssh-gateway
Poor man's SSH gateway for multiple projects
https://github.com/zachcheung/ssh-gateway
Last synced: about 1 month ago
JSON representation
Poor man's SSH gateway for multiple projects
- Host: GitHub
- URL: https://github.com/zachcheung/ssh-gateway
- Owner: zachcheung
- License: mit
- Created: 2026-03-27T08:08:08.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-03T09:14:42.000Z (about 2 months ago)
- Last Synced: 2026-06-03T09:26:43.177Z (about 2 months ago)
- Language: Go
- Homepage:
- Size: 83 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SSH Gateway
Poor man's SSH gateway for multiple projects.
```mermaid
flowchart LR
client --> gw_alpha
client --> gw_beta
subgraph host [Gateway Host]
gw_alpha["ssh-gw-alpha :2201"]
gw_beta["ssh-gw-beta :2202"]
end
gw_alpha --> alpha1
gw_alpha --> alpha2
gw_beta --> beta1
```
## Config
```yaml
project: alpha
key_provider: github
key_types:
allowed: [ed25519]
reconcile_interval: 15m
users:
- name: alice
keys:
- ssh-ed25519 AAAA... alice@laptop
- name: bob
```
| Field | Description |
|------------------------|-------------|
| `project` | Project name (required) |
| `key_provider` | Default key source for users without explicit `keys`. Shorthands: `github`, `gitlab`, or a full URL base (e.g. `https://keys.example.com`). Keys are fetched from `/.keys`. |
| `key_types` | Filter keys by type (`ecdsa`, `ecdsa-sk`, `ed25519`, `ed25519-sk`, `rsa`). Use `allowed` or `disallowed`; if both are set, `allowed` wins. |
| `reconcile_interval` | Periodically re-fetch keys from `key_provider` or URL keys, without any config file change. Useful when team members rotate their GitHub/GitLab keys. Minimum `5s`. Omit to disable. |
| `fetch_keys_on_reload` | Re-fetch provider and URL keys on config reload (fsnotify / SIGHUP), in addition to the periodic interval. Default `false`: reloads only apply structural changes (users added/removed, inline keys updated) while leaving existing fetched keys untouched. Set to `true` to force an immediate key refresh on every reload. |
| `keep_sshd_config` | If `true` and `/etc/ssh/sshd_config` already exists, leave it untouched on startup — the operator owns that file. Default `false`: the file is replaced when it drifts from the built-in (with a warning). Useful when custom sshd tunables (e.g. connection limits, timeouts, banner) are needed. |
| `log_endpoint` | Forward structured JSON logs to an external processor (`tcp://`, `udp://`, `http://`, `https://`). When set, reconcile events are emitted as JSON with `event_id`, `phase` (`start`/`end`), `trigger`, and per-change records. See [Change Notifications](#change-notifications). |
## Run
```yaml
# compose.yml
services:
ssh-gateway:
image: ghcr.io/zachcheung/ssh-gateway
restart: unless-stopped
ports:
- '2201:22'
volumes:
- .:/etc/ssh-gateway:ro
```
```sh
docker compose up -d
```
See [examples/](examples/) for multi-project and bind mount setups.
> **Note:** Mount the config *directory*, not the individual file. Docker binds single-file mounts to the original inode, so editors that write atomically (rename into place) leave the container reading the old content and fsnotify never fires.
### Config file locations
The binary searches for the config file in the following order, stopping at the first match:
| Path | Example mount |
|------|---------------|
| `/etc/ssh-gateway/config.yaml` | `- .:/etc/ssh-gateway:ro` |
| `/etc/ssh-gateway/config.yml` | `- .:/etc/ssh-gateway:ro` |
| `/etc/ssh-gateway/config/config.yaml` | `- ./config:/etc/ssh-gateway/config:ro` |
| `/etc/ssh-gateway/config/config.yml` | `- ./config:/etc/ssh-gateway/config:ro` |
The `config/` subdirectory layout lets you mount only the config directory rather than the entire `/etc/ssh-gateway` tree, which is useful when host keys or other generated files share the parent directory.
### Migrating existing host keys
Host keys are generated once on first start and reused on subsequent starts via the `/etc/ssh` volume. To migrate keys from an existing server, place them in the volume directory **before** starting the container — `GenerateHostKeys` skips generation if the files already exist:
```sh
cp /old-server/etc/ssh/ssh_host_*_key* ./ssh/
docker compose up -d
```
If the container is already running with auto-generated keys, copy the files then restart:
```sh
cp /old-server/etc/ssh/ssh_host_*_key* ./ssh/
docker compose restart ssh-gateway
```
Restarting is required because sshd loads host keys at startup and does not reload them at runtime.
## Change Notifications
Set `log_endpoint` to forward structured JSON logs to an external processor that can trigger notifications (email, Slack, PagerDuty, etc.):
```yaml
log_endpoint: tcp://log-processor:5170
```
Each reconcile cycle emits a `phase: start` record and a `phase: end` record sharing the same `event_id`. Change records (user added/removed, key added/removed) appear between them. The `changes` field on the end record is `0` for no-op reconciles, letting the processor suppress notifications when nothing changed.
Supported schemes: `tcp`, `udp`, `http`, `https`. Logs are forwarded asynchronously — a slow or unavailable endpoint does not block reconcile.
## Reload
Config changes are detected automatically via filesystem watch — no manual step needed when the config file is bind-mounted from the host or updated via Docker volumes.
To trigger a reload manually (e.g. from a script):
```sh
docker compose kill -s HUP ssh-gateway
```
## SSH
Connect through the gateway as a jump host:
```sh
ssh -J alice@gateway:2201 alice@alpha1
```
Or in `~/.ssh/config`:
```
Host gw-alpha
HostName gateway
Port 2201
User alice
Host alpha1
ProxyJump gw-alpha
User alice
```
## How It Works
A single host serves as SSH jump gateway for multiple projects, each with isolated users. One container per project, managed via YAML config.
The Go binary manages sshd and system users inside the container. It reconciles users and their `authorized_keys` on three triggers: startup, config file change (via inotify watch on the config directory), and `SIGHUP`. If `reconcile_interval` is set, keys are also re-fetched on a timer to pick up external key rotations without any config change. No shell access is granted (`ForceCommand /bin/false`). Host keys (`/etc/ssh`), home directories (`/home`), and the user database (`/var/lib/ssh-gateway-users`, where `/etc/passwd`, `/etc/shadow`, `/etc/group` symlink into) are persisted via Docker volumes so container recreation does not re-add existing users.
Each `authorized_keys` file is managed exclusively by ssh-gateway and annotated with source markers (ignored by sshd) that track where each key came from. On a config reload, only inline keys are updated from the config; provider and URL keys are preserved from the previous fetch. This means a compromised key provider cannot push new keys via a config reload — keys from external sources only change when the periodic timer fires (or when `fetch_keys_on_reload: true` is set). A container restart behaves the same as a config reload; only a missing `authorized_keys` file (first-ever start) triggers a fetch unconditionally. Sources removed from the config are evicted immediately on any reload.
## Development
Run the integration tests:
```sh
# --abort-on-container-exit stops all services when the test container exits
docker compose -f compose.test.yml up --build --abort-on-container-exit
```
## License
[MIT](LICENSE)