freebox-exporter-rs

Yet another Freebox API exporter for Prometheus! This project is actually in work in progress. New contributors are welcome!

Important

Disclaimer: This project is unofficial and is not affiliated in any way with Free S.A.S. ISP nor Iliad Group

Grafana board

You will find on Grafana gallery the board for the exporter, also source file is located here

Features

• Adaptive Freebox metrics exposition (detects network mode, see: related issue)
• Metrics caching & background update
• Customizable data directory
• Customizable metrics prefix
• Customizable log files retention
• Compressed log files
• Customizable/CLI overridable log verbosity
• CLI overridable configuration file path
• Freebox API certificate validation
• Configurable handling of WiFi stations with unresolved hostnames

API Implementation

• ➖ Authentication
  • ✅ Register: 100%
  • ✅ Login: 100%
• ➖ Configuration
  • ➖ Connection
    • ✅ Status: 100%
    • ✅ Configuration: 100%
    • ✅ Configuration IPV6: 100%
    • ✅ xDSL: 100%
    • ✅ FTTH: 100%
    • ❌ DynDNS: 0%
  • ✅ Lan: 100%
  • ✅ Lan Browser: 100%
  • ❌ Freeplug: 0%
  • ✅ DHCP: 100%
  • ✅ Switch: 100%
  • ✅ Wi-Fi: 100%%
  • ✅ System: 100%
  • ❌ VPN Server: 0%
  • ❌ VPN Client: 0%

Enhancements

You can suggest your ideas in discussion section

Usage

You will find usage by using the following command freebox-exporter-rs -h

Usage: freebox-exporter-rs [OPTIONS] <COMMAND>

Commands:
  auto                starts the application and registers it if necessary
  register            registers the application
  serve               starts the application
  session-diagnostic  runs a diagnostic on the session
  revoke              
  help                Print this message or the help of the given subcommand(s)

Options:
  -c, --configuration-file <CONFIGURATION_FILE>  
  -v, --verbosity <VERBOSITY>                    
  -h, --help                                     Print help
  -V, --version                                  Print version

WiFi Station Hostname Resolution

The exporter handles WiFi stations that may have incomplete hostname/IP information from the Freebox API. This can occur when:

• Station is connected at Layer 2 but has no Layer 3 connectivity
• DHCP lease has expired
• Device is in sleep mode
• Host information is temporarily unavailable

You can control how these stations are handled via the [policies] section in your configuration:

Policy Options

ignore (recommended)

• Skips stations without complete host information
• Prevents potential crashes and ensures stable operation
• Only shows stations with fully resolved hostnames and IP addresses

relabel

• Includes all detected stations in metrics
• Uses "unresolved" as hostname/IP for stations with missing data
• Provides complete visibility of all connected devices
• Useful for troubleshooting and monitoring all WiFi activity

Example configuration:

[policies]
unresolved_station_hostnames = "ignore"  # or "relabel"

Running project

Running with docker

docker pull ghcr.io/shackerd/freebox-exporter-rs:latest

version: '3.8'

services:
  freebox-exporter:
    image: ghcr.io/shackerd/freebox-exporter-rs:latest-amd64
    container_name: freebox-exporter
    volumes:
      - ./config:/etc/freebox-exporter-rs
      - ./data:/data
    ports:
      - "9102:9102"
    restart: unless-stopped
    command: ["/usr/bin/freebox-exporter-rs", "-c", "/etc/freebox-exporter-rs/config.toml" ,"auto"]

Important

port must match with value set in your configuration file data volume path must match with data_directory value set in your configuration file

Configuring

[api]
# Refresh wait interval in seconds, application will send requests to the freebox host on each refresh iteration
# This does not affect prometheus scrap agents, application will use cached values between calls
# Remark:
#   more you set API exposition (c.f: [metrics] section) more requests will be sent,
#   setting a too low interval between refreshs could lead to request rate limiting from freebox host
refresh = 5

[metrics]
# Exposes connection
connection = true
# Exposes lan
lan = true
# Exposes lan browser, this option will be disabled if freebox is in bridge_mode
lan_browser = true
# Exposes switch, this option will be disabled if freebox is in bridge_mode
switch = true
# Exposes wifi, this option will be disabled if freebox is in bridge_mode or device is disabled on the host
wifi = true
# Exposes dhcp, this option will be disabled if freebox is in bridge_mode
dhcp = true
# Exposes system
system = true
# Sets metrics prefix, it cannot be empty
# Warning if you are using the exporter Grafana board, changing this value will cause the board to be unable to retrieve data if you do not update it
prefix = "fbx_exporter"

[policies]
# Specify how to handle WiFi stations with unresolved hostnames (missing host data from Freebox API)
unresolved_station_hostnames = "ignore"
# Acceptable values :
#   * "ignore"  : Skip stations without host data (recommended for stability)
#   * "relabel" : Include stations with "unresolved" labels for missing host information

[core]
# Specify where to store data for exporter such as APP_TOKEN, logs, etc.
data_directory = "."
# Specify which TCP port to listen to, for the /metrics HTTP endpoint
port = 9102

[log]
# Specify which log level to use
# Acceptable values :
#   * "Off"     : A level lower than all log levels
#   * "Error"   : Corresponds to the `Error` log level
#   * "Warn"    : Corresponds to the `Warn` log level
#   * "Info"    : Corresponds to the `Info` log level
#   * "Debug"   : Corresponds to the `Debug` log level
#   * "Trace"   : Corresponds to the `Trace` log level
level = "Info"
# Specify how long application should keep compressed log files, value is in days
retention = 31

Building, debugging

Clone project

git clone --recurse-submodules https://github.com/shackerd/freebox-exporter-rs.git && cd freebox-exporter-rs

Run

cargo run auto

The auto command will prompt the user to consent the application if needed, otherwise it will serve the metrics on http.

• See the serve command if you want to only serve the metrics.
• See the register command if you want to only register the application.

Tip

You can change output log level by specifying verbosity, such as cargo run -- -v Debug auto

Running tests

Run the following command.

cargo test

Verify it works

If you changed port in conf.toml, update the command line below.

curl http://localhost:9102/metrics

Troubleshooting

Having issues? Check our comprehensive troubleshooting guide which includes:

• Session diagnostic commands
• Raw API data collection for bug reports
• Common issues and solutions
• Advanced debugging techniques

For bug reports, please include diagnostic data as described in the troubleshooting guide.

License

Support this project

You like this project? Don't forget to leave a ⭐!

If you want to help ❤️, you can contribute, give feedbacks or you can still buy me a ☕, i like coffee ☕.

Useful links

• https://dev.freebox.fr/blog : official Freebox blog
• https://dev.freebox.fr/bugs : official Freebox bugs report board