TA-ProxMenu/README.md

# TA-ProxMenu

Interactive installation and configuration helpers used when deploying Proxmox
VE environments.

## Install

Run as `root` on a Proxmox VE host:

```bash
bash <(curl -fsSL https://tagit.technologyarch.com/TAI/TA-ProxMenu/raw/branch/main/install-ta_proxmenu.sh)
```

The installed launcher loads TA-ProxMenu's bundled defaults and colors, then
opens the interactive menu. Updates are installed only when explicitly
selected or requested with `tapm update`.

On a clustered Proxmox host, both `tapm update` and the management-menu update
update every online cluster node over Proxmox's root SSH trust, then update the
initiating node. Each node independently performs the same clean-worktree,
branch, and fast-forward safety checks. Offline, unreachable, dirty, ahead, or
diverged nodes are never overwritten and are reported as failures. Standalone
hosts retain the local-only update behavior. The menu reloads the locally installed
code and version after an update attempt, including when another node fails.
Failures remain visible until you press Enter to continue.

Legacy installations automatically update from the published `main` branch.
On their first launch after receiving this version, control is handed to the
current preloader so the new startup configuration and registration procedures
run before the menu opens.

The TAPM Management menu can safely switch TA-ProxMenu between branches published on
its Git origin. Branch switching is refused when the installed repository has
local changes or when the destination branch has commits that would be
discarded.

## Menu presentation

Menus use cyan for the selection and task prompts, muted context and navigation
help, and text labels alongside success, warning, and error colors. A `>` on the
right of an item marks a submenu. Extra context appears below the selected item.
Menus and disk reports share a 75-column maximum and wrap on narrower terminals.
CPU and ISO detail views wrap full values instead of truncating them.
The header stacks host details on narrow terminals and separates update status
from menu actions. Task output replaces the choices while retaining the header.

The shared menu layout and disk report omit ANSI styling when redirected or when
`NO_COLOR` is set. Disk reports separate scan coverage from result counts, group
findings by storage and node, and explain approximate sizes without adding CSV
columns. CSV content and disk classification are unchanged by the presentation.

## Menu organization

- **Host Configuration & Recovery**: TAPM host profile and local Proxmox service recovery.
- **Monitoring & Agents**: Pulse, Glances, supported legacy Dell OMSA, RMM,
  Acronis, SentinelOne, ScreenConnect, and Proxmox notifications.
- **Cluster & High Availability**: host maintenance, cluster VM CPU baseline,
  and the Keepalived floating IP.
- **Storage, ISOs & Backups**: shared ISO storage, Windows VirtIO driver ISOs,
  orphan/unused disk reporting, and local Proxmox backup bandwidth/I/O priority.
- **TAPM Management**: TAPM updates, Git branch selection, and installation information.

Existing direct actions remain compatible. Installed agent entries still run
installers; they do not launch the corresponding application. Host configuration
backups are explicitly identified to distinguish them from guest backups.

## Proxmox notifications

Open **Monitoring & Agents → Proxmox Notifications → Update notification policy**:

- **All available package updates**: use Proxmox's native daily update alerts,
  regardless of subscription status, through the existing notification routing.
- **Proxmox VE version updates only**: notify when a newer Proxmox VE version,
  including a patch release, is available from a host's configured repositories.
- **Disable update notifications**: suppress native daily update alerts.

The policy applies to the Proxmox datacenter, including all cluster nodes.
Selecting a policy displays its scope and requires confirmation before applying.
Other notification types and destination credentials are preserved. Normal
Proxmox repository checks remain enabled; this feature never upgrades packages
or sends an alert confirming that a host was upgraded.

Version-only mode installs an hourly systemd timer on the host where the policy
is applied. This host checks online cluster nodes through the Proxmox API;
standalone hosts check themselves. Repository indexes are refreshed by Proxmox's
existing daily update job, not by the TAPM checker. Kernel-only and other package
updates do not trigger version-only alerts. Checks pause while the checker host
is offline. Reapply the version-only policy on another host to move the checker;
old checkers consult the shared policy and stop sending automatically. Newly
joined nodes are discovered at the next check.

Version alerts include the hostname, installed version, and available version.
They use the existing system-update routing rules and destinations. Configure
recipients and delivery credentials in **Datacenter → Notifications** in the
Proxmox Web UI. TAPM can display the destinations/rules and explicitly send a
chosen destination a test notification. Testing a destination does not test its
routing rules; ensure those rules allow informational system-update events.

The checker records announced versions per node in the private cluster
configuration, so moving the checker preserves its history. Failed sends are
retried on subsequent checks. Submission to the notification subsystem is not
confirmation of delivery; the configured destination and routing must work.
Offline nodes and failed reads are logged and retried without stopping checks
for other nodes. No notification policy is changed merely by installing or
opening TAPM.

Operational files:

- `/etc/pve/priv/tapm-update-policy.json`: shared policy and checker host.
- `/etc/pve/priv/tapm-update-policy.previous.json`: previous policy and native
  notification options, saved before each change for manual recovery.
- `/etc/pve/priv/tapm-update-receipts.json`: announced versions per host.
- `/etc/pve/notification-templates/default/tapm-pve-version-*.hbs`: version alert templates.
- `tapm-version-notifications.timer` and `.service`: checker scheduling; inspect
  results with `journalctl -u tapm-version-notifications.service`.

## Direct actions

The menu script also supports these direct actions:

```text
pulse        Install Pulse monitoring
rmm          Install the ConnectWise RMM agent
omsa         Install legacy Dell OMSA on supported PowerEdge x30/x40 hosts
glances      Install Glances
acronis      Install the Acronis agent
post-install Open the native TAPM host configuration menu
proxmenux     Open TAPM host configuration for migration compatibility
virtio       Download current VirtIO drivers
sentinelone  Install the SentinelOne agent
screenconnect Install the ScreenConnect agent
restart      Restart core local Proxmox management services
cpu          Detect and optionally apply a migration-safe CPU model
maintenance  Toggle local HA maintenance mode
keepalived   Deploy Keepalived across the cluster
iso-nfs      Create an LXC NFS server and cluster-wide shared ISO storage
orphan-disks Report cluster-wide orphan candidates and unused disks (read-only)
```

## Orphaned and unused disks

Open **Storage, ISOs & Backups → Report orphan candidates and unused disks (read-only)**.
The menu offers CSV export after displaying the report. Direct commands:

```bash
tapm orphan-disks
tapm orphan-disks --csv /root/orphan-disks.csv
```

Run as root on a Proxmox node. The report uses `pvesh` and Python 3, inventories
online nodes' storage-managed VM and container volumes, and compares them with
cluster guest configurations in `/etc/pve/nodes`, including offline guests,
snapshots, pending changes, EFI/TPM disks, and detached `unusedN` entries.
Shared storage IDs are scanned once; local storage remains scoped to its node.
Results are grouped by node and storage, with volume IDs and disk
sizes in readable units (MiB, GiB, or TiB). CSV includes both `disk_size` and
`size_bytes`. When Proxmox supplies only `approximate-size`, the display and CSV
show a `~` prefix. Exact sizes take
precedence; unavailable sizes are displayed as `Unknown`.
Backups, ISOs, unmanaged files, and physical/passthrough disks are excluded.

An **Orphan candidate** has no configuration reference. **Unused disk** means
only current `unusedN` entries reference it. Remote-node references and possible
template/clone backing relationships are marked **Needs review**. This is an
inventory, not proof that a volume can be deleted: replication copies, storage
aliases, and backend-specific backing dependencies require review. No guest or
storage changes are made.

Offline nodes, inactive storage, and failed reads are reported as incomplete
coverage; missing guest configurations prevent orphan classification.
Inactive/disabled storage warning lines are hidden in the terminal display.
Changes to guest configurations during the scan require a rerun. Scan when migration,
replication, and disk operations are idle because the inventory is not atomic.
CSV export contains disk rows only, omits coverage warnings, and refuses to
overwrite an existing file.
Export paths without a `.csv` extension receive it automatically. Folder paths
use `tapm-orphan-disks-YYYY-MM-DD-HHMMSS.csv` (local host time), with a numbered
suffix if that generated name already exists. A trailing `/` marks a folder
path and creates it if needed. The final saved path is displayed after export.
Exit status is 0 for a completed scan, 2 for incomplete coverage or changed
configurations, and 1 for a fatal scan/export error.

## Companion files

Large installer artifacts used by this project are stored in the private
`TAI/files` package registry. SentinelOne, RMM, Acronis, and ScreenConnect
installation require a temporary deployment code from TAPM Deployment Access.
The private Git credentials are never stored on or returned to a Proxmox
host. SentinelOne package versions can be updated through the deployment
portal without changing ProxMenu.

## Runtime requirements

- Proxmox VE and root privileges
- Bash, Git, curl, wget, Python 3, and standard Debian package tools
- The bundled `defaults.inc` and `colors.inc` files

The Keepalived deployment additionally requires a healthy, quorate Proxmox
cluster and passwordless root SSH between cluster nodes.

The shared ISO storage wizard creates a privileged Debian LXC with a dedicated
secondary volume, restricts its NFS export to a supplied client CIDR, and adds
the export to Proxmox's cluster-wide storage configuration. The container host
and network path to the container must remain available for nodes to use the
ISO repository.

The legacy Dell OMSA installer is limited to supported PowerEdge x30/x40
systems running Proxmox VE 9 on Debian 13 (Trixie), amd64.

CPU compatibility analysis compares every cluster host's physical processor,
processor generation/family, and supported generic VM CPU baseline. It then previews
QEMU VM and template changes before applying the highest baseline shared by
all nodes through the Proxmox CLI. Running VMs are not restarted automatically.

The native TAPM host configuration workflow replaces the former ProxMenux
post-install dependency. It can audit a host, apply the recommended PVE 9
profile, customize individual items, migrate recognized ProxMenux
configurations, repair ProxMenux's system gzip replacement, and remove
ProxMenux after validation. Every mutating run first creates a timestamped
backup under `/var/backups/ta-proxmenu/post-install`.

The recommended profile installs only missing diagnostic utilities, preserves
the configured timezone and NTP servers, enables conservative kernel and
network safeguards, retains up to 1 GiB or 30 days of persistent journal
history, verifies logrotate, and uses Proxmox's native pigz support without
replacing `/bin/gzip`. APT remains dual-stack by default; its conditional IPv4
compatibility check is optional. Global vzdump bandwidth and I/O-priority
changes are available through a separate explicit menu.

Pulse can also be deployed without installing TA-ProxMenu. Run the standalone
bootstrap as root on a Proxmox VE host:

```bash
bash <(curl -fsSL https://tagit.technologyarch.com/TAI/TA-ProxMenu/raw/branch/main/install-pulse.sh)
```

The bootstrap downloads the Pulse deployment module and its LXC storage helper
from the same branch into a protected temporary directory, validates their Bash
syntax and expected entry points, runs the normal interactive Pulse workflow,
and removes the temporary files afterward. It does not clone or install
TA-ProxMenu. Set `TAPM_PULSE_SOURCE_BRANCH` before running it to use another
branch.

VirtIO downloads are managed from a dedicated submenu. The stable release is
checked only when that submenu is opened, and curated compatibility ISOs are
available for Windows Server 2008, 2008 R2, 2012/R2, and 2016. Downloads are
validated before atomically replacing a file with the same name.

Maintenance evacuation leaves HA-managed guests under Proxmox HA control.
Remaining shared-storage guests are routed to online, non-maintenance nodes
with the required storage, while local-storage guests are gracefully shut
down. HA node-affinity preferences are honored when an eligible node exists.

## Development checks

Run the local validation suite with Bash 4.3 or newer:

```bash
./tests/run.sh
```

The suite checks Bash syntax and Git whitespace, runs ShellCheck when it is
installed, and exercises Git update states, LXC input/storage selection,
maintenance evacuation routing, HA affinity parsing, host-profile migration
signatures and backups, and VirtIO filename validation. Tests use temporary
files and mocked Proxmox output; they do not download installers or change a
Proxmox host.
## Deployment service endpoints

TA-ProxMenu uses the built-in production endpoints:

```text
Broker: https://tapm.technologyarch.com
Git:    https://tagit.technologyarch.com
```

No first-run prompt or `/etc/ta-proxmenu/config.env` file is required. For a
controlled development or test environment only, `TAPM_BROKER_URL` and
`GITEA_DOMAIN` environment variables can override the built-in values for that
process. Repository updates continue to use the installed checkout's configured
Git `origin`.

## Installation registry

TA-ProxMenu creates a random installation UUID and 256-bit credential in
`/var/lib/ta-proxmenu/identity.env`. The directory is mode `0700` and the file
is mode `0600`. The first successful launch enrolls the host with the broker.
Later launches make one best-effort HTTPS call on completion or failure to
record the hostname, duration, result, TA-ProxMenu and Git versions,
PVE/OS/kernel versions, architecture, and whether the host is clustered. A
failed event schedules re-enrollment on the next invocation instead of adding
another retry to the current run. The installation registry does not install a background service, and
broker availability never prevents the menu from running.

Automatic Git update checks and the stable VirtIO release lookup are cached for
24 hours. Their explicit **Check again** and **Refresh** actions bypass the
cache. Installer, package-repository, and vendor download traffic occurs only
after a technician selects the corresponding action.

The hostname is treated as a limited operational identifier. The registry does
not send machine IDs, MAC addresses, usernames, VM/container inventory,
deployment codes, authorization tokens, credentials, or command output. The
broker stores only a digest of the random host credential. A successful
deployment-code exchange carrying the same random installation ID marks that
registry entry as verified.