Web interface

Documentation index

The web interface at http://<server>:23300/ displays a dark teal title bar with the caption “Vigilent since October 2026” and a Drive Configuration table. Enter existing absolute server paths in Source directory and Target directory. Subdirectories may have different names, for example /disk1/archive/incoming/movies and /disk2/inbox/media-center. Click Check directories to inspect the detected mounts, filesystem UUIDs, stable drive IDs, and space readings. After reviewing the direction, click Save directories. Editing either field requires another check. Saving rechecks the directories, updates mirroring and SMART monitoring together, and retains the schedules and email settings. It changes the next scheduled sync; files absent from the source are deleted from the target. See data synchronization for supported drives and safeguards. The Role column labels Disk 1 as Source and Disk 2 as Target. Backing filesystem capacity, used space, and free space are shown in decimal TB (1 TB = 1,000,000,000,000 bytes), rounded to two decimal places. Reload the page to refresh the readings. Missing mounts, changed identities, and failed usage readings display “Unavailable” with a reason. Space readings describe the backing filesystem, not the size of the selected directory. The Disk Health panel reads the latest saved check results and displays their timestamp in server local time (YYYY-MM-DD HH:MM:SS), each disk’s status and details, and email delivery failures. No recorded result and unreadable or corrupt results have explicit messages. Most recent health check output opens a separate page with the saved timestamp, health summary, both disks’ raw SMART output, and any email delivery failure. The Health Check Schedule section reads the installed cron entry to populate Enabled and Cron Schedule. Edit the five-field expression and click Update to save it. Uncheck Enabled and click Update to remove the job. An absent job shows an empty schedule. Times use the server’s timezone. In Disk Health, click Run Now to request a background health check, then reload to see its completed result. Checks retain their email alerts and overlap protection. The button is disabled when monitoring is disabled or settings are unavailable. Data Sync Schedule appears below Health Check Schedule with the same Enabled, Cron Schedule, and Update controls. It defaults to every four hours (0 */4 * * *) and reads its installed cron entry on each page load. Sync Now, beside Update, requests a background sync with the saved settings. The button is disabled when scheduling is disabled. Most recent sync output opens a separate page showing the latest rsync output, timestamps, and success or failure. See data synchronization for configuration. The final Email Notification section shows Contact, the configured alert recipient. Click Email Health Check to request a fresh, verbose SMART report for both disks, including healthy disks. The request runs in the background, waits for an active health check, and works when the cron schedule is disabled. Reload Disk Health after completion to see the latest results and any email delivery failure. The email button is disabled when mail settings are missing or unavailable. See disk health for scheduling. It listens on all IPv4 interfaces and requires no third-party Python packages.

Install and manage

On a Linux host with Python 3.10 or newer, systemd with LoadCredential support, cron with the crontab command, and a running local MariaDB server with the mariadb client, run from the checkout. Enabled monitoring also needs smartctl and msmtp with a configured credential file. Directory selection requires findmnt, lsblk, and smartctl. Enabled synchronization also requires rsync. Root must be able to connect to MariaDB through Unix socket authentication. Schedule controls and manual checks also require sudo and visudo.

sudo scripts/install.sh
sudo scripts/upgrade.sh
sudo scripts/restart.sh

Installation bundles the server and its page into /opt/prod/diskha/bin/disk-ha-web, deploys the Python package and readable CMDB metadata, and enables disk-ha-web.service at boot. The service runs under the persistent diskha account; serving this page requires no root privileges. The root helper reads directory and filesystem metadata; the Web UI does not read file contents.

Register DiskHA (case-sensitive) through CMDB’s Add Application. Discovery reads /opt/prod/diskha/diskha/constants/DDiskHA.py for the installed version, type, subtype, supplier, release codename, configuration and saved-data directories, and local MariaDB catalog reference. CMDB_NETWORK declares the default HTTP listener; CMDB network collection is not yet implemented. Development checkouts are not discovery targets.

When upgrading an installation at /opt/prod/disk-ha, the installer creates /opt/prod/diskha as a symlink to that directory. Configuration, credentials, data, worker locks, and the account’s existing home stay in place; services and cron commands use the new path. If both paths exist and refer to different directories, installation fails before changing saved state. Reconcile them before retrying. If the legacy account remains after both installation directories were removed, reinstallation restores its home as an alias to /opt/prod/diskha.

Accounts and database

Installation creates the diskha Linux system account and group with a non-login shell and no separate home directory. Application code stays root-owned; /opt/prod/diskha/data/ belongs to root and the diskha group with mode 0750. Root runs scheduled health checks and writes results with mode 0640; the Web UI account has read access. The root-owned disk-ha-health.service runs manual checks; disk-ha-email-report.service runs requested email reports; disk-ha-sync.service runs manual syncs through the same guarded worker as cron. Validated rules in /etc/sudoers.d/disk-ha-health let diskha start these services and call the disk-ha-schedule helper to read or update only disk-ha’s marked root cron entry. The helper validates settings, detects and saves selected directory identities, preserves unrelated jobs, and keeps the workers consistent with GUI updates. It also supplies the configured contact address to the page. The Web UI cannot read mail credentials. The Web UI is intended for a trusted network; users with page access can update schedules, select source and target directories, and request checks or syncs.

Following the BMDynIP provisioning pattern, installation creates:

• MariaDB database diskha, using utf8mb4 with utf8mb4_bin collation.
• Local MariaDB account 'diskha'@'localhost' with a generated password.
• Root-owned credentials at /opt/prod/diskha/conf/database.env, mode 0600, inside the root-only conf/ directory.

The database account receives SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, and REFERENCES privileges on diskha only. The database currently has no application tables.

Systemd supplies a private copy of database.env to the service through LoadCredential; the service can read it under $CREDENTIALS_DIRECTORY. The page does not query the database yet.

Upgrade validates and retains saved credentials. If the credential file is missing, installation generates a new password for the local application database account while preserving the database. Uninstall preserves both accounts, the Linux group, the database, credentials, and saved data.

Listener configuration

DDiskHA.CMDB_NETWORK defines the http listener’s defaults: 0.0.0.0:23300. Installation creates /opt/prod/diskha/conf/diskha.json from those defaults only when missing. Reinstall, upgrade, and uninstall preserve an existing file. The root-only configuration is delivered to the service through LoadCredential.

For example, to listen only on loopback:

{
  "network": {
    "http": {"interface": "127.0.0.1", "port": 23300}
  },
  "request_timeout": 15
}

A missing file, omitted listener, or omitted field uses the declared defaults. The request timeout defaults to 15 seconds. Interfaces must be IPv4 addresses; ports must be integers from 1 to 65535. Unknown settings and invalid JSON fail with the configuration filename. Settings are read once at startup. --config <path> selects a different JSON file; --host and --port override resolved settings for one invocation.

After editing, run sudo scripts/restart.sh from the checkout. It validates the configuration before restarting the service, then checks readiness at the resolved address and port. A wildcard binding uses loopback for the local readiness request. The former conf/web-interface.cfg format is no longer read or migrated; configure the new JSON file when installing this update.

Service checks

Check readiness and logs:

curl --fail http://127.0.0.1:23300/ready
systemctl status disk-ha-web.service
journalctl -u disk-ha-web.service

Remove the service and application with sudo scripts/uninstall.sh. Upgrade and removal preserve configuration, credentials, and saved data in /opt/prod/diskha/conf/ and /opt/prod/diskha/data/.

Run from a checkout

python3 -m diskha.server

Use --host 127.0.0.1 to listen locally or --port <port> to override the port. Stop the foreground server with Ctrl+C.