Download the PHP package texxasrulez/server-dashboard without Composer

Server Dashboard

Server Dashboard is a lightweight PHP admin console for operators who want one place to watch server health, services, probes, alerts, logs, cron health, and related maintenance tasks without introducing a framework-heavy stack.

It is aimed at small VPS, homelab, agency, and single-host production environments where a pragmatic dashboard is more useful than a large observability platform. The project already has broad surface area; the current focus is making that surface safer to operate and easier to maintain.

What It Includes

• Service and process dashboards
• Local Attack Monitor page backed by cached security events
• Admin-only OPNsense Firewall page backed by shared read-only API settings and cached collector data
• Optional Internet Exposure card for configured public services and lightweight local port visibility
• Visitors Map for public request IPs collected from dashboard-known logs
• History and probe exports
• Alerts administration and alert event history
• Alerts rule backups stored alongside config backups under config/backups/
• Lightweight Other Devices UP/DOWN page for LAN/WAN host attention checks
• Config UI backed by config/local.json
• Config UI includes an About tab backed by data/about.json
• Config About tab can check GitHub releases from SERVER_DASHBOARD_GITHUB_REPO=owner/repo or the package.json repository
• Cron health helpers and headless endpoints
• User management and session auth
• Log viewer, bookmarks, diagnostics, and server tests
• Server tests include a read-only security-update check that uses local package-manager status without changing host state
• Adapter-based environment detection for generic Linux and Hestia-style installs

Production-Readiness Baseline

Recent foundation work adds:

• An actionable admin doctor at diag.php
• Cron token management with reveal authorization, rotation, and audit logging
• Monthly uptime/SLA reporting with JSON, CSV, and HTML export
• A minimal PHP lint + PHPUnit baseline
• A GitHub Actions CI workflow for lint, formatting, and test smoke checks
• Admin-facing audit and asset audit tools in the diagnostics area
• A left-sidebar navigation layout option without adding more header tabs
• Live privileged log reads inside the existing Logs page
• Correlated incidents, incident timelines, and per-service drill-down pages
• Backup restore verification plus redacted troubleshooting bundle export
• Micro-backup purge action that keeps a configurable newest set while deleting older micro directories on the backup host
• Expanded browser smoke coverage for core operator flows

Project Layout

Install / Update

1. Place the project under your web root or subdirectory.
2. Create the first admin from CLI: php bin/bootstrap-admin.php
3. Sign in and immediately rotate the temporary password in users.php.
4. Verify the PHP user can write to:
   • data/
   • state/
   • config/ when using config backups/UI saves
5. Generate script environment helpers if you plan to run bundled cron/systemd helpers: php bin/install-scripts.php

For updates, replace the code, keep your writable data/, state/, and config/local.json, then rerun the validation steps in the Testing section below.

Configuration Model

The project keeps the current compatibility model intact:

• Primary editable config: config/local.json
• Schema/defaults: config/schema.php and config/defaults.php
• Compatibility sync: data/security_config.json
• Runtime fallbacks: environment variables and token files
• Alerts rule snapshots from alerts_admin.php: config/backups/alerts-YYYYmmdd-HHMMSS.json
• Alerts admin can restore the latest alerts snapshot back into data/alerts.json after confirmation

Important configuration paths:

• Cron token: alerts.cron_token, DASH_CRON_TOKEN, data/cron_token.txt
• Mail transport: mail.*
• Security controls: security.*
• History and cron expectations: history.*, alerts.*, cron.*

Admin configuration is done primarily through bin/config-cli.php.

Cron / Headless Usage

The cron helper flow no longer adds tokens to generated cron jobs. Use plain curl lines for the built-in cron endpoints:

Some other automation endpoints may still support header-based auth for compatibility, but the cron jobs generated from cron.php no longer require cron tokens.

If you use the bundled scripts:

• Generate script env: php bin/install-scripts.php
• Review: scripts/lib/dashboard_env.sh
• Generated env file: state/generated/dashboard-scripts.env

NVMe Collector

Install smartmontools on the host so smartctl is available, then run:

The collector reads /dev/nvme0n1 and /dev/nvme1n1, writes the latest snapshot to data/nvme_history.jsonl.

The admin UI now includes a top-level docs/pages/drive-health.md for page behavior and data sources.

Attack Monitor Collector

Run the local collector from cron:

The collector reads only allowlisted local security sources, writes sanitized cache to api/watch_data.php. The live event stream is paginated in the browser with a persisted rows-per-page control.

CrowdSec decisions are read through cscli decisions list -o json. If CrowdSec uses a non-default Local API endpoint or port, set attack_monitor.crowdsec_config_path in the Config page's Attack Monitor section to the CrowdSec config file that contains that endpoint, such as /etc/crowdsec/config.yaml.

Set attack_monitor.excluded_ips in the Config page's Attack Monitor section to omit exact IPv4 or IPv6 addresses from attack counts, top lists, indicators, and event tables.

Optional OPNsense edge-firewall collection uses the read-only HTTPS API endpoint GET /api/diagnostics/firewall/log from the same cron collector; the browser never contacts the firewall directly. Shared OPNsense URL, API credentials, TLS, CA, timeout, refresh, and stale settings now live in Config -> OPNsense under opnsense.*. Attack Monitor keeps only firewall-log collection toggles, GeoIP rule identifiers/labels, interfaces, poll limit, and lookback under attack_monitor.opnsense.*. Legacy Attack Monitor credential keys are mapped at runtime when central settings are absent.

The Edge Firewall section derives timeline buckets, blocks/hour, prior-window comparison, Edge Containment, unique-country counts, GeoIP-policy country markers, and data-coverage warnings from retained normalized history. These are observational metrics; OPNsense blocks and local server attack events measure different stages and are not guaranteed to represent the same individual connection attempts.

OPNsense Firewall Collector

The admin-only opnsense.php page is backed by a dedicated read-only collector and cache:

It writes state/opnsense/opnsense_latest.json, state/opnsense/opnsense_history.jsonl, and state/opnsense/opnsense_capabilities.json. See docs/config-tabs/opnsense.md.

See docs/config-tabs/attack-monitor.md for page behavior and settings.

Other Devices

The state/other_servers_latest.json, and admins can refresh checks from the page or run php scripts/other_servers_collect.php from cron.

Example config:

Supported checks are ping, tcp, http, and https. TCP, HTTP, and HTTPS require port. Ping can report DOWN when ICMP is blocked, so TCP or HTTP checks are often more reliable. The optional link field turns the device name on the Other Devices page into an HTTP/HTTPS link.

Optional SSH details can be enabled per device in Config -> Other Devices. When detail_method is ssh, the dashboard uses the configured password or key login to run a fixed read-only command set for hostname, OS release, kernel, uptime, and load. Key auth supports auto, openssh, and libssh2 backends; auto tries libssh2 first, then falls back to OpenSSH. Use auto or libssh2 when the dashboard should unlock an encrypted key with key_passphrase; use openssh when the same key works with ssh -i or an agent but libssh2 rejects it. For key auth, the public key path is the matching .pub file, the private key path is the identity file without .pub, and the remote user must already have the public key in ~/.ssh/authorized_keys. SSH passwords, key paths, and optional key passphrases are stored in config/local.json.

If OpenSSH reports No ED25519 host key is known ... Host key verification failed, authentication has not started yet. Add the host key to the known_hosts file shown in the Other Devices details, or use auto/libssh2 for stored key passphrases.

Internet Exposure

The optional Internet Exposure card on the main dashboard lists configured public-facing services and classifies them as Protected, Warning, Danger, Closed, or Unknown. It uses short PHP socket checks from the dashboard host, does not run nmap, does not require root, and does not scan arbitrary remote hosts unless a service entry explicitly sets scan_remote.

Example config:

Backend services use local listener binding from ss -ltnH or netstat -ltn; localhost-only backends are treated as protected, while wildcard or LAN/public binds are flagged. This is a lightweight visibility tool, not a replacement for a real external scan. Validate the public attack surface occasionally from another network. A read-only helper can write the latest status to state/internet_exposure_status.json:

Visitors Collector

Run the local visitor collector from cron:

The collector reads configured logical sources only, writes latest status to docs/visitors.md for GeoIP setup, privacy notes, and troubleshooting.

Navigation Order

Top-level admin navigation order is defined by the feature registry in config.php by dragging items in the Navigation Order block and saving.

If you prefer to edit it manually, the saved override is stored under ui.nav_feature_order in config/local.json.

Logs: Copied And Live Privileged

The existing Logs page still keeps the copied-log mirror under state/logs_mirror. That workflow is unchanged and remains the default view.

The same page now also includes an in-page switcher for Copied Logs and Live Privileged Logs. No new header tab was added. The live mode is for admin users only and reads selected protected logs on demand without making /var/log world-readable and without running PHP or the web server as root.

For the copied-log workflow, the separate log-watcher mirror should run as root and then write mirrored files back with the configured destination owner. That preserves the quick copied-log view for current root-owned service and vhost logs without changing permissions on the source files.

Security Model

• Browser input is limited to an allowlisted logical key such as syslog or nginx_error.
• logs.php validates the admin session, applies CSRF checks, clamps line counts, and calls one exact sudo target.
• scripts/log_bridge.sh is the only root-executed entrypoint. It accepts only --key, --mode, --lines, and --search.
• The bridge resolves keys from config/privileged_logs.json, allows only configured file or journal sources, treats search as a literal string, and never accepts raw paths or arbitrary commands from the web app.
• Sudo is scoped to the exact bridge script through a sudoers drop-in. There is no general shell execution path from the dashboard.

Allowed Sources

The default allowlist currently includes:

• exim_main
• exim_reject
• nginx_error
• nginx_access
• syslog
• auth
• fail2ban

Each entry defines its label, internal key, source, whether literal search is allowed, and default/max line counts in config/privileged_logs.json.

Sudoers Setup

The live privileged-log mode only works after an admin explicitly allows the web user to run the exact bridge script through sudo.

Do not place the helper script itself in /etc/sudoers.d/. The helper only prints the sudoers rule. The file in /etc/sudoers.d/ must contain sudoers syntax, not shell code.

1. Confirm the actual PHP/web user on the host. On Hestia-style single-user installs this may be your hosting account name, for example user:user. On more typical setups it may be www-data, apache, or similar.

2. Generate an example drop-in for that exact web user:

3. Copy the printed rule into /etc/sudoers.d/server-dashboard-log-bridge.

Example content:

4. Set the correct permissions and validate it before enabling it:

5. Test the bridge directly from shell before trying the UI:

6. Open the existing Logs page, switch to Live Privileged Logs, pick an allowlisted source, and refresh.

The expected rule should allow only the exact bridge script path. It should not allow arbitrary shell commands, arbitrary arguments, or a directory wildcard. Example:

For a Hestia-style install where the PHP user is a hosting account such as user, the practical commands still follow the same pattern:

If the direct sudo -n ...log_bridge.sh ... command fails, fix that first. The web UI depends on the same exact bridge invocation.

Extending The Allowlist

To add another protected log:

1. Add a new entry to config/privileged_logs.json.
2. Use a new logical key; do not expose raw file paths in the browser.
3. Set source.type to file with an absolute path, or journal with a fixed unit name.
4. Keep max_lines conservative and only enable allow_search when it is operationally useful.

Troubleshooting

• If live reads fail with a sudo error, the sudoers drop-in is missing, invalid, or uses the wrong web user.
• If the shell says syntax error near unexpected token '(', you pasted a sudoers rule into bash instead of saving it into /etc/sudoers.d/....
• If visudo -cf fails with input in flex scanner failed, the sudoers file likely contains the helper shell script or stray markdown/prompt text instead of a single sudoers rule.
• If a log key is denied, verify the key exists in config/privileged_logs.json and matches the UI selection.
• If a source is missing, confirm the underlying host actually has that log file or journal unit.
• If copied logs work but live logs do not, that usually means the new bridge path is not executable or not allowed in sudoers.
• If the UI reports This privileged log request was denied., test the exact same bridge command directly with sudo -n ...scripts/log_bridge.sh .... If that direct call fails, the problem is in the bridge or host log source, not the page wiring.
• If the bridge rejects every request with Denied: invalid search literal., make sure you are using the current repo version of scripts/log_bridge.sh. Older copies had a bad null-byte check that falsely rejected empty searches.

Security Notes

• Keep security.allow_web_bootstrap_admin=false after the first admin exists.
• Treat config/local.json, data/cron_token.txt, and generated env files as sensitive.
• Cron helper jobs shown in cron.php no longer embed a cron token in their URLs.
• Rotation events for legacy cron-token compatibility are logged to data/logs/security.log.
• If the app sits behind a reverse proxy, set security.trusted_proxies.
• Persisted audit metadata, support bundles, and exported config payloads now redact sensitive values by default through lib/Redaction.php.

Incident And Service Drill-Down

The dashboard now correlates related alert floods into incidents instead of forcing operators to interpret each alert in isolation.

• Correlation rules live in config/incident_rules.json.
• The existing History page now includes a Recent Incidents section.
• Incident detail lives at incident.php and merges alerts, service state changes, audit events, backup actions, and speedtest anomalies into one timeline.
• Services now link to service_detail.php, which aggregates current status, recent failures, restart/recovery history, related incidents, relevant logs, and recent admin actions.

This is an in-place operational drill-down. No new top-level nav item was added.

Audit Logging

The structured admin audit stream now lives in:

• state/logs/admin_audit.log

It complements the existing security and diagnostics logs and records:

• config changes
• config export/import actions
• privileged log reads
• service actions
• backup actions
• restore verification runs
• support bundle generation

The admin-facing view remains tools/admin_audit.php.

Restore Verification And Support Bundles

The existing Backups page now contains a compact Restore Verification & Support section.

• Run Verification performs conservative artifact checks through state/backup_restore_verification.json.
• Build Support Bundle creates a redacted ZIP through state/support_bundles.

Current verification is intentionally conservative: it reports integrity-verified, not a destructive restore test.

Documentation

The Config page includes a Documents tab before About for browsing local files in docs/.

Current documentation starts at docs/README.md and is organized into:

• docs/INSTALL.md
• docs/CONFIG.md
• docs/ADMIN.md
• docs/pages/ai.md
• docs/config-tabs/
• docs/pages/

Diagnostics And Reporting

• Environment doctor: diag.php
• Basic health endpoint: api/health.php
• Assets audit: tools/assets_audit.php
• Admin audit: tools/admin_audit.php
• Cron token admin API: api/cron_token_admin.php
• Monthly uptime summary export: api/report_uptime.php

The uptime report uses stored probe history and currently focuses on:

• time-weighted up/down intervals
• per-service uptime percentage with coverage percentage
• average/max latency
• CSV/HTML export for handoff or archive

The History page also includes lightweight System Hardware history. The normal history cron/probe path records CPU/load, memory, and disk samples into data/hardware_history.jsonl.

The diagnostics page groups checks into PASS, WARN, and FAIL so environment problems are actionable instead of just raw dumps. Admin shortcuts open the health endpoint and audit tools in modals.

Top-level feature pages are controlled from Config -> Features. Unchecking a feature removes its header tab and returns a disabled response for direct page requests until it is re-enabled.

Testing

Recommended local verification sequence:

Add browser smoke after JS or page-behavior changes:

Current browser smoke covers:

• dashboard load
• config UI load
• history load
• logs page mode switching
• incident list/detail flow
• service detail drill-down
• backups verification/support panel render
• speedtest page render

PHP lint:

Install test dependencies:

Run PHPUnit:

Run the lightweight admin smoke probe:

Expected result:

• one [OK] line for each maintained endpoint/page check
• exit code 0 on success
• any [FAIL] line or invalid JSON causes a non-zero exit

Run the browser smoke checks for the key admin pages:

Expected result:

• browser smoke passed: diag
• browser smoke passed: config
• browser smoke passed: history
• browser smoke passed: speedtest

Expected skip result in restricted environments:

• browser smoke skipped: no Chrome/Chromium binary found
• browser smoke skipped: local TCP listener unavailable in this environment

Those skip cases are environment limitations, not app failures.

Format check:

The PHPUnit baseline is intentionally small. It covers:

• shared helper behavior
• config bootstrap assumptions
• config mutation and compatibility sync
• uptime report interval math
• smoke checks for critical JSON endpoints
• page rendering for maintained admin tools

The browser smoke script loads the real pages through a local php -S server and verifies:

• diag.php renders the doctor UI
• config.php renders the Security tab token controls
• history.php opens the HTML report modal
• speedtest.php changes visible rows when the page-size selector changes

There is also an admin-facing audit viewer at tools/admin_audit.php for recent security and diagnostic actions already written to:

• data/logs/security.log
• state/logs/diag_audit.log

Security log entries are created by token-management actions such as reveal authorization and token rotation. Diagnostic log entries are created by server-test actions and related manual diagnostics.

There is still a legacy full-repo formatting backlog. CI enforces a maintained-file formatting baseline introduced in this hardening pass instead of gating on untouched historical files.

CI

The repository now includes .github/workflows/ci.yml with:

• composer install --no-interaction --prefer-dist
• npm ci
• PHP lint
• maintained-file Prettier baseline
• PHPUnit smoke/unit tests
• browser smoke checks for key admin pages

This is a floor, not a full release pipeline.

Screenshots

Existing screenshots live under:

• assets/images/screenshots/main.png
• assets/images/screenshots/config.png
• assets/images/screenshots/history.png
• assets/images/screenshots/services.png
• assets/images/screenshots/logs.png

Roadmap Summary

Near-term work that still makes sense:

• broader token and secret inventory management
• more probe/alert reporting views
• additional PHPUnit coverage around config mutation and auth flows
• smoke probes for more admin APIs
• stronger release/update docs
• follow-up hardening on writable state and backup flows