wmantly
d47d08ecab
Implements protocol v1.2.0. verifySignature() returned true when no public_key was configured, logging "skipping signature verification". The SSO installer never wrote a public_key, so a default install executed reboot, service_restart, configure_ldap, arbitrary_bash and update_binary UNVERIFIED from anything that could reach its socket. An agent that cannot verify now refuses. Canonicalization also disagreed with the server. Go's encoding/json escapes <, > and & by default; JSON.stringify does not. Any payload containing them hashed differently on each side and failed verification -- for arbitrary_bash that is most real scripts (`>` redirection, `&&`). Now uses json.Encoder with SetEscapeHTML(false), trailing newline trimmed. The SSO now rejects tokens it did not issue. Handles its close codes (4001/4002/4003/4004) and backs off 5 minutes on an enrollment failure instead of retrying every 5s forever. The connect log no longer prints the URL, which carried ?token=. install.sh gains --public-key and warns when none is configured. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.0 KiB
Installation Guide: Theta Agent
Theta Agent is designed for rapid deployment across the fleet. The recommended method is via the "One-Liner" install, which marries the agent to a specific SSO Manager instance.
Prerequisite: enroll the host
The agent's token is issued by the SSO, not chosen by you. In the SSO open Directory → Install Agent, name the host, bind it to a host resource, and press Enroll & issue token. You get:
- the agent token — shown once; only its hash is stored
- the SSO public key — pinned by the agent to verify high-risk commands
The modal builds the install command below with both already filled in. A token
the SSO did not issue is rejected at connect time with close code 4001.
Quick Start (The One-Liner)
The SSO Manager provides a pre-generated installation command. Copy and paste it into your terminal as root:
Option A: Full Configuration (Recommended)
Use this for precise control over capabilities:
curl -fsSL https://sso.example.com/resources/theta-agent/install.sh | sh -s -- "BASE64_ENCODED_CONFIG"
Option B: Minimal Setup
Use this for rapid deployment with basic telemetry:
curl -fsSL https://sso.example.com/resources/theta-agent/install.sh | sh -s -- \
--url "https://sso.example.com" --token "<ISSUED_TOKEN>" --public-key "<BASE64_PUBLIC_KEY>"
What this does:
- Downloads the latest
theta-agentbinary. - Decodes the base64 configuration string into
/etc/theta42/agent.yml. - Installs a systemd service unit.
- Starts the agent automatically.
Manual Installation
If you are in an air-gapped environment or prefer manual control:
1. Deploy Binary
Place the theta-agent binary in /usr/local/bin/ and ensure it is executable:
chmod +x /usr/local/bin/theta-agent
2. Configure
Create the configuration directory and the agent.yml file:
mkdir -p /etc/theta42
nano /etc/theta42/agent.yml
Ensure the file has restricted permissions:
chmod 600 /etc/theta42/agent.yml
3. Setup systemd
Create the file /etc/systemd/system/theta-agent.service:
[Unit]
Description=Theta Agent Unified Endpoint Management
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/theta-agent
Restart=always
RestartSec=5
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=theta-agent
[Install]
WantedBy=multi-user.target
Enable and start the service:
systemctl daemon-reload
systemctl enable theta-agent
systemctl start theta-agent
Troubleshooting
Verifying Connection
Check the logs to ensure the agent has successfully connected to the SSO Manager:
journalctl -u theta-agent -f
You should see: Successfully connected to SSO Manager.
Configuration Errors
If the agent fails to start, verify the config file exists and is valid YAML:
ls -l /etc/theta42/agent.yml
Root Privileges
The agent must run as root to execute system commands like reboot and systemctl restart. If you manually run the binary, ensure you use sudo.