OS Agent - Install Telegraf

This page explains how to install the Telegraf agent on the target host so it can push OS metrics to the Collector.

The fastest path is the one-shot setup script generated by the Collector. The manual steps are also documented below if you prefer to do it yourself, or if your environment blocks scripts.

1. Open the OS Agent modal in the Collector or Cockpit
2. Go to the Configuration tab
3. At the bottom, copy the wget command
4. Paste it on the target host as root (or with sudo)

The command looks like this:

wget https://collector.example.com/api/v1/os-agent/generate?format=sh -O setup.sh && chmod +x setup.sh && sudo ./setup.sh

The script does:

1. Detect the package manager (apt or yum)
2. Add the official InfluxData repository
3. Install the telegraf package
4. Write /etc/telegraf/telegraf.conf with the Collector URL and API key already filled in
5. Enable and start the telegraf service

You should see Done. Telegraf installed and running. at the end.

1. Open the OS Agent modal
2. Go to the Configuration tab
3. Click setup.ps1 to download the file
4. Open PowerShell as Administrator
5. Run the script:

.\setup.ps1

The script does:

1. Try to fetch the latest Telegraf version from the GitHub API. If GitHub is not reachable, it falls back to a built-in version
2. Download the Telegraf zip from dl.influxdata.com
3. Extract to C:\Program Files\Telegraf\
4. Write telegraf.conf with the Collector URL and API key already filled in
5. Install and start the telegraf Windows service

Important: Telegraf must be installed as a service on Windows. Running it as a normal user limits which processes it can read.

Use this if the one-shot script does not fit (offline host, custom path, etc.).

# Debian / Ubuntu
curl -s https://repos.influxdata.com/influxdata-archive.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/influxdata-archive.gpg
echo "deb https://repos.influxdata.com/debian stable main" | sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt-get update && sudo apt-get install -y telegraf
 
# RHEL / CentOS / Rocky
sudo tee /etc/yum.repos.d/influxdata.repo <<'EOF'
[influxdata]
name = InfluxData Repository
baseurl = https://repos.influxdata.com/rhel/$releasever/$basearch/stable
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive_compat.key
EOF
sudo yum install -y telegraf

1. Download the latest Telegraf zip from influxdata.com
2. Extract it to C:\Program Files\Telegraf\
3. Open PowerShell as Administrator
4. Install as a service:

& "C:\Program Files\Telegraf\telegraf.exe" --service install --config "C:\Program Files\Telegraf\telegraf.conf"
Start-Service telegraf

After Telegraf is installed, you still need a valid telegraf.conf. The simplest way:

1. Open the OS Agent modal in the Collector
2. Go to the Configuration tab
3. Click telegraf.conf to download the file
4. Copy it to:
   • Linux: /etc/telegraf/telegraf.conf
   • Windows: C:\Program Files\Telegraf\telegraf.conf
5. Restart the Telegraf service

# Linux
sudo systemctl restart telegraf
 
# Windows (PowerShell as Admin)
Restart-Service telegraf

sudo systemctl status telegraf
journalctl -u telegraf -f

A healthy log shows Loaded inputs: and Loaded outputs: lines, then nothing else - Telegraf only logs errors after startup.

Get-Service telegraf
Get-EventLog -LogName Application -Source Telegraf -Newest 20

1. Open the OS Agent modal
2. Go to the Monitor tab (or Hosts in Cockpit)
3. The host should appear within 30 seconds with status OK
4. Click the row to expand and see CPU, memory, disk and per-process detail

If the host does not appear, see Troubleshooting.

You can test the push endpoint with curl before installing Telegraf:

curl -X POST https://collector.example.com/api/v1/os-agent/push \
  -H "Content-Type: text/plain" \
  -H "X-API-Key: YOUR-KEY-HERE" \
  -d 'cpu,host=test_host,cpu=cpu-total usage_idle=85.5,usage_user=10.2,usage_system=4.3
mem,host=test_host used_percent=72.1,available=4294967296'

Expected response: OK.

After this, the host test_host appears in the Monitor tab. You can then delete it manually once you are done testing.

If your Collector uses a self-signed certificate, Telegraf will refuse to connect by default. Open telegraf.conf and add this in the outputs.http section:

[[outputs.http]]
  url = "https://collector.example.com/api/v1/os-agent/push"
  ...
  insecure_skip_verify = true

The setup script adds this line automatically when the Collector URL starts with https.

Set the proxy as an environment variable before starting Telegraf:

# Linux - in /etc/default/telegraf
HTTPS_PROXY=http://proxy.example.com:8080
HTTP_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

On Windows, set the same variables at the system level (Environment Variables) and restart the service.

sudo systemctl stop telegraf
sudo systemctl disable telegraf
sudo apt-get remove --purge telegraf   # or: sudo yum remove telegraf
sudo rm -rf /etc/telegraf

Stop-Service telegraf
& "C:\Program Files\Telegraf\telegraf.exe" --service uninstall
Remove-Item -Recurse "C:\Program Files\Telegraf"

The host stays in the Collector database with status ERROR (no recent push) until you delete it from the Monitor tab.