Telegraf Controller configuration options

Telegraf Controller accepts configuration through environment variables and, in many cases, equivalent command-line flags. You can also load environment variables from a .env file in the working directory where you start Telegraf Controller.

• Configure Telegraf Controller
• Configuration options

Configure Telegraf Controller

Pass configuration options using command-line flags or environment variables. Command-line flags take precedence over environment variables.

Use a .env file

Telegraf Controller loads environment variables from a .env file in the working directory where you start the application. Use a .env file to keep sensitive values out of shell history and to share configuration across processes.

# .env
APP_PORT=3000
HEARTBEAT_PORT=9000
DATABASE_URL=postgresql://user:password@localhost:5432/telegraf_controller
TELEGRAF_CONTROLLER_EULA=accept

Example: command flags

telegraf_controller \
  --port=3000 \
  --heartbeat-port=9000 \
  --database="postgresql://user:password@localhost:5432/telegraf_controller" \
  --eula-accept \
  --no-interactive

Example: environment variables

export APP_PORT=3000
export HEARTBEAT_PORT=9000
export DATABASE_URL="postgresql://user:password@localhost:5432/telegraf_controller"
export TELEGRAF_CONTROLLER_EULA=accept

telegraf_controller --no-interactive

Configuration options

• General
  • port
  • heartbeat-port
  • database
• TLS
  • ssl-cert-path
  • ssl-key-path
• Database TLS
  • sslmode
  • sslrootcert
  • database-ca-cert
  • database-ssl-no-verify
• Owner account
  • owner-email
  • owner-username
  • owner-password
  • reset-owner-password
  • owner-auth-provider
  • owner-external-id
• Authentication and security
  • session-secret
  • disable-auth-endpoints
  • Local authentication
    • auth-local-enabled
    • login-lockout-attempts
    • login-lockout-minutes
    • password-complexity
  • LDAP authentication
    • auth-ldap-enabled
    • auth-ldap-url
    • auth-ldap-bind-dn
    • auth-ldap-bind-password
    • auth-ldap-user-search-base
    • auth-ldap-user-search-filter
    • auth-ldap-start-tls
    • auth-ldap-ca-cert-path
    • auth-ldap-reject-unauthorized
    • auth-ldap-attr-username
    • auth-ldap-attr-email
    • auth-ldap-attr-display-name
    • auth-ldap-attr-groups
  • OIDC authentication
    • auth-oidc-enabled
    • auth-oidc-issuer
    • auth-oidc-client-id
    • auth-oidc-client-secret
    • auth-oidc-redirect-uri
    • auth-oidc-scopes
    • auth-oidc-username-claim
    • auth-oidc-groups-claim
    • auth-oidc-display-name
    • auth-oidc-post-login-redirect
    • auth-oidc-allow-insecure
• Logging
  • rust-log
  • logs-dir
• Audit logging
  • audit-enabled
  • audit-log-retention
  • audit-syslog-host
  • audit-syslog-port
  • audit-syslog-protocol
  • audit-webhook-url
  • audit-webhook-auth-header
  • audit-file-path
• EULA and setup
  • eula-accept
  • no-interactive
• Licensing
  • license-file-path

General

• port
• heartbeat-port
• database

port

Web interface and API port.

Default: 8888

heartbeat-port

Agent heartbeat service port.

Default: 8000

database

Database connection URL or filesystem path. Telegraf Controller supports SQLite and PostgreSQL.

Default: file:./sqlite.db

# PostgreSQL
telegraf_controller --database="postgresql://user:password@localhost:5432/telegraf_controller"

# Custom SQLite path
telegraf_controller --database="/path/to/database.db"

TLS

Provide both a certificate and a private key to serve the Telegraf Controller web interface, API, and the agent heartbeat service over HTTPS. The web interface, API, and heartbeat service share the same certificate and key.

• ssl-cert-path
• ssl-key-path

For a full walkthrough that includes configuring agents to trust the certificate, see Secure Telegraf Controller with TLS.

ssl-cert-path

Path to a PEM-encoded SSL/TLS certificate. Set this together with ssl-key-path to enable HTTPS.

ssl-key-path

Path to the PEM-encoded SSL/TLS private key that matches ssl-cert-path. Set this together with the certificate to enable HTTPS.

Database TLS

When you connect Telegraf Controller to PostgreSQL, use the following options to encrypt the database connection and to control how Telegraf Controller verifies the PostgreSQL server’s certificate. These options apply only to PostgreSQL connections and have no effect when you use SQLite.

• sslmode
• sslrootcert
• database-ca-cert
• database-ssl-no-verify

sslmode

Set sslmode as a query parameter in the PostgreSQL database connection URL to control whether Telegraf Controller uses TLS and whether it verifies the server certificate.

telegraf_controller \
  --database="postgresql://user:password@localhost:5432/telegraf_controller?sslmode=verify-full&sslrootcert=/etc/ssl/certs/ca.pem"

Telegraf Controller supports the following sslmode values:

To verify the server certificate, provide a CA certificate with sslrootcert, database-ca-cert, or PGSSLROOTCERT. If you request verification but do not provide a CA certificate, Telegraf Controller falls back to the system trust store.

sslrootcert

Path to a PEM-encoded CA certificate used to verify the PostgreSQL server’s certificate. Set sslrootcert as a query parameter in the database connection URL. This is equivalent to setting database-ca-cert. When you provide a CA certificate, Telegraf Controller verifies the server certificate even if database-ssl-no-verify is set.

database-ca-cert

Path to a PEM-encoded CA certificate used to verify the PostgreSQL server’s certificate. Use this environment variable as an alternative to the sslrootcert connection parameter. Telegraf Controller also accepts the standard PGSSLROOTCERT environment variable for the same purpose.

database-ssl-no-verify

When set to 1, true, or yes, Telegraf Controller encrypts the PostgreSQL connection but does not verify the server certificate. Use this only for development or troubleshooting. If you also provide a CA certificate, Telegraf Controller verifies the server certificate and ignores this setting.

Default: false

Owner account

Use the following options to bootstrap the owner account with non-default values on first startup of Telegraf Controller. The owner account has full administrative access to Telegraf Controller.

• owner-email
• owner-username
• owner-password
• reset-owner-password
• owner-auth-provider
• owner-external-id

owner-email

Email address for the bootstrap owner account.

owner-username

Username for the bootstrap owner account.

owner-password

Password for the bootstrap owner account. Also used as the new password when RESET_OWNER_PASSWORD forces a password reset.

reset-owner-password

When set to true, forces an owner password reset on the next startup using OWNER_PASSWORD as the new password.

owner-auth-provider

Primary authentication provider for the bootstrap owner account. Set this when you intend to disable local authentication after bootstrap. The owner can still sign in with the bootstrap password as a recovery credential.

Supported values: local, ldap, oidc

Default: local

owner-external-id

External identifier that links the bootstrap owner to its identity in an external authentication provider. Required when owner-auth-provider is ldap or oidc.

• For LDAP, set to the user’s distinguished name (DN), for example uid=alice,ou=people,dc=example,dc=com.
• For OIDC, set to the sub claim from the ID token.

Authentication and security

• session-secret

• disable-auth-endpoints

• Local authentication

  • auth-local-enabled
  • login-lockout-attempts
  • login-lockout-minutes
  • password-complexity

• LDAP authentication (Telegraf Enterprise)

  • auth-ldap-enabled
  • auth-ldap-url
  • auth-ldap-bind-dn
  • auth-ldap-bind-password
  • auth-ldap-user-search-base
  • auth-ldap-user-search-filter
  • auth-ldap-start-tls
  • auth-ldap-ca-cert-path
  • auth-ldap-reject-unauthorized
  • auth-ldap-attr-username
  • auth-ldap-attr-email
  • auth-ldap-attr-display-name
  • auth-ldap-attr-groups

• OIDC authentication (Telegraf Enterprise)

  • auth-oidc-enabled
  • auth-oidc-issuer
  • auth-oidc-client-id
  • auth-oidc-client-secret
  • auth-oidc-redirect-uri
  • auth-oidc-scopes
  • auth-oidc-username-claim
  • auth-oidc-groups-claim
  • auth-oidc-display-name
  • auth-oidc-post-login-redirect
  • auth-oidc-allow-insecure

session-secret

Secret used to encrypt session cookies. Telegraf Controller generates a value automatically if you do not set one. Set an explicit value to keep existing sessions valid across restarts.

Default: Generated at startup

disable-auth-endpoints

Comma-separated list of API endpoint groups to skip authentication for. Use "*" to disable authentication for all endpoint groups.

Valid endpoint groups:

• agents
• configs
• labels
• reporting-rules
• heartbeat

# Disable authentication on agents and heartbeat only
telegraf_controller --disable-auth-endpoints=agents,heartbeat

# Disable authentication on all endpoint groups
telegraf_controller --disable-auth-endpoints="*"

Local authentication

Local authentication is enabled by default and is the only authentication provider available without a Telegraf Enterprise license. The variables in this group apply only when auth-local-enabled is true. LDAP and OIDC providers enforce their own credential and lockout policies.

For setup details, see Configure local authentication.

auth-local-enabled

Enable username and password authentication using credentials stored in Telegraf Controller. Read once at startup; immutable at runtime.

Set this to false to require sign-in through an external provider (LDAP or OIDC). When disabled, the owner must have been bootstrapped with owner-auth-provider and owner-external-id set to the external provider.

Default: true

For setup details, see Configure local authentication.

login-lockout-attempts

Number of failed login attempts allowed before an account is locked out. Minimum: 1.

Default: 5

login-lockout-minutes

Number of minutes a locked-out account remains locked. Minimum: 1.

Default: 15

password-complexity

Password complexity level applied to all password operations, including initial setup, password changes, password resets, and invite completion.

Default: low

LDAP authentication

LDAP authentication is a Telegraf Enterprise feature. If AUTH_LDAP_* variables are set on an unlicensed instance, Telegraf Controller starts normally, logs a warning, and leaves LDAP inactive until a license is applied and the application is restarted.

All AUTH_LDAP_* variables are read once at startup and are immutable at runtime. Provisioning rules, default role, allowed domains, and group-to-role mappings are runtime-editable from the Settings page.

For setup details, see Configure LDAP authentication.

auth-ldap-enabled

Enable LDAP authentication.

Default: false

auth-ldap-url

LDAP server URL. Must use the ldap:// or ldaps:// scheme. Required when auth-ldap-enabled is true.

auth-ldap-bind-dn

Distinguished name (DN) of the service account that Telegraf Controller binds as to search for users. Required when auth-ldap-enabled is true.

auth-ldap-bind-password

Password for the service account specified by auth-ldap-bind-dn. Required when auth-ldap-enabled is true.

auth-ldap-user-search-base

Base DN under which Telegraf Controller searches for user entries (for example, ou=people,dc=example,dc=com). Required when auth-ldap-enabled is true.

auth-ldap-user-search-filter

LDAP filter used to locate a user. The literal token {{username}} is replaced with the value the user types on the sign-in page.

Default: (uid={{username}})

auth-ldap-start-tls

When true, upgrade an unencrypted ldap:// connection to TLS using StartTLS before binding. Ignored for ldaps:// connections.

Default: false

auth-ldap-ca-cert-path

Path to a PEM-encoded certificate authority used to verify the LDAP server’s TLS certificate. Use this when your LDAP server is signed by a private CA not in the system trust store.

auth-ldap-reject-unauthorized

When false, accept any TLS certificate the LDAP server presents. For development and troubleshooting only.

Default: true

auth-ldap-attr-username

LDAP attribute that supplies the Telegraf Controller username for an authenticated user.

Default: sAMAccountName

auth-ldap-attr-email

LDAP attribute that supplies the user’s email address.

Default: mail

auth-ldap-attr-display-name

LDAP attribute that supplies the user’s display name.

Default: displayName

auth-ldap-attr-groups

LDAP attribute that supplies the user’s group memberships. Telegraf Controller matches values from this attribute against the group-to-role mappings configured on the Settings page.

Default: memberOf

OIDC authentication

OIDC authentication is a Telegraf Enterprise feature. If AUTH_OIDC_* variables are set on an unlicensed instance, Telegraf Controller starts normally, logs a warning, and leaves OIDC inactive until a license is applied and the application is restarted.

Telegraf Controller always uses authorization code flow with PKCE (S256). All AUTH_OIDC_* variables are read once at startup and are immutable at runtime. Provisioning rules, default role, allowed domains, and group-to-role mappings are runtime-editable from the Settings page.

For setup details, see Configure OIDC authentication.

auth-oidc-enabled

Enable OIDC authentication.

Default: false

auth-oidc-issuer

OIDC issuer URL. Required when auth-oidc-enabled is true.

auth-oidc-client-id

OAuth2 client identifier registered with the OIDC provider. Required when auth-oidc-enabled is true.

auth-oidc-client-secret

OAuth2 client secret. Required when auth-oidc-enabled is true.

auth-oidc-redirect-uri

Full callback URL registered with the OIDC provider. Must end with /api/auth/oidc/callback. Required when auth-oidc-enabled is true.

auth-oidc-scopes

Space-separated list of OAuth2 scopes to request. openid is added automatically if missing.

Default: openid profile email

auth-oidc-username-claim

Name of the ID-token claim used as the Telegraf Controller username.

Default: preferred_username

auth-oidc-groups-claim

Name of the ID-token claim that contains the user’s group memberships. Telegraf Controller matches values from this claim against the group-to-role mappings configured on the Settings page.

Default: groups

auth-oidc-display-name

Friendly name displayed on the Sign in with… button on the sign-in page. The Settings > OIDC Authentication panel can override this value at runtime.

Default: SSO

auth-oidc-post-login-redirect

Path inside Telegraf Controller where users are sent after a successful OIDC callback.

Default: /

auth-oidc-allow-insecure

When true, allow http:// issuer URLs and callback URLs. For development only. Telegraf Controller logs a warning at startup when this is enabled.

Default: false

Logging

• rust-log
• logs-dir

rust-log

Tracing level for the Rust heartbeat server. Supports trace, debug, info, warn, and error.

Default: info

logs-dir

Absolute path for heartbeat agent logs.

Default: System temp directory

Audit logging

Audit logging is a Telegraf Enterprise feature. All of the following options are read at startup only; changes after startup require a restart. For a task-based walkthrough, see Enable and configure audit logging.

• audit-enabled
• audit-log-retention
• audit-syslog-host
• audit-syslog-port
• audit-syslog-protocol
• audit-webhook-url
• audit-webhook-auth-header
• audit-file-path

audit-enabled

Enable audit logging on startup. Audit logging requires a Telegraf Enterprise license to take effect.

Default: false

audit-log-retention

Sets the initial audit log retention period, in hours. Telegraf Controller persists this value to the database on first startup; later changes to the environment variable have no effect. Update retention after first startup from the Settings page.

Supported values: 720 (30 days), 2160 (90 days), 4320 (180 days), 8760 (1 year), 17520 (2 years), or 0 (infinite).

Default: 2160

audit-syslog-host

Hostname or IP address of a syslog server. When set together with audit-syslog-port and audit-syslog-protocol, Telegraf Controller forwards each audit event to the configured syslog destination.

audit-syslog-port

Port number of the syslog server. Required to enable syslog forwarding.

audit-syslog-protocol

Transport protocol used to deliver audit events to the syslog server. Required to enable syslog forwarding.

Supported values: tcp, udp

audit-webhook-url

URL that receives each audit event as a JSON-encoded HTTP POST request. Telegraf Controller retries each delivery up to three times with backoff and honors Retry-After response headers.

audit-webhook-auth-header

Optional value sent as the Authorization HTTP header on webhook requests. Use it to pass a bearer token, basic-auth credential, or other shared secret your webhook endpoint requires.

audit-file-path

Absolute path to a local file. When set, Telegraf Controller appends each audit event as a single JSON object on its own line (.jsonl format). The path must be writable by the Telegraf Controller process.

Telegraf Controller does not rotate or trim this file. Pair it with a system log rotator if you keep the forwarder on long term.

EULA and setup

• eula-accept
• no-interactive

eula-accept

Accept the InfluxData End User License Agreement non-interactively. The TELEGRAF_CONTROLLER_EULA environment variable accepts the value accept to indicate acceptance.

no-interactive

Skip interactive prompts at startup. When --no-interactive is set, you must provide owner account values and EULA acceptance through other options.

Licensing

• license-file-path

license-file-path

Path to a Telegraf Enterprise license JWT file. Telegraf Controller reads this file on startup, validates the license, and stores it in the database. If the database already contains a license, this variable is ignored on subsequent restarts.

If the file is missing, unreadable, or contains an invalid license, Telegraf Controller starts in unlicensed mode and logs the validation error.

See Apply a license for full guidance, including systemd examples.