v0.3

docs/INSTALL.md

@@ -86,6 +86,62 @@ Then visit `http://127.0.0.1:9090` on your workstation. For a directly reachable
 - Listener bindings supplied explicitly via service arguments/systemd are locked against panel changes. Network bind, administration TLS and some monitoring changes take effect after a restart.
 - Ports below 1024 need the appropriate OS privileges/capability; use the installed service model rather than running the whole application as root.
 
+## Optional systemd JSON configuration
+
+This is **optional**. Without `--config`, RustProxy keeps its active configuration in `/var/lib/rustproxy/config.sqlite3` (SQLite). With `--config`, panel/API saves and history restores write `/etc/rustproxy/config.json` atomically; SQLite still contains history, administrator state and audit entries. In **Settings → Manual config** you can see which mode and path are active.
+
+1. First export your existing, validated **full configuration** (do not start with `{}` on an established host). On the running instance with administration reachable at `127.0.0.1:9090`, use a privileged shell with `set -o pipefail`:
+
+   ```bash
+   sudo install -d -o root -g root -m 0700 /etc/rustproxy
+   sudo install -o root -g root -m 0600 /dev/null /etc/rustproxy/config.json
+   sudo -u rustproxy /usr/bin/rust-proxy --data-dir /var/lib/rustproxy \
+     --admin-listen 127.0.0.1:9090 config get | sudo tee /etc/rustproxy/config.json >/dev/null
+   ```
+
+   If the installed binary is at `/opt/rustproxy/current/rust-proxy`, use that path in **both** commands and the override. The export requires an existing initialized administrator. You may instead use **Settings → Manual config → Export JSON**, then install that file securely with `sudo install -o root -g root -m 0600 exported.json /etc/rustproxy/config.json`.
+
+2. Keep the directory and initial file owned by `root`, allow only the RustProxy service identity through **named POSIX ACLs** (install the `acl` package first, e.g. `sudo apt-get install acl` on Debian, to obtain `setfacl`/`getfacl`). The directory needs `rwx` for atomic create/rename; the original JSON needs `rw` for startup and backup tools. `root` retains ownership until the first atomic panel save, after which the new `0600` file is normally owned by `rustproxy`:
+
+   ```bash
+   sudo chown root:root /etc/rustproxy /etc/rustproxy/config.json
+   sudo chmod 0700 /etc/rustproxy
+   sudo chmod 0600 /etc/rustproxy/config.json
+   sudo setfacl -m u:rustproxy:rwx /etc/rustproxy
+   sudo setfacl -m u:rustproxy:rw- /etc/rustproxy/config.json
+   sudo getfacl /etc/rustproxy /etc/rustproxy/config.json
+   sudo -u rustproxy test -r /etc/rustproxy/config.json
+   sudo -u rustproxy test -w /etc/rustproxy
+   ```
+
+   Never make `/etc/rustproxy` world-writable. RustProxy checks that `--config` is an existing absolute **regular non-symlink** file. The parent directory must be on a filesystem that supports atomic rename. Restoring a file as root may require reapplying its named ACL; atomic saves generate a new owner-only `0600` file.
+
+3. Edit the systemd drop-in with `sudo systemctl edit rustproxy` and add the following example (the binary path must match your installation):
+
+   ```ini
+   [Service]
+   ExecStart=
+   ExecStart=/usr/bin/rust-proxy --data-dir /var/lib/rustproxy --admin-listen 0.0.0.0:9090 serve --proxy-listen 0.0.0.0:80 --tls-listen 0.0.0.0:443 --allow-remote-admin --config /etc/rustproxy/config.json
+   ReadWritePaths=/etc/rustproxy
+   ```
+
+   `ReadWritePaths=` is needed when the unit has `ProtectSystem=strict`; it does **not** grant Unix file permissions, hence the ACLs above. An existing `ExecReload` can remain; it reloads through the local control API. Keep the existing unit's sandboxing, state/log writable paths, network capabilities and runtime user. Do not expose the example's `0.0.0.0:9090` admin listener over plaintext on an untrusted network: enable administration HTTPS and strict network controls first, or use the safer `127.0.0.1:9090` binding without `--allow-remote-admin`.
+
+4. Verify and restart during a maintenance window:
+
+   ```bash
+   sudo systemctl daemon-reload
+   sudo systemctl cat rustproxy
+   sudo systemd-analyze verify rustproxy.service
+   sudo systemctl restart rustproxy
+   sudo systemctl status rustproxy
+   sudo journalctl -u rustproxy -n 60 --no-pager
+   ```
+
+   Confirm in **Settings → Manual config** that the source is **JSON file** and the path is `/etc/rustproxy/config.json`. Save a harmless edit and confirm that the file is rewritten and readable by `rustproxy`; check that a revision appears in SQLite. To import a deliberate external file edit without restarting, run `sudo systemctl reload rustproxy` (if the unit has `ExecReload`) or `rust-proxy --data-dir /var/lib/rustproxy --admin-listen 127.0.0.1:9090 config reload`. The file is not watched automatically. An incompatible external edit must fail validation rather than silently overwrite the live configuration.
+
+For the alternate environment-variable method, set `RUST_PROXY_CONFIG=/etc/rustproxy/config.json` in the service's protected EnvironmentFile. Do not set **both** unrelated config paths. See [Configuration](CONFIGURATION.md) and the [deployment example](../deploy/README.md).
+
 ## Managed update
 
 Test the new build first. Then execute:
@@ -105,4 +161,4 @@ The managed certificate service can create a private Python/Certbot environment
 
 Verify `systemctl status rustproxy` and `journalctl -u rustproxy` (managed systemd), the panel login, frontend certificates, first Vhost, real backend response, access policies, optional QUIC, current logs and a full backup/restore test. For error diagnosis, consult [Troubleshooting](TROUBLESHOOTING.md).
 
-**Release verification:** supplied 0.34.0 source changes still require target-platform compilation and functional acceptance before Internet-facing production use.
+**Release verification:** RustProxy 0.34.2 is a source package; complete a Rust 1.99+ build and target-platform HTTP/systemd/security acceptance tests before Internet-facing production use.