Hodei-Shield Agent: beta guide for Linux¶

Install the 2.20.0 release on Linux x86_64 with systemd and OpenSSL 3. You need root, outbound HTTPS to your platform URL and to hs-agent-releases.s3.gra.io.cloud.ovh.net, one enrollment token (works once; your administrator, or your MSSP's, creates it in the console), an agent id (letters, digits, . _ : -; it becomes the machine's permanent name) and the platform URL (https://…). MEASURED: the step was run and its output kept; NOT RUN: written from the packaging only. If a step misbehaves, stop and write to info@hodeitek.com. Crash reports go to Sentry by default: to opt out before the first start, see the end of this guide.

1. Download¶

Only from the release store, never from a link in an e-mail or chat.

V="${V:?set V to the version you were given}"
B=https://hs-agent-releases.s3.gra.io.cloud.ovh.net
mkdir hodei-install && cd hodei-install
curl -fsSLO "$B/agent/$V/hodei-shield-$V-linux-x86_64-musl.tar.gz"
curl -fsSLO "$B/agent/$V/SHA256SUMS"
curl -fsSLO "$B/agent/$V/SHA256SUMS.sig"

Before you run anything, check that the download is authentic: verify an agent release and verify the download.

2. Verify¶

Linux has no OS-native signature; the tarball is covered by the release signature (Ed25519) over SHA256SUMS. Save as hodei-shield-release.pub.pem:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEUqKd+ot7BESwk+vf6EVBKudMi6F6jmY3dJeHXfCWkQ=
-----END PUBLIC KEY-----

MEASURED on a published release. Key fingerprint (details: verify-release.md; openssl pkey -pubin -in hodei-shield-release.pub.pem -outform DER | tail -c 32 | sha256sum): 8b730d2fcbd90e2656bd9b3f265638f1e8e8ac2379d48b0636feb5efe5a88f07. This is the key's fingerprint, not the package's checksum; the package is checked against SHA256SUMS.

openssl base64 -d -A -in SHA256SUMS.sig -out SHA256SUMS.sig.raw
wc -c < SHA256SUMS.sig.raw                      # must print 64
openssl pkeyutl -verify -rawin -pubin -inkey hodei-shield-release.pub.pem \
  -sigfile SHA256SUMS.sig.raw -in SHA256SUMS    # Signature Verified Successfully
sha256sum --ignore-missing -c SHA256SUMS        # your .tar.gz must say: OK

Anything else means do not install: delete the files and tell Hodeitek.

3. Install¶

MEASURED (Debian 12, 2026-10-29).

tar xzf "hodei-shield-$V-linux-x86_64-musl.tar.gz"
cd "hodei-shield-$V-linux-x86_64-musl"
sudo useradd --system --no-create-home --shell /usr/sbin/nologin hodei-shield
sudo install -o root -g root -m 0755 hodei-shield /usr/local/bin/hodei-shield
sudo install -o root -g root -m 0644 hodei-shield.service /etc/systemd/system/
sudo install -d -o root -g root -m 0755 /etc/hodei-shield
sudo install -o root -g hodei-shield -m 0640 platform-ca.pem /etc/hodei-shield/
sudo install -d -o hodei-shield -g hodei-shield -m 0700 /var/lib/hodei-shield
sudo -u hodei-shield tee /var/lib/hodei-shield/hodei-shield.toml >/dev/null <<'EOT'
platform_url = "https://<platform host>"
state_dir = "/var/lib/hodei-shield"
EOT
sudo systemctl daemon-reload
hodei-shield version          # prints: hodei-shield <version>, then a line on error reports

4. Enroll¶

MEASURED (Debian 12, 2026-10-29). Once per machine; the service starts only after it. The token is typed hidden, never on a command line.
cd /
IFS= read -rs HODEI_TOKEN && echo
printf '%s' "$HODEI_TOKEN" | sudo -u hodei-shield env \
  HODEI_PLATFORM_URL="https://<platform host>" \
  HODEI_STATE_DIR=/var/lib/hodei-shield \
  /usr/local/bin/hodei-shield enroll --token-stdin --agent-id '<this machine id>'
unset HODEI_TOKEN
sudo systemctl enable --now hodei-shield
Once it is running with both, it evaluates and submits straight away, then again every submit interval (default 3600 seconds). Success prints enrolled: producer=endpoint_agent:<id> public_key_id=… tenant_id=…, after a log line and before a pin-update-identity command for automatic updates: run it only once your administrator confirms its values in the console. If it fails, do not reuse the token: ask for a new one. Certificate or TLS error: add no certificate and turn no check off; the agent trusts only /etc/hodei-shield/platform-ca.pem. Send the output of hodei-shield diagnose to your administrator; other failures: troubleshooting.

5. Check in the console¶

MEASURED (Debian 12, 2026-10-29). systemctl is-active hodei-shield must say active. The machine appears under Endpoints in the console after its first cycle. Logs: sudo journalctl -u hodei-shield -n 50 --no-pager.

Controls showing "Error" in this beta: some controls may show "Error" on systems whose language is not English, or because the agent runs without administrator rights. This does not mean the control is failing: the agent could not read it reliably, and it does not count it as compliant. The next beta version corrects this.

6. Update by hand¶

Do not enroll again. From 2.16.0 on, a Linux host updates itself only when the console's signed policy approves the release; otherwise, or to update yourself, update by hand. MEASURED (2.14.0 to 2.14.1, isolated container): binary replaced, version printed the new number, one cycle accepted, key and identity files byte-identical; systemctl, self-test and rollback were not part of that run. Verify the new version as in steps 1 and 2, then:

V=<new version>
tar xzf "hodei-shield-$V-linux-x86_64-musl.tar.gz" && cd "hodei-shield-$V-linux-x86_64-musl"
sudo systemctl stop hodei-shield
sudo cp -p /usr/local/bin/hodei-shield /usr/local/bin/hodei-shield.prev   # rollback copy
sudo install -o root -g root -m 0755 hodei-shield /usr/local/bin/hodei-shield
sudo install -o root -g root -m 0644 hodei-shield.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo -u hodei-shield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test' \
  && sudo systemctl start hodei-shield
hodei-shield version                          # the new version

7. Uninstall¶

MEASURED (Debian 12, 2026-10-29). First ask your administrator to revoke the machine (console: Endpoints, the endpoint, Revoke enrolment); a revoked agent logs "credential rejected" and sends nothing.

sudo systemctl disable --now hodei-shield
sudo rm /etc/systemd/system/hodei-shield.service /usr/local/bin/hodei-shield && sudo systemctl daemon-reload
sudo pkill -KILL -u hodei-shield; ! pgrep -u hodei-shield && sudo chown root:root /var/lib/hodei-shield /etc/hodei-shield \
  && sudo chmod 0700 /var/lib/hodei-shield && l="$(sudo find /var/lib/hodei-shield /etc/hodei-shield -xdev ! -type d -links +1 -print -quit)" && [ -z "$l" ] \
  && sudo chown -R root:root /var/lib/hodei-shield /etc/hodei-shield \
  && sudo chmod -R u=rwX,go= /var/lib/hodei-shield && sudo userdel hodei-shield

NOT RUN: pkill/pgrep, the folder lock and the find, which stops the chain on a second hard link (with fs.protected_hardlinks=0 the service could plant one to a system file for chown to re-own). If id hodei-shield still answers, write to Hodeitek. Left behind, owned by root so no account later given the freed uid can read the key: /var/lib/hodei-shield (private key, queue, hodei-shield.toml; 0700/0600), /etc/hodei-shield (CA, telemetry-off) and the journal; no log file. Purge (irreversible, after revoking): sudo rm -rf /var/lib/hodei-shield /etc/hodei-shield.

Privacy and help. Error reports (crashes only, no personal data) go to Sentry; to turn them off before the first start (MEASURED, Debian 12, 2026-10-29): sudo mkdir -p /etc/hodei-shield && sudo touch /etc/hodei-shield/telemetry-off. Help: info@hodeitek.com or the Beta button in the console.