Repository navigation
Advanced Configuration
This page adds optional security, enrichment, and tuning after the default API-only startup works.
The default setup has no login. Anyone who can reach the published main or admin port can use the controls available there.
Browser mutation requests must come from the same origin in both modes. Network mode derives that origin from the requested address, so it needs no extra setting. Use the explicit public-origin settings when a reverse proxy changes the address seen by the services.
Enable built-in Basic authentication when reachability is broader than the people who should control the app:
ADMIN_AUTH_MODE=basic
ADMIN_AUTH_USERNAME=operator
ADMIN_AUTH_PASSWORD=replace-with-a-long-random-password
APP_PUBLIC_ORIGIN=https://storage-ui.example.test
ADMIN_PUBLIC_ORIGIN=https://storage-admin.example.testIn Basic mode, the same username and password protect all admin pages and the write controls in the main UI. Main-UI inventory and history reads remain available without a login. Set each origin to the exact scheme, host, and port shown in the browser. Basic mode refuses to start the admin service when its origin is missing or invalid.
Each main-UI page starts signed out. The in-page sign-in keeps credentials in page memory and clears them on reload or sign-out. Basic credentials are only encoded, not encrypted, so use HTTPS or an encrypted VPN.
An HTTPS reverse proxy protects credentials in transit and can provide another authentication layer. Firewall rules and network segmentation reduce who can reach the ports, but reachability still grants access to every enabled control when built-in or proxy authentication is absent. Do not publish the app ports directly to the Internet.
The first-run default accepts a self-signed appliance certificate without
verifying it. To verify the TrueNAS certificate, copy the CA certificate that
signed it into the app's config/tls folder:
mkdir -p config/tls
cp /path/to/truenas-ca.pem config/tls/truenas-ca.pem
chmod 0644 config/tls/truenas-ca.pemThen add these settings to .env:
TRUENAS_VERIFY_SSL=true
TRUENAS_TLS_CA_BUNDLE_PATH=/app/config/tls/truenas-ca.pem
TRUENAS_TLS_SERVER_NAME=truenas.example.testUse the DNS name on the certificate for TRUENAS_TLS_SERVER_NAME.
The app supports:
- a simple single-system env-driven flow
- a richer multi-system YAML config
If you want the optional history sidecar or the offline snapshot export flow, use:
If you want one app instance to manage multiple hosts, use systems: in
config/config.yaml.
default_system_id: archive-core
systems:
- id: archive-core
label: Archive CORE
default_profile_id: supermicro-cse-946-top-60
truenas:
host: https://archive-core.example.local
api_key: ""
platform: core
verify_ssl: true
ssh:
enabled: true
host: archive-core.example.local
user: jbodmap
key_path: /run/ssh/id_truenas
strict_host_key_checking: true
commands:
- /sbin/glabel status
- /usr/local/sbin/zpool status -gP
- gmultipath list
- sudo -n /usr/sbin/sesutil map
- sudo -n /usr/sbin/sesutil show
- id: offsite-scale
label: Offsite SCALE
enclosure_profiles:
"5003048001c1043f": supermicro-ssg-6048r-front-24
"500304801e977aff": supermicro-ssg-6048r-rear-12
truenas:
host: https://offsite-scale.example.local
api_key: ""
platform: scale
verify_ssl: true
ssh:
enabled: true
host: offsite-scale.example.local
user: jbodmap
key_path: /run/ssh/id_truenas
strict_host_key_checking: true
commands:
- /usr/sbin/zpool status -gP
- /usr/bin/lsblk -o NAME,TYPE,SIZE,MODEL,SERIAL,TRAN,HCTL
- /usr/bin/lsscsi -g
- sudo -n /usr/bin/sg_ses -p aes /dev/sg27
- sudo -n /usr/bin/sg_ses -p aes /dev/sg38
- sudo -n /usr/bin/sg_ses -p ec /dev/sg27
- sudo -n /usr/bin/sg_ses -p ec /dev/sg38Useful app-level settings:
app:
port: 8080
refresh_interval_seconds: 30
snapshot_cache_ttl_seconds: 10
source_bundle_cache_ttl_seconds: 60
smart_cache_ttl_seconds: 300
sg_ses_device_cache_ttl_seconds: 300
log_level: INFO
debug: falsesnapshot_cache_ttl_seconds controls how long rendered inventory snapshots
stay warm.
source_bundle_cache_ttl_seconds controls how long the heavier API/SSH source
payload stays warm. Leave this at least as high as the snapshot cache on
appliances with low SSH MaxStartups limits.
smart_cache_ttl_seconds controls selected-slot SMART detail reuse.
sg_ses_device_cache_ttl_seconds controls how long discovered Linux/SCALE/SES
device paths stay warm before rediscovery.
Older configs can still use cache_ttl_seconds; when the newer split fields
are not set, that legacy value feeds the snapshot and source-bundle caches.
Smaller:
- fresher view
- more load
Larger:
- less load
- slightly more stale view
Treat SSH command lists as:
- standing inventory commands
and treat things like these as:
- on-demand per-slot enrichment commands
Examples:
smartctlnvme smart-lognvme id-ctrlnvme id-ns- LED identify actions
That split helps keep the standing SSH probe lighter.
Inventory refreshes batch configured commands and dynamic enrichment through one SSH session per target where possible, but operators should still keep refreshes friendly to storage appliances:
- keep
refresh_interval_secondsat30or higher unless you are actively debugging - prefer
source_bundle_cache_ttl_secondsof60or higher for appliances with low SSH startup limits - keep optional SMART and LED actions on demand instead of adding every possible
per-disk command to the standing
ssh.commandslist - SMART detail probes batch JSON plus text enrichment per device and serialize SSH sessions per saved system; after a connection startup failure, optional SSH batches pause briefly before retrying
- use
ssh.extra_hostsonly for real HA/peer fallback paths; stale or duplicate hosts can still add avoidable connection attempts - watch app logs for SSH refresh command counts, failure counts, and duration after changing cache or command settings
Mappings are stored in JSON on the bind-mounted data path.
That means:
- they survive container rebuilds
- they are easy to back up
- they can be exported and imported in the UI
Mappings saved by older releases were stored without the system and enclosure they belong to. On a deployment with more than one configured system, or more than one detected enclosure, such a row cannot be tied to a specific shelf, so the app no longer resolves it: it could otherwise label or light up the wrong physical disk on another shelf. Those bays render unmapped after the upgrade.
Nothing is deleted. The rows are still in the mapping file. To bring one back, open the bay and save the mapping again. The save writes the current system- and enclosure-scoped key and removes the old unscoped aliases for that bay. Deployments with a single system and a single enclosure are unaffected, because there is nothing to disambiguate.
If you are running the optional history sidecar, the main retention knobs are:
HISTORY_BACKUP_DIRHISTORY_BACKUP_RETENTION_COUNTHISTORY_LONG_TERM_BACKUP_DIRHISTORY_WEEKLY_BACKUP_RETENTION_COUNTHISTORY_MONTHLY_BACKUP_RETENTION_COUNTHISTORY_RAW_METRIC_RETENTION_DAYSHISTORY_EVENT_RETENTION_DAYSHISTORY_HOURLY_ROLLUP_RETENTION_DAYSHISTORY_DAILY_ROLLUP_RETENTION_DAYSHISTORY_RETENTION_INTERVAL_SECONDSHISTORY_RETENTION_BATCH_SIZEHISTORY_RETENTION_MAX_BATCHES_PER_RUN-
HISTORY_SEGMENT_CATALOG_PATHfor an already migrated segmented deployment
The default behavior is:
- keep short-term rotating SQLite snapshots under
./history/backups - keep
4weekly promoted copies - keep
3monthly promoted copies - keep raw metric samples for
30days and slot events for365days - keep hourly metric rollups for
365days and daily rollups for1825days - run retention hourly in at most
20transactions of5000rows per table
Set any of the four retention-day values to 0 to keep that data tier forever.
Each retention transaction commits separately, so a stop or restart resumes from
the remaining rows instead of restarting one large delete. The collector starts
retention only after creating a backup successfully in the same slow pass.
SQLite reuses pages
released by pruning. The database file therefore plateaus near its high-water
size rather than shrinking after every pass; retention does not run VACUUM or
replace the live database.
History queries combine retained raw values with hourly and daily rollups. Temperature and annualized-rate rollups use the sample-count-weighted average; cumulative byte and power-on-hour counters use the latest value in each bucket. Slot events remain discrete records and are unavailable before the configured event-retention cutoff.
When HISTORY_SEGMENT_CATALOG_PATH is set, retention modifies only the writable
hot database. Immutable segments are never edited in place. Segment removal or
compaction requires a new complete catalog generation with matching tombstones
and supersedes declarations. V1-only history backup/restore and system-wide
delete, purge, or adopt operations fail closed while segmented history is
active.
If you want longer-lived copies on a different disk or NAS later, point
HISTORY_LONG_TERM_BACKUP_DIR at that mounted path and leave the short-term
local backup path alone.
Use enclosure_profiles when:
- a system has front and rear SES IDs
- you want deterministic profile selection
- you want to prevent generic runtime profile fallback
Prefer custom YAML when:
- the geometry is new
- the slot ordering is new
- only the presentation is different
Prefer code only when:
- a whole new inventory adapter is needed
- the host needs new parser logic
- the UI model itself must change
Getting Started
Platform Guides
Feature Guides
- Live Enclosures and Storage Views
- Heat Map Mode
- History and Snapshot Export
- Admin UI and System Setup
- Demo and Offline Workflows
- Public Demo Site
- History Maintenance and Recovery
Operations and Configuration