Install Telegraf Controller

Telegraf Controller is a web-based configuration management system for Telegraf agents. It provides a user-friendly interface for managing Telegraf configurations, monitoring agents, and organizing plugins.

• System Requirements
• Review the EULA
• Download and install Telegraf Controller
• Set up your database
• Configure Telegraf Controller
• Access Telegraf Controller

System Requirements

• Operating Systems: Linux, macOS, Windows
• Architecture: x64 (Intel/AMD) or ARM64 (Apple Silicon/ARM)
• Database: SQLite (default), PostgreSQL, or PostgreSQL-compatible
• Ports: 8888 (web interface), 8000 (heartbeat service)

Review the EULA

Review the InfluxData End User Software License Agreement (EULA) for Telegraf Controller before downloading and installing.

Telegraf Controller requires that you accept the EULA before the server can start. When you first run Telegraf Controller in interactive mode (default), it prompts you to accept the EULA. Once accepted on a host machine, the EULA does not need to be accepted again unless the EULA is updated or the Telegraf Controller local data directory is removed.

Accept in interactive mode

Run the executable in a terminal and follow the prompt.

telegraf_controller

Enter v to view the full text of the Telegraf Controller EULA. Enter accept to accept the EULA and proceed.

Accept non-interactively

Use the --eula-accept command option or set the TELEGRAF_CONTROLLER_EULA environment variable to accept. This is required for non-interactive runs such as systemd, LaunchDaemons, or CI—for example:

telegraf_controller --eula-accept --no-interactive

TELEGRAF_CONTROLLER_EULA=accept telegraf_controller --no-interactive

$env:TELEGRAF_CONTROLLER_EULA="accept"
./telegraf_controller.exe --no-interactive

Download and install Telegraf Controller

1. Download the Telegraf Controller executable.

   Contact InfluxData for download

   If you are currently participating in the Telegraf Controller private alpha, send your operating system and architecture to InfluxData and we will provide you with the appropriate Telegraf Controller executable.

   If you are not currently in the private alpha and would like to be, request early access.

2. Install Telegraf Controller.

   Telegraf Controller executable name

   The downloaded Telegraf Controller executable includes platform-specific information in the file name. You can leave the information in the file name or you can rename the file to telegraf_controller. This documentation assumes the executable is named telegraf_controller.

   Linux macOS Windows

   Linux

   You can add the telegraf_controller executable to your system path or you can run it in place. You can also run Telegraf Controller as a service.

   • Add the executable to your system path
   • Run the executable in place
   • Install the executable as a systemd service

   Add the executable to your system path

   1. Add the following to your shell profile (for example ~/.bashrc):

      export PATH="$PATH:$PWD/telegraf_controller"

   2. Reload the profile or open a new shell.

   Run the executable in place

   ./telegraf_controller

   Install the executable as a systemd service

   If this is the first run on the host, accept the EULA in a TTY or set TELEGRAF_CONTROLLER_EULA=accept in the service environment.

   1. Create a Telegraf Controller service file:

      sudo tee /etc/systemd/system/telegraf-controller.service > /dev/null <<EOF
      [Unit]
      Description=Telegraf Controller
      After=network.target
      
      [Service]
      Type=simple
      User=$USER
      WorkingDirectory=/opt/telegraf-controller
      ExecStart=/opt/telegraf-controller/telegraf_controller
      Restart=on-failure
      RestartSec=10
      
      [Install]
      WantedBy=multi-user.target
      EOF

   2. Move the executable to /opt:

      sudo mkdir -p /opt/telegraf-controller
      sudo mv telegraf_controller /opt/telegraf-controller/
      sudo chmod +x /opt/telegraf-controller/telegraf_controller

   3. Enable and start the service:

      sudo systemctl daemon-reload
      sudo systemctl enable telegraf-controller
      sudo systemctl start telegraf-controller

   macOS

   You can add the telegraf_controller executable to your system path or you can run it in place. You can also run Telegraf Controller as a LaunchDaemon service.

   • Prepare the downloaded executable
   • Add the executable to your system path
   • Run the executable in place
   • Install as a LaunchDaemon

   Prepare the downloaded executable

   1. Give telegraf_controller executable permissions:

      chmod +x telegraf_controller

   2. Remove the macOS quarantine attribute (if downloaded via browser):

      xattr -d com.apple.quarantine telegraf_controller

   Add the executable to your system path

   sudo mv telegraf_controller /usr/local/bin/
   export PATH="/usr/local/bin:$PATH"

   Run the executable in place

   ./telegraf_controller

   Install as a LaunchDaemon

   If this is the first run on the host, accept the EULA in a TTY or set TELEGRAF_CONTROLLER_EULA=accept in the service environment.

   1. Create a plist file:

      sudo tee /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist > /dev/null <<EOF
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <dict>
          <key>Label</key>
          <string>com.influxdata.telegraf-controller</string>
          <key>ProgramArguments</key>
          <array>
              <string>/usr/local/bin/telegraf_controller</string>
          </array>
          <key>RunAtLoad</key>
          <true/>
          <key>KeepAlive</key>
          <true/>
          <key>StandardOutPath</key>
          <string>/var/log/telegraf-controller.log</string>
          <key>StandardErrorPath</key>
          <string>/var/log/telegraf-controller.error.log</string>
      </dict>
      </plist>
      EOF

   2. Move the executable to /usr/local/bin:

      sudo mv telegraf_controller /usr/local/bin/

   3. Load the service:

      sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist

   Windows

   You can run the telegraf_controller executable in place or you can run Telegraf Controller as a Windows service.

   • Run the application in place
   • Install as a Windows Service

   Run the application in place

   Double-click the executable or open Command Prompt or PowerShell and run:

   ./telegraf_controller.exe

   Install as a Windows Service

   Use NSSM (Non-Sucking Service Manager) to run Telegraf Controller as a Windows service.

   If this is the first run on the host, accept the EULA in a TTY or set TELEGRAF_CONTROLLER_EULA=accept in the service environment.

   1. Download NSSM

   2. In Command Prompt or PowerShell, install the Telegraf Controller service:

      nssm install TelegrafController "C:\Program Files\TelegrafController\telegraf_controller.exe"
      nssm set TelegrafController DisplayName "Telegraf Controller"
      nssm set TelegrafController Description "Web-based Telegraf configuration manager"
      nssm set TelegrafController Start SERVICE_AUTO_START

   3. Start the service:

      nssm start TelegrafController

Set up your database

Telegraf Controller supports SQLite (default), PostgreSQL, or PostgreSQL-compatible databases as its data backend.

SQLite

With SQLite installed, no additional setup is required. Telegraf Controller creates the database file automatically on first run.

Default SQLite data locations

Telegraf Controller stores its data in platform-specific locations:

PostgreSQL

The following steps assume you have a running PostgreSQL or PostgreSQL-compatible server running.

1. Create a database named telegraf_controller:

   CREATE DATABASE telegraf_controller;

2. Run with PostgreSQL URL:

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

The application will automatically run migrations on first startup.

Configure Telegraf Controller

Use the following command line options to configure Telegraf Controller.

Configuration options

Examples

# Use custom ports
telegraf_controller --port=3000 --heartbeat-port=9000

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

# Use custom SQLite database location
telegraf_controller \
  --database="/path/to/custom/database.db"

# Enable HTTPS
telegraf_controller \
  --ssl-cert="/path/to/cert.pem" \
  --ssl-key="/path/to/key.pem"

# Accept the EULA non-interactively
telegraf_controller \
  --no-interactive \
  --eula-accept

# Use custom ports
./telegraf_controller.exe --port=3000 --heartbeat-port=9000

# Use PostgreSQL database
./telegraf_controller.exe `
  --database="postgresql://user:password@localhost:5432/telegraf_db"

# Use custom SQLite database location
./telegraf_controller.exe `
  --database="C:\path\to\custom\database.db"

# Enable HTTPS
./telegraf_controller.exe `
  --ssl-cert="C:\path\to\cert.pem" `
  --ssl-key="C:\path\to\key.pem"

# Accept the EULA non-interactively
./telegraf_controller.exe `
  --no-interactive `
  --eula-accept

# Use custom ports
PORT=3000
HEARTBEAT_PORT=9000

# Use PostgreSQL database
DATABASE=postgresql://user:password@localhost:5432/telegraf_db

# Use custom SQLite database location
DATABASE=/path/to/custom/database.db

# Enable HTTPS
SSL_CERT=/path/to/cert.pem
SSL_KEY=/path/to/key.pem

# Accept the EULA
TELEGRAF_CONTROLLER_EULA=accept

telegraf_controller

# Use custom ports
$env:PORT=3000
$env:HEARTBEAT_PORT=9000

# Use PostgreSQL database
$env:DATABASE=postgresql://user:password@localhost:5432/telegraf_db

# Use custom SQLite database location
$env:DATABASE=C:\path\to\custom\database.db

# Enable HTTPS
$env:SSL_CERT=C:\path\to\cert.pem
$env:SSL_KEY=C:\path\to\key.pem

# Accept the EULA
$env:TELEGRAF_CONTROLLER_EULA=accept

./telegraf_controller.exe

Access Telegraf Controller

Once started, access the Telegraf Controller web interface at http://localhost:8888 (or using your custom port).