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 (WIP)
• 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

Current API progress

• ➖ 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: 0%
  • ❌ Ftp: 0%
  • ❌ NAT: 0%
  • ❌ Port Forwarding: 0%
  • ❌ Incoming port configuration: 0%
  • ❌ UPnP IGD: 0%
  • ❌ LCD: 0%
  • ❌ Network Share: 0%
  • ❌ UPnP AV: 0%
  • ✅ Switch: 100%
  • ❌ Wi-Fi: 0%
  • ✅ System: 100%
  • ❌ VPN Server: 0%
  • ❌ VPN Client: 0%

• ➖ Download

  • ❌ Stats: 0%
  • ❌ Files: 0%
  • ❌ Trackers: 0%
  • ❌ Peers: 0%
  • ❌ Pieces: 0%
  • ❌ Blacklist: 0%
  • ❌ Feeds: 0%
  • ❌ Configuration: 0%

• ➖ File

  • ❌ System: 0%
  • ❌ Sharing Link: 0%
  • ❌ Upload: 0%

• ➖ Air Media

  • ❌ Configuration: 0%
  • ❌ Receivers: 0%

• ❌ Storage: 0%

• ❌ Parental filter: 0%

• ➖ PVR

  • ❌ Programmed records: 0%
  • ❌ Finished records: 0%
  • ❌ Storage media: 0%

Roadmap

• Expose all Freebox API*
• Speedtest metrics
• Provide systemd registration
• Provide container support
• Publish to crates.io (cargo install)

(*) Which can be used as stats

You can suggest your ideas in discussion section

Usage

This project uses clap crate you will find usage by using the following command freebox-exporter-rs -h

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

Commands:
  register
  serve
  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

Building, debugging, configuring project

Clone project

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

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 settings
settings = true
# Exposes contacts
contacts = true
# Exposes calls
calls = true
# Exposes explorer
explorer = true
# Exposes downloader
downloader = true
# Exposes parental
parental = true
# Exposes pvr
pvr = 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

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

[!TIP] This project uses Mockoon for API mocking, you need to install GUI or CLI and start it with api-mock.json file.

Then 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 :heart:, you can contribute, give feedbacks or you can still buy me a :coffee: or leave a :star:!

Useful links

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