freebox-exporter-rs

Yet another Freebox API exporter for Prometheus! This project is actually in work in progress. New contributors are welcome! Please join our Matrix room and say "hey!"

Important

Disclaimer: This project is unofficial and is not affiliated 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

You will find here the original Grafana board for the exporter, thanks go to @ottobaer!

Features

• Freebox metrics exposition
• 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

API Implementation

• ➖ Authentication
  • ✅ Register: 100%
  • ✅ Login: 100%
• ➖ Configuration
  • ➖ Connection
    • ✅ Status: 100%
    • ✅ Configuration: 100%
    • ✅ Configuration IPV6: 100%
    • ❌ xDSL: 0%
    • ✅ FFTH: 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

Running project

Running with docker

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

version: '3.8'

services:
  freebox-exporter:
    image: docker.io/shackerd/freebox-exporter-rs:latest
    container_name: freebox-exporter
    volumes:
      - ./config:/etc/freebox-exporter-rs
      - ./data:/data
    ports:
      - "9102:9102"
    restart: unless-stopped
    command: ["/root/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]
# Acceptable values: "router" or "bridge"
# These values will determine whether use discovery or not, see: https://github.com/shackerd/freebox-exporter-rs/issues/2#issuecomment-2234856496
# * discovery on:
#   * Traffic will be using host like xxxxxxxx.fbxos.fr
#   * FQDN resolves to your public IP address.
#   * However, you do not need to activate remote_access from local network to get API working.
# * discovery off:
#   * Traffic will be using host mafreebox.freebox.fr
#   * FQDN resolves to a public IP address (not yours), which allows you to reach your freebox API even if it's set to bridge mode.
# Remark:
#   * If the application is set in "bridge" mode, it works even when Freebox is set to "router" mode but some functionalities will be disabled
#   * If the application is set in "router" mode, it does not work when Freebox is set to "bridge" mode
mode = "bridge"

# 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, this option may not work in bridge_mode
lan = true
# Exposes lan browser, this option does not work in bridge_mode
lan_browser = true
# Exposes switch, this option may not work properly in bridge_mode
switch = true
# Exposes wifi
wifi = true
# Exposes dhcp
dhcp = 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"

[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 https://github.com/shackerd/freebox-exporter-rs.git && cd freebox-exporter-rs

Run debug configuration, assuming application is registered on Freebox host

cargo run serve

Tip

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

Register application if application is not registered on Freebox host

cargo run register

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

License

Support this project

If you want to help ❤️, you can contribute, give feedbacks or you can still buy me a ☕ or leave a ⭐!

Useful links

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