Configuration

The control plane is nebula serve. A setting is a flag, an environment variable or a key in a nebula.yaml file. A flag wins over the environment variable, and the environment variable wins over the file. This page groups the settings of nebula serve by what they do. The CLI reference lists every command.

How a setting is namedCopy Anchor Link

Form	Name	Example
Flag	-- plus the name	--base-url
Environment variable	NEBULA_ plus the name in capitals, with - as _	NEBULA_BASE_URL
nebula.yaml key	The name	base-url

nebula.yaml is read from the working directory, from /etc/nebula, or from the path in --config. A missing file is not an error. In an environment variable, --trusted-proxies and --previous-master-keys take comma-separated values.

Which settings an installed control plane receivesCopy Anchor Link

The installer writes its answers to .env in the install directory (/opt/nebula by default) and starts the control plane with a compose file. Docker Compose passes a variable from .env to the container only if the compose file names it. The compose file the installer downloads names these variables:

Variable	Setting
NEBULA_DATABASE_URL, NEBULA_MASTER_KEY, NEBULA_BASE_URL	Required settings.
NEBULA_OIDC_ISSUER, NEBULA_OIDC_CLIENT_ID, NEBULA_OIDC_CLIENT_SECRET	Required settings.
NEBULA_OIDC_PROVIDER_NAME, NEBULA_OIDC_SCOPES, NEBULA_OIDC_INSECURE_HTTP	Sign-in.
NEBULA_PREVIOUS_MASTER_KEYS	Secrets.
NEBULA_TRUSTED_PROXIES	Network.
NEBULA_LOG_LEVEL	--log-level.
NEBULA_AGENT_IMAGE	--agent-image.
NEBULA_UPDATER_TOKEN	--updater-token.

The compose file fixes NEBULA_LISTEN at 0.0.0.0:8080 inside the container and NEBULA_METRICS_LISTEN at 127.0.0.1:9090. The installer's --listen option sets the address the container publishes on the host, as NEBULA_HOST_LISTEN.

To set any other setting, add it to the environment block of your own compose file and install with --compose-file. Running the installer without --compose-file downloads the compose file again and replaces the one in the install directory.

RequiredCopy Anchor Link

nebula serve refuses to start unless all six are set, and lists the missing ones.

Flag	Meaning
--database-url	PostgreSQL connection URL. Postgres needs TimescaleDB 2.13 or newer, loaded through shared_preload_libraries.
--master-key	Base64 of exactly 32 bytes. Every stored secret is sealed under it.
--base-url	The public URL of this installation, for example https://nebula.example.com. Every cluster's agent connects back to it.
--oidc-issuer	OIDC issuer URL. Sign-in is delegated to it.
--oidc-client-id	OIDC client ID registered with the issuer.
--oidc-client-secret	OIDC client secret registered with the issuer.

NetworkCopy Anchor Link

Flag	Default	Meaning
--listen	:8080	Address the API and the console listen on.
--metrics-listen	127.0.0.1:9090	Address Prometheus metrics listen on.
--trusted-proxies	none	Proxy IP addresses or CIDRs allowed to supply client IP headers. Use cloudflare for Cloudflare's reviewed edge ranges, and include the exact local reverse proxy or Docker bridge CIDR.
--pprof	false	Expose /debug/pprof on the metrics listener.

Sign-inCopy Anchor Link

Flag	Default	Meaning
--oidc-scopes	openid profile email	Space-separated OIDC scopes to request.
--oidc-provider-name	your identity provider	Name shown on the sign-in button.
--oidc-acr-values	none	acr_values sent on every sign-in, for a provider that only reports a second factor when asked for a stronger context, for example urn:okta:loa:2fa:any.
--oidc-insecure-http	false	Allow an issuer on plain http. Development and end-to-end tests only.

SecretsCopy Anchor Link

Flag	Default	Meaning
--previous-master-keys	none	Older master keys, comma-separated. Keep them only until nebula secrets reseal has re-encrypted every stored secret.

Clusters and agentsCopy Anchor Link

Flag	Default	Meaning
--agent-image	ghcr.io/nebulactrl/nebula-agent at this binary's version	Container image the cluster install manifest deploys.
--agent-update-deadline	10m	How long a running agent update may go without the new agent reporting in before it is rolled back automatically.
--k3s-version	v1.36.4+k3s1	K3s version the install script pins with INSTALL_K3S_VERSION.
--k3s-channels-url	https://update.k3s.io/v1-release/channels	K3s release-channel feed that a cluster's available upgrades are computed against.
--simulated-cluster	false	Run an in-process simulated cluster instead of waiting for a real one. For development.
--simulated-cluster-expandable-storage	false	Give the simulated cluster an expandable default storage class next to local-path.

IntegrationsCopy Anchor Link

Flag	Default	Meaning
--github-api-base	https://api.github.com	GitHub API base URL. Override it for GitHub Enterprise Server.
--github-web-base	https://github.com	GitHub web base URL used for the GitHub App manifest flow. Override it for GitHub Enterprise Server.
--acme-directory-url	https://acme-v02.api.letsencrypt.org/directory	ACME directory that DNS-01 certificates are issued from. Point it at Let's Encrypt staging when testing.
--acme-dns-resolvers	the system resolver	Recursive DNS servers (host:port) used to find a hostname's zone and to check DNS-01 propagation. Set it for split-horizon DNS or a private test CA.
--cloudflare-api-base	https://api.cloudflare.com/client/v4	Cloudflare API base URL. Override it for a test fake.
--pagerduty-events-url	https://events.pagerduty.com	PagerDuty Events API origin that notification channels deliver to. Override it for a test fake.

Update checksCopy Anchor Link

Flag	Default	Meaning
--update-check	true	Check the release feed for a newer release. false turns update checks off, for an air-gapped install.
--release-feed-url	https://get.nebulactrl.dev/changelog.json	Another release feed in the same shape, such as a mirror. Requests carry no instance id or version, only a plain NebulaCtrl User-Agent.
--updater-token	empty	Secret the host updater presents when it polls the control plane. The installer generates it as NEBULA_UPDATER_TOKEN in .env. Empty turns console updates of the control plane off.

TemplatesCopy Anchor Link

Flag	Default	Meaning
--community-templates	true	Read the public community template repository (see Templates). false turns it off, for an air-gapped install.
--community-templates-repo	nebulactrl/nebula-templates	The community repository, as owner/name. Every instance reads its main branch. The value is checked at startup.

GlobalCopy Anchor Link

Flag	Default	Meaning
--config	none	Path to a nebula.yaml file.
--log-level	info	debug, info, warn or error. Any other value is refused at startup.