W0CHP.radio

Overview

The recommended way to configure ChroGPS Dash is directly from the browser using the built-in Admin Panel. Click the gear icon (⚙) in the dashboard header, or append ?admin to the dashboard URL. All settings below are available in the Admin Panel across three tabs: Dashboard, Features, and Security.

If you prefer to edit the file directly:

/var/www/chrogps-dash/cgpsd-settings.php

…however, hand-editing this is more risky, and may break things due to file permissions and possible syntax errors. Caveat emptor!

Table of Contents:

Settings Reference

CHECK_UPDATES

• Default: true
• Description: Toggles the automatic daily update check. If an update is available, an Update Available button appears in the dashboard header.
• Function:
  • true: The dashboard makes a single outgoing call once every 8 hours to the repository API to check for a newer version. If an update is found, an Update Available button appears in the header and persists across page reloads.
  • false: Disables all outgoing network connections from the dashboard and disables update notifications entirely.

GRAPH_SAMPLE_SEC

• Default: 30
• Description: Controls the resolution of the data points plotted on the graphs.
• Function: This setting acts as a “sampling interval” in seconds.
  • If set to 30, the graph will plot one data point for every 30-second block of time found in the logs.
  • If set to 0, the dashboard will attempt to plot every single line from the log file.
• Usage: Increasing this value smoothes out the graph and improves performance on slower devices. Setting it to 0 provides maximum detail but may look cluttered or load slower.

ENABLE_CLIENTS

• Default: false
• Description: Toggles the “Client Monitor” feature.
• Function:
  • true: Adds a "🌐 Clients" button to the dashboard header. When clicked, it pauses the live dashboard and loads a snapshot of active NTP connections.
  • false: Hides the button and disables the backend PHP logic for querying client data.
• Requirements: This feature requires the clientlog directive in chrony.conf and specific sudo permissions.
  • Tip

    The Quick Installer automatically configures these requirements for you.

MASK_CLIENT_IPS

• Default: false
• Description: Controls the privacy masking of client IP addresses in the Client Monitor.
• Function:
  • true: Applies a privacy mask to all displayed IP addresses
    • Masks the last two octets of IPv4 (1.2.*.*) and last 5 hextets of IPv6 (2001:db8:1:*:*:*:*:*)
  • false: Displays full IP addresses.
• Note: This setting only affects the display in the dashboard modal; the underlying Chrony logs remain untouched.

SHOW_CLIENT_HOSTNAMES

• Default: false
• Description: Controls hostname resolution in the Client Monitor list.
• Function:
  • true: The dashboard will attempt to resolve and display hostnames for connected clients.
    • Note: This requires server-side DNS resolution and may significantly slow down the loading of the client list.
  • false: Displays raw IP addresses only (faster performance).

ADMIN_TOKEN

• Default: '' (empty string – admin panel and web updates disabled)
• Description: A secret token that authorizes access to the dashboard admin panel and one-click browser updates. Generated and stored automatically by the installer.
• Function:
  • Non-empty string: Enables the admin panel (accessible via the gear icon in the header or by appending ?admin to the dashboard URL) and the web update endpoint. When an Update Available button appears in the header, use this token to authenticate the update. The dashboard will authenticate, download, verify, and install the update – and automatically inject any new settings into cgpsd-settings.php – all live from the browser. When complete, click the Reload Dashboard button to load the updated version.
  • Empty string (''): Disables the admin panel and web update endpoint entirely. Settings must be edited manually and updates must be performed via the command line.
• Security: The token is validated server-side using constant-time comparison (hash_equals) to prevent timing attacks, with a built-in delay on failed attempts. It is never exposed in URLs – only accepted via HTTP POST. You can view, copy, or regenerate the token at any time from the admin panel under the Security tab.
• Generation: On fresh installs and upgrades, the installer generates a cryptographically random 32-character hex token (openssl rand -hex 16) and writes it to cgpsd-settings.php. To generate a replacement token from the command line at any time:

  curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -rt
  

  This replaces the value in cgpsd-settings.php and prints the new token to the terminal. You can also regenerate it directly from the Security tab in the admin panel.

curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -dt

DASHBOARD_TITLE

• Default: '' (empty string – uses system hostname)
• Description: A custom label displayed in the dashboard header and browser tab title. Useful when running multiple ChroGPS Dash instances across several machines.
• Function:
  • Non-empty string: Replaces the system hostname in the header and sets the browser tab to ChroGPS Dash - Your Title.
  • Empty string (''): Falls back to the system hostname returned by gethostname().
• Limit: Maximum 60 characters. Values longer than 60 characters are silently truncated. Keep it concise so the header layout remains clean.
• Examples:

  $DASHBOARD_TITLE = 'W0CHP Stratum 1 - Winona';
  $DASHBOARD_TITLE = 'Lab NTP Server - Rack 3';
  $DASHBOARD_TITLE = 'Rooftop GPS Node';
  

Settings Migration

Both the web updater and the shell installer use the same mechanism to keep cgpsd-settings.php current. When either runs, it reads $defaultConfig directly from index.php as the single source of truth, then audits your settings file and injects any setting blocks whose variable is absent. This means:

• If you installed ChroGPS Dash before a new setting was introduced, running an update – via the browser or the command line – will add the missing setting with its documented default value. No manual editing required.
• ADMIN_TOKEN (and the legacy UPDATE_TOKEN) are always skipped during injection. A token already present is never overwritten.
• Injection is idempotent: running the updater multiple times will never duplicate or overwrite existing values.
• Because both paths read their defaults directly from $defaultConfig in index.php, adding a new setting to the PHP is all that is ever required. No separate maintenance of the installer is needed.
• Obsolete settings are removed automatically. The web updater strips $ENABLE_SAT_HISTORY and $ENABLE_PPS_HISTORY from cgpsd-settings.php if they are present, since those features are now always-on and no longer require a toggle.

To update and migrate settings from the command line at any time:

curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash

Default Settings File

Here is the complete default cgpsd-settings.php as written on a fresh installation. All settings default to their most conservative values – optional features are off until explicitly enabled.

<?php
// --- OPTIONAL CONFIGURATION ---

// 1. CHECK FOR UPDATES (True/False)
//    Set to false to disable daily outgoing calls to the repo API,
//    and will disable update notifications in the footer.
$CHECK_UPDATES = true;

// 2. DISPLAY RESOLUTION (Sampling Interval in Seconds)
//    60 = Plot one point every minute. 0 = Plot all points.
$GRAPH_SAMPLE_SEC = 30;

// 3. CLIENT MONITOR (True/False)
//    Enable the "Clients" button to view active NTP connections.
//    (Requires 'clientlog' in chrony.conf and sudo permissions)
$ENABLE_CLIENTS = false;

// 4. PRIVACY: MASK IP ADDRESSES (True/False)
//    Masks the last two octets of IPv4 (1.2.*.*) and last 5 hextets of IPv6 (2001:db8:1:*:*:*:*:*).
$MASK_CLIENT_IPS = false;

// 5. CLIENT LIST HOSTNAMES (True/False)
//    If true, attempts to resolve hostnames. (Default: false)
//    Note: This may be slower and requires DNS resolution on the server.
$SHOW_CLIENT_HOSTNAMES = false;

// 6. ADMIN TOKEN (String)
//    Secret token required to access the admin panel and perform one-click
//    updates from the browser. Leave empty to disable both features.
//    Generate one with: openssl rand -hex 16
$ADMIN_TOKEN = '';

// 7. DASHBOARD TITLE (String, max 60 characters)
//    Custom label shown in the header and browser tab.
//    Leave empty to use the system hostname (default).
//    Example: "W0CHP Stratum 1 - Winona"  |  "Lab NTP - Rack 3"
$DASHBOARD_TITLE = '';

// --- END OPTIONAL CONFIGURATION ---

Satellite History Graphing & Logging

No configuration is required. The two satellite history graphs appear automatically once data has accumulated in their rolling log files:

• Visibility — tracks the number of satellites Seen vs. Active over time. Useful for analyzing antenna placement, sky obstructions, and constellation coverage.
• GPS SNR Trend — tracks the average signal-to-noise ratio (dBHz) of satellites used in the timing fix vs. all visible satellites. A widening gap between the two lines means chrony is rejecting weaker satellites. Drops in both lines simultaneously may indicate RF interference, a cable problem, or a solar transit event.

How It Works

The installer automatically creates and enables a systemd timer (chrogps-poller.timer) that fires every 30 seconds and hits the dashboard’s data endpoint (?ajax=1) in the background. This keeps all history logs populated continuously — no browser tab needs to be open and no manual cron job is needed.

The two units installed are:

• /etc/systemd/system/chrogps-poller.service — a oneshot service that runs curl against the local endpoint.
• /etc/systemd/system/chrogps-poller.timer — fires chrogps-poller.service every 30 seconds (OnUnitActiveSec=30s).

Both units are removed automatically when you uninstall ChroGPS Dash.

Log Management

• File Locations:
  • /var/tmp/cgpsd-sat-counts.data — Visibility (Seen vs. Active counts)
  • /var/tmp/cgpsd-gps-snr.data — GPS SNR Trend (avg dBHz used vs. all)
• Rotation: Both logs are self-managing, using a Rolling Buffer (15,000 lines) to ensure they never grow indefinitely. Once the limit is reached, the oldest entry is removed to make room for the new one.
• Note: Log files are stored in /var/tmp (not the web root) and are owned by www-data. They survive reboots on most systems but are not guaranteed persistent across power cycles on tmpfs mounts.

System Offset / PPS Offset Graphing & Logging

This graph tracks your system clock’s offset from its reference source over a rolling window. The graph label adapts automatically based on what Chrony is currently locked to:

• PPS Drift — shown when Chrony’s Reference ID is a hardware PPS source. Gives you a direct, long-term view of sub-microsecond PPS stability — the kind of data that reveals subtle antenna issues, oscillator aging, or RF interference invisible in real-time.
• System Offset — shown for all other reference sources (GPS-only, network peers, stratum 2+ servers). Tracks the same underlying metric (system clock offset from reference) at the accuracy range of the source in use.

The graph and its tab button label update automatically on each dashboard refresh — no configuration is required. The graph appears automatically once data has accumulated in the rolling log file.

What Gets Logged

Each dashboard poll captures two values directly from chronyc tracking:

• System Offset – the signed offset of your system clock from its reference source (e.g. +/-123 ns for PPS, or +/-1.2 ms for a network peer). When locked to a PPS source, this is your PPS offset.
• RMS Offset – the rolling root-mean-square of recent offsets, representing the statistical noise floor of your timing solution.

Each entry is written as a single line: UNIX_TIMESTAMP OFFSET_SECONDS RMS_OFFSET_SECONDS

The graph plots both series simultaneously: System/PPS Offset as a solid primary line and RMS Offset as a dashed secondary line, with automatic unit scaling (ns → µs → ms) and inline Min/Max/Avg statistics in the legend.

How It Works

Like the satellite history graphs, the PPS log is written by the PHP script on every dashboard poll. The systemd timer (chrogps-poller.timer) installed by the installer polls the dashboard endpoint every 30 seconds, so data is recorded continuously – no browser tab needs to be open and no cron job is needed. See Satellite History Graphing & Logging above for details on the timer units.

Log Management

• File Location: /var/tmp/cgpsd-pps-offset.data
• Rotation: The log is self-managing, using the same Rolling Buffer (15,000 lines) as the satellite history logs. At the default 5-second refresh interval, this provides approximately 20 hours of raw data retention – comfortably ahead of the 12-hour maximum graph window.
• The installer creates this file, sets ownership to www-data, and wires up the correct permissions automatically. On uninstall or -r/--reset, it is cleanly removed alongside all other dashboard data files.

Installer Command Reference

The installer uses a single, consistent flag-based interface. No flags means install or update.

Examples:

# Standard install or update
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash

# Install without ZeroConf/mDNS
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -np

# Factory reset (wipes settings and data, then reinstalls)
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -r

# Factory reset, suppressing output
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -r -q

# Uninstall
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -u

# Generate a new admin token
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -rt

# Display the current admin token
curl -fsSL https://w0chp.radio/ChroGPS-Dash/install | sudo bash -s -- -dt