v.34.5_fix_systemd

docs/ACME_PROVIDERS.md

@@ -2,6 +2,15 @@
 
 Certificates are managed under **Certificates**. You can import a PEM pair, reference accessible external certificate files or request a managed ACME certificate. Issuing a certificate does **not** automatically assign it to a Vhost; choose the certificate in the intended frontend/Vhost afterwards.
 
+On Linux, the updated DEB/RPM service allows **read-only** access to
+external certificate paths according to the `rustproxy` user's Unix group/
+ACL permissions, including paths inside `/home`. A separate safety rule still
+requires the actual PEM files and real parent directories to be owned by root
+or `rustproxy`; user-owned `/home/alice` is therefore unsuitable as a PEM
+ancestor even though it can host a Web Server document root. See
+[Installation: external paths](INSTALL.md#linux-debrpm-read-only-access-to-external-paths)
+for scoped ACLs and Certbot renewal handling.
+
 ## Supported certificate methods
 
 | Mode | Requirements |

docs/INSTALL.md

@@ -87,6 +87,78 @@ 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.
 
+## Linux DEB/RPM: read-only access to external paths
+
+New Linux packages (package-builder filesystem-access policy, revision 5) and
+the maintained manual service template use `ProtectHome=read-only` rather than
+`ProtectHome=true`. This makes document roots under `/home`, `/var/www` and
+`/srv` readable if the service account has **ordinary Unix group or ACL
+permissions**. `ProtectSystem=strict` remains enabled: the service cannot
+modify these files merely because a group or ACL permits it. No systemd
+drop-in or extra `ReadOnlyPaths=` entry is needed to **read** site content or
+an external certificate. This also applies when paths are stored in the panel.
+
+The service runs as the unprivileged `rustproxy` user. To use a dedicated web
+group, give that group directory traversal and file read permissions on the
+site, then add RustProxy to it:
+
+```bash
+sudo usermod -aG web-readers rustproxy   # use an existing narrow site group
+sudo systemctl restart rustproxy       # renew the service process's group list
+```
+
+Alternatively, to expose only `/home/alice/public_html` (install `acl` to get
+`setfacl`), grant traversal of the private home and read/traversal of the site:
+
+```bash
+sudo setfacl -m u:rustproxy:--x /home/alice
+sudo setfacl -R -m u:rustproxy:r-X /home/alice/public_html
+sudo -u rustproxy test -r /home/alice/public_html/index.html && echo readable
+sudo systemctl restart rustproxy
+```
+
+Use appropriate **default ACLs** or group ownership on directories where the
+deployment process creates new files. Never expose the entire home directory
+or use world-writable permissions to work around access errors. The
+`sudo -u` check tests Unix permissions on the host, not the effective systemd
+mount namespace.
+
+External PEM files have **additional application security checks**. The
+certificate/key and every real ancestor directory must be owned by root or
+the RustProxy service user, and ancestors cannot be group/world-writable;
+private keys cannot be world-readable. For Certbot files at
+`/etc/letsencrypt/live/example.com`, for example:
+
+```bash
+sudo setfacl -m u:rustproxy:--x /etc/letsencrypt /etc/letsencrypt/live \
+  /etc/letsencrypt/live/example.com /etc/letsencrypt/archive \
+  /etc/letsencrypt/archive/example.com
+sudo setfacl -m u:rustproxy:r-- "$(readlink -f /etc/letsencrypt/live/example.com/fullchain.pem)"
+sudo setfacl -m u:rustproxy:r-- "$(readlink -f /etc/letsencrypt/live/example.com/privkey.pem)"
+sudo systemctl reload rustproxy
+```
+
+Apply the file ACL again when a renewal replaces the symlink's target, then
+reload. Arbitrary user-owned parent directories (for example `/home/alice`)
+are suitable for static websites but **not** for external keys under the
+current trusted-path validation. Use root-owned certificate storage instead.
+Keep all key access narrow and read-only.
+
+To diagnose unresolved errors, run `systemctl cat rustproxy` and
+`systemctl show rustproxy -p ProtectHome -p ProtectSystem -p User -p Group`,
+check parent permissions with `namei -l /path/to/file`, and examine
+`journalctl -u rustproxy`. A legacy whole-unit file in
+`/etc/systemd/system/rustproxy.service` takes precedence over the packaged
+unit and is **not** automatically removed by an upgrade. On SELinux/AppArmor
+hosts, additional mandatory access-control policy may be required; POSIX ACLs
+cannot bypass it. See [Web Server](WEB_SERVER.md) and
+[Certificates](ACME_PROVIDERS.md).
+
+**Write access is intentionally different.** An app that needs to upload or
+modify files under an arbitrary document root needs a separately planned
+writable location/policy; group membership alone does not bypass the read-only
+systemd mount. Keep mutable data isolated from served files.
+
 ## 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.

docs/WEB_SERVER.md

@@ -13,6 +13,14 @@ The built-in Web Server serves local files and, optionally, passes PHP scripts t
 
 A Web Service can be shared across several Vhosts. A Vhost may also use ordinary Reverse Proxy as its default and a Web Service for `/assets` or another custom location. Web Server and HTTP reverse proxy use the normal frontend TLS, access, logging and eligible cache pipeline.
 
+**Linux DEB/RPM paths:** With the updated package unit, `/home/user/public_html`,
+`/var/www/site` and `/srv/site` are readable using an appropriately scoped
+service-user group or POSIX ACL; no `systemctl edit` or
+`ReadOnlyPaths=` exception is needed. The filesystem remains read-only to the
+service outside its private state/log/config paths. Grant execute/traversal
+on each parent directory and read permission on served files; see
+[Installation: external paths](INSTALL.md#linux-debrpm-read-only-access-to-external-paths).
+
 ## File serving options
 
 | Feature | Behavior / caution |
@@ -58,7 +66,7 @@ Vhosts can intercept selected application error bodies in **Pages** and return a
 
 A Web Service's dashboard shows request rate, status/error counts, response-header timing, delivered bytes and PHP permit usage (when PHP is configured). These are application observations, not proof of external PHP worker count or final compressed network bytes.
 
-- **403 / unexpected block:** inspect document-root permissions, symlink policy, hardening and inherited ACLs.
+- **403 / unexpected block:** inspect document-root permissions (including parent traversal), symlink policy, hardening, inherited ACLs and any SELinux/AppArmor denial; verify the active systemd unit is the updated one.
 - **404 / unwanted SPA rewrite:** check actual files, index list, `try_files`, location matching and rewrite order.
 - **Wrong Content-Type/download:** check MIME override and attachment extensions.
 - **PHP script downloaded instead of executed:** check PHP enablement, script extension and FPM endpoint.