Skip to content
FMainzPublic

About

A Home Assistant integration for IPFire.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

96 Commits

Folders and files

Repository files navigation

marketplace_badge GitHub release last commit License: MIT Package downloads stars

HA-IPFire

This documentation is available in 🇬🇧 English and 🇩🇪 German.

Home Assistant integration for monitoring IPFire system information, network status, traffic statistics, and internet connection control.

Contents


What’s New in This Version

v0.3.7

  • Added a privacy-conscious diagnostic report with integration and connection status, API data availability, update status, entity counts, UTC timestamps and sanitized error details. Button entities in their normal unknown state are excluded from the unavailable/unknown count; the report omits credentials, IP addresses, hostnames and DHCP client details. API revision is included when supported by IPFire-API v0.2.1 or later.
  • Added the network-card vendor (mac_vendor) to DHCP lease attributes, looked up locally from the lease MAC address.
  • Added a native Home Assistant update entity that shows available IPFire core and package updates and can start the full Pakfire upgrade.
  • Added update-operation status reporting and a native Home Assistant update action for starting a required IPFire reboot. These update and reboot features require a compatible api.cgi; reboot requires IPFire-API v0.2.5 or later.
  • Updated the aiooui dependency requirement to accept compatible versions from 0.1.9 onward.

v0.3.6

  • Added DHCP lease count and client details as sensor attributes (requires api.cgi).
  • Added cumulative traffic counters for the GREEN, ORANGE, and BLUE interfaces (requires api.cgi).
  • Added a reboot-required sensor and a combined count of available core and package updates (requires api.cgi).

v0.3.5

  • Development of the IPFire CGI api.cgi continues in the standalone IPFire-API repository.

v0.3.4

  • Fixed and enabled the download counter.

v0.3.3

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

Features

HA-IPFire provides the following features:

  • RED download traffic counter
  • RED 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
  • DHCP lease sensor with client details¹
  • Traffic counters for individual network zones¹
  • Reboot-required status and total available update count¹
  • Review available IPFire updates and install the full Pakfire upgrade from Home Assistant¹
  • Confirm and start a required IPFire reboot through Home Assistant's native Updates interface¹
  • Generate a privacy-conscious diagnostic report in Home Assistant notifications

¹Requires api.cgi from IPFire-API.

IPFire

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.

IPFire API

The optional api.cgi script extends speed.cgi with system information and connection control. It is developed separately in the IPFire-API project.

Additional information

In addition to connection status and controls, the API provides information such as:

  • IPFire, Pakfire, and kernel versions, plus system vendor, model, and architecture
  • CPU model and number of cores
  • Memory and disk usage, including I/O statistics and SMART status
  • Network interface states and per-zone traffic counters, plus IPFire service states
  • Active DHCP leases and their client details
  • Installed add-ons and their status
  • Core and package update status, plus whether a reboot is required

For a complete description of the JSON fields, see the IPFire-API documentation.

Connection control

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.

IPFire CGI installation

The CGI is maintained in the standalone IPFire-API project. Follow its installation instructions to set it up on your 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.cgi

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

Sensors

The integration provides the following sensors:

Traffic

  • Red Traffic Received – cumulative received bytes on the RED interface.
  • Red Traffic Sent – cumulative sent bytes on the RED interface.
  • Download Speed – current download speed.
  • Upload Speed – current upload speed.

The following additional sensors and functions require api.cgi to be installed on the IPFire firewall.

Internal network traffic

  • Green Traffic Received/Sent – cumulative received and sent bytes on the GREEN interface.
  • Orange Traffic Received/Sent – cumulative received and sent bytes on the ORANGE interface.
  • Blue Traffic Received/Sent – cumulative received and sent bytes on the BLUE interface.

Sensors are created only for internal interfaces configured on the IPFire firewall.

DHCP leases

  • Active DHCP Leases – number of active DHCP leases. The leases attribute contains the client records reported by IPFire, including IP address, MAC address, hostname, expiry, and status. HA-IPFire also adds mac_vendor, looked up locally from the MAC address prefix. This may be unavailable or inaccurate for private or unregistered MAC addresses. To view the lease details, open the sensor's more-info panel in Home Assistant and inspect its attributes.

System status

  • Reboot Required – indicates when IPFire requires a reboot after an update. Requires a current version of api.cgi; older versions leave the sensor unknown.
  • Updates Available – total number of available updates, including core and package updates. Its updates attribute lists the exact core/package updates and versions.
  • IPFire System Updates – native Home Assistant update entity. It appears in Home Assistant's Updates section when updates are available; its release summary lists the included core and package updates. Installing it starts the full Pakfire upgrade, because IPFire does not support selecting individual updates.
  • Update Operation – reports whether an API-started update is idle, running, completed, or failed.
  • Restart router – appears as a native Home Assistant update action when api.cgi revision 0.2.5 or newer reports that a reboot is required. Start the router reboot from the Updates interface after confirmation.

Internet connection

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

System

  • IPFire Version
  • Pakfire Version
  • Kernel Version
  • Architecture
  • CPU Model
  • CPU Count
  • Model
  • Vendor
  • Uptime

CPU

  • CPU Usage
  • CPU Total
  • CPU Idle

Memory

  • Memory Total
  • Memory Available
  • Memory Free
  • Memory Buffers
  • Memory Cached

Disk

  • Disk Total
  • Disk Used
  • Disk Available
  • Disk Usage

SMART

  • Disk Temperature
  • SMART Errors

Internet connection control

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.

Polling interval

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 certificates

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.

Authentication

The IPFire speed.cgi endpoint requires authentication.

HA-IPFire therefore supports:

  • Username
  • Password

The credentials are configured when adding the integration to Home Assistant.

Installation

Directly via this button:

Open HA-IPFire in HACS

HACS

HA-IPFire can be installed directly through HACS.

  1. Open HACS.
  2. Select Integrations.
  3. Search for HA-IPFire.
  4. Install the integration.
  5. 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

Manual installation

Copy the following directory:

custom_components/ipfire

into:

config/custom_components/ipfire

Restart Home Assistant and add IPFire through:

Settings → Devices & services → Add integration

Configuration

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.

IPFire data

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.

Device

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.

Connection control

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.

Home Assistant

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.

Support

If you encounter a problem, press Error Report in the device's Diagnostics section. The generated notification contains a copyable report with integration and Home Assistant versions, the configured scan interval, enabled and disabled entity counts, counts of enabled entities in unavailable or unknown state (the normal unknown state of buttons is excluded), UTC timestamps for the last successful update and last error (to the second), a sanitized last error, the DHCP lease count, API feature availability, and update status. The API revision is included starting with IPFire-API v0.2.1. Review the report before sharing; it excludes credentials, IP addresses, hostnames, and DHCP client details.

You can also open an issue or suggest an improvement in the GitHub repository:

https://github.com/FMainz/HA-IPFire/issues

If you find HA-IPFire useful, you can support its ongoing development on Ko-fi:

Support FMainz on Ko-fi

Repository

https://github.com/FMainz/HA-IPFire

License

HA-IPFire is released under the MIT License.


About

A Home Assistant integration for IPFire.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages