vps/runbooks/home-assistant-maintenance.md

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

Target: [hass.windy.lan](../hosts/hass.windy.lan.md) (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`](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:

```bash
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

```bash
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)

```bash
./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

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

Expect `Command completed successfully.` before a Core restart.

### 3. Inspect logs

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

### 4. Apply updates (mutating)

```bash
./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)

```bash
./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

```bash
./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](https://www.home-assistant.io/common-tasks/os/)
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](../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](../hosts/hass.windy.lan.md)