Private Configuration File

Set the identity provider (IdP) mode for authentication. By default both global and org pages will show until set. See the Identity Providers documentation for more details on how this affects authentication and user management.

Possible values:

• global: (default) Both global and organization-level IdP login pages are available. Users can authenticate using either global or organization-specific identity providers.
• org: Only organization-level IdP login pages are available. Users must authenticate using identity providers defined at the organization

app:
  identity_provider_mode: "org"

The region identifier for this Pangolin instance. Used for multi-region deployments.

app:
  region: "us-east-1"

Path to the RSA private key used for encrypting sensitive data. Must be at least 8 characters long. THIS IS ONLY USED WITH pangolin_dns FEATURE FLAG ENABLED AND REQUIRES EXTERNAL COMPONENTS.

server:
  encryption_key_path: "./config/encryption.pem"

openssl genrsa -out encryption.pem 4096

Redis server hostname or IP address.

redis:
  host: "redis.example.com"

Redis server port (1-65535).

redis:
  port: 6379

Redis authentication password.

Environment Variable: REDIS_PASSWORD (or REDIS_PASSWORD_FILE to read the value from a file — see Reading secrets from a file)

redis:
  password: "your-secure-password"

Redis database number (0-15 typically).

redis:
  db: 0

Array of read replica configurations for high-availability deployments.

redis:
  host: "redis-primary"
  port: 6379
  replicas:
    - host: "redis-replica-1"
      port: 6379
      password: "replica-password"
      db: 0
    - host: "redis-replica-2"
      port: 6379
      password: "replica-password"
      db: 0

Enables the authoritative DNS server. When false or omitted, no DNS listener is started.

dns:
  enabled: true

UDP port the authoritative DNS server listens on.

dns:
  listen_port: 53

The FQDN Pangolin advertises as itself when acting as a nameserver. Used as the mname in SOA responses and included in the NS record set returned for zones it is authoritative for. This is the hostname you point your domain's nameservers at when using NS-based domain delegation (e.g. ns1.pangolin-ns.net).

dns:
  nameserver_name: "ns1.pangolin-ns.net"

The domain suffix used for single-domain CNAME delegation. When an org adds a domain using the CNAME delegation type, Pangolin generates {domainId}.{cname_extension} and _acme-challenge.{domainId}.{cname_extension} targets to point your records at.

dns:
  cname_extension: "cname.pangolin.net"

Suffix used to resolve a site's WireGuard tunnel subnet address by DNS. A query for {newtId}.{site_extension} resolves to the tunnel subnet IP of the site running the Newt agent with that ID. This is used for site-to-cloud networking.

dns:
  site_extension: "site.pangolin.net"

Additional CNAME suffixes (besides cname_extension) that are treated the same way. Useful when Pangolin should respond to more than one CNAME delegation domain, such as for white-label/multi-brand deployments.

dns:
  cname_alternate_extensions:
    - "cname.example.com"

Additional nameserver hostnames appended after nameserver_name in the NS record set Pangolin returns for a zone, and in the NS records shown when using NS-based domain delegation (e.g. ns2.pangolin-ns.net, ns3.pangolin-ns.net).

dns:
  alternate_nameservers:
    - "ns2.pangolin-ns.net"
    - "ns3.pangolin-ns.net"

Per-source-IP rate limiting for DNS queries. Queries exceeding these limits are refused.

dns:
  rate_limit:
    enabled: true
    window_ms: 60000
    max_requests: 1200
    max_requests_per_query_type: 600

Hardcoded DNS answers served by the authoritative DNS server, checked before database-backed lookups. Useful for fixed entries such as domain verification TXT records.

dns:
  static_records:
    - domain: "example.com"
      type: "TXT"
      value: "v=spf1 include:_spf.example.com ~all"
      ttl: 300

URL where the local Gerbil exit node can be reached by Pangolin. Useful when clustering multiple pangolin nodes. Overrides the value stored in the database. Useful when using Docker and address the local gerbil container using the host's address.

gerbil:
  local_exit_node_reachable_at: "http://gerbil:3004"

DEPRECATED! See app.identity_provider_mode: "org" instead.

Restrict identity provider (IdP) authentication to organization-level only.

flags:
  use_org_only_idp: true

Enable Redis for caching and session management. Requires redis configuration.

flags:
  enable_redis: true

Allow creating domains using CNAME and NS.

flags:
  use_pangolin_dns: true

Controls who is responsible for obtaining and renewing TLS certificates.

Possible values:

• traefik: (default) Traefik's built-in ACME resolver handles certificate issuance and renewal itself.
• pangolin: Pangolin issues and manages certificates itself via its self-hosted ACME client, using DNS-01 challenges. Requires dns.enabled and acme.enable_acme_client to both be true. ENSURE ONLY ONE NODE IN A CLUSTER HAS THE acme.enable_acme_client FLAG ENABLED, OTHERWISE MULTIPLE NODES WILL TRY TO ISSUE CERTIFICATES SIMULTANEOUSLY.

acme:
  cert_mode: "pangolin"

Enable the self-hosted ACME client and its certificate issuance/renewal jobs. Must be true, along with cert_mode: "pangolin", for the certificate manager to start.

acme:
  enable_acme_client: true

Email address registered with the ACME account, used by the CA for expiry and policy notices.

acme:
  contact_email: "admin@example.com"

The ACME server directory URL Pangolin's client talks to.

acme:
  acme_directory_url: "https://acme-staging-v02.api.letsencrypt.org/directory"

Filesystem path where the ACME account's private key is stored. Generated automatically on first run if it doesn't exist.

acme:
  acme_account_key_path: "./config/account.key"

How long, in milliseconds, a DNS-01 challenge TXT record is considered valid and served by the authoritative DNS server before expiring.

acme:
  challenge_ttl_ms: 300000

How often, in milliseconds, Pangolin checks for certificates approaching expiry and renews them.

acme:
  renewal_check_interval_ms: 3600000

How often, in milliseconds, Pangolin checks for newly-needed certificates and issues them. Set much lower than renewal_check_interval_ms since new certificates are user-facing and blocking.

acme:
  new_cert_check_interval_ms: 5000

Shared rate limit on outbound calls Pangolin's client makes directly to the ACME server (create order, get authorizations, verify challenge, finalize, get certificate). Kept under Let's Encrypt's ~20 req/s limit.

acme:
  acme_requests_per_second: 15

How often, in milliseconds, Pangolin checks pending (not-yet-verified) domains' DNS records against live DNS to flip them to verified once the records are in place.

acme:
  dns_check_interval_ms: 60000

How often, in milliseconds, Pangolin runs a periodic pass re-checking already-verified domains, to catch removing or changing their DNS records after the fact.

acme:
  domain_reverification_interval_ms: 3600000

Minimum age, in milliseconds, a verified domain's last check must have before it becomes eligible for reverification. A given domain is reverified at most roughly this often, not on every reverification pass.

acme:
  domain_reverification_window_ms: 259200000

Maximum number of verified domains reverified per reverification pass, to bound database and DNS load per tick.

acme:
  domain_reverification_batch_size: 20

Upstream public DNS resolvers used to perform live lookups against real DNS (not Pangolin's own authoritative server) when validating or reverifying domain records. Resolvers are rotated across on each attempt so a single resolver's cache or propagation lag doesn't wrongly fail a check.

acme:
  dns_resolvers:
    - "8.8.8.8"
    - "1.1.1.1"