0.34.2_agent
This commit is contained in:
Mateusz Gruszczyński committed
1 parent
b2b5b45d8a
commit
8c0de520d7
13 files changed
+820
-123
No files matched your search
+83
-23
@@ -1,46 +1,106 @@
|
||||
# RustProxy Docker Agent
|
||||
# RustProxy Docker Agent: Linux DEB/RPM or manual installation
|
||||
|
||||
Small read-only discovery service for Docker hosts. It talks to the local Docker Engine Unix socket, reports running containers with non-loopback published TCP ports, preserves every host binding for each service, and exposes the inventory to RustProxy through a Bearer-token protected HTTPS endpoint.
|
||||
The optional `rustproxy-docker-agent` runs **on a Docker host**, not on the RustProxy server. It exposes a read-only, Bearer-protected Docker discovery API over HTTPS. It reports containers with published TCP ports, host bindings, and usable host addresses. RustProxy itself never needs access to the Docker socket.
|
||||
|
||||
The inventory also reports multiple usable host addresses: active host interface addresses, the primary routed address, an optional public-IP lookup result, and the optional advertised/preferred address. Loopback/link-local and obvious Docker-generated bridge/veth interfaces are omitted from the host-address list.
|
||||
## Requirements and security
|
||||
|
||||
## TLS by default
|
||||
- Linux amd64/x86_64 with **systemd and Docker Engine** (including a usable `/var/run/docker.sock`). No FreeBSD `pkg` is built for this agent.
|
||||
- Restrict inbound port `9876` to the RustProxy server through a firewall. The example binds `0.0.0.0:9876`; this is reachable from other machines when the firewall permits it.
|
||||
- Access to `docker.sock` grants substantial **host-level privilege**, regardless of the agent's read-only HTTP API. The service uses a dedicated unprivileged identity granted access to the `docker` group.
|
||||
- Self-signed ECDSA P-256 HTTPS is enabled by default; the certificate and private key persist under `/var/lib/rustproxy-docker-agent/` and are **not** regenerated on upgrades/restarts. The key is `0600`.
|
||||
- The Bearer token is generated using a cryptographically secure random source, saved to `/etc/rustproxy/docker-agent.env` with mode `0600`, and preserved on upgrade. Never include it in tickets, unattended logs, or screenshots.
|
||||
|
||||
HTTPS is enabled by default. On first start the agent creates a persistent ECDSA P-256 self-signed certificate under `/var/lib/rustproxy-docker-agent/` and reuses it across restarts. The private key is written with mode `0600`.
|
||||
## Recommended: install from DEB/RPM
|
||||
|
||||
The installer prints the certificate SHA-256 fingerprint. Configure that fingerprint in **RustProxy -> Settings -> Docker agents**. RustProxy then pins the exact agent certificate while still verifying the TLS handshake signatures. A changed/replaced certificate is rejected until the configured fingerprint is updated.
|
||||
The Linux package repository publishes **two independent packages** built from the same source commit: `rustproxy` (main server) and `rustproxy-docker-agent` (Docker host). Installing the latter does **not** install the main RustProxy server and does **not** require Go on the destination host.
|
||||
|
||||
Show the current fingerprint again with:
|
||||
On a Debian/Ubuntu Docker host, after configuring the RustProxy signed APT repository:
|
||||
|
||||
```bash
|
||||
sudo rustproxy-docker-agent --print-fingerprint
|
||||
sudo apt update
|
||||
sudo apt install rustproxy-docker-agent
|
||||
# Or install a downloaded artifact directly:
|
||||
sudo apt install ./rustproxy-docker-agent_<version>-<release>_amd64.deb
|
||||
```
|
||||
|
||||
If you replace the generated certificate with one signed by a normal public CA, the fingerprint field in RustProxy may be left empty so standard CA/hostname validation is used. Plain HTTP is available only when `RUSTPROXY_DOCKER_AGENT_TLS=false`; it is not the default.
|
||||
|
||||
## Quick install on systemd
|
||||
On a RHEL/Rocky/Alma/Fedora Docker host, after configuring the signed RPM repository:
|
||||
|
||||
```bash
|
||||
sudo ./install.sh
|
||||
sudo dnf install rustproxy-docker-agent
|
||||
# Or install a downloaded artifact directly:
|
||||
sudo dnf install ./rustproxy-docker-agent-<version>-<release>.x86_64.rpm
|
||||
```
|
||||
|
||||
The installer runs tests, builds the binary, creates the service account, writes a random token on first install, installs the hardened unit, starts it and prints the TLS fingerprint.
|
||||
Find APT/DNF repository configuration in the Package Builder README or on the repository's index page. The package post-install script creates the system account/state directory, generates missing token and TLS identity, enables the service and starts it when Docker is available. It **does not print the secret token** into package manager logs. If Docker isn't installed/running, the package can be installed first, but the service cannot run until Docker/socket/group are available.
|
||||
|
||||
## Build manually
|
||||
Show all connection details **locally, as root**:
|
||||
|
||||
```bash
|
||||
sudo rustproxy-docker-agent info
|
||||
sudo rustproxy-docker-agent info --show-token
|
||||
sudo rustproxy-docker-agent info --json # machine-readable, redacted by default
|
||||
sudo rustproxy-docker-agent print-fingerprint
|
||||
sudo systemctl status rustproxy-docker-agent
|
||||
sudo journalctl -u rustproxy-docker-agent -n 100 --no-pager
|
||||
```
|
||||
|
||||
Configure **RustProxy → Settings → Docker agents** with the host's `https://host:9876` URL, the full Bearer token, and the printed certificate SHA-256 fingerprint. The RustProxy server pins the certificate when a fingerprint is configured; a replaced certificate requires updating the fingerprint in the panel.
|
||||
|
||||
## CLI commands
|
||||
|
||||
| Command | Behavior |
|
||||
|---|---|
|
||||
| `rustproxy-docker-agent serve` (or no arguments) | Run the discovery API, auto-create a missing TLS certificate with the service account, log endpoint/cert details and **redacted** token status |
|
||||
| `sudo rustproxy-docker-agent init` | Create missing token and self-signed TLS identity; keep existing valid values and certificate |
|
||||
| `sudo rustproxy-docker-agent info` | Show listening endpoint, hostname, Docker socket, token status/length, TLS certificate paths, SHA-256, issuer, subject, SAN, serial, algorithms and validity |
|
||||
| `sudo rustproxy-docker-agent info --show-token` | Explicitly reveal the full Bearer token in addition to metadata |
|
||||
| `sudo rustproxy-docker-agent show-token` | Print **only** the full secret token (protect stdout) |
|
||||
| `sudo rustproxy-docker-agent rotate-token` | Create a new token without replacing the certificate; **restart the service and update RustProxy** before continuing |
|
||||
| `sudo rustproxy-docker-agent cert-init` | Create a missing certificate/key and print SHA-256; never overwrites existing valid certificate/key |
|
||||
| `sudo rustproxy-docker-agent print-fingerprint` | Print current SHA-256 certificate fingerprint |
|
||||
| `rustproxy-docker-agent version` | Print agent version |
|
||||
|
||||
All subcommands accept `--env-file /path/to/file` and relevant connection/TLS overrides such as `--cert-file`, `--key-file`, `--hostname` and `--listen`. Older `--init-cert` and `--print-fingerprint` flags still work. Use `--help` for options; it never includes the configured token in default values.
|
||||
|
||||
To rotate the token:
|
||||
|
||||
```bash
|
||||
sudo rustproxy-docker-agent rotate-token
|
||||
sudo systemctl restart rustproxy-docker-agent
|
||||
sudo rustproxy-docker-agent info --show-token
|
||||
```
|
||||
|
||||
**Important:** The previous token becomes invalid after restart. Update the token in RustProxy Settings. Do not paste the full token into public logs. At normal startup only nonsecret certificate details and token presence/length are written to the journal.
|
||||
|
||||
## Optional: compile and install manually
|
||||
|
||||
From `docker-agent/` in this source tree (Go 1.22+ required):
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go build -trimpath -ldflags='-s -w' -o rustproxy-docker-agent .
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
## systemd
|
||||
The installer builds Go, installs `/usr/local/bin/rustproxy-docker-agent`, creates the same service account/config/state layout, calls the Go CLI `init`, enables/starts systemd and prints the certificate and token for interactive setup. Subsequent manual installations preserve existing credentials.
|
||||
|
||||
1. Create a dedicated `rustproxy-docker-agent` system user and grant it read access to the Docker socket (commonly by membership in the `docker` group). Docker socket access is privileged; isolate this account and the host firewall.
|
||||
2. Copy the binary to `/usr/local/bin/rustproxy-docker-agent`.
|
||||
3. Copy `docker-agent.env.example` to `/etc/rustproxy/docker-agent.env`, generate a long random token and bind only to an address reachable by RustProxy.
|
||||
4. Ensure `/var/lib/rustproxy-docker-agent` is writable only by the service identity. The shipped systemd unit creates it through `StateDirectory=`.
|
||||
5. Copy `rustproxy-docker-agent.service` to `/etc/systemd/system/`, then run `systemctl daemon-reload && systemctl enable --now rustproxy-docker-agent`.
|
||||
For completely manual setup, create a system account with access to the `docker` group; install the binary; copy `docker-agent.env.example` into `/etc/rustproxy/docker-agent.env`; make the env file root-only; and place `rustproxy-docker-agent.service` under `/etc/systemd/system`. Create a writable `/var/lib/rustproxy-docker-agent` owned by the service account, then run `sudo rustproxy-docker-agent init`, `sudo systemctl daemon-reload` and `sudo systemctl enable --now rustproxy-docker-agent`.
|
||||
|
||||
The inventory endpoint is `GET /v1/inventory` with `Authorization: Bearer <token>`. `/healthz` does not expose Docker inventory. Both are served over HTTPS by default.
|
||||
### Switching from manual to package-managed
|
||||
|
||||
`RUSTPROXY_DOCKER_ADVERTISE_IP` marks a preferred address but does not suppress automatic discovery of the host's other addresses. `RUSTPROXY_DOCKER_PUBLIC_IP_URL` adds the externally observed address when enabled. RustProxy can choose a concrete reported address independently for every Docker-backed vhost.
|
||||
Both installation types use the **same** config and certificate paths, but different binary paths (`/usr/local/bin` versus `/usr/bin`). A manual unit in `/etc/systemd/system/` takes precedence over the package unit in `/usr/lib/systemd/system/`. To migrate, first back up `/etc/rustproxy/docker-agent.env` and `/var/lib/rustproxy-docker-agent/`, stop the service, and move the manual service unit outside systemd's unit directories. Run `systemctl daemon-reload`, install the DEB/RPM, and inspect `systemctl cat rustproxy-docker-agent`. Remove the obsolete `/usr/local/bin` binary only after verifying the packaged service. Do **not** delete or regenerate the existing token/key.
|
||||
|
||||
### Removing or upgrading the package
|
||||
|
||||
Upgrades do not reset credentials or private state. The environment file is installed with `config|noreplace`; local edits remain in place according to package-manager conffile behavior. Removal does not delete `/etc/rustproxy/docker-agent.env` or `/var/lib/rustproxy-docker-agent` (back these up separately).
|
||||
|
||||
## API and troubleshooting
|
||||
|
||||
The API is `GET /v1/inventory` with `Authorization: Bearer <token>`; `GET /healthz` has no inventory and requires no token. Both use HTTPS by default. Plain HTTP is possible with `RUSTPROXY_DOCKER_AGENT_TLS=false` but exposes credentials in transit; use it only in a secured network and never across the public Internet.
|
||||
|
||||
- `no valid token`: execute `sudo rustproxy-docker-agent init`; check env file permissions and `EnvironmentFile`.
|
||||
- `Docker socket unavailable`: install/start Docker Engine, check `/var/run/docker.sock`, the `docker` group and membership of `rustproxy-docker-agent`.
|
||||
- `TLS certificate/key`: inspect ownership of `/var/lib/rustproxy-docker-agent/`, mode `0600` on the private key, and both certificate/key paths. Refuse partially missing pairs rather than overwriting them.
|
||||
- `x509` or fingerprint mismatch in RustProxy: compare `sudo rustproxy-docker-agent print-fingerprint` with the pin configured in Settings.
|
||||
- Cannot reach port `9876`: check `RUSTPROXY_DOCKER_AGENT_LISTEN`, listening socket, firewall, and that HTTPS is used.
|
||||
|
||||
`RUSTPROXY_DOCKER_ADVERTISE_IP` adds a preferred host address without suppressing automatic address discovery. `RUSTPROXY_DOCKER_PUBLIC_IP_URL` controls the optional externally observed public IP. The agent's Docker socket access remains privileged; isolate the Docker host and network accordingly.
|
||||
Reference in new issue
Block a user