X-ONU Dashboard

A lightweight monitoring dashboard for the EXEN X-ONU-SFPP and compatible ONTs running 8311 community firmware.

The dashboard provides live and historical XGS-PON telemetry using the 8311 JSON metrics endpoint, with optional SSH-based advanced monitoring, configurable alerting, alert history, and multiple notification providers.

The browser interface is organized around three telemetry views:

• Dashboard — quick operational health, optical signal, live traffic, and recent alerts.
• Advanced — detailed system health, PON error counters, historical charts, and module information.
• Diagnostics — explicit, on-demand troubleshooting using fixed SSH diagnostic profiles. Diagnostics do not run automatically when the page is opened.

Alert, notification, and retention configuration remains on the separate Alerts & Notifications page.

Features

Core telemetry does not require SSH and includes:

• RX optical power
• TX optical power
• TX bias current
• Module voltage
• Optical temperature
• CPU temperatures
• PLOAM state
• ONT reachability
• Historical optical and temperature charts
• 1 hour, 6 hour, 24 hour, 7 day, and 30 day history
• Persistent history-range selection
• Configurable telemetry and alert-history retention

Optional advanced SSH telemetry adds:

• Live XGS-PON download and upload rate
• Downloaded and uploaded byte counters
• FEC upstream/downstream status
• BIP errors
• Corrected and uncorrected FEC counters
• HEC counters
• PLOAM MIC errors
• Active alarms
• GEM key-error counters
• ONT uptime
• Memory usage
• Load averages
• Ethernet GEM / Allocation information
• Optical module information
• Historical traffic charts
• Error-counter deltas over the selected history range

Advanced telemetry is optional. If SSH is disabled or unavailable, the core dashboard continues to operate normally.

Alerts

The dashboard includes server-side alert monitoring. Alerts are evaluated by the collectors even when the dashboard is not open in a browser.

Alert monitoring includes:

• RX optical power quality changes
• TX optical power quality changes
• Optical and CPU thermal conditions
• PLOAM leaving or returning to the configured operational state
• Core telemetry becoming unreachable or recovering
• Active ONT alarm increases, decreases, and clearing
• GEM key-error increases
• BIP error increases
• Corrected and uncorrected FEC errors
• Corrected and uncorrected PSBd HEC errors
• Corrected and uncorrected FS HEC errors
• PLOAM MIC errors

Alert thresholds, severities, debounce behavior, minimum counter deltas, and counter cooldowns can be configured from the dedicated Alerts & Notifications page.

Warning conditions can require multiple consecutive samples before an alert is generated. Critical conditions can be reported immediately.

Counter alerts are based on increases rather than simply whether a lifetime counter is non-zero. This helps distinguish new errors from historical errors already recorded by the ONT.

Alert Settings Reference

The Alert Settings panel on the Alerts & Notifications page controls when alert events are generated and what severity is assigned to them.

Changing an alert severity does not change when the condition is detected. It changes how the resulting event is classified. Available severities are Info, Warning, and Critical.

The defaults are intended to provide useful monitoring without generating an alert for every small fluctuation. They can be adjusted for the optical levels and behavior normally seen on a particular ONT or network.

Warning Debounce

Warning debounce is the number of consecutive warning-level samples that must be observed before a signal-quality warning is generated.

Default:

3 samples

For example, with the default value of 3, a warning condition must be present for three consecutive samples before the dashboard records a warning.

This helps prevent a brief optical or temperature fluctuation from creating an unnecessary alert.

Poor or critical conditions are not delayed by the warning debounce and can generate an alert immediately.

If a warning condition disappears before the required number of consecutive samples is reached, the pending warning is cleared.

RX Power Thresholds

The RX power settings define the receive optical-power ranges used by the alert system.

Defaults:

Poor low:   -27 dBm
Fair low:   -24 dBm
Great low:  -20 dBm
Great high: -14 dBm
Poor high:   -8 dBm

The settings exposed in the dashboard define the important boundaries used to decide whether received optical power is normal, warning-level, or poor.

Poor low defines the lower extreme. RX power at or beyond the poor range is treated as a critical-quality condition.

Fair low defines the transition into the lower warning range.

Poor high defines the upper extreme where excessive receive power is considered poor.

The internal Great range is used for signal-quality classification and is not normally something that needs to be adjusted.

Because optical power is expressed in negative dBm values, a value such as -27 dBm represents less received optical power than -20 dBm.

Warning-level RX conditions are subject to Warning debounce. Poor conditions can alert immediately. When an active RX warning or critical condition returns to the normal range, a recovery event is generated.

TX Power Thresholds

TX power uses a profile-aware operational health model. The selected profile and its persisted thresholds drive both the dashboard TX badge and server-side TX alerts.

Operational states are:

• NORMAL: inside the configured warning and alarm boundaries.
• WARNING: beyond a warning boundary but not an alarm boundary. Warning alerts use the configured consecutive-sample debounce.
• ALARM: at or beyond an alarm boundary. Alarm conditions can alert immediately.
• UNKNOWN: the reading is missing, invalid, or nonfinite.

The following profiles are available:

Legacy preserves the original dashboard behavior exactly. It is the default for fresh installations and for an existing saved configuration that still matches the original defaults:

Low alarm:     1 dBm
Low warning:   2 dBm
High warning:  7 dBm
High alarm:    8 dBm
Cosmetic Great range: 4-5 dBm

Legacy retains the historical GOOD / FAIR / POOR display wording. GREAT is only a cosmetic subdivision of the healthy state: it does not change alert severity or overall operational health.

XGSPONST2001 A-01 uses the documented XGS-PON upstream mean launch-power operating specification:

Operating minimum: 4.00 dBm
Operating maximum: 9.00 dBm
Warning bands:     None

Its behavior is:

TX < 4.00 dBm         ALARM / OUT OF SPEC
4.00 <= TX <= 9.00   NORMAL
TX > 9.00 dBm         ALARM / OUT OF SPEC

This specification defines an operating envelope, not separate warning thresholds. A value outside the envelope therefore enters the existing immediate alarm path without warning debounce. Readings such as 6.22 dBm and 7.1-7.3 dBm are NORMAL.

The EEPROM investigation remains useful background but does not define this profile's operational policy. The module reports low alarm 2.00 dBm, low warning 3.00 dBm, and 0xFFFF for both upper threshold words. 0xFFFF is the maximum SFF-8472 TX-power encoding, approximately 8.16 dBm, rather than a meaningful calibrated high-side threshold. None of those EEPROM values are used as operational thresholds by the XGSPONST2001 A-01 profile.

Custom allows user-defined low thresholds and optional upper warning and alarm thresholds. Leaving an upper field blank disables that boundary; disabled thresholds are stored as JSON null, not a magic numeric value. Manually editing a TX threshold changes the selected profile to Custom.

Existing saved configurations are preserved. A source-code default change does not silently migrate them, and the XGSPONST2001 A-01 profile is applied only when selected explicitly. Changing the TX profile or thresholds clears only the in-memory TX debounce and active-classification baseline so the policy change itself cannot create a bogus warning or recovery event. Historical telemetry and alert events are not rewritten.

Thermal Thresholds

Thermal alerts monitor ONT temperature readings.

Defaults:

Warm: 75 °C
Hot:  85 °C

Warm is a warning-level condition and is subject to Warning debounce.

Hot is a critical-quality condition and can generate an alert immediately.

When an active thermal warning or critical condition returns to the normal range, a recovery event is generated.

GEM Key Errors

GEM key errors are monitored as a counter increase rather than simply checking whether the counter is non-zero.

Defaults:

Minimum delta: 1
Severity:      Warning

Minimum delta is the minimum increase required before an alert is generated.

For example, with a Minimum Delta of 1, a GEM key-error counter increasing from 100 to 101 can generate an alert. A counter that remains at 100 does not repeatedly alert merely because its lifetime value is non-zero.

Severity controls whether a generated GEM key-error event is recorded as Info, Warning, or Critical.

PLOAM State

The alert system monitors whether the ONT is in its configured operational PLOAM state.

Default operational state:

51 = O5.1 - Associated

The PLOAM settings control the severity assigned to two events:

Not operational is used when the ONT is observed outside the configured operational PLOAM state.

Default severity:

Critical

Recovered is used when the ONT returns to the configured operational state.

Default severity:

Info

If the dashboard starts while the ONT is already in a non-operational PLOAM state, that condition can also generate an alert rather than requiring a transition to occur after startup.

Active Alarms

The dashboard monitors the number of active alarms reported by the ONT.

Three severity settings control how changes are reported:

Increased is used when the active alarm count rises.

Default severity:

Critical

Decreased is used when the active alarm count falls but remains above zero.

Default severity:

Info

Cleared is used when the active alarm count returns to zero.

Default severity:

Info

The first observed alarm count establishes the initial baseline and does not by itself generate a change event.

ONT Reachability

ONT reachability monitors the core JSON telemetry connection independently from optional SSH telemetry.

Failure debounce controls how many consecutive failed core telemetry samples are required before the ONT is considered unreachable.

Default:

3 samples

A successful telemetry sample before the debounce threshold is reached clears the pending failures without generating an unreachable or recovery event. After an outage has been confirmed, the first successful telemetry sample generates the recovery event immediately.

Unreachable controls the severity used when the core metrics endpoint becomes unreachable.

Default severity:

Critical

Recovered controls the severity used when the core telemetry connection becomes reachable again.

Default severity:

Info

If the dashboard starts and the core telemetry endpoint is already unreachable, an initial unreachable event can be generated.

A failure of optional SSH telemetry does not by itself cause a core reachability alert.

Error Counter Alerts

Advanced SSH telemetry provides several cumulative XGS-PON error counters. These alerts are based on new counter increases, not on the lifetime value already stored by the ONT.

Each counter rule can contain:

Minimum delta — the amount the counter must increase before an alert is generated.

Cooldown — the minimum number of seconds after an alert before another alert of the same type may be generated.

Severity — whether the generated event is classified as Info, Warning, or Critical.

Counter increases can accumulate across multiple collection cycles until Minimum Delta is reached.

For example, with:

Minimum delta: 10

three successive increases of +3, +4, and +3 accumulate to +10 and can generate an alert.

If a counter decreases, the dashboard assumes that the ONT rebooted or the counter was reset. Any pending accumulated increase for that counter is discarded rather than treating the reset as an error event.

A cooldown does not mean counter monitoring stops. Increases can continue to be observed while the cooldown is active, and a pending alert can be emitted after the cooldown expires once its configured conditions are satisfied.

The default counter rules are:

A cooldown of 0 means there is no cooldown period.

The higher default thresholds and cooldowns on corrected-error counters help avoid excessive notifications from small bursts of errors that the link successfully corrected.

Uncorrected errors and PLOAM MIC errors default to a Minimum Delta of 1, Critical severity, and no cooldown because a newly observed uncorrected error is generally more significant than a corrected error.

Alert Recovery Events

Where recovery detection is supported, the dashboard records a separate event when an active problem returns to normal.

Examples include:

• RX or TX optical quality returning to normal
• Temperature returning to normal
• PLOAM returning to the operational state
• Core telemetry becoming reachable again

Active ONT alarm decreases and clearing are also recorded as separate alert events.

Recovery events default to Info where a separate recovery severity is available.

Alert Settings and Notifications

Alert generation and notification delivery are separate operations.

The dashboard provides a dedicated Alerts & Notifications page for configuring alert behavior and external notification delivery. The main dashboard continues to display Recent Alerts without using space for configuration controls.

Alert Settings determine whether an event is generated and the severity assigned to it.

Notification Settings determine whether generated events are sent to an external notification provider.

Supported notification providers are:

• Discord
• ntfy
• Gotify
• Pushover
• Generic Webhook
• Email (Gmail SMTP)

This means alerts continue to be evaluated and stored in the dashboard database even when external notifications are disabled.

Enabling a notification provider does not change the alert thresholds. It simply allows generated alert events to be delivered through the configured provider.

Recent Alerts and Alert History

Generated alerts are stored in the dashboard SQLite database.

The main dashboard displays the 3 most recent alerts, keeping the Recent Alerts section compact while still providing immediate visibility into the latest events.

Select View Alert History → to open the dedicated Alert History page. Stored alerts are displayed newest first with 25 alerts per page and Previous / Next pagination, allowing older retained events to be reviewed without cluttering the main dashboard.

The amount of alert history available depends on the configured alert-history retention period.

Alert events include information such as:

• Timestamp
• Severity
• Alert type
• Metric
• Previous value
• Current value
• Delta
• Human-readable message

Recovery events are also recorded when supported conditions return to normal.

Notification Providers

Notification delivery is performed server-side, so the dashboard does not need to remain open in a browser for notifications to be sent.

Notification delivery is intentionally isolated from telemetry collection and alert storage. A failed notification request does not stop telemetry collection or prevent the alert event from being stored.

Multiple notification providers can be configured from the Notification Settings panel on the Alerts & Notifications page.

Discord

Discord notifications are delivered using a Discord webhook.

To enable Discord notifications:

1. Create a webhook for the desired Discord channel.
2. Open the Alerts & Notifications page.
3. Enter the Discord webhook URL.
4. Enable Discord notifications.
5. Save the settings.

Alert notifications include the alert severity and message, along with the affected metric when applicable.

ntfy

ntfy notifications can be delivered through the public ntfy service or a compatible self-hosted ntfy server.

To enable ntfy notifications:

1. Open the Alerts & Notifications page.
2. Enter the ntfy server URL. The default public server is https://ntfy.sh.
3. Enter the topic that should receive dashboard alerts.
4. Enter an access token if the server or topic requires authentication. The token is optional.
5. Enable ntfy notifications.
6. Save the settings.

An ntfy account is not required when using a server or topic that permits unauthenticated publishing.

Gotify

Gotify notifications can be delivered to a Gotify server using an application token.

To enable Gotify notifications:

1. Create an application in Gotify and obtain its application token.
2. Open the Alerts & Notifications page.
3. Enter the Gotify server URL.
4. Enter the application token.
5. Enable Gotify notifications.
6. Save the settings.

The dashboard maps alert severity to Gotify message priority so more important alerts can be presented with a higher priority.

Pushover

Pushover notifications are delivered through the Pushover message API.

To enable Pushover notifications:

1. Obtain the Pushover user key for the destination account.
2. Create or select a Pushover application and obtain its API token.
3. Open the Alerts & Notifications page.
4. Enter the user key and API token.
5. Enable Pushover notifications.
6. Save the settings.

Critical dashboard alerts use Pushover priority 1. Emergency priority 2 is intentionally not used because it requires retry and expiration parameters and has different acknowledgement behavior.

Generic Webhook

The Generic Webhook provider sends the complete alert event to a custom HTTP or HTTPS endpoint using an HTTP POST request with a JSON body.

To enable Generic Webhook notifications:

1. Open the Alerts & Notifications page.
2. Enter the destination HTTP or HTTPS URL.
3. Enable Webhook notifications.
4. Save the settings.

The request uses the following general structure:

{
  "source": "X-ONU-SFPP Dashboard",
  "event": {
    "...": "complete alert event"
  }
}

The event object contains the alert data generated by the dashboard, which may include fields such as severity, message, metric, previous value, current value, and delta.

Generic Webhook endpoints should validate incoming requests as appropriate for the receiving system.

Email (Gmail SMTP)

Email notifications are delivered through Gmail SMTP using implicit TLS on port 465.

To enable Email notifications:

1. Enable 2-Step Verification for the Google account if it is not already enabled.
2. Create a Google App Password for the dashboard.
3. Open the Alerts & Notifications page.
4. Enter the Google account email, App Password, and one recipient email address.
5. Enable Email notifications.
6. Save the settings.

Use a Google App Password only. Do not enter the normal Google account password. Google Workspace addresses using a custom domain are supported when the account can authenticate through Gmail SMTP.

The App Password is stored in the persistent notification configuration. Treat the dashboard's persistent /data directory and its backups as sensitive.

ntfy Topic Security

Topics on a public ntfy server should not be treated as private merely because the topic name is difficult to guess.

Anyone who knows or discovers an unauthenticated topic name may be able to subscribe to messages published to that topic. Use a sufficiently random topic name and avoid including sensitive information in notifications sent to a public unauthenticated topic.

For stronger access control, use an authenticated ntfy configuration or a self-hosted ntfy server and configure an access token when required.

Private Notification Destinations

Gotify, ntfy, and Generic Webhook destinations are restricted to publicly routable IP addresses by default to protect against SSRF.

Private or self-hosted destinations must be explicitly allowed by the administrator with NOTIFICATION_PRIVATE_ORIGINS, using a comma-separated list of exact origins:

NOTIFICATION_PRIVATE_ORIGINS=http://gotify.example.lan:8080,https://ntfy.example.lan

Origins are matched by exact scheme, host, and port. Paths and query strings are not allowed. DNS addresses are validated before connecting, connections are pinned to validated addresses, redirects are not followed, and URL-embedded credentials are rejected.

Leave NOTIFICATION_PRIVATE_ORIGINS unset when all destinations are public.

Notification Credential Security

Discord webhook URLs, Gotify application tokens, Pushover credentials, ntfy access tokens, private Generic Webhook URLs, and Gmail App Passwords should be treated as sensitive configuration.

Do not publish notification credentials in screenshots, logs, Git repositories, support posts, or other public locations.

Anyone with a Discord webhook URL may be able to post messages to the associated Discord channel. If a Discord webhook URL is accidentally exposed, rotate or delete the webhook and create a new one.

If another notification credential or private endpoint is exposed, revoke, rotate, or replace it when supported by the notification service.

Data Retention

Telemetry and alert-history retention can be configured from the Data Retention panel on the Alerts & Notifications page.

Telemetry retention applies to both standard and advanced telemetry samples.

Available telemetry retention periods are:

• 7 days
• 30 days
• 60 days
• 90 days
• 180 days
• 1 year
• Unlimited

New installations default to 90 days of telemetry history.

Alert-history retention can be configured separately.

Available alert-history retention periods are:

• 30 days
• 90 days
• 180 days
• 1 year
• Unlimited

New installations default to 1 year of alert history.

Expired records are removed automatically. Selecting Unlimited disables automatic cleanup for that data type.

Existing installations preserve their effective telemetry retention setting during upgrade rather than being silently changed to the new-install default.

Requirements

An ONT running compatible 8311 community firmware with the metrics endpoint available at:

/cgi-bin/luci/8311/metrics

The default endpoint is:

https://192.168.11.1/cgi-bin/luci/8311/metrics

The Docker host must be able to reach the management IP of the ONT.

For advanced monitoring, SSH access to the ONT is also required.

Internet-Facing HTTPS

The dashboard can be used over plain HTTP on a trusted local network by default.

Internet-facing deployments should be placed behind a trusted HTTPS reverse proxy and configured with:

REQUIRE_HTTPS=true

When REQUIRE_HTTPS is enabled, the dashboard sends:

Strict-Transport-Security: max-age=31536000

The reverse proxy is responsible for terminating TLS and redirecting or rejecting plain HTTP traffic. The dashboard does not automatically trust client-supplied forwarding headers such as X-Forwarded-Proto.

Do not expose the dashboard application port directly to the Internet. Leave REQUIRE_HTTPS disabled for ordinary HTTP-only LAN deployments.

Optional Dashboard Authentication

The dashboard can optionally require HTTP Basic authentication.

Authentication is disabled by default for trusted-LAN deployments.

To enable it, configure both:

DASHBOARD_AUTH_USERNAME=admin
DASHBOARD_AUTH_PASSWORD=use-a-strong-password

Both variables must be configured together. If only one is supplied, the application refuses to start.

HTTP Basic authentication must only be used over HTTPS on untrusted networks. Internet-facing deployments must still use a trusted HTTPS reverse proxy and must not expose the dashboard application port directly.

Users with access to the Docker or Unraid host may be able to inspect container environment variables. Protect the dashboard authentication password with the same care as SSH_PASSWORD.

ONT Management Connectivity

The Docker host must be able to reach the management IP of the ONT. The dashboard does not create or manage that network path for you.

The optional UCG Fiber helper scripts are also usable without X-ONU-SFPP Dashboard. They can be used independently to maintain persistent access to an ONT management interface for its web UI, SSH, or other administrative tools.

The helper documentation includes installation paths for Linux/macOS and Windows PowerShell. In all cases, the helper scripts themselves execute on the UCG Fiber gateway, not on the administrator's computer.

UniFi Cloud Gateway Fiber users

[!CAUTION] ⚠️ USE AT YOUR OWN RISK. Optional UCG Fiber reference scripts are provided for users whose gateway repeatedly removes a manually configured ONT management address. These scripts modify a WAN-side interface and can disrupt Internet access, PPPoE connectivity, ONT management access, or other network services if configured incorrectly. They are unofficial, are not required by the dashboard, and must be reviewed and adapted for each network before use.

See UCG Fiber and Persistent ONT Management Access and the examples/ucg-fiber/ reference scripts.

Docker Image

The published Docker image is:

ghcr.io/jpetovello/x-onu-sfpp-dashboard:latest

Docker Installation

Basic installation without SSH telemetry:

docker run -d \
  --name x-onu-dashboard \
  --restart unless-stopped \
  -p 8766:8080 \
  -e ONT_URL="https://192.168.11.1/cgi-bin/luci/8311/metrics" \
  -e POLL_SECONDS="10" \
  -e REQUEST_TIMEOUT="5" \
  -e DATA_DIR="/data" \
  -e SSH_ENABLED="false" \
  -v ./data:/data \
  ghcr.io/jpetovello/x-onu-sfpp-dashboard:latest

The dashboard will then be available on port 8766 of the Docker host.

Advanced SSH Telemetry

To enable advanced monitoring, provide SSH connection details for the ONT:

docker run -d \
  --name x-onu-dashboard \
  --restart unless-stopped \
  -p 8766:8080 \
  -e ONT_URL="https://192.168.11.1/cgi-bin/luci/8311/metrics" \
  -e POLL_SECONDS="10" \
  -e REQUEST_TIMEOUT="5" \
  -e DATA_DIR="/data" \
  -e SSH_ENABLED="true" \
  -e SSH_HOST="192.168.11.1" \
  -e SSH_PORT="22" \
  -e SSH_USER="root" \
  -e SSH_PASSWORD="your-password" \
  -e SSH_POLL_SECONDS="30" \
  -e SSH_TIMEOUT="10" \
  -e SSH_COMMAND_TIMEOUT="30" \
  -v ./data:/data \
  ghcr.io/jpetovello/x-onu-sfpp-dashboard:latest

SSH telemetry is collected independently from the core JSON metrics collector.

A failed SSH login or unavailable SSH service does not make the ONT appear offline if the JSON metrics endpoint is still reachable.

Security Note

SSH_PASSWORD is supplied to the container as a Docker environment variable.

Docker environment variables can be inspected by users with access to Docker or the Unraid host. Masking the password field in the Unraid interface only hides it visually; it does not provide secret storage.

Alert and notification configuration is stored in the dashboard's persistent SQLite database. This includes a Gmail App Password when Email notifications are configured. Treat the persistent /data directory as sensitive if notification credentials or private notification endpoint URLs have been configured.

Do not expose this dashboard or the ONT management interface directly to the public Internet.

Configuration

Core telemetry

ONT_URL

Default:

https://192.168.11.1/cgi-bin/luci/8311/metrics

URL of the 8311 metrics endpoint.

ONT_TLS_VERIFY

Default:

false

Controls TLS certificate verification for the core ONT metrics request.

Set to true to require normal certificate-chain and hostname or IP verification using the container's trusted CA certificates.

The default remains false for compatibility with ONTs that use self-signed or locally issued certificates.

ONT_TLS_CA_BUNDLE

Default: unset.

Optional path to a PEM CA bundle used to verify the ONT certificate.

Setting this variable enables verification using that CA bundle. ONT_TLS_VERIFY may be left unset or set to true.

Configuring a CA bundle together with ONT_TLS_VERIFY=false is rejected as contradictory.

A trusted CA does not disable hostname or IP identity checking. The ONT certificate must also be valid for the hostname or IP address used in ONT_URL.

POLL_SECONDS

Default:

10

Number of seconds between core ONT metric requests.

RETENTION_DAYS

Legacy compatibility setting used when upgrading an existing installation that does not yet have a saved retention configuration.

The existing value is used to preserve the installation's effective telemetry retention period during migration.

For new installations, telemetry retention is configured from the dashboard and defaults to 90 days. After a retention configuration has been saved in the dashboard database, use the Data Retention panel rather than this environment variable to manage retention.

REQUEST_TIMEOUT

Default:

5

Timeout in seconds when requesting the JSON metrics endpoint.

DATA_DIR

Default:

/data

Directory used for persistent dashboard data.

Advanced SSH telemetry

SSH_ENABLED

Default:

false

Enables or disables advanced SSH telemetry.

SSH_HOST

Default:

192.168.11.1

SSH host or management IP of the ONT.

SSH_PORT

Default:

22

SSH port.

SSH_USER

Default:

root

SSH username.

SSH_PASSWORD

Default:

empty

Password used for SSH authentication.

The password is not stored in the dashboard SQLite database and is not returned by the dashboard APIs.

SSH Host Key Verification

SSH host keys use trust on first use (TOFU).

After the first successful SSH authentication, the dashboard stores the ONT host key in:

/data/ssh_known_hosts

Future SSH connections require the ONT to present the same host key. If the host key changes, advanced SSH telemetry rejects the connection instead of automatically trusting the new key.

Because the initial connection uses TOFU, the first host key is not independently authenticated. The persistent /data directory must be preserved across container updates to retain host key verification.

SSH_POLL_SECONDS

Default:

30

Number of seconds between advanced SSH collection cycles.

SSH_TIMEOUT

Default:

10

SSH connection timeout in seconds.

SSH_COMMAND_TIMEOUT

Default:

30

Maximum time allowed for advanced telemetry commands.

Persistent Data

Historical samples, alert configuration, notification configuration, retention configuration, and alert events are stored in an SQLite database at:

/data/metrics.db

The /data directory should be mapped to persistent storage so history and configuration survive container upgrades and recreation.

For Unraid, the recommended mapping is:

/mnt/user/appdata/x-onu-dashboard -> /data

V3 continues to use the existing core samples and advanced_samples telemetry tables and automatically adds the database structures required for alert history and configuration.

Existing telemetry history is preserved during upgrade.

Upgrading Existing Installations

Existing installations can continue using the same persistent /data directory.

On startup, V3 creates the additional database structures required for alert events, alert configuration, notification configuration, and retention configuration if they do not already exist.

Existing core and advanced telemetry history is preserved. Existing installations also preserve their effective telemetry retention period when the retention configuration is created for the first time.

After upgrading, review Alert Settings before enabling external notifications so the configured thresholds and severities are appropriate for your ONT and environment.

Upgrading to the Non-Root Runtime

The container runs as the unprivileged Unraid user nobody:users (UID 99 / GID 100) instead of root.

Fresh Unraid installations require no additional permission changes.

Existing installations created by earlier versions may have /data/metrics.db owned by root:root. Before starting the updated container, run this one-time command on the Unraid host if using the default appdata path:

chown -R 99:100 /mnt/user/appdata/x-onu-dashboard

This preserves the existing SQLite database and historical data while allowing the non-root container to continue writing new samples, alerts, and configuration.

Web Interface

Dashboard

The main Dashboard at / is intended to answer:

Is my ONT healthy?

It provides the at-a-glance operational view:

• Overall ONT status
• PLOAM state
• Overall PON health
• RX and TX optical levels
• TX bias and module voltage
• Live download and upload rate
• Recent alerts

The core Dashboard continues to operate when optional SSH telemetry is disabled or temporarily unavailable.

Advanced

The Advanced page at /advanced is intended to answer:

What exactly is my ONT doing?

It contains the more detailed monitoring views:

• Optical and CPU temperatures
• ONT uptime
• Memory usage and system load
• FEC status
• PON error counters
• Active alarms and GEM key-error counters
• Historical optical charts
• Historical temperature charts
• Historical traffic charts
• Optical module information
• Ethernet GEM and allocation information

Advanced telemetry depends on optional SSH access to the ONT. When SSH telemetry is disabled or unavailable, the affected values show an unavailable state without causing the core Dashboard to report the ONT itself as offline.

Diagnostics

The Diagnostics page at /diagnostics is intended for explicit troubleshooting:

What is going on at the ONT?

Diagnostics are on-demand only. Opening the page does not run SSH commands.

Standard Diagnostics profiles are:

• Overview — ONT status, capability/configuration, LAN interface status and counters, active alarms, optical interface status, and optical interface information.
• Counters — allocation counters and upstream/downstream PLOAM counters.

Expert Diagnostics profiles expose deeper troubleshooting pages:

• Datapath — raw CQM offload, CQM queue-map, Datapath Ports, and Datapath QoS views.
• PPv4 — raw buffer-manager, queue-rate, queue-statistics, tree, and QStats views.
• Burst Profile — raw Debug Burst Profile output.

Expert output is intentionally presented as raw technical information. The dashboard does not assign health grades or inferred alarm meanings to these undocumented fields.

The user explicitly selects a profile and chooses Run Diagnostics before a diagnostic request is made.

Diagnostic commands are fixed by the application. The browser cannot submit an arbitrary shell or pontop command.

Diagnostic output is returned to the requesting browser and is not added to telemetry history or fed into alert processing.

Only one diagnostic operation runs at a time per dashboard process. If another request is already active, the later request fails quickly with a non-fatal busy message instead of waiting or starting another SSH workload.

Diagnostics require optional SSH telemetry to be configured.

Alerts & Notifications

Alert thresholds, notification providers, telemetry retention, and alert-history retention are managed from the separate Alerts & Notifications page.

The main Dashboard continues to show recent alerts without using space for configuration controls.

PLOAM State

A PLOAM state of 51 represents O5.1 Associated and is the default operational PLOAM state used by the alert system.

The operational state can be configured from Alert Settings.

Optical Health

The dashboard displays optical quality classifications for RX and TX signal levels.

The dashboard and server-side alert engine use the same persisted threshold policy. Warning and alarm classifications therefore affect overall PON health as well as alert generation. The browser loads that policy from the backend rather than carrying separate hard-coded TX thresholds.

The Legacy TX profile may display GREAT within part of its healthy range. GREAT is cosmetic only and maps to the same healthy operational level as GOOD or NORMAL.

Alert thresholds and the active TX profile are configurable through Alert Settings.

Unraid

X-ONU Dashboard is designed to run as a Docker container on Unraid.

Recommended configuration:

Container WebUI Port: 8080
Default Host Port:    8766
Container Data Path:  /data
Default Appdata Path: /mnt/user/appdata/x-onu-dashboard

Advanced SSH telemetry is optional and can be enabled from the container settings.

Alert configuration and notification provider settings are managed from within the dashboard.

Development

Developer documentation, architecture, and local build instructions are available in DEVELOPMENT.md.

Source

Project repository:

https://github.com/JPetovello/x-onu-sfpp-dashboard

Issues and bug reports:

https://github.com/JPetovello/x-onu-sfpp-dashboard/issues

Development Note

This project was developed with substantial assistance from AI-based coding tools. Project direction, design decisions, hardware testing, validation, deployment, and ongoing maintenance are performed by the project maintainer.

License

X-ONU Dashboard is licensed under the GNU Affero General Public License version 3 or later (AGPL-3.0-or-later).

Copyright (c) 2026 Jeff Petovello