Home Assistant integration for monitoring IPFire system information, network status, traffic statistics, and internet connection control.
This documentation is also available in 🇩🇪 German.
- What’s New in This Version
- Features
- IPFire
- IPFire API
- Sensors
- Internet connection control
- Polling interval
- SSL certificates
- Authentication
- Installation
- Configuration
- IPFire data
- Device
- Connection control
- Home Assistant
- Support
- Repository
- License
- Added system information sensors for IPFire version, Pakfire version, kernel version, architecture, CPU model, CPU count, model and vendor.
- Added CPU usage, CPU total and CPU idle sensors.
- Added memory sensors for total, available, free, buffers and cached memory.
- Added disk space sensors for total, used, available space and disk usage.
- Added disk temperature and SMART error sensors.
- Added IPFire uptime sensor.
- Added package update information.
- Added improved icon handling for sensors and network interfaces.
- Network interface icons now dynamically indicate whether an interface is connected or disconnected.
HA-IPFire provides the following features:
- Download traffic counter
- Upload traffic counter
- Current download speed
- Current upload speed
- Internet connection state
- Internet connection duration
- Connect and Disconnect controls
- Configurable polling interval
- Polling interval from 5 to 60 seconds
- Optional SSL certificate verification
- Username/password authentication
- HACS compatible
- German and English translations
The integration retrieves traffic information from the IPFire endpoint:
/cgi-bin/speed.cgi
The default URL is:
https://ipfire.local:444
The hostname or IP address can be changed during configuration.
HA-IPFire uses the cumulative traffic counters provided by IPFire to calculate the current transfer rates.
The optional api.cgi script provides additional information and control functions that are not available through speed.cgi.
The api.cgi script allows HA-IPFire to control the IPFire internet connection directly from Home Assistant.
The following actions are available:
- Connect – establishes the internet connection.
- Disconnect – disconnects the internet connection.
If Connect is pressed while a connection is already active, the current connection is disconnected and re-established.
The connection control uses the native IPFire connection handling provided by the api.cgi script.
The system section provides the following information:
| Parameter | Description |
|---|---|
version |
IPFire version |
pakfire_version |
Pakfire version |
kernel_version |
Linux kernel version |
architecture |
System architecture |
cpu_model |
CPU model |
cpu_count |
Number of CPU cores |
model |
System model |
vendor |
System vendor |
virtual |
Indicates whether the system is virtualized |
core_update |
Indicates whether a core update is available |
package_updates |
Number of available package updates |
uptime |
System uptime in seconds |
| Parameter | Description |
|---|---|
total |
Total accumulated CPU time |
idle |
Accumulated CPU idle time |
| Parameter | Description |
|---|---|
total |
Total physical memory in bytes |
available |
Available memory in bytes |
free |
Free memory in bytes |
buffers |
Memory used for buffers in bytes |
cached |
Memory used for cache in bytes |
Disk space information for the root filesystem is provided under disk.root.
| Parameter | Description |
|---|---|
total |
Total disk space in bytes |
used |
Used disk space in bytes |
available |
Available disk space in bytes |
use_percent |
Disk usage in percent |
Disk I/O statistics for the sda device are provided under disk.sda.
| Parameter | Description |
|---|---|
reads |
Number of completed read operations |
sectors_read |
Number of sectors read |
writes |
Number of completed write operations |
sectors_written |
Number of sectors written |
io_in_progress |
Number of I/O operations currently in progress |
io_time |
Time spent performing I/O operations |
SMART information is provided for the system disk.
| Parameter | Description |
|---|---|
power_on_hours |
Disk power-on hours |
remaining_lifetime |
Remaining disk lifetime in percent |
health |
SMART health status |
errors |
SMART error count |
uncorrectable_errors |
Number of uncorrectable errors |
power_cycles |
Number of power cycles |
temperature |
Disk temperature |
The network section provides the current state of the IPFire network interfaces.
| Parameter | Description |
|---|---|
blue |
State of the BLUE network interface |
green |
State of the GREEN network interface |
orange |
State of the ORANGE network interface |
red |
State of the RED network interface |
The values are boolean:
true– the interface is activefalse– the interface is inactive
The services section provides the current status of the services managed by IPFire.
| Parameter | Description |
|---|---|
dhcp |
DHCP server status |
web_server |
IPFire web server status |
cron |
Cron service status |
dns_resolver |
DNS resolver status |
logging |
Logging service status |
ntp |
NTP service status |
ssh |
SSH service status |
vpn |
VPN service status |
web_proxy |
Web proxy status |
ips |
Intrusion Prevention System (IPS) status |
ovpn_roadwarrior |
OpenVPN Roadwarrior status |
lldp |
LLDP service status |
dbus |
D-Bus service status |
The values are boolean:
true– the service is runningfalse– the service is not running
The addons section provides the current status of supported IPFire add-ons.
The following example shows how an add-on status is represented:
| Parameter | Description |
|---|---|
transmission.running |
Indicates whether the Transmission add-on is running |
The value is boolean:
true– the add-on is runningfalse– the add-on is not running
Transmission is used here as an example. The addons section can provide status information for other supported add-ons as well.
The system section provides information about available IPFire updates.
| Parameter | Description |
|---|---|
core_update |
Indicates whether an IPFire core update is available |
package_updates |
Number of available package updates |
The core_update value is boolean:
true– a core update is availablefalse– no core update is available
package_updates contains the number of available package updates.
The CGI script is included in this repository at:
ipfire/api.cgi
The CGI must be installed manually on the IPFire firewall. HACS installs only the Home Assistant integration and cannot copy files to the separate IPFire system.
Copy the CGI to:
/srv/web/ipfire/cgi-bin/api.cgi
Then set the correct ownership and permissions:
chown root:root /srv/web/ipfire/cgi-bin/api.cgi
chmod 755 /srv/web/ipfire/cgi-bin/api.cgiThe CGI uses the existing IPFire web interface authentication. No additional CGI credentials are required.
Security: The CGI should only be accessible through the trusted IPFire web interface and must not be exposed to untrusted networks.
The integration provides the following sensors:
- Download – cumulative download traffic in bytes.
- Upload – cumulative upload traffic in bytes.
- Download Speed – current download speed.
- Upload Speed – current upload speed.
The following sensors and functions require api.cgi to be installed on the IPFire firewall.
- Connection Duration – duration of the current internet connection.
- Connection State – current IPFire connection state.
- Connected Since – time when the current connection was established.
- External IP – current external IP address.
- External Hostname – current external hostname.
- IPFire Version
- Pakfire Version
- Kernel Version
- Architecture
- CPU Model
- CPU Count
- Model
- Vendor
- Uptime
- Package Updates
- CPU Usage
- CPU Total
- CPU Idle
- Memory Total
- Memory Available
- Memory Free
- Memory Buffers
- Memory Cached
- Disk Total
- Disk Used
- Disk Available
- Disk Usage
- Disk Temperature
- SMART Errors
HA-IPFire provides two buttons to control the IPFire internet connection:
- Connect starts the IPFire internet connection.
- Disconnect stops the IPFire internet connection.
The buttons use the dedicated api.cgi endpoint on the IPFire firewall. The CGI uses IPFire's native connection control and authentication.
Note
The function requires api.cgi to be installed on the IPFire firewall.
The polling interval can be configured between:
- Minimum: 5 seconds
- Default: 30 seconds
- Maximum: 60 seconds
The interval can be adjusted in steps of 5 seconds using the slider in the configuration.
A shorter interval provides more frequent updates but also results in more requests to the IPFire firewall.
SSL certificate verification can be enabled or disabled during configuration.
Because IPFire installations commonly use self-signed certificates, certificate verification is disabled by default.
If your IPFire installation uses a certificate signed by a trusted certificate authority, SSL verification can be enabled.
The IPFire speed.cgi endpoint requires authentication.
HA-IPFire therefore supports:
- Username
- Password
The credentials are configured when adding the integration to Home Assistant.
Directly via this button:
HA-IPFire can be installed directly through HACS.
- Open HACS.
- Select Integrations.
- Search for
HA-IPFire. - Install the integration.
- Restart Home Assistant.
If HA-IPFire is not available in the standard HACS search, the repository can alternatively be added as a custom repository:
https://github.com/FMainz/HA-IPFire
Select Integration as the repository type.
After installation, add the integration through:
Settings → Devices & services → Add integration
Search for:
HA-IPFire
Copy the following directory:
custom_components/ipfire
into:
config/custom_components/ipfire
Restart Home Assistant and add IPFire through:
Settings → Devices & services → Add integration
During setup, HA-IPFire asks for the following information:
- IPFire URL – the hostname or IP address of the IPFire firewall.
- Username – the IPFire web interface username.
- Password – the corresponding IPFire password.
- SSL certificate verification – enables or disables SSL certificate verification.
- Polling interval – determines how often HA-IPFire requests updated data from IPFire.
The default IPFire URL is:
https://ipfire.local:444
HA-IPFire automatically uses the following endpoints:
/cgi-bin/speed.cgi
for traffic data and
/cgi-bin/api.cgi
for additional system information, network and service status, update information, and internet connection control. The polling interval can be configured between 5 and 60 seconds.
The data is read directly from IPFire. Traffic statistics are provided by
speed.cgi. Additional system, network, service, and update information is
provided through the optional api.cgi.
HA-IPFire creates a single device for the IPFire firewall in Home Assistant.
All sensors and controls provided by the integration are grouped under this device.
HA-IPFire can control the Internet connection of the IPFire firewall directly from Home Assistant.
The following actions are available through the provided buttons:
- Connect – establishes the Internet connection.
- Disconnect – disconnects the Internet connection.
If Connect is pressed while a connection is already active, the current connection is disconnected and re-established.
HA-IPFire uses Home Assistant's native sensor classes, units, and statistics support.
Traffic counters are provided as cumulative, increasing values, allowing Home Assistant to use them for statistics and history.
Current transfer rates are calculated from the traffic counters and are provided as data rates.
If you encounter a problem or have a suggestion, please open an issue in the GitHub repository:
https://github.com/FMainz/HA-IPFire/issues
https://github.com/FMainz/HA-IPFire
HA-IPFire is released under the MIT License.