diff --git a/cmd/zrok2/adminCreateFrontend.go b/cmd/zrok2/adminCreateFrontend.go index b4aad304..db07e757 100644 --- a/cmd/zrok2/adminCreateFrontend.go +++ b/cmd/zrok2/adminCreateFrontend.go @@ -21,7 +21,7 @@ type adminCreateFrontendCommand struct { func newAdminCreateFrontendCommand() *adminCreateFrontendCommand { cmd := &cobra.Command{ - Use: "frontend [urlTemplate]", + Use: "frontend ", Short: "Create a global public frontend", Args: cobra.RangeArgs(2, 3), } diff --git a/nfpm/zrok2-bootstrap.bash b/nfpm/zrok2-bootstrap.bash index 6e96f945..3a432c8c 100755 --- a/nfpm/zrok2-bootstrap.bash +++ b/nfpm/zrok2-bootstrap.bash @@ -805,7 +805,7 @@ step_create_frontend() { info "Found public identity Ziti ID: $public_ziti_id" local output - if ! output=$(zrok2_admin create frontend --dynamic "$public_ziti_id" public 2>&1); then + if ! output=$(zrok2_admin create frontend --dynamic -- "$public_ziti_id" public 2>&1); then error "zrok2 admin create frontend failed: $output" return 1 fi diff --git a/website/docs/self-hosting/deployment/linux.mdx b/website/docs/self-hosting/deployment/linux.mdx index ff4122b8..bdcc9255 100644 --- a/website/docs/self-hosting/deployment/linux.mdx +++ b/website/docs/self-hosting/deployment/linux.mdx @@ -285,7 +285,7 @@ With `ZROK2_ADMIN_TOKEN` and `ZROK2_API_ENDPOINT` set, create a dynamic frontend identity created by `zrok2 admin bootstrap` (shown in its output): ```bash -zrok2 admin create frontend --dynamic public +zrok2 admin create frontend --dynamic -- public ``` This outputs a **frontend token** (e.g., `zEjQqHliYXF6`). Save it—you'll need it for the frontend configuration and @@ -430,18 +430,46 @@ Replace `` with the token from [Step 6](#step-6-create-a-dynamic sudo chmod 640 /etc/zrok2/frontend.yml ``` -3. (If applicable) If the TLS certificate files are only readable by root (common with Let's Encrypt), grant read access - to the service users: +3. (If applicable) If the zrok controller terminates TLS directly (i.e., you uncommented the `tls:` section in + `ctrl.yml` rather than fronting with Caddy or Traefik), the service users need read access to the certificate + files. Let's Encrypt certificates are typically only readable by root. + + Create a shared group and grant it read access to the certificate files: ```bash sudo groupadd --system zrok2-tls 2>/dev/null || true - sudo usermod -aG zrok2-tls zrok2-controller - sudo usermod -aG zrok2-tls zrok2-frontend sudo chgrp -R zrok2-tls /etc/letsencrypt/archive/zrok.example.com/ sudo chmod g+r /etc/letsencrypt/archive/zrok.example.com/* sudo chmod o+x /etc/letsencrypt /etc/letsencrypt/live /etc/letsencrypt/archive ``` + Then add `SupplementaryGroups=zrok2-tls` to each service's systemd override so the process runs with the group. + `systemctl edit` creates a drop-in override that persists across package upgrades: + + ```bash + sudo -E systemctl edit zrok2-controller + ``` + + Add: + + ```ini + [Service] + SupplementaryGroups=zrok2-tls + ``` + + Repeat for the frontend: + + ```bash + sudo -E systemctl edit zrok2-frontend + ``` + + Add the same `[Service]` / `SupplementaryGroups=zrok2-tls` block. Then reload and restart: + + ```bash + sudo systemctl daemon-reload + sudo systemctl restart zrok2-controller zrok2-frontend + ``` + For a complete reference of all frontend options including OAuth, see the [Dynamic proxy frontend migration guide](@zrokdocs/self-hosting/dynamic-proxy). diff --git a/website/docs/self-hosting/dynamic-proxy.md b/website/docs/self-hosting/dynamic-proxy.md index 05693bff..b4d127c1 100644 --- a/website/docs/self-hosting/dynamic-proxy.md +++ b/website/docs/self-hosting/dynamic-proxy.md @@ -229,17 +229,16 @@ Parameters: Create a frontend with the dynamic flag enabled: ```bash -zrok2 admin create frontend --dynamic public "http://{token}.zrok.example.com:8080" +zrok2 admin create frontend --dynamic -- public ``` This creates a dynamic frontend and outputs a frontend token (e.g., `KMmfE0VXO7Pp`). Command breakdown: - **`--dynamic`**: enables dynamic mode (required for dynamicProxy) -- **`public`**: Ziti identity that will bind the frontend (must have dial permissions to dynamicProxyController service) -- **`"http://{token}.zrok.example.com:8080"`**: URL template for shares - - This is the legacy URL template used with legacy `publicProxy` frontends; disregarded by new v2 `dynamicProxy` installations and will be removed in future versions of zrok - - `{token}` is replaced with the share token or name +- **``**: Ziti ID of the `public` identity (from `zrok2 admin bootstrap` output) +- **`public`**: the public name for the frontend +- **`--`**: end-of-flags separator (prevents Ziti IDs starting with `-` from being parsed as flags) - can use `https` if you configure TLS in the frontend config diff --git a/website/docs/self-hosting/scaling-frontends.md b/website/docs/self-hosting/scaling-frontends.md index 678c553b..bdd3d53d 100644 --- a/website/docs/self-hosting/scaling-frontends.md +++ b/website/docs/self-hosting/scaling-frontends.md @@ -58,8 +58,8 @@ optionally its own Ziti identity. Map each to the same namespace(s). ```bash # Create additional frontends (each gets a unique token) -zrok2 admin create frontend --dynamic frontend-2 -zrok2 admin create frontend --dynamic frontend-3 +zrok2 admin create frontend --dynamic -- frontend-2 +zrok2 admin create frontend --dynamic -- frontend-3 # Map them to the same namespace zrok2 admin create namespace-frontend public @@ -77,7 +77,7 @@ To create a separate identity for each frontend: zrok2 admin create identity public-2 # Create the frontend using the new identity's Ziti ID -zrok2 admin create frontend --dynamic frontend-2 +zrok2 admin create frontend --dynamic -- frontend-2 ``` Then configure each frontend's `frontend.yaml` with its own `frontend_token`,