HYDRA Command Center host agent (hcc-agent)
============================================

hcc-agent runs on the Linux or Windows host whose PCIe links reach the
drives in your HYDRA enclosure. It reports what that host sees (/dev/nvmeX, PCI address,
link speed and width, model, firmware) keyed by drive serial number, and
HYDRA Command Center (HCC) joins that to its bay view.

The agent connects out to HCC. Nothing listens on the host, and the agent
never runs shell commands: it accepts only typed, allow-listed jobs.

Contents of this bundle
-----------------------
  hcc-agent.pyz          the agent (one self-contained Python file)
  install.sh             Linux installer (copies the agent and the systemd unit)
  install-agent.cmd      Windows installer (runs install-agent.ps1)
  install-agent.ps1
  hcc-agent.service      systemd unit
  hcc-agent-writes.conf  optional systemd drop-in for write recipes
  LICENSE                license terms
  README.txt             this file

Windows host? Do step 1, then follow "Windows hosts" near the end. The
requirements and everything from step 2 on are for Linux.

Requirements
------------
  - Linux with systemd
  - python3 3.8 or newer (no pip and no extra packages needed)
  - root access (sudo)
  - network access from the host to the HCC server (default port 8600)

1. Get an enrollment code
-------------------------
In HCC open Host Agents, and in the Enroll a host card click
New enrollment code. The code is single use and expires after 15 minutes.
Under the code HCC shows the exact command for step 2, with its address,
the code and its certificate fingerprint filled in.

2. Install, enroll and start - one command
------------------------------------------
In the unzipped bundle directory on the host, run the command HCC showed:

  sudo sh install.sh --url https://<hcc-host>:8600 --code <code> --pin <sha256>

This installs /usr/local/bin/hcc-agent and the hcc-agent systemd unit,
enrolls the host and starts the service. The host appears under Host Agents
in HCC within a few seconds. Check it with:
  systemctl status hcc-agent   and   journalctl -u hcc-agent

The agent stores its own token in /etc/hcc-agent/config.json (mode 0600).
That token reaches only this agent's own HCC routes: never slot power,
resets, I2C, or firmware.

TLS options (pass one):
  --pin <sha256>          HCC's self-signed certificate: trust exactly this
                          fingerprint (shown in HCC); anything else is refused
  --tls-ca /path/ca.pem   trust a private certificate authority
  --insecure              pin whatever certificate HCC presents on first use
                          (compare the logged fingerprint with HCC's)
A plain http:// URL also works but sends the token unencrypted.

Upgrade: re-run  sudo sh install.sh  from a newer bundle (no options); an
enrolled agent is restarted automatically.

Optional: write recipes
-----------------------
By default the agent refuses every write recipe (link retrain, bus reset,
controller reset, rescan, self-test). To allow them, add --allow-writes to
the step 2 command. On an already-enrolled host instead:

  set "allow_writes": true in /etc/hcc-agent/config.json, then
  sudo install -D -m 0644 hcc-agent-writes.conf \
       /etc/systemd/system/hcc-agent.service.d/writes.conf
  sudo systemctl daemon-reload && sudo systemctl restart hcc-agent

Every write recipe still requires the operator's confirmation in HCC. To
turn writes off again, remove the drop-in and the config key, then
daemon-reload and restart.

Other commands
--------------
  hcc-agent inventory   print what the agent would report (no network)
  hcc-agent version     print the agent version

Uninstall
---------
  sudo systemctl disable --now hcc-agent
  sudo rm -rf /usr/local/bin/hcc-agent /usr/local/lib/hcc-agent \
              /etc/systemd/system/hcc-agent.service \
              /etc/systemd/system/hcc-agent.service.d /etc/hcc-agent
  sudo systemctl daemon-reload
  (Revoke the agent in HCC under Host Agents as well.)

Windows hosts
-------------
Requirements: Windows 10 22H2 / 11 / Server 2019 or newer, an administrator
account, network access to HCC. Python 3.8+ installed for all users (under
C:\Program Files); if there is none, the installer downloads Python 3.12
from python.org, checks its signature and installs it. A per-user or Store
Python is never used: the agent runs as SYSTEM.

Get a code as in step 1, then open a Command Prompt in the unzipped bundle
folder - a local folder, not a network share - and run the Windows command
HCC showed:

  install-agent.cmd --url https://<hcc-host>:8600 --code <code> --pin <sha256>

It asks for administrator rights once (UAC), installs the agent in
C:\Program Files\SerialCables\HCC-Agent, enrolls the host and starts the
scheduled task "\SerialCables\HCC Host Agent" (runs as SYSTEM at boot; a
watchdog restarts it within 5 minutes if it stops). Check it in Task
Scheduler, or:  schtasks /Query /TN "\SerialCables\HCC Host Agent"
Its log (Administrator prompt):
  type C:\ProgramData\SerialCables\HCC-Agent\logs\hcc-agent.log

The token is kept in C:\ProgramData\SerialCables\HCC-Agent\config.json;
that folder is readable by SYSTEM and Administrators only. If the folder
already exists and was not created by an administrator, the installer
refuses to use it - delete it from an Administrator prompt and re-run.
The TLS options are the same as on Linux; a --tls-ca file is copied into
that folder.

Upgrade: run  install-agent.cmd  from a newer bundle (no options); an
enrolled agent keeps its enrollment and is restarted. A new --code
re-enrolls it.

--allow-writes enables the write recipes Windows has: device self-test and
namespace rescan (both still need confirm=true per job).

Uninstall (the installer keeps a copy of itself next to the agent):

  "C:\Program Files\SerialCables\HCC-Agent\install-agent.cmd" --uninstall

--purge also deletes the enrollment folder. (Revoke the agent in HCC under
Host Agents as well.)

Support: https://www.serialcables.com/products/hydra
