Connectors

Tenant console > Connectors controls runtimes installed near SAP. A connector works in pull mode: it reaches SPOT over outbound HTTPS, receives configuration, and publishes telemetry without exposing SAP to the Internet.

Create and install

1. Create a connector with an operational name.
2. Copy the one-time installation code, valid for 30 minutes.
3. Generate the temporary bootstrap URL in Add agent guide.
4. Download the bootstrap, verify its SHA-256, and run it on the final host.
5. Enter the code only at the hidden prompt.
6. Wait for the first healthy heartbeat.

The card summarizes identity, version, applied configuration, heartbeat, and upgrade state.

The guide never uses manual extraction or curl | sh. The bootstrap embeds its environment's TUF public root and installs only a runtime with valid metadata, version, and digest. Each environment keeps deployment, data, and trust separate; production never trusts a non-production root.

If Platform has not yet synchronized a bootstrap and its matching signed runtime, installation remains blocked. SPOT does not offer a legacy tarball or an unverified download as a fallback.

The guide covers bootstrap download, verification, hidden prompt, service, and diagnostics.

Development and production

The guide and Download verified bootstrap show Development candidate when the development environment has a trusted, active candidate for testing. They select the newest valid generation with a matching bootstrap and signed Linux amd64 runtime from the same release. Production shows Stable package and allows only trusted stable packages.

If valid identity, bootstrap or its verified matching runtime is missing, installation stays blocked and Generate stays disabled. Do not switch environments or bypass verification to enable it.

Test the candidate in development before requesting manual promotion to production. Generating a URL or downloading the bootstrap does not upgrade or re-enroll an existing connector. Request upgrade retains the stable channel; displaying a development candidate does not enable it as an automatic upgrade.

States

State	Meaning	Check
Pending	No authenticated heartbeat yet	Code validity, outbound HTTPS, and local service
OK	Configuration, heartbeat, and telemetry are healthy	SAP connections and stable version
NOK	Active failure or unapplied configuration	Agent logs, RFC, network, and upgrade
Stale	Heartbeat expired	Process, linger, and connectivity
Disabled/Revoked	SPOT rejects the credential	Retire or re-enroll the host

Actions

Action	Effect
Download verified bootstrap	Issues a temporary URL for the bootstrap tied to the trusted release
Request upgrade	Requests the latest stable generation; it is not offered as a downgrade when the connector already runs a newer candidate
Generate re-enrollment code	Creates a 30-minute code without interrupting the active credential
Disable connector	Immediately revokes credentials, codes, sessions, and pending upgrades while preserving SAP assignments
Delete connector	Permanently removes the identity and unassigns its SAP connections

The host generates the persistent credential and SPOT stores only its hash. It is never shown by the console or included in a download.

Safe upgrades

The agent verifies TUF, installs generations, and atomically switches the active pointer. A stable supervisor outside the active generation remains in control even when the new wrapper, environment, loader, or binary cannot start. It confirms the version only after authentication, configuration, heartbeat, and telemetry; on failure or deadline expiry it restores the previous generation. The card identifies the package available for installation as Development candidate or Stable package. Request upgrade still uses only the stable channel and does not replace a newer candidate with an older version.

The first generation containing this supervisor installs it from its own signed artifact and automatically re-enters under its control. It also migrates the flat layout used by earlier connectors, but only after health is confirmed. This requires no re-enrollment, configuration loss, or technician action. Status and stop scripts, PID, and log stay below $HOME/spot-agent-saas, so their paths do not change when generations switch.

stable releases roll out automatically in waves. Request upgrade is a one-off administrative action; normal operation does not require a technician to restart the service or request each version. Platform can pause a wave on TUF/digest failure, rollback, success below 98%, or degradation above 5%. Before requesting a canary, the workflow records and validates that its previous version is different and older; candidate must prove the real transition, and promotion reuses the exact digest.

Safe re-enrollment

Creating a code does not interrupt the current connector. Stop it only when ready and provide the code through the hidden prompt or a protected 0600 file. The old credential is invalidated only after the new one is accepted.

Use a separate connector for a different logical host. Keep the same identity only to recover its local installation or credential.

Diagnostics

• No heartbeat: check service, linger, DNS, and outbound HTTPS.
• TUF error: check clock, expired metadata, and version; never bypass verification.
• Upgrade rollback: inspect Agent logs and configuration, authentication, and telemetry health.
• No SAP data: check assignment, SAP credentials, RFC permissions, and time range.

After a connector upgrade, use the same SAP source and time range in Jobs and SM37. Confirm that start, end, and JOBCOUNT identify the same execution, that the Jobs cursor advances for at least two complete cycles, and that a terminal execution has a complete or empty Job Log, or an explicit status. The connector supports the verified requested-column and physical-DDIC orders of RFC_READ_TABLE; an ambiguous shape is blocked as unsupported_rfc_read_table_shape without publishing the read or advancing the cursor. This does not make arbitrary SAP formats compatible. Also confirm that heartbeat and the other collections continue to advance.

Never paste codes, connector.json, SAP secrets, or complete configuration into tickets. Share connector ID, version, timestamp, and sanitized errors.

Persistent outbound proxy

Use an HTTP CONNECT proxy for HTTPS installation, enrollment, configuration, heartbeat, SAP metrics and logs, Agent logs and signed updates. SPOT retains destination TLS and TUF verification. An https:// proxy URL is currently unsupported; ask your network administrator for an HTTP CONNECT endpoint. The host must also resolve the public SPOT hostname.

Create a private JSON file with mode 0600 using a secure editor:

{"schema":1,"mode":"explicit","url":"http://proxy.example:3128","no_proxy":".example.internal"}

If authentication is required, put the proxy username/password only in that file and URL-encode reserved characters. Keep credentials out of commands, service unit variables and screenshots. no_proxy supports hosts, domain suffixes, CIDR networks and optional ports.

After downloading and verifying the bootstrap, append --proxy-config /private/path/proxy.json to the guide's bootstrap command. Import happens before its first download. Configuration remains at <installation>/config/proxy.json, outside replaceable generations. The config directory must be 0700 and the file 0600, both owned by the user running the connector.

For an existing installation, use its stable launcher:

<installation>/bin/spot-agent-saas saas-proxy configure --file /private/path/proxy.json
<installation>/bin/spot-agent-saas saas-proxy status
<installation>/bin/spot-agent-saas saas-proxy test

status hides credentials. Restart the service to apply changes to clients already open. Configuration survives systemd-user/nohup restarts and upgrades without shell exports. Use saas-proxy direct for direct connections. Import {"schema":1,"mode":"environment"} to use HTTPS_PROXY/HTTP_PROXY and NO_PROXY again. A missing file keeps this compatibility; explicit configuration overrides the environment. A failed configured proxy never triggers direct fallback.

On failure, check DNS, proxy access, CONNECT authentication and destination certificates. Keep TLS and TUF enabled. If an older updater fails through its proxy, request controlled recovery using a verified bootstrap and an enrollment/re-enrollment code for the same connector. Keep the installation and state, and verify identity and cursors. Credentials may rotate during authorized re-enrollment. Do not delete state as a routine workaround; contact support if preservation cannot be verified. Confirm the new version and a fresh heartbeat after recovery.

Upgrades without enabled SAP connections

When the connector has no enabled SAP connections, it can confirm a signed upgrade after accepting its current configuration, sending a successful authenticated heartbeat and receiving acknowledgement of a fresh health event in Agent logs. This also applies when all connections are explicitly disabled. Omitting the enabled setting keeps a connection enabled; disabling only its collection families does not change that condition.

Enabled SAP connections still require completed supported collection. If telemetry acknowledgement fails, the upgrade stays pending and can roll back at the health deadline; check the proxy and access to Agent logs. A test without SAP proves connector transport and upgrade behavior, but does not prove extraction or real SAP coverage.