Support read-only rootfs with self-signed certs in /config/tls

.github/workflows/ci.yml

@@ -101,7 +101,7 @@ jobs:
           # directive user; stdout discarded because -t reopens the config's
           # /dev/stdout logs and the docker exec pipe is root-owned
           docker exec frigate /command/s6-setuidgid frigate bash -c '/usr/local/nginx/sbin/nginx -e stderr -t -c /tmp/nginx/conf/nginx.conf >/dev/null'
-          docker exec frigate stat -c %a /etc/letsencrypt/live/frigate/privkey.pem | grep -qx 600
+          docker exec frigate stat -c %a /config/tls/privkey.pem | grep -qx 600
           docker exec frigate stat -c %a /dev/shm/go2rtc.yaml | grep -qx 640
       - name: Assert services run as non-root
         run: |

docker/main/rootfs/etc/s6-overlay/s6-rc.d/certsync/run

@@ -26,7 +26,13 @@ function reload_nginx() {
 
 echo "[INFO] Starting certsync..."
 
-lefile="/etc/letsencrypt/live/frigate/fullchain.pem"
+# Resolved once, to match the choice nginx made at its own startup: watching a
+# path nginx did not load would compare fingerprints that can never agree.
+if [ -f /etc/letsencrypt/live/frigate/fullchain.pem ]; then
+    lefile="/etc/letsencrypt/live/frigate/fullchain.pem"
+else
+    lefile="/config/tls/fullchain.pem"
+fi
 
 tls_enabled=`python3 /usr/local/nginx/get_nginx_settings.py | jq -r .tls.enabled`
 listen_external_port=`python3 /usr/local/nginx/get_nginx_settings.py | jq -r .listen.external_port`

docker/main/rootfs/etc/s6-overlay/s6-rc.d/nginx/run

@@ -80,22 +80,43 @@ cp -r /usr/local/nginx/conf/. /tmp/nginx/conf/
 
 set_worker_processes
 
-# ensure the directory for ACME challenges exists
-mkdir -p /etc/letsencrypt/www
-
-# Create self signed certs if needed
+# TLS certs: user-mounted certs at /etc/letsencrypt/live/frigate (documented
+# contract) always win; otherwise fall back to a self-signed cert persisted in
+# /config/tls, which stays writable under a read-only root filesystem.
 letsencrypt_path=/etc/letsencrypt/live/frigate
-mkdir -p $letsencrypt_path
+selfsigned_path=/config/tls
 
-if [ ! \( -f "$letsencrypt_path/privkey.pem" -a -f "$letsencrypt_path/fullchain.pem" \) ]; then
-    echo "[INFO] No TLS certificate found. Generating a self signed certificate..."
-    openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
-        -subj "/O=FRIGATE DEFAULT CERT/CN=*" \
-        -keyout "$letsencrypt_path/privkey.pem" -out "$letsencrypt_path/fullchain.pem" 2>/dev/null
-    chmod 600 "$letsencrypt_path/privkey.pem"
-    chmod 644 "$letsencrypt_path/fullchain.pem"
+if [ -f "$letsencrypt_path/privkey.pem" ] && [ -f "$letsencrypt_path/fullchain.pem" ]; then
+    cert_path="$letsencrypt_path"
+else
+    cert_path="$selfsigned_path"
+
+    # The ownership sweep hands /config to the runtime user, so root must not
+    # create or chmod anything here: that user could plant a symlink and
+    # redirect openssl onto any root path (both follow symlinks). Generating as
+    # the runtime user keeps every write inside the privileges it already has.
+    # The escape hatch never sweeps, so /config stays root-owned and root writes.
+    gen=()
+    if [[ "$(id -u)" -eq 0 && "${FRIGATE_RUN_AS_ROOT:-false}" != "true" ]]; then
+        gen=(s6-setuidgid frigate)
+    fi
+
+    "${gen[@]}" mkdir -p "$cert_path"
+
+    if [ ! \( -f "$cert_path/privkey.pem" -a -f "$cert_path/fullchain.pem" \) ]; then
+        echo "[INFO] No TLS certificate found. Generating a self signed certificate..."
+        "${gen[@]}" openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
+            -subj "/O=FRIGATE DEFAULT CERT/CN=*" \
+            -keyout "$cert_path/privkey.pem" -out "$cert_path/fullchain.pem" 2>/dev/null
+        "${gen[@]}" chmod 600 "$cert_path/privkey.pem"
+        "${gen[@]}" chmod 644 "$cert_path/fullchain.pem"
+    fi
 fi
 
+# ACME challenges are only served from a writable rootfs; skipping the mkdir
+# under read_only leaves the location 404ing, which is the same as unused
+mkdir -p /etc/letsencrypt/www 2>/dev/null || true
+
 # nginx settings are read once; both templates consume them
 nginx_settings=$(python3 /usr/local/nginx/get_nginx_settings.py)
 
@@ -104,8 +125,10 @@ echo "$nginx_settings" | \
     tempio -template /usr/local/nginx/templates/base_path.gotmpl \
            -out /tmp/nginx/conf/base_path.conf
 
-# build templates for additional network settings
+# build templates for additional network settings; listen.conf is the only
+# template that needs the resolved cert directory
 echo "$nginx_settings" | \
+    jq --arg p "$cert_path" '.tls.cert_path = $p' | \
     tempio -template /usr/local/nginx/templates/listen.gotmpl \
            -out /tmp/nginx/conf/listen.conf
 
@@ -118,9 +141,12 @@ if [[ "$(id -u)" -eq 0 && "$runs_as_root" -eq 0 ]]; then
     # nginx reopens /dev/stdout by path for its logs, and s6 made the pipe
     # root-owned 0600; without this the non-root master exits EACCES
     chown frigate /dev/stdout
-    # self-signed certs are root-generated; tolerant because mounted certs may be :ro
-    if [ -f "$letsencrypt_path/privkey.pem" ]; then
-        chown frigate:frigate "$letsencrypt_path/privkey.pem" "$letsencrypt_path/fullchain.pem" 2>/dev/null || true
+    # Only mounted certs need handing over; the self-signed pair is already
+    # owned by the runtime user that generated it. Never chown the /config copy:
+    # chown follows symlinks, so it would retarget onto any root file the
+    # runtime user pointed it at. Tolerant because mounted certs may be :ro.
+    if [ "$cert_path" = "$letsencrypt_path" ] && [ -f "$cert_path/privkey.pem" ]; then
+        chown frigate:frigate "$cert_path/privkey.pem" "$cert_path/fullchain.pem" 2>/dev/null || true
     fi
 fi
 

docker/main/rootfs/usr/local/nginx/templates/listen.gotmpl

@@ -8,8 +8,8 @@ listen {{ .listen.internal }};
     listen {{ .listen.external }} ssl;
     {{ if .ipv6.enabled }}listen [::]:{{ .listen.external_port }} ssl;{{ end }}
 
-    ssl_certificate /etc/letsencrypt/live/frigate/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/frigate/privkey.pem;
+    ssl_certificate {{ .tls.cert_path }}/fullchain.pem;
+    ssl_certificate_key {{ .tls.cert_path }}/privkey.pem;
 
     # generated 2024-06-01, Mozilla Guideline v5.7, nginx 1.25.3, OpenSSL 1.1.1w, modern configuration, no OCSP
     # https://ssl-config.mozilla.org/#server=nginx&version=1.25.3&config=modern&openssl=1.1.1w&ocsp=false&guideline=5.7

docs/docs/configuration/tls.md

@@ -9,7 +9,7 @@ import NavPath from "@site/src/components/NavPath";
 
 # TLS
 
-Frigate's integrated NGINX server supports TLS certificates. By default Frigate will generate a self signed certificate that will be used for port 8971. Frigate is designed to make it easy to use whatever tool you prefer to manage certificates.
+Frigate's integrated NGINX server supports TLS certificates. By default Frigate will generate a self signed certificate that will be used for port 8971, stored in `/config/tls` so it survives container recreation. Frigate is designed to make it easy to use whatever tool you prefer to manage certificates.
 
 Frigate is often running behind a reverse proxy that manages TLS certificates for multiple services. You will likely need to set your reverse proxy to allow self signed certificates or you can disable TLS in Frigate's config. However, if you are running on a dedicated device that's separate from your proxy or if you expose Frigate directly to the internet, you may want to configure TLS with valid certificates.
 
@@ -45,7 +45,9 @@ frigate:
   ...
 ```
 
-Within the folder, the private key is expected to be named `privkey.pem` and the certificate is expected to be named `fullchain.pem`.
+Within the folder, the private key is expected to be named `privkey.pem` and the certificate is expected to be named `fullchain.pem`. Mounted certificates take precedence over the self signed pair in `/config/tls`.
+
+`privkey.pem` must be readable by the runtime user that runs NGINX. Frigate hands it over at startup when the mount is writable; on a `:ro` mount, make it readable by uid 1000 (or your `PUID`) yourself. See [Running as a non-root user](/configuration/non_root).
 
 Note that certbot uses symlinks, and those can't be followed by the container unless it has access to the targets as well, so if using certbot you'll also have to mount the `archive` folder for your domain, e.g.:
 
@@ -73,4 +75,4 @@ frigate:
 
 ## ACME Challenge
 
-Frigate also supports hosting the acme challenge files for the HTTP challenge method if needed. The challenge files should be mounted at `/etc/letsencrypt/www`.
+Frigate also supports hosting the acme challenge files for the HTTP challenge method if needed. The challenge files should be mounted at `/etc/letsencrypt/www`. With a read-only root filesystem this has to be a mounted volume, since Frigate cannot create the directory itself.