A python 3 program to send pfSense information collected from FauxAPI to InfluxDB
PythonMIT
pfSense-to-InfluxDB
This program is built to collect information from pfSense and send it to InfluxDB. The eventual goal in creating this program was to provide pfSense metrics and alerts to Grafana. The program uses FauxAPI to call the native PHP functions pfSense uses to create widgets on its dashboard.
Note: pfSense-to-InfluxDB is not intended to be installed on pfSense since pfSense doesn't ship with python3 installed. Installing on your InfluxDB host or another host is recommended.
Installation
Install and configure FauxAPI on your pfSense router. Remember to add a new user to /etc/fauxapi/credentials.ini with permissions: config_get, function_call
Then add the following lines to /etc/fauxapi/pfsense_function_calls.txt:
git clone https://github.com/ArmaanT/pfsense-to-influxdb.git --branch 1.2.0
cd pfsense-to-influxdb
Or download directly:
wget -O pfsense-to-influxdb.tar.gz "https://github.com/ArmaanT/pfsense-to-influxdb/archive/1.2.0.tar.gz"
tar -xf pfsense-to-influxdb.tar.gz
mv pfsense-to-influxdb-* pfsense-to-influxdb
rm pfsense-to-influxdb.tar.gz
cd pfsense-to-influxdb
Install requirements:
pip3 install -r requirements.txt
Docker
pfSense-to-InfluxDB is also published on Docker Hub and can be run using the following command with a custom settings file:
docker run -v settings.conf:/app/config/settings.conf armaant/pfsense-to-influxdb:1.2.0
Configuration
Rename settings.sample.conf to settings.conf and add your desired settings:
General
Key
Description
Delay
Time (in seconds) between updates sent to InfluxDB
FauxAPI
Key
Description
APIHost
IP Address or FQDN of pfSense Router
APIKey
API Key created in /etc/fauxapi/credentials.ini
APISecret
API Secret created in /etc/fauxapi/credentials.ini
InfluxDB
Key
Description
InfluxDBHost
IP Address or FQDN of InfluxDB Host
Port
InfluxDB port. Normally 8086
Username
InfluxDB Username
Password
InfluxDB Password
Database
InfluxDB Database
Modules
Key
Description
Gateway_Status
Enable metric gathering on gateway statuses (true/false)
Interface_Statistics
Enable metric gathering on interface statistics (true/false)
Interface_Status
Enable metric gathering on interface statuses (true/false)
OpenVPN_Client_Status
Enable metric gathering on pfSense OpenVPN clients (true/false)
OpenVPN_Connected_Clients
Enable metric gathering on clients connected to pfSense OpenVPN servers (true/false)
Services_Status
Enable metric gathering on service statuses (true/false)
Start at boot
A sample systemd service file, pfsense_influx_collector.service, is included to automatically run pfSense-to-InfluxDB on boot. Open the file to change the following lines to reflect your user and path to pfSenseInfluxCollector.py:
A sample pfsense_dashboard.json is provided. First, add your pfsense InfluxDB database as a Grafana Data Source. Then to import the dashboard: hover over the create dashboard button (the plus sign) in Grafana, click "Import" and upload the dashboard.json file or paste the contents of the file in the text box and click "Load".
Updating
Using git:
cd /path/to/pfsense-to-influxdb
git pull origin 1.2.0
Downloading directly
cd /tmp/
wget -O pfsense-to-influxdb.tar.gz "https://github.com/ArmaanT/pfsense-to-influxdb/archive/1.2.0.tar.gz"
tar -xf pfsense-to-influxdb.tar.gz
mv pfsense-to-influxdb-*/* /path/to/previously-installed/pfsense-to-influxdb/
rm pfsense-to-influxdb.tar.gz
rm -r pfsense-to-influxdb-*
InfluxDB Schema
Measurement: gateway_status
Field
Description
name
Name of gateway
rtt
Round-trip time
rttsd
Standard deviation of RTT
status
Status of gateway (1 for online, 0 for other statuses)
Tag
Description
host
pfSense hostname with domain
Measurement: interface_statistics
Field
Description
bytes_in
Number of bytes in
bytes_out
Number of bytes out
collisions
Number of collisions
errors_in
Number of errors in
errors_out
Number of errors out
name
Name of gateway
packets_in
Number of packets in
packets_out
Number of packets out
Tag
Description
host
pfSense hostname with domain
interface
Interface being polled
Measurement: interface_status
Field
Description
ip_address
IP address of interface
name
Name of interface
status
Status of interface (1 for online, 0 for offline)
Tag
Description
host
pfSense hostname with domain
interface
Interface being polled
Measurement: openvpn_client_status
Field
Description
remote_host
Remote IP address of OpenVPN client
status
Status of OpenVPN client (1 for online, 0 for offline)
virtual_address
Virtual IP address of OpenVPN client
Tag
Description
host
pfSense hostname with domain
vpnid
ID of OpenVPN Client
Measurement: openvpn_connected_clients
Field
Description
client_id
Client ID of connection
common_name
Name connected user
connected_clients
Number of connected clients
remote_host
Remote IP address of user
virtual_address
Virtual IP address of user
Tag
Description
host
pfSense hostname with domain
server
pfSense OpenVPN Server client is connected to
Measurement: services_status
Field
Description
description
Description of service
status
Status of service (1 for online, 0 for offline)
Tag
Description
host
pfSense hostname with domain
service
Service being polled
License
Licensed under the terms of the MIT license. See LICENSE.md