Documentation

Telegraf Controller

Telegraf Controller configuration options

Telegraf Controller is in Public Beta

Telegraf Controller is in public beta and will be part of the future Telegraf Enterprise offering. While in beta, Telegraf Controller is not meant for production use. The Telegraf Controller documentation is a work in progress, and we are actively working to improve it. If you have any questions or suggestions, please submit an issue. We welcome any and all contributions.

Beta expectations

Provide beta feedback

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

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

Web interface and API port.

Default: 8888

Command flagEnvironment variable
--portAPP_PORT

heartbeat-port

Agent heartbeat service port.

Default: 8000

Command flagEnvironment variable
--heartbeat-portHEARTBEAT_PORT

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"
Command flagEnvironment variable
--databaseDATABASE_URL

TLS

ssl-cert-path

Path to the SSL/TLS certificate file. Required to enable HTTPS for the web interface and API.

Command flagEnvironment variable
(none)SSL_CERT_PATH

ssl-key-path

Path to the SSL/TLS private key file. Required to enable HTTPS for the web interface and API.

Command flagEnvironment variable
(none)SSL_KEY_PATH

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.

Bootstrap-only settings

On first startup, Telegraf Controller persists OWNER_EMAIL, OWNER_USERNAME, and OWNER_PASSWORD in the database; the database is the authoritative source thereafter. Changes to these environment variables or CLI flags do not affect the stored values. To change owner account details after bootstrap, use the Telegraf Controller UI or API.

owner-email

Email address for the bootstrap owner account.

Command flagEnvironment variable
--owner-emailOWNER_EMAIL

owner-username

Username for the bootstrap owner account.

Command flagEnvironment variable
--owner-usernameOWNER_USERNAME

owner-password

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

Command flagEnvironment variable
--owner-passwordOWNER_PASSWORD

reset-owner-password

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

Use RESET_OWNER_PASSWORD only to recover from a forgotten or compromised owner password. Unset the variable after the password has been reset to avoid resetting the password on subsequent restarts.

Command flagEnvironment variable
(none)RESET_OWNER_PASSWORD

Authentication and security

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

Command flagEnvironment variable
--session-secretSESSION_SECRET

Bootstrap-only login security settings

On first startup, Telegraf Controller persists LOGIN_LOCKOUT_ATTEMPTS, LOGIN_LOCKOUT_MINUTES, and PASSWORD_COMPLEXITY in the database; the database is the authoritative source thereafter. Changes to these environment variables do not affect the stored values. To change these settings after bootstrap, use the Telegraf Controller UI.

login-lockout-attempts

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

Default: 5

Command flagEnvironment variable
(none)LOGIN_LOCKOUT_ATTEMPTS

login-lockout-minutes

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

Default: 15

Command flagEnvironment variable
(none)LOGIN_LOCKOUT_MINUTES

password-complexity

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

LevelMin lengthUppercaseLowercaseDigitsSpecial characters
low8NoNoNoNo
medium10YesYesYesNo
high12YesYesYesYes

Default: low

Command flagEnvironment variable
(none)PASSWORD_COMPLEXITY

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

Telegraf Controller reads this value once at startup; the value is immutable at runtime. Anyone with network access to the listed endpoint groups can use them without an API token.

# 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="*"
Command flagEnvironment variable
--disable-auth-endpointsDISABLED_AUTH_ENDPOINTS

Logging

rust-log

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

Default: info

Command flagEnvironment variable
(none)RUST_LOG

logs-dir

Absolute path for heartbeat agent logs.

Default: System temp directory

Command flagEnvironment variable
--logs-dirLOGS_DIR

EULA and setup

eula-accept

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

Command flagEnvironment variable
--eula-acceptTELEGRAF_CONTROLLER_EULA

no-interactive

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

Command flagEnvironment variable
--no-interactive(none)

Was this page helpful?

Thank you for your feedback!

© 2026 InfluxData, Inc.

Where are you running InfluxDB?

Select your InfluxDB Cloud region and cluster or your InfluxDB OSS URL and we’ll customize code examples for you. Identify your InfluxDB Cloud cluster.

  • InfluxDB Cloud
  • InfluxDB OSS or Enterprise
AWS

  • US West (Oregon)

GCP
Azure
Default
Custom

For more information, see InfluxDB Cloud regions or InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

Key enhancements in Explorer 1.8

Explorer 1.8 is now available with streaming data subscriptions (beta), line protocol preview, and query history & saved queries.

View Explorer 1.8 release notes

Explorer 1.8 includes new features and improvements that make it easier to ingest, explore, and manage data.

Highlights:

  • Streaming data subscriptions (beta): Stream data into Explorer from MQTT, Kafka, and AMQP sources.
  • Line protocol preview: Preview line protocol, schema, and parse errors before data is written.
  • Custom sample data: Generate custom sample datasets with line protocol and schema preview.
  • Query history and saved queries: Browse query history and save/re-run named queries.
  • Retention period management: Set, update, or clear retention periods on databases and tables.

For more details, see Explorer 1.8 release notes

InfluxDB 3.9: Performance upgrade preview

InfluxDB 3 Enterprise 3.9 includes a beta of major performance upgrades with faster single-series queries, wide-and-sparse table support, and more.

InfluxDB 3 Enterprise 3.9 includes a beta of major performance and feature updates.

Key improvements:

  • Faster single-series queries
  • Consistent resource usage
  • Wide-and-sparse table support
  • Automatic distinct value caches for reduced latency with metadata queries

Preview features are subject to breaking changes.

For more information, see:

Telegraf Enterprise now in public beta

Get early access to the Telegraf Controller and provide feedback to help shape the future of Telegraf Enterprise.

See the Blog Post

The upcoming Telegraf Enterprise offering is for organizations running Telegraf at scale and is comprised of two key components:

  • Telegraf Controller: A control plane (UI + API) that centralizes Telegraf configuration management and agent health visibility.
  • Telegraf Enterprise Support: Official support for Telegraf Controller and Telegraf plugins.

Join the Telegraf Enterprise beta to get early access to the Telegraf Controller and provide feedback to help shape the future of Telegraf Enterprise.

For more information:

Telegraf Controller v0.0.7-beta now available

Telegraf Controller v0.0.7-beta is now available with new features, improvements, bug fixes, and an important breaking change.

View the release notes
Download Telegraf Controller v0.0.7-beta

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On May 27, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2