Add documentation about listening on port < 1024 (#6785)

This commit is contained in:
reimda 2019-12-11 11:23:51 -07:00 committed by Daniel Nelson
parent 05cefe61bd
commit 61fbc68279
2 changed files with 35 additions and 2 deletions

View File

@ -17,7 +17,11 @@ the SNMP [README.md](../snmp/README.md) for details.
## Transport, local address, and port to listen on. Transport must ## Transport, local address, and port to listen on. Transport must
## be "udp://". Omit local address to listen on all interfaces. ## be "udp://". Omit local address to listen on all interfaces.
## example: "udp://127.0.0.1:1234" ## example: "udp://127.0.0.1:1234"
# service_address = udp://:162 ##
## Special permissions may be required to listen on a port less than
## 1024. See README.md for details
##
# service_address = "udp://:162"
## Timeout running snmptranslate command ## Timeout running snmptranslate command
# timeout = "5s" # timeout = "5s"
``` ```
@ -41,3 +45,28 @@ the SNMP [README.md](../snmp/README.md) for details.
snmp_trap,mib=SNMPv2-MIB,name=coldStart,oid=.1.3.6.1.6.3.1.1.5.1,source=192.168.122.102,version=2c snmpTrapEnterprise.0="linux",sysUpTimeInstance=1i 1574109187723429814 snmp_trap,mib=SNMPv2-MIB,name=coldStart,oid=.1.3.6.1.6.3.1.1.5.1,source=192.168.122.102,version=2c snmpTrapEnterprise.0="linux",sysUpTimeInstance=1i 1574109187723429814
snmp_trap,mib=NET-SNMP-AGENT-MIB,name=nsNotifyShutdown,oid=.1.3.6.1.4.1.8072.4.0.2,source=192.168.122.102,version=2c sysUpTimeInstance=5803i,snmpTrapEnterprise.0="netSnmpNotificationPrefix" 1574109186555115459 snmp_trap,mib=NET-SNMP-AGENT-MIB,name=nsNotifyShutdown,oid=.1.3.6.1.4.1.8072.4.0.2,source=192.168.122.102,version=2c sysUpTimeInstance=5803i,snmpTrapEnterprise.0="netSnmpNotificationPrefix" 1574109186555115459
``` ```
### Using a Privileged Port
On many operating systems, listening on a privileged port (a port
number less than 1024) requires extra permission. Since the default
SNMP trap port 162 is in this category, using telegraf to receive SNMP
traps may need extra permission.
Instructions for listening on a privileged port vary by operating
system. It is not recommended to run telegraf as superuser in order to
use a privileged port. Instead follow the principle of least privilege
and use a more specific operating system mechanism to allow telegraf to
use the port. You may also be able to have telegraf use an
unprivileged port and then configure a firewall port forward rule from
the privileged port.
To use a privileged port on Linux, you can use setcap to enable the
CAP_NET_BIND_SERVICE capability on the telegraf binary:
```
setcap cap_net_bind_service=+ep /usr/bin/telegraf
```
On Mac OS, listening on privileged ports is unrestricted on versions
10.14 and later.

View File

@ -50,7 +50,11 @@ var sampleConfig = `
## Transport, local address, and port to listen on. Transport must ## Transport, local address, and port to listen on. Transport must
## be "udp://". Omit local address to listen on all interfaces. ## be "udp://". Omit local address to listen on all interfaces.
## example: "udp://127.0.0.1:1234" ## example: "udp://127.0.0.1:1234"
# service_address = udp://:162 ##
## Special permissions may be required to listen on a port less than
## 1024. See README.md for details
##
# service_address = "udp://:162"
## Timeout running snmptranslate command ## Timeout running snmptranslate command
# timeout = "5s" # timeout = "5s"
` `