====== 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.

===== One-shot setup (recommended) =====

==== Linux ====

  - Open the OS Agent modal in the Collector or Cockpit
  - Go to the **Configuration** tab
  - At the bottom, copy the **wget command**
  - Paste it on the target host as ''root'' (or with ''sudo'')

The command looks like this:

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

The script does:

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

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

==== Windows ====

  - Open the OS Agent modal
  - Go to the **Configuration** tab
  - Click **setup.ps1** to download the file
  - Open **PowerShell as Administrator**
  - Run the script:

<code powershell>
.\setup.ps1
</code>

The script does:

  - Try to fetch the latest Telegraf version from the GitHub API. If GitHub is not reachable, it falls back to a built-in version
  - Download the Telegraf zip from ''dl.influxdata.com''
  - Extract to ''C:\Program Files\Telegraf\''
  - Write ''telegraf.conf'' with the Collector URL and API key already filled in
  - 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.

===== Manual install =====

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

==== Linux - install Telegraf ====

<code bash>
# 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
</code>

==== Windows - install Telegraf ====

  - Download the latest Telegraf zip from [[https://www.influxdata.com/downloads/|influxdata.com]]
  - Extract it to ''C:\Program Files\Telegraf\''
  - Open **PowerShell as Administrator**
  - Install as a service:

<code powershell>
& "C:\Program Files\Telegraf\telegraf.exe" --service install --config "C:\Program Files\Telegraf\telegraf.conf"
Start-Service telegraf
</code>

==== Get the config file ====

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

  - Open the OS Agent modal in the Collector
  - Go to the **Configuration** tab
  - Click **telegraf.conf** to download the file
  - Copy it to:
    * Linux: ''/etc/telegraf/telegraf.conf''
    * Windows: ''C:\Program Files\Telegraf\telegraf.conf''
  - Restart the Telegraf service

<code bash>
# Linux
sudo systemctl restart telegraf

# Windows (PowerShell as Admin)
Restart-Service telegraf
</code>

===== Verify Telegraf is running =====

==== Linux ====

<code bash>
sudo systemctl status telegraf
journalctl -u telegraf -f
</code>

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

==== Windows ====

<code powershell>
Get-Service telegraf
Get-EventLog -LogName Application -Source Telegraf -Newest 20
</code>

===== Verify the host is registered in the Collector =====

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

If the host does not appear, see [[products:promonitor:latest:userguide:administration:os-agent:troubleshooting|Troubleshooting]].

===== Test the push manually =====

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

<code bash>
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'
</code>

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.

===== Connection problems =====

==== HTTPS with self-signed certificate ====

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:

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

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

==== Behind a corporate proxy ====

Set the proxy as an environment variable before starting Telegraf:

<code bash>
# 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
</code>

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

===== Uninstall =====

==== Linux ====

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

==== Windows ====

<code powershell>
Stop-Service telegraf
& "C:\Program Files\Telegraf\telegraf.exe" --service uninstall
Remove-Item -Recurse "C:\Program Files\Telegraf"
</code>

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