From d94c338e726dd357969fab67336cf822707d31e4 Mon Sep 17 00:00:00 2001 From: Tommaso Bailetti Date: Tue, 1 Sep 2026 16:33:49 +0200 Subject: [PATCH 1/2] feat: documented how to export telegraf data --- .../advanced-cli/telegraf_prometheus.md | 150 +++++++++++++++++ .../advanced-cli/telegraf_prometheus.md | 153 ++++++++++++++++++ 2 files changed, 303 insertions(+) create mode 100644 docs/administrator-manual/advanced-cli/telegraf_prometheus.md create mode 100644 i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md diff --git a/docs/administrator-manual/advanced-cli/telegraf_prometheus.md b/docs/administrator-manual/advanced-cli/telegraf_prometheus.md new file mode 100644 index 00000000..3bce6269 --- /dev/null +++ b/docs/administrator-manual/advanced-cli/telegraf_prometheus.md @@ -0,0 +1,150 @@ +--- +title: "Telegraf Prometheus exporter" +sidebar_position: 13 +--- + +# Telegraf Prometheus exporter {#telegraf-prometheus-exporter} + +Telegraf collects the system and service metrics of the firewall and writes them +to the local VictoriaMetrics instance. Starting from NethSecurity 8.8, Telegraf +can also expose the very same metrics in Prometheus format, so an external +Prometheus server, Grafana Agent or any other compatible collector can scrape +them directly from the firewall. + +The exporter is **disabled by default**. + +## Enabling the exporter {#enabling-the-exporter} + +Always pick a listening port other than the default `9273`: that port is +reserved for the controller, which scrapes the unit through the VPN tunnel. +Port `9274` is a safe choice. + +1. Open a terminal window on the firewall. +2. Enable the Prometheus output on port `9274` and apply the change: + +``` bash +uci set telegraf.output_prometheus.enabled='1' +uci set telegraf.output_prometheus.listen_addr=':9274' +uci commit telegraf +reload_config +``` + +3. Check that the metrics are served: + +``` bash +curl -s http://127.0.0.1:9274/metrics | head +``` + +The exporter now listens on port `9274` and publishes the metrics on the +`/metrics` path. The firewall still blocks the port for any incoming traffic, so +continue with [Accessing the exporter +remotely](#accessing-the-exporter-remotely) to reach it from the collector. + +:::warning + +If the exporter is left on the default port `9273` while the firewall is +connected to a controller, two Prometheus outputs compete for the same port and +one of them fails to bind. See [Units connected to a +controller](#telegraf-prometheus-controller). + +::: + +## Accessing the exporter remotely {#accessing-the-exporter-remotely} + +Two options are available. Both of them restrict who can read the metrics, so +pick the one that fits the collector. + +### Reverse proxy path {#reverse-proxy-path} + +Recommended: the metrics travel over HTTPS on port 443 and no extra port is +opened on the firewall. Go to the [Certificates and reverse +proxy](../network/reverse_proxy.md) page, click **Add reverse proxy** and fill +in: + +- `Type`: **Path**, for example `/telegraf-metrics` +- `Destination URL`: `http://127.0.0.1:9274/metrics` +- `Allowed networks`: the address of the collector in CIDR format, for example + `203.0.113.5/32` + +The metrics are then available at `https:///telegraf-metrics`. + +### Firewall input rule {#firewall-input-rule} + +Use this option when the collector must reach port `9274` directly. Go to the +[Rules](../firewall/firewall_rules.md) page, `Input rules` tab, and add a rule +with: + +- `Source address`: the address of the collector +- `Source zone`: the zone the collector belongs to +- `Destination service`: **Custom**, protocol `TCP`, port `9274` +- `Action`: **Accept** + +The metrics are then available at `http://:9274/metrics`. This +option exposes the exporter in clear text, so also protect it with a password, +as described below. + +## Protecting the exporter with a password {#protecting-the-exporter-with-a-password} + +The exporter can require HTTP basic authentication. Both the user name and the +password must be set, otherwise authentication is not configured at all: + +``` bash +uci set telegraf.output_prometheus.basic_auth_username='prometheus' +uci set telegraf.output_prometheus.basic_auth_password='' +uci commit telegraf +reload_config +``` + +Verify the credentials with: + +``` bash +curl -s -u prometheus:'' http://127.0.0.1:9274/metrics | head +``` + +:::warning + +The exporter serves plain HTTP and has no authentication until the two options +above are set. Do not expose it outside a trusted network without a password. + +::: + +## Changing the listening address {#changing-the-listening-address} + +The `listen_addr` option accepts the `address:port` syntax; when the address is +omitted, Telegraf binds all the available IPv4 and IPv6 addresses. + +To restrict the exporter to a single address: + +``` bash +# only reachable from the firewall itself, enough for the reverse proxy path +uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274' + +# only reachable on a specific LAN address +uci set telegraf.output_prometheus.listen_addr='192.168.1.1:9274' + +uci commit telegraf +reload_config +``` + +## Units connected to a controller {#telegraf-prometheus-controller} + +When the firewall is connected to a controller, the controller already scrapes +Telegraf through the VPN tunnel: at every connection the unit binds port `9273` +on its own VPN address. + +That endpoint is managed by the system and must be left alone. Keep the +`listen_addr` of the exporter on a different port, as described in [Enabling the +exporter](#enabling-the-exporter), and both endpoints coexist without +interfering with each other. + +## Disabling the exporter {#disabling-the-exporter} + +``` bash +uci set telegraf.output_prometheus.enabled='0' +uci commit telegraf +reload_config +``` + +Local monitoring and the metrics stored in VictoriaMetrics are not affected: the +exporter is an additional output, and disabling it only stops the Prometheus +endpoint. diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md new file mode 100644 index 00000000..1dae0fad --- /dev/null +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md @@ -0,0 +1,153 @@ +--- +title: "Esportatore Prometheus di Telegraf" +sidebar_position: 13 +--- + +# Esportatore Prometheus di Telegraf {#telegraf-prometheus-exporter} + +Telegraf raccoglie le metriche di sistema e dei servizi del firewall e le scrive +nell'istanza locale di VictoriaMetrics. A partire da NethSecurity 8.8, Telegraf +può esporre le stesse metriche anche in formato Prometheus, così un server +Prometheus esterno, Grafana Agent o qualsiasi altro collettore compatibile può +leggerle direttamente dal firewall. + +L'esportatore è **disabilitato per impostazione predefinita**. + +## Abilitare l'esportatore {#enabling-the-exporter} + +Scegliere sempre una porta di ascolto diversa da quella predefinita `9273`: +quella porta è riservata al controller, che legge le metriche dell'unità +attraverso il tunnel VPN. La porta `9274` è una scelta sicura. + +1. Aprire un terminale sul firewall. +2. Abilitare l'output Prometheus sulla porta `9274` e applicare la modifica: + +``` bash +uci set telegraf.output_prometheus.enabled='1' +uci set telegraf.output_prometheus.listen_addr=':9274' +uci commit telegraf +reload_config +``` + +3. Verificare che le metriche vengano servite: + +``` bash +curl -s http://127.0.0.1:9274/metrics | head +``` + +L'esportatore ora ascolta sulla porta `9274` e pubblica le metriche sul percorso +`/metrics`. Il firewall blocca comunque la porta per il traffico in ingresso, +quindi proseguire con [Accedere all'esportatore da +remoto](#accessing-the-exporter-remotely) per raggiungerlo dal collettore. + +:::warning + +Se l'esportatore viene lasciato sulla porta predefinita `9273` mentre il +firewall è collegato a un controller, due output Prometheus entrano in +competizione sulla stessa porta e uno dei due non riesce ad aprirla. Vedere +[Unità collegate a un controller](#telegraf-prometheus-controller). + +::: + +## Accedere all'esportatore da remoto {#accessing-the-exporter-remotely} + +Sono disponibili due opzioni. Entrambe limitano chi può leggere le metriche, +quindi scegliere quella più adatta al collettore. + +### Percorso su reverse proxy {#reverse-proxy-path} + +Consigliata: le metriche transitano su HTTPS sulla porta 443 e non viene aperta +nessuna porta aggiuntiva sul firewall. Accedere alla pagina [Certificati e +reverse proxy](../network/reverse_proxy.md), fare clic su **Aggiungi reverse +proxy** e compilare: + +- `Tipo`: **Percorso**, per esempio `/telegraf-metrics` +- `URL di destinazione`: `http://127.0.0.1:9274/metrics` +- `Reti consentite`: l'indirizzo del collettore in formato CIDR, per esempio + `203.0.113.5/32` + +Le metriche sono poi disponibili all'indirizzo +`https:///telegraf-metrics`. + +### Regola di firewall in ingresso {#firewall-input-rule} + +Usare questa opzione quando il collettore deve raggiungere direttamente la porta +`9274`. Accedere alla pagina [Regole](../firewall/firewall_rules.md), scheda +`Regole di ingresso`, e aggiungere una regola con: + +- `Indirizzo sorgente`: l'indirizzo del collettore +- `Zona sorgente`: la zona a cui appartiene il collettore +- `Servizio di destinazione`: **Personalizzato**, protocollo `TCP`, porta `9274` +- `Azione`: **Accetta** + +Le metriche sono poi disponibili all'indirizzo +`http://:9274/metrics`. Questa opzione espone l'esportatore in +chiaro, quindi proteggerlo anche con una password, come descritto qui sotto. + +## Proteggere l'esportatore con una password {#protecting-the-exporter-with-a-password} + +L'esportatore può richiedere l'autenticazione HTTP basic. Devono essere +impostati sia il nome utente sia la password, altrimenti l'autenticazione non +viene configurata: + +``` bash +uci set telegraf.output_prometheus.basic_auth_username='prometheus' +uci set telegraf.output_prometheus.basic_auth_password='' +uci commit telegraf +reload_config +``` + +Verificare le credenziali con: + +``` bash +curl -s -u prometheus:'' http://127.0.0.1:9274/metrics | head +``` + +:::warning + +L'esportatore serve HTTP in chiaro e non richiede alcuna autenticazione fino a +quando le due opzioni sopra non vengono impostate. Non esporlo al di fuori di +una rete fidata senza una password. + +::: + +## Modificare l'indirizzo di ascolto {#changing-the-listening-address} + +L'opzione `listen_addr` accetta la sintassi `indirizzo:porta`; se l'indirizzo +viene omesso, Telegraf si lega a tutti gli indirizzi IPv4 e IPv6 disponibili. + +Per limitare l'esportatore a un solo indirizzo: + +``` bash +# raggiungibile solo dal firewall stesso, sufficiente per il reverse proxy +uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274' + +# raggiungibile solo su un indirizzo LAN specifico +uci set telegraf.output_prometheus.listen_addr='192.168.1.1:9274' + +uci commit telegraf +reload_config +``` + +## Unità collegate a un controller {#telegraf-prometheus-controller} + +Quando il firewall è collegato a un controller, il controller legge già le +metriche di Telegraf attraverso il tunnel VPN: a ogni connessione l'unità apre +la porta `9273` sul proprio indirizzo VPN. + +Quell'endpoint è gestito dal sistema e non va modificato. Mantenendo il +`listen_addr` dell'esportatore su una porta differente, come descritto in +[Abilitare l'esportatore](#enabling-the-exporter), i due endpoint convivono +senza interferire tra loro. + +## Disabilitare l'esportatore {#disabling-the-exporter} + +``` bash +uci set telegraf.output_prometheus.enabled='0' +uci commit telegraf +reload_config +``` + +Il monitoraggio locale e le metriche salvate in VictoriaMetrics non vengono +influenzati: l'esportatore è un output aggiuntivo e disabilitarlo interrompe +solo l'endpoint Prometheus. From 38c75dca0f85ffe722c77e7f124792e2720ab628 Mon Sep 17 00:00:00 2001 From: Tommaso Bailetti Date: Tue, 1 Sep 2026 16:50:24 +0200 Subject: [PATCH 2/2] adjusted warnings, addressed comment from Giacomo --- .../advanced-cli/telegraf_prometheus.md | 49 ++++++++++++++-- .../advanced-cli/telegraf_prometheus.md | 56 ++++++++++++++++--- 2 files changed, 93 insertions(+), 12 deletions(-) diff --git a/docs/administrator-manual/advanced-cli/telegraf_prometheus.md b/docs/administrator-manual/advanced-cli/telegraf_prometheus.md index 3bce6269..2c76afcb 100644 --- a/docs/administrator-manual/advanced-cli/telegraf_prometheus.md +++ b/docs/administrator-manual/advanced-cli/telegraf_prometheus.md @@ -36,10 +36,20 @@ curl -s http://127.0.0.1:9274/metrics | head ``` The exporter now listens on port `9274` and publishes the metrics on the -`/metrics` path. The firewall still blocks the port for any incoming traffic, so -continue with [Accessing the exporter +`/metrics` path. Continue with [Accessing the exporter remotely](#accessing-the-exporter-remotely) to reach it from the collector. +:::danger + +The exporter binds every address of the firewall, so the port is reachable from +every zone whose input policy is `ACCEPT`. With the default configuration this +means the whole LAN; if the input policy of a WAN or guest zone has been changed +to `ACCEPT`, the metrics are exposed there too. Never leave the port open like +that: restrict it as described in [Restricting access to the +metrics](#restricting-access-to-the-metrics). + +::: + :::warning If the exporter is left on the default port `9273` while the firewall is @@ -79,9 +89,38 @@ with: - `Destination service`: **Custom**, protocol `TCP`, port `9274` - `Action`: **Accept** -The metrics are then available at `http://:9274/metrics`. This -option exposes the exporter in clear text, so also protect it with a password, -as described below. +The metrics are then available at `http://:9274/metrics`. This rule +alone does not close the port to the other zones: complete the configuration as +described in [Restricting access to the +metrics](#restricting-access-to-the-metrics). The exporter is exposed in clear +text, so also protect it with a password. + +## Restricting access to the metrics {#restricting-access-to-the-metrics} + +Choose one of the two following approaches, depending on how the collector +reaches the exporter. + +**With the reverse proxy path**, bind the exporter to the loopback address only: +nothing is published on the network interfaces and the reverse proxy remains the +single entry point, filtered by its `Allowed networks` field. + +``` bash +uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274' +uci commit telegraf +reload_config +``` + +**With a firewall input rule**, close the port to everyone else. On the +[Rules](../firewall/firewall_rules.md) page, `Input rules` tab, add a second +rule *below* the one that accepts the collector: + +- `Source address`: any source address +- `Source zone`: Any +- `Destination service`: **Custom**, protocol `TCP`, port `9274` +- `Action`: **Drop** + +The first matching rule wins, so the collector is accepted and every other host +is dropped, whatever the input policy of its zone is. ## Protecting the exporter with a password {#protecting-the-exporter-with-a-password} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md index 1dae0fad..4349d547 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md @@ -36,10 +36,21 @@ curl -s http://127.0.0.1:9274/metrics | head ``` L'esportatore ora ascolta sulla porta `9274` e pubblica le metriche sul percorso -`/metrics`. Il firewall blocca comunque la porta per il traffico in ingresso, -quindi proseguire con [Accedere all'esportatore da +`/metrics`. Proseguire con [Accedere all'esportatore da remoto](#accessing-the-exporter-remotely) per raggiungerlo dal collettore. +:::danger + +L'esportatore si lega a tutti gli indirizzi del firewall, quindi la porta è +raggiungibile da ogni zona la cui politica di ingresso è `ACCEPT`. Con la +configurazione predefinita questo significa tutta la LAN; se la politica di +ingresso di una zona WAN o guest è stata modificata in `ACCEPT`, le metriche +sono esposte anche lì. Non lasciare mai la porta aperta in questo modo: +limitarla come descritto in [Limitare l'accesso alle +metriche](#restricting-access-to-the-metrics). + +::: + :::warning Se l'esportatore viene lasciato sulla porta predefinita `9273` mentre il @@ -61,9 +72,9 @@ nessuna porta aggiuntiva sul firewall. Accedere alla pagina [Certificati e reverse proxy](../network/reverse_proxy.md), fare clic su **Aggiungi reverse proxy** e compilare: -- `Tipo`: **Percorso**, per esempio `/telegraf-metrics` -- `URL di destinazione`: `http://127.0.0.1:9274/metrics` -- `Reti consentite`: l'indirizzo del collettore in formato CIDR, per esempio +- `Type`: **Path**, per esempio `/telegraf-metrics` +- `Destination URL`: `http://127.0.0.1:9274/metrics` +- `Allowed networks`: l'indirizzo del collettore in formato CIDR, per esempio `203.0.113.5/32` Le metriche sono poi disponibili all'indirizzo @@ -81,8 +92,39 @@ Usare questa opzione quando il collettore deve raggiungere direttamente la porta - `Azione`: **Accetta** Le metriche sono poi disponibili all'indirizzo -`http://:9274/metrics`. Questa opzione espone l'esportatore in -chiaro, quindi proteggerlo anche con una password, come descritto qui sotto. +`http://:9274/metrics`. Questa regola da sola non chiude la porta +alle altre zone: completare la configurazione come descritto in [Limitare +l'accesso alle metriche](#restricting-access-to-the-metrics). L'esportatore è +esposto in chiaro, quindi proteggerlo anche con una password. + +## Limitare l'accesso alle metriche {#restricting-access-to-the-metrics} + +Scegliere uno dei due approcci seguenti, in base a come il collettore raggiunge +l'esportatore. + +**Con il percorso su reverse proxy**, legare l'esportatore solo all'indirizzo di +loopback: nulla viene pubblicato sulle interfacce di rete e il reverse proxy +resta l'unico punto di accesso, filtrato dal suo campo `Allowed networks`. + +``` bash +uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274' +uci commit telegraf +reload_config +``` + +**Con una regola di firewall in ingresso**, chiudere la porta a tutti gli altri. +Nella pagina [Regole](../firewall/firewall_rules.md), scheda `Regole di +ingresso`, aggiungere una seconda regola *sotto* quella che accetta il +collettore: + +- `Indirizzo sorgente`: qualsiasi indirizzo sorgente +- `Zona sorgente`: Qualsiasi +- `Servizio di destinazione`: **Personalizzato**, protocollo `TCP`, porta `9274` +- `Azione`: **Scarta** + +Vince la prima regola che corrisponde, quindi il collettore viene accettato e +ogni altro host viene scartato, qualunque sia la politica di ingresso della sua +zona. ## Proteggere l'esportatore con una password {#protecting-the-exporter-with-a-password}