Skip to content

Latest commit

 

History

History
511 lines (382 loc) · 27.6 KB

README.md

File metadata and controls

511 lines (382 loc) · 27.6 KB

GitHub release last commit License: GPL-3.0-only API downloads stars

IPFire-API

IPFire-API logo

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.

Contents

Features

  • System, CPU, memory, disk, SMART, and lm_sensors information, 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

Installation

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

The CGI uses IPFire's existing web interface authentication. No separate API credentials are configured by this script.

Endpoint

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 control

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.

Update installation

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'

Reboot

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'

Backup management

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'

System parameters

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

CPU

Parameter Description
total Accumulated CPU time
idle Accumulated CPU idle time

Memory

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

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

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

lm_sensors

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.

Network

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 present
  • false – 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.

Hosts file

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

DNS servers

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'

VLANs

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.

Neighbors

The neighbors array mirrors IPFire's ip neigh show output and includes address, device, link-layer address (when available), and neighbor state.

Routes

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.

DHCP leases

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.

Services

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 running
  • false – the service is not running

Add-ons

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.

UPS

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.

Certificates

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.

Updates

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.

Security

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.

Support

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

Support FMainz on Ko-fi

License

IPFire-API is licensed under the GNU General Public License version 3 only. See LICENSE.