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
@@ -4,13 +4,57 @@ RustProxy discovers published Docker services through a **separate read-only Doc
|
||||
|
||||
## Set up a Docker host
|
||||
|
||||
1. On the Docker host, review `docker-agent/README.md`, `docker-agent/docker-agent.env.example` and `docker-agent/install.sh`.
|
||||
2. Build/install the Go agent with `cd docker-agent && sudo ./install.sh`; the installer runs tests, installs the service, initializes a Bearer token and an HTTPS certificate, and prints the SHA-256 certificate fingerprint.
|
||||
3. Restrict the agent port (default shown in the example environment: `9876`) to the RustProxy host/network. Access to the Docker socket is privileged, even though the agent's HTTP API is read-only.
|
||||
4. In **Settings → Docker agents**, create an agent with an endpoint such as `https://10.10.0.21:9876`, its token and printed fingerprint, base domain, selected listener IDs and optional certificate/ACL/default backend IP.
|
||||
5. Use **Docker vhosts → Refresh agents** and check that the agent observation is successful before publishing any service.
|
||||
Install the **optional Docker agent on each Linux Docker host**, not on the RustProxy server. It is distributed as a separate `rustproxy-docker-agent` DEB/RPM package and is **not built as FreeBSD `pkg`**. Docker Engine, systemd and access to `/var/run/docker.sock` are required at runtime.
|
||||
|
||||
The agent normally presents its own persistent self-signed certificate; pin the exact fingerprint in RustProxy. When using a CA-issued agent certificate, normal TLS CA/hostname verification can be used instead. Plain HTTP exposes the bearer token and should be avoided.
|
||||
### Option A: prebuilt DEB/RPM (recommended)
|
||||
|
||||
After configuring the signed APT/DNF RustProxy repository (see [Installation](INSTALL.md)):
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt update && sudo apt install rustproxy-docker-agent
|
||||
|
||||
# Or on RHEL / Rocky / Alma / Fedora
|
||||
sudo dnf install rustproxy-docker-agent
|
||||
```
|
||||
|
||||
For offline/local installation use `sudo apt install ./rustproxy-docker-agent_<version>-<release>_amd64.deb` or `sudo dnf install ./rustproxy-docker-agent-<version>-<release>.x86_64.rpm`. The post-install script generates a random token and self-signed TLS certificate on first install, creates a systemd service, and preserves credentials across upgrades. It does not print the token to unattended installation logs.
|
||||
|
||||
```bash
|
||||
sudo rustproxy-docker-agent info # endpoint, TLS fingerprint, validity, token status
|
||||
sudo rustproxy-docker-agent info --show-token # full secret token: run locally as root
|
||||
sudo systemctl status rustproxy-docker-agent
|
||||
```
|
||||
|
||||
### Option B: build and install manually (optional)
|
||||
|
||||
```bash
|
||||
cd docker-agent
|
||||
go test ./...
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
Go 1.22+ is required only for the manual build, not for a DEB/RPM installation. The manual installer uses the same Go CLI to create credentials and TLS identity and displays the token interactively. Detailed custom systemd setup and migration between manual/package-managed services are in [docker-agent/README.md](../docker-agent/README.md).
|
||||
|
||||
### Connect to RustProxy
|
||||
|
||||
1. Allow port `9876` **only from the RustProxy server** in the Docker-host firewall. The default example listens on `0.0.0.0:9876`.
|
||||
2. In **Settings → Docker agents**, create an agent with an endpoint such as `https://10.10.0.21:9876`, its Bearer token and certificate SHA-256 fingerprint, base domain, selected listener IDs, and optional certificate/ACL/default backend IP.
|
||||
3. Use **Docker vhosts → Refresh agents** and check that discovery succeeds before publishing.
|
||||
|
||||
The self-signed certificate is persistent. RustProxy pins its exact fingerprint; if replaced, update the pin. A trusted CA-issued certificate can use normal CA and hostname verification instead. Plain HTTP is available only by explicit opt-out and exposes the token in transit.
|
||||
|
||||
To inspect or rotate credentials after installation:
|
||||
|
||||
```bash
|
||||
sudo rustproxy-docker-agent info --json
|
||||
sudo rustproxy-docker-agent print-fingerprint
|
||||
sudo rustproxy-docker-agent rotate-token
|
||||
sudo systemctl restart rustproxy-docker-agent
|
||||
sudo rustproxy-docker-agent show-token # secret: update it in RustProxy settings
|
||||
```
|
||||
|
||||
A token change invalidates the previous token after service restart. The agent logs certificate details and **redacted** token status at startup. The Docker socket is root-equivalent access; isolate the service account and host even though the HTTP inventory endpoint is read-only.
|
||||
|
||||
## What discovery reports
|
||||
|
||||
|
||||
+3
-2
@@ -6,13 +6,14 @@ Use maintained packages whenever possible. For custom installations, use the scr
|
||||
|
||||
| Installation | Recommended starting point |
|
||||
|---|---|
|
||||
| Linux DEB/RPM | https://rustproxy.linuxiarz.pl/ |
|
||||
| Linux DEB/RPM (RustProxy server) | https://rustproxy.linuxiarz.pl/ |
|
||||
| Docker host discovery agent (independent DEB/RPM) | `sudo apt install rustproxy-docker-agent` or `sudo dnf install rustproxy-docker-agent`; see [Docker discovery](DOCKER_DISCOVERY.md) |
|
||||
| OPNsense plugin | https://rustproxy-opn.linuxiarz.pl/ |
|
||||
| Debian 13+ source bootstrap | `install-debian13.sh` from the project repository |
|
||||
| Manual Linux/systemd install | Compile the application; use `install.sh` and `update.sh` |
|
||||
| OCI container | Included `Dockerfile`; see [Container](CONTAINER.md) |
|
||||
|
||||
Package/plugin instructions and maintenance policies are maintained separately from the source archive.
|
||||
Package/plugin instructions and maintenance policies are maintained separately from the source archive. The optional Docker agent is packaged independently of RustProxy's main service for **Linux amd64/x86_64 only**, not FreeBSD pkg. On a Docker host, the agent can also be installed manually from `docker-agent/install.sh`; the installer and packages preserve existing tokens and TLS keys. See [Docker discovery](DOCKER_DISCOVERY.md) and [agent operations](../docker-agent/README.md).
|
||||
|
||||
## Debian 13+ source bootstrap
|
||||
|
||||
|
||||
+1
-1
@@ -24,7 +24,7 @@ Practical guides for **RustProxy 0.34.2**. This index and the listed pages are a
|
||||
## Integrations and operations
|
||||
|
||||
- [Certificates and automatic renewal](ACME_PROVIDERS.md) — PEM, HTTP-01, DNS-01, Certbot and external certificates.
|
||||
- [Docker discovery](DOCKER_DISCOVERY.md) — agent installation, networking and generated Vhosts.
|
||||
- [Docker discovery](DOCKER_DISCOVERY.md) — optional Linux agent DEB/RPM or manual installation, TLS/token CLI, networking and generated Vhosts.
|
||||
- [Other integrations](INTEGRATIONS.md) — Tinyauth, NPM migration, OPNsense and monitoring tools.
|
||||
- [Dashboard](DASHBOARD.md) — metrics panels, presets and configuration history.
|
||||
- [Monitoring](MONITORING.md) — Prometheus, full JSON and compact `summary` API, traffic, backend and cache observations.
|
||||
|
||||
Reference in new issue
Block a user