vps/runbooks/home-assistant-maintenance.md

Runbook: Home Assistant maintenance (hass.windy.lan)

Target: hass.windy.lan (HAOS, machine: green) Upstream: HAOS 18.1 / Core 2026.8.x / Supervisor 2026.07.5 (verified 2026-08-13)

This runbook covers routine Home Assistant maintenance through the ha supervisor CLI. All commands are wrapped by a single script scripts/ha-maintenance.sh; the sections below document the exact commands it runs, for manual/agent use.

Access pattern

ha authenticates to the Supervisor with SUPERVISOR_TOKEN. Interactive SSH login works because ~hassio/.zprofile runs exec sudo -i; the root login environment carries the token. Non-interactive use must be:

ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i ha <cmd>'

Running ha as hassio directly (or sudo -n without -i) returns unauthorized: missing or invalid API token.

MOTD: every sudo -n -i login prints the SSH & Web Terminal MOTD banner. The script runs its whole procedure in one remote login (sudo -n -i bash -s) so the banner appears once, then strips it with awk up to the System is ready! Use browser or app to configure. line.

Script usage

cd runbooks/scripts

./ha-maintenance.sh                                # read-only health snapshot
./ha-maintenance.sh --check-config                 # validate core configuration
./ha-maintenance.sh --logs core 200                # tail core logs
./ha-maintenance.sh --logs supervisor              # tail supervisor logs (default 100)
./ha-maintenance.sh --logs host 50                 # tail host journald logs
./ha-maintenance.sh --logs apps:<slug>             # tail an add-on log

# Mutating — refuse to run without --yes:
./ha-maintenance.sh --update --yes                 # refresh + update core(--backup)/supervisor/os
./ha-maintenance.sh --restart-core --yes           # restart Core
./ha-maintenance.sh --restart-core --safe-mode --yes   # restart Core in safe mode
./ha-maintenance.sh --rebuild-core --yes           # rebuild Core image (after options change)
./ha-maintenance.sh --rollback-os --yes            # boot previous OS slot (A/B rollback)
./ha-maintenance.sh --reboot --yes                 # reboot the HAOS host
./ha-maintenance.sh --backup [NAME] --yes          # full backup (optionally named)
./ha-maintenance.sh --restore <slug> --yes         # restore a backup (DESTRUCTIVE)
./ha-maintenance.sh --app restart core_mosquitto --yes   # add-on lifecycle

• --app action is one of start|stop|restart|update; needs an add-on slug.
• HA_HOST / HA_SSH_USER override the defaults (hass.windy.lan / hassio).
• --restore overwrites the current installation — run only from a planned recovery, with the backup verified.

Command reference (verified 2026-08-13)

All verified against the live host. MOTD prepends each command's output; strip with the awk pattern above or read the last block.

Routine / read-only

Purpose	Command
General overview	ha info
Core version/status	ha core info
Core config validation	ha core check
Core stats	ha core stats
Supervisor status	ha supervisor info (incl. add-on list)
Supervisor stats	ha supervisor stats
OS status	ha os info (boot slots A/B)
Host status	ha host info (disk free/total, kernel)
Network	ha network info (supervisor_internet)
Hardware	ha hardware info
Pending updates	ha available-updates
Reload stores/versions	ha refresh-updates
Job manager	ha jobs info
Resolution center	ha resolution info
Core logs	ha core logs -n 100 (-f follow, -b boot id)
Supervisor logs	ha supervisor logs -n 100
Host journald logs	ha host logs -n 100
Add-on logs	ha apps logs <slug> -n 100
Add-on list	ha supervisor info → addons: (started/stopped/error)
Security integrity	ha security integrity

Mutating (require --yes)

Purpose	Command
Update core (with partial backup)	ha core update --backup
Update supervisor	ha supervisor update
Update OS	ha os update
Update add-on	ha apps update <slug>
Restart core	ha core restart / ha core restart --safe-mode
Rebuild core	ha core rebuild
OS rollback	ha os boot-slot other
Reboot host	ha host reboot
Full backup	ha backups new [--name NAME]
Restore backup	ha backups restore <slug>
Add-on start/stop/restart	ha apps start|stop|restart <slug>

Procedure

1. Health snapshot (read-only)

./ha-maintenance.sh

Review: supervisor healthy: true/supported: true; core/OS update_available; add-on states (any state: error?); resolution info issues; disk free.

2. Validate config after any configuration.yaml change

./ha-maintenance.sh --check-config

Expect Command completed successfully. before a Core restart.

3. Inspect logs

./ha-maintenance.sh --logs core 200
./ha-maintenance.sh --logs supervisor
./ha-maintenance.sh --logs apps:core_mosquitto

4. Apply updates (mutating)

./ha-maintenance.sh --update --yes

Runs refresh-updates → core update --backup (partial backup first) → supervisor update → os update, then re-prints pending updates. Prefer the web UI (Settings → System → Updates) for a human-supervised pass.

5. Recovery operations (mutating, only when needed)

./ha-maintenance.sh --restart-core --safe-mode --yes   # start Core without custom integrations
./ha-maintenance.sh --rollback-os --yes                # OS update broke boot? go back one slot
./ha-maintenance.sh --restore <slug> --yes             # full restore; overwrites current install

OS update policy: HAOS uses two boot slots (A/B); ha os info shows which slot booted. After a bad OS update, ha os boot-slot other boots the previous slot.

6. Backup before major changes

./ha-maintenance.sh --backup pre-migration --yes       # named backup

Command families intentionally NOT scripted

These exist in ha but are either rare, dangerous, or better done in the web UI; documented here so nothing is a surprise. Use ha <family> --help on the host for exact syntax.

Family	Notes
ha audio	Audio device management; peripheral.
ha authentication	auth list/reset/cache; user password ops — do in web UI. auth list is local-terminal only.
ha cli	Internal CLI backend info/update; self-maintained.
ha dns	Internal DNS server; only relevant if Supervisor DNS add-on in use.
ha docker	Host Docker backend info/options/registries; HAOS-managed.
ha mounts	Network storage (NFS/CIFS) mounts — configure in Settings → System → Storage.
ha multicast / ha observer	Internal services; self-maintained.
ha network scan/update/vlan	WiFi AP scan & interface config — prefer web UI networking.
ha host disks/options/shutdown/reload	Disk ops / host options; shutdown is equivalent to --reboot but off.
ha os datadisk list/move/wipe	Data-disk migration; wipe is local-terminal only and erases all data.
ha os import	Import config from USB stick.
ha os boards / os config	Board / OS settings.
ha core options / supervisor options	Core/OS config options (e.g. --duplicate-log-file); changes need ha core rebuild + restart.
ha backups freeze/thaw/remove/options	Freeze/thaw for external backup tools; removal is destructive.
ha jobs options/reset	Job-manager tuning.
ha resolution check/healthcheck/issue/suggestion	Resolution center management; healthcheck runs fixups.
ha store add/delete/repair	Repository management — add repos in web UI app store.
ha security info/options	Security backend options.

Docs vs actual CLI discrepancies

The official HAOS common-tasks docs reference ha backups list and ha host update. Neither exists in the installed CLI (2026-08-13): backups are inspected with ha backups info <slug> (a slug is required) and host has no update subcommand. Trust the server CLI (ha <cmd> --help) over the docs.

Known issues on hass.windy.lan (2026-08-13)

All items from the original 2026-08-13 health snapshot were resolved same day (W1N-70/71/72/73/74/75/76): OTBR and the duplicate SSH add-on uninstalled, all resolution-center issues cleared (ha resolution info → empty), full backup pre-maintenance-20260813 (slug 411a4ba5) taken. Remaining known issues (documented in hosts/hass.windy.lan.md):

• Bluetooth hci0 instability (RTL8821CS): bluetooth_auto_recovery power-reset times out every ~2 min; kernel hci0 hardware error. No BLE entities exist, so no user impact. HAOS image ships x88-bt-hci-recovery workaround units.
• host info reports disk_life_time: 10 (boot eMMC ~10% life left) — monitor on each snapshot; plan disk replacement / data-disk migration.

Pass criteria

• Health snapshot completes; supervisor healthy/supported: true
• Mutating modes refuse to run without --yes (incl. --restore, --app)
• --check-config returns success
• Update / rollback / restore / reboot confirmed only after explicit --yes
• Update the Verified line on hosts/hass.windy.lan.md