This documentation is available in 🇬🇧 English and 🇩🇪 German.
IPFire-API is an interface for IPFire that returns selected system, network, service, add-on, UPS, traffic, and internet connection information in JSON format. It also provides authenticated controls to bring the RED connection online or offline, start the installation of available updates remotely, and request a router reboot when IPFire reports that one is required.
The API was originally developed for the HA-IPFire Home Assistant integration and is now maintained as a separate project, so other integrations and clients can use it as well.
Installing additional software on a firewall always carries some risk, including this API. If you do not need the API, you should not install it.
- System, CPU, memory, disk, SMART, and
lm_sensorsinformation, plus network, service, UPS, and certificate data - Status information for supported add-ons
- Available IPFire core and package updates, with an authenticated action to start the Pakfire upgrade
- Authenticated router reboot action when IPFire reports that a reboot is required
- Create, list, download, and delete system and add-on backups remotely; start ISO backup creation
- RED traffic counters
- Internet connection state and details
- Connect and disconnect actions through IPFire's native
redctrl - JSON responses with API version and script revision fields
Copy cgi-bin/api.cgi to the IPFire web server's CGI directory:
/srv/web/ipfire/cgi-bin/api.cgi
Set the owner and executable permissions:
chown root:root /srv/web/ipfire/cgi-bin/api.cgi
chmod 755 /srv/web/ipfire/cgi-bin/api.cgiThe CGI uses IPFire's existing web interface authentication. No separate API credentials are configured by this script.
The endpoint is:
https://<ipfire-host>:444/cgi-bin/api.cgi
An authenticated GET request returns the current data as JSON. The response uses API version 1, reports the api.cgi script revision in api_revision, and includes system, network, dhcp, updates, services, ups, traffic, connection, and certificates sections. The api_version describes the JSON interface; api_revision is the script version from the file header. The addons section is included only when supported add-ons with services are installed. Unavailable measurements are returned as null where applicable; unavailable add-on and service states are reported as false. The backup directories are scanned only when the request includes ?backup=1; then the response also contains backups. The network section includes enabled DNS servers. Add ?dns=1 to include the complete DNS configuration and disabled servers.
All authenticated POST actions require the X-IPFire-API: 1 header. For compatibility with existing clients, the legacy X-HA-IPFire-API: 1 header is also accepted.
Connection actions use authenticated POST requests with a form body and the X-IPFire-API: 1 header.
The following example uses curl to establish the connection:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=connect' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'To disconnect, use action=disconnect instead. curl prompts for the WebGUI password. Replace the placeholders with the WebGUI username and IPFire host name. If IPFire uses a self-signed certificate, configure curl to trust that certificate, for example with --cacert /path/to/ipfire-certificate.pem.
The CGI invokes IPFire's native /usr/local/bin/redctrl command. A connect action starts or restarts the connection; disconnect stops it. Other methods, missing headers, and unsupported actions are rejected.
An authenticated POST request with the X-IPFire-API: 1 header can start the installation of all updates currently listed by Pakfire.
Example using curl:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=upgrade' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'The API starts the same non-interactive Pakfire upgrade used by the IPFire web interface. The request returns immediately with result: "accepted"; poll the updates.operation object in GET responses to see whether the run is running, completed, or failed. The API rejects the request if no updates are available or another API-started upgrade is running. This action installs the full update set; it does not install individual packages selectively. Only run this request when you are ready to install all updates currently listed by Pakfire.
The updates.operation object is included in every GET response. The following command prints the full JSON response; the operation status is in updates.operation:
curl --user '<webgui-user>' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'If jq is installed, you can filter the response to display only updates.operation. On Debian Trixie, jq is available in the package of the same name and can be installed with sudo apt install jq:
curl --user '<webgui-user>' \
'https://<ipfire-host>:444/cgi-bin/api.cgi' \
| jq '.updates.operation'An authenticated POST request with action=reboot asks IPFire to restart. The API accepts this action only while /var/run/need_reboot exists and uses IPFire's native /usr/local/bin/ipfirereboot helper. The router restarts shortly after the API returns result: "accepted"; the connection to Home Assistant will be interrupted until IPFire is available again.
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=reboot' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'The backups object is included only in an authenticated GET request ending in ?backup=1. This keeps routine API polling from scanning the backup directories. It contains a system array of full system backup files (.ipf) from /var/ipfire/backup, newest first. Each entry contains the filename, file size in bytes, and modification time as a Unix timestamp. If IPFire lists add-ons with backup support, addons_available contains their names, including add-ons that do not yet have a saved backup. If add-on backup files are present in /var/ipfire/backup/addons/backup, an addons array is also included with their file metadata and add-on name. Add-on backups contain configuration files, not the installed add-on packages. An empty system array means no system backups are available; null means the system backup directory could not be read. The operation object reports the most recent backup creation, deletion, or ISO creation started through the API. IPFire creates ISO images locally using its native backup method. The official IPFire backup documentation does not document HTTP/API access for listing or downloading generated ISO files. Use https://<ipfire-host>:444/cgi-bin/api.cgi?backup=1 to list backups or poll backups.operation.
To create a system backup, send an authenticated POST request with action=create_backup, type=system, and logs=include or logs=exclude. The API starts the task in the background and returns result: "accepted"; poll backups.operation from GET ...?backup=1 until its status is completed or failed. Including logs can take considerably longer. Example without logs:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=create_backup' \
--data-urlencode 'type=system' \
--data-urlencode 'logs=exclude' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'To create an add-on configuration backup, use type=addon and the add-on package name:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=create_backup' \
--data-urlencode 'type=addon' \
--data-urlencode 'addon=wio' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'To create a remastered installer ISO containing the current system backup, use type=iso. IPFire downloads its base installer image when needed, so this can take a long time and requires an internet connection and sufficient free disk space. Poll backups.operation through GET ...?backup=1; the operation remains running until the ISO creation process finishes:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=create_backup' \
--data-urlencode 'type=iso' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'To download a listed backup, send an authenticated POST request with action=download_backup, its type (system or addon), and the exact filename. The response is the file itself, so use curl --output to save it:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=download_backup' \
--data-urlencode 'type=system' \
--data-urlencode 'filename=2026-11-12-1200.ipf' \
--output '2026-11-12-1200.ipf' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'To delete a listed backup, send an authenticated POST request with action=delete_backup, its type (system or addon), and the exact filename. A successful request returns JSON with result: "ok"; backups.operation then reports the completed deletion, including its type and filename. Deletion is permanent; verify the type and filename before sending the request:
curl --user '<webgui-user>' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=delete_backup' \
--data-urlencode 'type=system' \
--data-urlencode 'filename=2026-11-08-1724.ipf' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'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 |
Whether the system is virtualized |
core_update |
Whether an IPFire core update is available |
package_updates |
Number of available package updates |
reboot_required |
Whether IPFire has marked a reboot as required after an update |
uptime |
System uptime in seconds |
| Parameter | Description |
|---|---|
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 |
Root filesystem space information 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 |
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. The result is cached for one hour so the disk is not queried on every API request. After the cache expires, the next API request refreshes the data; there is no background refresh, so the values remain unchanged until another request is made.
| 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 |
When /usr/bin/sensors is available and sensors -j returns valid, non-empty JSON, the system.sensors object contains its readings. Chip names, adapter names, measurement labels, and available fields depend on the hardware and drivers. The API preserves the field names and values reported by sensors -j; the *_input values are current readings, while fields such as *_max, *_crit, and *_crit_alarm are included when the driver provides them. The sensors field is omitted when the command is unavailable or returns no usable data.
The network section reports configured IPFire network zones and information about their assigned devices. Zone booleans indicate whether the zone is present in IPFire's hardware profile; they do not indicate the current physical link state.
| Parameter | Description |
|---|---|
blue |
Whether the BLUE zone is present in the hardware profile |
green |
Whether the GREEN zone is present in the hardware profile |
orange |
Whether the ORANGE zone is present in the hardware profile |
red |
Whether the RED zone is present in the hardware profile |
Values are boolean:
true– the zone is presentfalse– the zone is not present
The interfaces object contains data for each configured zone, read from IPFire's interface settings, the Linux interface counters, and ethtool:
| Parameter | Description |
|---|---|
device |
Linux network device assigned to the zone |
rx_bytes |
Cumulative number of bytes received by the interface |
tx_bytes |
Cumulative number of bytes transmitted by the interface |
driver |
Network driver name |
driver_version |
Driver version reported by ethtool |
firmware_version |
Firmware version reported by ethtool |
supported_link_modes |
Link modes supported by the device and driver |
max_supported_speed_mbps |
Highest speed found in the supported link modes |
advertised_link_modes |
Link modes currently advertised for autonegotiation |
link_partner_advertised_link_modes |
Link modes advertised by the connected partner, if reported |
supports_auto_negotiation |
Whether the device supports autonegotiation |
auto_negotiation |
Whether autonegotiation is currently enabled |
speed_mbps |
Currently negotiated link speed in Mbps |
duplex |
Currently negotiated duplex mode |
link_detected |
Whether a physical link is detected |
rx_bytes and tx_bytes are cumulative counters read from /sys/class/net/<device>/statistics/; clients can calculate rates by comparing successive readings. An interface entry is null when no assigned device is present. If the device exists but has no physical link, its supported and advertised modes may still be available while speed_mbps and duplex are null.
The optional network.hosts array reads static host mappings from IPFire's /var/ipfire/main/hosts file. It also includes disabled entries, whose enabled value is false. Dynamic DHCP leases remain separate under dhcp.leases. If the file cannot be read, hosts is omitted; a readable but empty file produces an empty array.
| Field | Description |
|---|---|
enabled |
Whether IPFire uses the entry |
ip_address |
Mapped IP address |
hostname |
Hostname |
domain |
Configured domain, when present |
fqdn |
Hostname with its domain, when present |
ptr_enabled |
Whether IPFire should generate a PTR record |
network.dns.enabled_servers contains the enabled DNS servers IPFire is allowed to use. These are configured resolver candidates; Unbound may choose among them based on reachability and response time. Each entry contains id, address, source (manual or isp), and enabled.
With ?dns=1, network.dns also contains configured_servers, including all manual entries and ISP-assigned servers, and settings with use_isp_nameservers, protocol, enable_safe_search, and enable_safe_search_youtube. ISP-assigned server addresses are read from /var/run/dns1 and /var/run/dns2. The extended DNS data is only collected when this parameter is present.
DNS settings can only be changed through authenticated POST requests; ?dns=1 is not required for these actions. dns_check_servers explicitly checks enabled resolver candidates for a DNS answer to ping.ipfire.org; this check is never run during a normal GET. Supported actions and form fields:
| Action | Required fields | Optional fields |
|---|---|---|
dns_check_servers |
– | – |
dns_add_server |
address |
tls_hostname, remark |
dns_edit_server |
id, address |
tls_hostname, remark |
dns_toggle_server |
id, enabled (true or false) |
– |
dns_delete_server |
id |
– |
dns_save_settings |
protocol (UDP, TCP, or TLS), use_isp_nameservers, enable_safe_search, enable_safe_search_youtube (each true or false) |
– |
Manual server IDs start at 3; ISP-assigned servers cannot be edited or deleted. Server addresses must be valid IP addresses. With the TLS protocol, every enabled manual server must have a TLS hostname; ISP DNS combined with TLS is rejected. After a change, the API schedules a DNS configuration reload as the IPFire web interface does. Its response confirms that the reload was scheduled, not that every DNS server is reachable.
Run the explicit DNS check with POST; the response reports working or failed for each enabled resolver:
curl --user 'root' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=dns_check_servers' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'Example for adding an enabled server:
curl --user 'root' \
--header 'X-IPFire-API: 1' \
--data-urlencode 'action=dns_add_server' \
--data-urlencode 'address=9.9.9.9' \
--data-urlencode 'tls_hostname=dns.quad9.net' \
--data-urlencode 'remark=Quad9' \
'https://<ipfire-host>:444/cgi-bin/api.cgi'The optional vlans array lists VLANs configured through IPFire's zone configuration. It is omitted when no VLANs are configured. Each entry contains:
| Parameter | Description |
|---|---|
zone |
IPFire zone using the VLAN |
vlan_id |
Configured VLAN identifier |
parent_device |
Parent network device, if it can be matched to the configured parent MAC address |
parent_mac_address |
Parent MAC address recorded by IPFire |
zone_device |
Network device assigned to the zone |
zone_interface_present |
Whether the zone device currently exists in Linux |
mac_address |
MAC address configured for the VLAN interface |
The API reads this information from IPFire's /var/ipfire/ethernet/vlans settings file. VLANs created outside IPFire's zone configuration are not listed here.
The neighbors array mirrors IPFire's ip neigh show output and includes address, device, link-layer address (when available), and neighbor state.
The routes array contains the main routing table. If IPFire has entries in routing table 220, they are included in the optional ipsec_routes array; this field is omitted when that table is empty.
The dhcp.leases array is read from /var/state/dhcp/dhcpd.leases, the lease database used by IPFire's web interface. It includes the latest record for each IP address, including expired leases, with its IP address, MAC address, hostname, expiry time, and active or expired status. A lease with no expiry is marked with expires_never: true. If the lease file cannot be read, dhcp.leases is null. The DHCP server's running state remains available under services.dhcp.
The services section provides the current status of 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 |
Values are boolean:
true– the service is runningfalse– the service is not running
The addons section is included only when supported IPFire add-ons with services are installed. It provides their current status. If no such add-ons are installed, the section is omitted entirely. This section is intended to grow as add-on integrations are added. Contributions should document the add-on, its status source, and any IPFire version assumptions. For example, an add-on status is represented as:
| Parameter | Description |
|---|---|
transmission.running |
Whether the Transmission add-on is running |
Values are boolean: true means the add-on is running; false means it is not running. Transmission is an example; the section can provide status information for other supported add-ons.
The ups.apcupsd object is included only when the optional IPFire apcupsd add-on is installed. It reports data using the add-on's apcaccess status command. If the command cannot return a status report, status is unavailable and measurements are null.
| Parameter | Description |
|---|---|
status |
UPS state reported by apcupsd, such as ONLINE, ONBATT, or COMMLOST |
battery_charge_percent |
Battery charge in percent (BCHARGE) |
runtime_minutes |
Estimated remaining runtime in minutes (TIMELEFT) |
load_percent |
Current UPS load in percent (LOADPCT) |
model |
UPS model reported by apcupsd |
ups_name |
Configured UPS name |
The values depend on the UPS and driver and have not been verified against every supported device.
The certificates section reports the certificate Apache presents for the IPFire web interface on port 444, and OpenVPN client certificates recorded by IPFire. The API reads Apache's certificate over the local TLS connection, so the reported expiry reflects the active certificate, including certificates managed by external tools such as ACME clients. OpenVPN client entries are read from IPFire's certificate database; the OpenVPN server certificate is excluded from that list.
| Parameter | Description |
|---|---|
apache.status |
valid, expired, or unavailable |
apache.subject |
Certificate subject |
apache.issuer |
Certificate issuer |
apache.not_before |
Start of validity, as reported by OpenSSL |
apache.not_after |
Expiry date in UTC using ISO 8601 format |
apache.remaining.years |
Whole calendar years remaining |
apache.remaining.months |
Additional whole calendar months remaining |
apache.remaining.days |
Additional calendar days remaining |
apache.remaining_days |
Total whole days remaining |
If Apache's certificate cannot be read, status is unavailable and certificate details are null. When the certificate has expired, the remaining counters are zero.
OpenVPN client certificates are returned as an array under openvpn.clients. Each entry includes:
| Parameter | Description |
|---|---|
common_name |
Certificate common name |
serial |
Certificate serial number |
status |
valid, expired, revoked, or unknown |
not_after |
Expiry date in UTC using ISO 8601 format |
remaining.years |
Whole calendar years remaining |
remaining.months |
Additional whole calendar months remaining |
remaining.days |
Additional calendar days remaining |
remaining_days |
Total whole days remaining |
An empty array means that no OpenVPN client certificates are present. If the OpenVPN certificate database or server certificate cannot be read, openvpn.clients is null.
The system section provides the existing update summary. The updates section lists the individual core and package updates and reports the status of an API-started upgrade. The list uses the local Pakfire package metadata; refresh the package lists in IPFire's Pakfire page first if they may be out of date. The API does not refresh them as part of a GET request.
| Parameter | Description |
|---|---|
core_update |
Whether an IPFire core update is available |
package_updates |
Number of available package updates |
reboot_required |
Whether IPFire has marked a reboot as required after an update |
core_update and reboot_required are boolean. package_updates is the number of available package updates. reboot_required reflects whether /var/run/need_reboot exists.
updates.available is an array of pending updates, built from Pakfire's local core list, package list, and installed package metadata. Core entries contain type, name, version, installed_release, and available_release. Package entries contain type, name, installed_version, available_version, installed_release, and available_release. It is an empty array when no updates are pending and null if the required local Pakfire data cannot be read or parsed. The API does not refresh these lists during a GET request.
updates.operation contains status, started_at, finished_at, exit_code, and, when relevant, error. The timestamps are Unix timestamps in seconds. The status is idle before an API-started upgrade, running during it, then completed or failed. Temporary operation state and the update log are kept under /tmp/ipfire-api and are cleared when IPFire reboots.
Keep this endpoint behind IPFire's authenticated web interface. Do not expose it to untrusted networks. System and add-on backups and remastered installer ISOs contain sensitive configuration data; protect downloaded files accordingly. Backup deletion is permanent. POST requests can change the internet connection state, install IPFire updates, create, download, or delete backups, or reboot the router when required.
If you find IPFire-API useful, you can support its ongoing development on Ko-fi:
IPFire-API is licensed under the GNU General Public License version 3 only. See LICENSE.