wildcard domains support

Author: terion-labs

ansible/roles/traefik/tasks/main.yml

@@ -92,6 +92,14 @@
     - "{{ terrarium_traefik_config_dir }}/bootstrap-certs"
     - /var/lib/traefik
 
+- name: Create Traefik secret directory
+  ansible.builtin.file:
+    path: /etc/terrarium/secrets
+    state: directory
+    owner: root
+    group: root
+    mode: "0700"
+
 - name: Determine whether bootstrap TLS is required
   ansible.builtin.set_fact:
     terrarium_bootstrap_tls_enabled: "{{ terrarium_idp_mode == 'local' and (terrarium_auth_domain | default('') | length > 0) }}"
@@ -184,6 +192,23 @@
     state: touch
     mode: "0600"
 
+- name: Render Traefik DNS challenge credential environment
+  ansible.builtin.template:
+    src: traefik-dns.env.j2
+    dest: /etc/terrarium/secrets/traefik-dns.env
+    owner: root
+    group: root
+    mode: "0600"
+  notify: restart traefik
+  when: terrarium_acme_dns_provider | default('') | length > 0
+
+- name: Remove Traefik DNS challenge credential environment when DNS-01 is disabled
+  ansible.builtin.file:
+    path: /etc/terrarium/secrets/traefik-dns.env
+    state: absent
+  notify: restart traefik
+  when: terrarium_acme_dns_provider | default('') | length == 0
+
 - name: Render Traefik static config
   ansible.builtin.template:
     src: traefik.yml.j2

ansible/roles/traefik/templates/traefik-dns.env.j2

@@ -0,0 +1,3 @@
+{% for item in (terrarium_acme_dns_env | default({}) | dictsort) %}
+{{ item.0 }}={{ item.1 | to_json }}
+{% endfor %}

ansible/roles/traefik/templates/traefik.service.j2

@@ -5,6 +5,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
+EnvironmentFile=-/etc/terrarium/secrets/traefik-dns.env
 ExecStart=/usr/local/bin/traefik --configFile={{ terrarium_traefik_config_dir }}/traefik.yml --entrypoints.bootstrapweb.address=127.0.0.1:18080
 Restart=on-failure
 RestartSec=5s

ansible/roles/traefik/templates/traefik.yml.j2

@@ -18,8 +18,13 @@ certificatesResolvers:
     acme:
       email: {{ terrarium_acme_email }}
       storage: /var/lib/traefik/acme.json
+{% if terrarium_acme_dns_provider | default('') | length > 0 %}
+      dnsChallenge:
+        provider: {{ terrarium_acme_dns_provider }}
+{% else %}
       httpChallenge:
         entryPoint: web
+{% endif %}
 
 log:
   level: INFO

docs/getting-started/domains-and-auth.md

@@ -35,7 +35,7 @@ Container apps become public only when you add a `user.proxy` label to the LXD i
 For normal web apps, use this format:
 
 ```text
-https://<public-host>[:container-port][/path][@auth[:group[,group...]]]
+https://<public-host>[:container-port][/path][@auth[:group[,group...]][~callback-host]]
 ```
 
 Examples:
@@ -63,8 +63,30 @@ What each part means:
 - `/path` is optional and is matched as a path prefix.
 - `@auth` requires a successful OIDC login before traffic reaches the app.
 - `@auth:admins,devops` also requires membership in one of those groups.
+- `~auth.example.com` is required only for wildcard auth routes and gives Terrarium the concrete oauth2-proxy callback host.
 
-Use `https://` for normal public routes. Terrarium will request a Let's Encrypt certificate and redirect plain HTTP to HTTPS. Query strings and URL fragments are not part of route labels. Wildcard route hosts such as `*.example.com` are not supported; each published hostname needs its own explicit label.
+Use `https://` for normal public routes. Terrarium will request a Let's Encrypt certificate and redirect plain HTTP to HTTPS. Query strings and URL fragments are not part of route labels.
+
+Wildcard HTTPS routes are supported after DNS-01 ACME is configured:
+
+```bash
+terrariumctl set dns provider cloudflare CF_DNS_API_TOKEN:your-token
+lxc config set my-app user.proxy "https://*.example.com:8080"
+terrariumctl proxy sync
+```
+
+DNS credentials map directly to lego's provider environment variable names. See the [lego DNS provider list](https://go-acme.github.io/lego/dns/index.html) for supported providers and required variables. To disable DNS-01 and return to HTTP-01 certificate validation, run:
+
+```bash
+terrariumctl set dns provider
+```
+
+Wildcard auth routes need a concrete callback host under the same base domain:
+
+```bash
+lxc config set admin-ui user.proxy "https://*.example.com:3000@auth:admins~auth.example.com"
+terrariumctl proxy sync
+```
 
 You can publish more than one route from the same container by separating routes with commas or newlines:
 

docs/reference/terrariumctl.md

@@ -137,21 +137,32 @@ terrariumctl proxy sync
 HTTP(S) route format:
 
 ```text
-https://<public-host>[:container-port][/path][@auth[:group[,group...]]]
-http://<public-host>[:container-port][/path][@auth[:group[,group...]]]
+https://<public-host>[:container-port][/path][@auth[:group[,group...]][~callback-host]]
+http://<public-host>[:container-port][/path][@auth[:group[,group...]][~callback-host]]
 ```
 
 Use `https://` for normal public routes. It creates a HTTPS router with Let's Encrypt and redirects plain HTTP to HTTPS. Use `http://` only when you intentionally want a plain HTTP public route. The port is the port inside the container; the public listener is still 80/443. If the port is omitted, Terrarium targets container port `80`. A path, when present, is matched as a prefix. Query strings and fragments are not supported.
 
+Wildcard HTTPS hosts such as `https://*.example.com:8080` require DNS-01 ACME. Configure the single Traefik DNS provider with lego environment variable names:
+
+```bash
+terrariumctl set dns provider cloudflare CF_DNS_API_TOKEN:your-token
+terrariumctl set dns provider route53 AWS_ACCESS_KEY_ID:your-key AWS_SECRET_ACCESS_KEY:your-secret AWS_REGION:us-east-1
+terrariumctl set dns provider
+```
+
+The last command disables DNS-01 and returns Traefik to HTTP-01. Traefik supports one DNS challenge provider per instance; see the [lego DNS provider list](https://go-acme.github.io/lego/dns/index.html) for provider codes and required environment variables.
+
 Authentication suffixes are supported only on HTTP(S) routes:
 
 ```bash
 lxc config set grafana user.proxy "https://grafana.example.com:3000@auth"
 lxc config set admin-tool user.proxy "https://admin.example.com:8080@auth:admins,devops"
+lxc config set wildcard-admin user.proxy "https://*.example.com:8080@auth:admins~auth.example.com"
 terrariumctl proxy sync
 ```
 
-`@auth` allows any authenticated user. `@auth:admins,devops` allows users in any listed group. Group names may contain letters, numbers, dots, underscores, and hyphens. External OIDC providers must emit a `groups` claim for group-restricted routes.
+`@auth` allows any authenticated user. `@auth:admins,devops` allows users in any listed group. Group names may contain letters, numbers, dots, underscores, and hyphens. Wildcard auth routes must add `~callback-host`; Terrarium always uses HTTPS and oauth2-proxy's callback path for that host. External OIDC providers must emit a `groups` claim for group-restricted routes.
 
 TCP and UDP route formats:
 

scripts/ctl/completion.test.ts

@@ -15,6 +15,7 @@ describe("terrariumctl completion", () => {
     expect(script).toContain("--skip-reconfigure");
     expect(script).toContain("--storage-source");
     expect(script).toContain("local oidc");
+    expect(script).toContain("provider");
   });
 
   test("completes root command prefixes", () => {
@@ -30,8 +31,10 @@ describe("terrariumctl completion", () => {
     expect(zsh).toContain("#compdef terrariumctl trm");
     expect(zsh).toContain("update) opts=(--ref --skip-reconfigure --non-interactive)");
     expect(zsh).toContain("compadd local oidc");
+    expect(zsh).toContain("compadd provider");
     expect(fish).toContain("complete -c terrariumctl");
     expect(fish).toContain("complete -c trm");
+    expect(fish).toContain("__fish_seen_subcommand_from dns");
     expect(fish).toContain("-l oidc-client");
     expect(fish).toContain("-s p");
   });

scripts/ctl/completion.ts

@@ -23,7 +23,7 @@ const actions: Record<string, string[]> = {
   proxy: ["sync"],
   mount: ["add", "attach", "remove", "list"],
   idp: ["sync", "status", "logs", "backup", "restore"],
-  set: ["domains", "emails", "idp", "s3", "syncoid"],
+  set: ["domains", "emails", "idp", "dns", "s3", "syncoid"],
   completion: ["bash", "zsh", "fish"]
 };
 
@@ -197,6 +197,8 @@ _terrariumctl_complete() {
     3)
       if [[ "\${command}" == "set" && "\${COMP_WORDS[2]}" == "idp" ]]; then
         COMPREPLY=( $(compgen -W "local oidc" -- "\${cur}") )
+      elif [[ "\${command}" == "set" && "\${COMP_WORDS[2]}" == "dns" ]]; then
+        COMPREPLY=( $(compgen -W "provider" -- "\${cur}") )
       elif [[ "\${command}" == "mount" && "\${COMP_WORDS[2]}" == "add" ]]; then
         COMPREPLY=( $(compgen -W "smb cifs" -- "\${cur}") )
       elif [[ "\${command}" == "cluster" && "\${COMP_WORDS[2]}" == "ovn" ]]; then
@@ -249,6 +251,8 @@ _terrariumctl() {
 
   if [[ "$words[2]" == "set" && "$words[3]" == "idp" ]]; then
     compadd local oidc
+  elif [[ "$words[2]" == "set" && "$words[3]" == "dns" ]]; then
+    compadd provider
   elif [[ "$words[2]" == "mount" && "$words[3]" == "add" ]]; then
     compadd smb cifs
   elif [[ "$words[2]" == "cluster" && "$words[3]" == "ovn" ]]; then
@@ -277,6 +281,7 @@ function fishCompletion(): string {
       }
     }
     lines.push(`complete -c ${command} -f -n "__fish_seen_subcommand_from set; and __fish_seen_subcommand_from idp" -a "local oidc"`);
+    lines.push(`complete -c ${command} -f -n "__fish_seen_subcommand_from set; and __fish_seen_subcommand_from dns" -a "provider"`);
     lines.push(`complete -c ${command} -f -n "__fish_seen_subcommand_from mount; and __fish_seen_subcommand_from add" -a "smb cifs"`);
     lines.push(`complete -c ${command} -f -n "__fish_seen_subcommand_from cluster; and __fish_seen_subcommand_from ovn" -a "configure"`);
   }

scripts/ctl/config.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { applySetIdpConfig, parseSetCommandOptions, runReconcileActions, type ReconcileActions } from "./config";
+import { applySetDnsProviderConfig, applySetIdpConfig, parseSetCommandOptions, runReconcileActions, type ReconcileActions } from "./config";
 
 function recordActions(calls: string[], outputs: string[] = [""]): ReconcileActions {
   return {
@@ -233,4 +233,45 @@ describe("terrariumctl config reconciliation", () => {
     expect(parsed.idp.lxdOidcSecret).toBeUndefined();
     expect(parsed.s3.s3SecretKey).toBeUndefined();
   });
+
+  test("stores DNS provider credentials as exact lego environment variables", () => {
+    const config: Record<string, unknown> = {};
+
+    const summary = applySetDnsProviderConfig(config, {
+      provider: "Cloudflare",
+      credentials: ["CF_API_KEY:key:with:colon", "CF_DNS_API_TOKEN:token"]
+    });
+
+    expect(summary).toBe("Enabled DNS-01 ACME provider cloudflare");
+    expect(config.terrarium_acme_dns_provider).toBe("cloudflare");
+    expect(config.terrarium_acme_dns_env).toEqual({
+      CF_API_KEY: "key:with:colon",
+      CF_DNS_API_TOKEN: "token"
+    });
+  });
+
+  test("clears DNS provider and DNS credentials together", () => {
+    const config: Record<string, unknown> = {
+      terrarium_acme_dns_provider: "cloudflare",
+      terrarium_acme_dns_env: { CF_DNS_API_TOKEN: "token" }
+    };
+
+    const summary = applySetDnsProviderConfig(config, { provider: undefined, credentials: [] });
+
+    expect(summary).toBe("Disabled DNS-01 ACME");
+    expect(config.terrarium_acme_dns_provider).toBe("");
+    expect(config.terrarium_acme_dns_env).toEqual({});
+  });
+
+  test("rejects DNS credentials that are not environment variable assignments", () => {
+    expect(() =>
+      applySetDnsProviderConfig(
+        {},
+        {
+          provider: "cloudflare",
+          credentials: ["cf-token:secret"]
+        }
+      )
+    ).toThrow("uppercase lego environment variable");
+  });
 });

scripts/ctl/config.ts

@@ -79,6 +79,12 @@ export type SetSyncoidOptions = {
   syncoidSshKey?: string;
 };
 
+/** Reusable option bag for `set dns provider`. */
+export type SetDnsProviderOptions = {
+  provider?: string;
+  credentials: string[];
+};
+
 type SetIdpPlan = {
   summary: string;
   verifyOidc?: OidcVerificationOptions;
@@ -149,6 +155,59 @@ async function persistAndReconcile(config: MutableConfig, summary: string, actio
   console.log(success(summary));
 }
 
+function validateLegoDnsProvider(provider: string): string {
+  const normalized = provider.trim().toLowerCase();
+  if (!normalized) {
+    return "";
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
+    throw new Error("DNS provider must be a lego provider code such as cloudflare, hetzner, route53, or acme-dns");
+  }
+  return normalized;
+}
+
+function parseDnsCredentials(credentials: string[]): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const credential of credentials) {
+    const separator = credential.indexOf(":");
+    if (separator <= 0) {
+      throw new Error(`DNS credential must use KEY:VALUE form: ${credential}`);
+    }
+    const key = credential.slice(0, separator);
+    const value = credential.slice(separator + 1);
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+      throw new Error(`DNS credential key must be an uppercase lego environment variable name: ${key}`);
+    }
+    if (/[\r\n]/.test(value)) {
+      throw new Error(`DNS credential value for ${key} must be a single line`);
+    }
+    if (value) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+/** Enables or disables Traefik DNS-01 ACME using lego provider env names. */
+export function applySetDnsProviderConfig(config: MutableConfig, options: SetDnsProviderOptions): string {
+  const provider = validateLegoDnsProvider(options.provider ?? "");
+  if (!provider) {
+    setConfigValue(config, "terrarium_acme_dns_provider", "");
+    setConfigValue(config, "terrarium_acme_dns_env", {});
+    return "Disabled DNS-01 ACME";
+  }
+
+  setConfigValue(config, "terrarium_acme_dns_provider", provider);
+  setConfigValue(config, "terrarium_acme_dns_env", parseDnsCredentials(options.credentials));
+  return `Enabled DNS-01 ACME provider ${provider}`;
+}
+
+export async function setDnsProviderCmd(options: SetDnsProviderOptions, actions: ReconcileActions): Promise<void> {
+  const config = loadMutableConfig();
+  const summary = applySetDnsProviderConfig(config, options);
+  await persistAndReconcile(config, summary, actions);
+}
+
 /** Imports the local YAML export into the dqlite-backed LXD project store. */
 export function configImportCmd(): void {
   importConfigFileToClusterStore(CONFIG_PATH, "terrariumctl config import");