Skip to main content

Connector-only

Connector-only installs only spot-agent-sap, the local license validator, and the required SAP NetWeaver RFC SDK. It does not include the backend, web UI, or Elasticsearch. Use it when SPOT and Elasticsearch run on another host or when the agent must remain close to SAP.

Choose an installation method​

MethodArtifactPrivilegesRecommended management
RPM/DEBspot-agent-saproot for installationsystem systemd
Portablespot-agent-sap-portablenon-root usersystemd --user or a supervisor

Both methods run the same agent and produce the same data contract. Do not install connector-only over a SPOT suite or mix their directories. See also Installation matrix.

Before installing​

Prepare:

  • a Linux x86_64 host with a synchronized clock;
  • RFC connectivity from the host to every SAP system;
  • HTTPS connectivity to the Elasticsearch cluster that receives agent data;
  • a read-only SAP user authorized for the collection families you require;
  • a valid online key or offline license file;
  • the artifact and SHA256SUMS from the same SPOT Release.

The official artifact already contains the expanded SDK and validated compatibility libraries. Do not extract another SDK into the package or replace its binaries.

Install with RPM or DEB​

Verify and install​

From the directory that contains the package and SHA256SUMS:

sha256sum -c --ignore-missing SHA256SUMS

sudo rpm -Uvh spot-agent-sap-X.Y.Z-1.el10.x86_64.rpm
# or
sudo dpkg -i spot-agent-sap_X.Y.Z_amd64.deb

The package creates the service user and leaves the Elasticsearch destination empty and disabled. Configure it before starting the agent.

ContentSystem path
Binaries and SDK/opt/spot
Editable configuration/etc/spot/.spot-agent-sap.yaml
Incremental state/var/lib/spot-agent-sap
License and history/var/lib/spot/license
Agent log/var/log/spot/spot-agent-sap.log

Install portable without root​

Download, verify, and extract​

The official name is spot-agent-sap-portable_X.Y.Z_linux_amd64.tar.gz. To use the included systemd --user units without changes, extract it to the recommended path:

umask 077
SPOT_ARTIFACT=spot-agent-sap-portable_X.Y.Z_linux_amd64.tar.gz
grep -F "  ${SPOT_ARTIFACT}" SHA256SUMS | sha256sum -c -

export SPOT_HOME="$HOME/spot-agent-sap-portable"
mkdir -p "$SPOT_HOME"
tar -xzf "$SPOT_ARTIFACT" -C "$SPOT_HOME" --strip-components=1
chmod -R go-rwx "$SPOT_HOME"

Confirm the package type before configuring it:

test -x "$SPOT_HOME/bin/spot-agent-sap"
test -x "$SPOT_HOME/bin/spot-license-blackbox"
test -x "$SPOT_HOME/scripts/run-agent.sh"
test -x "$SPOT_HOME/scripts/run-license.sh"
test ! -e "$SPOT_HOME/bin/spot-server"
test ! -e "$SPOT_HOME/scripts/run-elasticsearch.sh"

Portable creates no users, system services, or files in /opt, /etc, or /var. Everything belongs to the runtime user:

ContentPortable path
Editable configuration$SPOT_HOME/config/spot-agent-sap.yaml
Generated runtime configuration$SPOT_HOME/run/spot-agent-sap.yaml
Incremental state$SPOT_HOME/data/spot-agent-sap
License and history$SPOT_HOME/data/license
Logs$SPOT_HOME/log
Included SDK$SPOT_HOME/nwrfcsdk

If you choose another $SPOT_HOME, the manual scripts still work. Adapt the included units to that path before copying them.

Configure the agent​

Edit the configuration file for your installation method. The portable template initially ships with elasticsearch.enabled: false; complete the destination and enable it only after reviewing TLS and authentication.

elasticsearch:
  url: https://elastic.example.local:9200
  transport_profile: external
  namespace: production
  apikey: "<elastic-credential>"
  manage_data_streams_ilm: false
  enabled: true

sapconnection:
  - id: sap-production
    alias: SAP Production
    system_id: PRD
    ashost: sap.example.local
    sysnr: "00"
    client: "100"
    user: SPOT_READER
    passwd: "enc:v1:<encrypted-secret>"
    lang: EN
    time_zone: Europe/Madrid
    enabled: true
    collections:
      metrics: {enabled: true, intervalSeconds: 300}
      ccms_events: {enabled: true, intervalSeconds: 300}
      jobs: {enabled: true, intervalSeconds: 300}
      work_processes: {enabled: true, intervalSeconds: 300}
      abap_dumps: {enabled: true, intervalSeconds: 300}
      rfc_failures: {enabled: true, intervalSeconds: 300}
      certificates: {enabled: true, intervalSeconds: 86400}

sapconnection[].id is mandatory, non-empty, and unique within the process. It is written as source_id in every document and becomes the user-facing targetId; SPOT does not generate sap-N, resolve aliases, or migrate the old topology. After trimming, the ID must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$; comparison is case-sensitive. Add N SAP blocks if needed: they all write to this one Elasticsearch+namespace. Run another connector instance and service to split SAP systems across clusters. One SAP must not belong to two connectors.

Use exactly one Elasticsearch authentication method: apikey or username/password. If the cluster uses a private CA, copy only the public certificate into the configuration area and set ca_file to an absolute path. insecure_skip_verify retains encryption but does not verify server identity; reserve it for a temporary, documented exception.

SAP passwd must contain an enc:v1: value encrypted for the same installation. Do not store the password in clear text or pass it as a process argument. On portable, preserve $SPOT_HOME/config/spot-sap-secret.key with the configuration; losing or replacing that key prevents existing credentials from being decrypted.

Generate enc:v1: safely​

On RPM/DEB, run the command as the service user. It prompts for the SAP password without echo and writes only the encrypted value:

sudo -u spot /opt/spot/bin/spot-agent-sap encrypt

Copy the single enc:v1:... line into sapconnection[].passwd. If automation already supplies the secret through a protected stream, use --stdin; never place the literal value on the command line:

IFS= read -r -s -p 'SAP password: ' SPOT_SAP_PASSWORD; printf '\n' >&2
printf '%s' "$SPOT_SAP_PASSWORD" |
  sudo -u spot /opt/spot/bin/spot-agent-sap encrypt --stdin
unset SPOT_SAP_PASSWORD

You can also use a temporary regular, non-symlink, private file:

sudo install -o spot -g spot -m 0600 /protected/path/password /run/spot-sap-password
sudo -u spot /opt/spot/bin/spot-agent-sap encrypt \
  --password-file /run/spot-sap-password
sudo rm -f /run/spot-sap-password

On portable, invoke the artifact wrapper; it derives its own root and uses the key below config/:

"$HOME/spot-agent-sap-portable/bin/spot-agent-sap" encrypt

Build a private Docker image with a temporary password​

When preparing a private connector-only image, the Dockerfile can consume the password through the sap_password BuildKit secret and run spot-agent-sap encrypt --password-file /run/secrets/sap-password during the build. In this case you do not need to create file-passwd-sap or add it to .dockerignore: pass the value directly from a temporary environment variable:

SAP_PASSWORD='SAP_PASSWORD' \
DOCKER_BUILDKIT=1 docker build \
  --no-cache \
  --secret id=sap_password,env=SAP_PASSWORD \
  --tag spot-agent-sap:2.0.4 .

The Dockerfile must mount that secret with RUN --mount=type=secret,id=sap_password,target=/run/secrets/sap-password,required=true. BuildKit does not add it to the image layers. The literal value may still remain in the local shell history, so use this method only on a controlled build host. Do not declare the password through ARG or ENV in the Dockerfile. Keep the image in a private registry when it also contains the offline license and the installation encryption key.

The system key is /etc/spot/spot-sap-secret.key; the portable key is $SPOT_HOME/config/spot-sap-secret.key. Ciphertext is bound to that key. Add it to the protected configuration backup and restore it together with its enc:v1: values. Never delete, regenerate, or copy it from another installation: a different key cannot decrypt existing passwords. If an existing portable key is not mode 0600, the command fails without changing it.

With manage_data_streams_ilm: false, bootstrap checks connectivity only and creates no resources. With true, the agent requires administration permissions and manages only the metrics and logs Data Streams. The namespace must match a SPOT backend read scope. The backend discovers each SAP through tenant_id=onprem + source_id; a wrong scope or duplicate ID across scopes produces a binding diagnostic, never silent fallback.

SPOT 2.0 does not support separate Jobs, Events, or WPInfo indices. Three names are derived from namespace: metrics telemetry, logs telemetry, and the isolated operational agent stream.

Activate or install the license​

The agent does not execute elastic-bootstrap or run without a valid license. Usage warnings do not stop the connector; a missing, invalid, expired, or revoked license does.

RPM/DEB​

sudo systemctl enable --now spot-license.service
sudo systemctl status spot-license.service --no-pager

# Online activation through the hidden prompt
sudo -u spot /opt/spot/bin/spot-agent-sap license-activate

For an offline license:

sudo install -o spot -g spot -m 0600 /received/path/license /run/spot-license.offline
sudo -u spot /opt/spot/bin/spot-agent-sap license-install /run/spot-license.offline
sudo rm -f /run/spot-license.offline

Portable with systemd --user​

The included units target $HOME/spot-agent-sap-portable. Install them and start the validator first:

mkdir -p "$HOME/.config/systemd/user"
install -m 0644 "$SPOT_HOME/systemd-user/spot-license.service" \
  "$HOME/.config/systemd/user/spot-license.service"
install -m 0644 "$SPOT_HOME/systemd-user/spot-agent-sap.service" \
  "$HOME/.config/systemd/user/spot-agent-sap.service"
systemctl --user daemon-reload
systemctl --user enable --now spot-license.service

"$SPOT_HOME/bin/spot-agent-sap" license-activate
# or: "$SPOT_HOME/bin/spot-agent-sap" license-install /protected/path/license
"$SPOT_HOME/bin/spot-agent-sap" license-check

systemctl --user enable --now spot-agent-sap.service

Ask the host administrator to enable linger for the runtime user if the service must stay active after logout. Do not run the user units and manual scripts at the same time.

Portable with manual startup​

For controlled validation or when using another supervisor:

umask 077
"$SPOT_HOME/scripts/run-license.sh" \
  >"$SPOT_HOME/log/license.out" 2>"$SPOT_HOME/log/license.err" &
printf '%s\n' "$!" >"$SPOT_HOME/run/license.pid"

"$SPOT_HOME/bin/spot-agent-sap" license-activate
# or: "$SPOT_HOME/bin/spot-agent-sap" license-install /protected/path/license
"$SPOT_HOME/bin/spot-agent-sap" license-check

"$SPOT_HOME/scripts/run-agent.sh"

run-agent.sh keeps the agent in the foreground for supervision by its parent. If the local validator is unavailable, it starts it and writes its output to $SPOT_HOME/log/license.out and license.err.

Never pass the online key as a positional argument. Automation can use --stdin or --key-file with a regular 0600 file. See Licenses and renewal for status, history, and encrypted renewal export without a web UI.

Apply configuration changes​

For RPM/DEB, edit /etc/spot/.spot-agent-sap.yaml and restart the service. On portable, every run-agent.sh invocation derives a fresh $SPOT_HOME/run/spot-agent-sap.yaml from the editable file, publishes it atomically with mode 0600, and uses the same copy for bootstrap and daemon.

When you save configuration in a local portable suite UI, SPOT serializes the save and restart. An identical save does not restart a healthy agent. If the agent cannot stop or start, the UI reports the failure and you can retry the same save; do not start another agent while an unverifiable PID remains. With systemd --user or manual startup, restart the supervised process after editing. Do not delete config/spot-sap-secret.key, data/license, or data/spot-agent-sap; you do not need to remove the generated runtime file.

When an RPM/DEB configuration reloads, the agent prepares the new namespace's Data Streams first. License evidence and SAP extraction start only afterwards. If bootstrap fails, the service remains failed without creating an incompatible regular index; correct the target and restart it.

Verify the installation​

RPM/DEB​

sudo -u spot /opt/spot/bin/spot-agent-sap license-status --json
sudo -u spot /opt/spot/bin/spot-agent-sap license-check
sudo -u spot /opt/spot/bin/spot-agent-sap elastic-bootstrap \
  --config /etc/spot/.spot-agent-sap.yaml
sudo systemctl enable --now spot-agent-sap.service
sudo systemctl status spot-agent-sap.service --no-pager
sudo journalctl -u spot-agent-sap -n 120 --no-pager

The first start may take up to 3 minutes while bootstrap waits for Elasticsearch and completes its checks. During that interval, systemd keeps the service in the activating state.

Portable​

"$SPOT_HOME/bin/spot-agent-sap" license-status --json
"$SPOT_HOME/bin/spot-agent-sap" license-check
test -f "$SPOT_HOME/run/spot-agent-sap.yaml"
tail -n 120 "$SPOT_HOME/log/spot-agent-sap.log"

systemctl --user status spot-license.service spot-agent-sap.service --no-pager
journalctl --user -u spot-agent-sap.service -n 120 --no-pager

The portable launcher runs elastic-bootstrap before the daemon. Invalid connectivity, authentication, TLS, or mappings make it exit with an error instead of starting extraction.

Then check Landing/Metrics, Events, Job Monitoring, Certificates, and RFC & Integrations in the remote SPOT instance. The backend interprets only documents with schema_version=2; legacy documents are ignored. If the selected target has no genuine v2 signal, the view shows No data or UNKNOWN according to its contract. In remote mode, a local connector journal neither authorizes nor blocks reads from a standalone connector.

Capabilities and security​

Each connection probe marks every family as supported, unauthorized, unavailable, or error. An unavailable family does not block the others. The RFC user must be read-only:

  • dumps include the error, program, user, client, host, and the generic runtime error description from SNAPT; they never include the long text of an ST22 instance, memory, or business data;
  • RFC records include status, destination, queue, function, and error, never payloads;
  • certificate records include subject, issuer, serial, fingerprint, PSE/application, and validity, never private keys.

The agent preserves watermarks, overlap, and deduplication. The initial Jobs, dumps, and RFC backfill covers 24 hours.

After upgrading an affected connector, SPOT runs one bounded repair of dump descriptions retained during the previous 30 days. The repair is separate from current collection, scoped to each source/client, and appends a deterministic observation: it does not update or delete historical documents. After a restart it retries with the same identities, and create-only conflicts are treated as deduplication. Progress is stored in /var/lib/spot-agent-sap/dump-description-repair-v2.json, or in portable mode in $SPOT_HOME/data/spot-agent-sap/dump-description-repair-v2.json. Include it in state backups and do not edit it to force another replay.

Collections use a fixed frequency, deterministic phases, and a dispatcher bounded to two executions. Metrics, Work Processes, and the long-running-jobs snapshot keep priority; delayed cycles coalesce without a backlog. Jobs and CCMS are paged and Elasticsearch bulks are capped at 500 documents or 8 MiB. The unit limits the agent to two cores, starts memory pressure at 640 MiB, and stops it before 768 MiB.

Backup, upgrade, and rollback​

For RPM/DEB, reinstall the same package name with rpm -Uvh or dpkg -i; configuration, license, journal, and incremental state are preserved. Follow Upgrade, backup, restore, and uninstall.

For portable:

  1. Stop the agent and validator or their user units.
  2. Take a private, verified backup of config and data.
  3. Verify the new tar and extract it to a different directory, never over the active tree.
  4. Migrate only config/spot-agent-sap.yaml, config/spot-sap-secret.key, data/license, and data/spot-agent-sap from the same installation.
  5. Do not copy bin, nwrfcsdk, scripts, share, or run from the previous version.
  6. Keep the stable $HOME/spot-agent-sap-portable path when using the included units, reload systemd, and start license before the agent.
  7. Validate license, bootstrap, ingestion, and history continuity before retiring the previous version.

Do not clone data/license to another installation: it contains the local verifiable identity. For rollback, restore the previous binary and its complete compatible backup.

Uninstall portable​

Disable and stop the user units, remove their copies from $HOME/.config/systemd/user, and run systemctl --user daemon-reload. Archive config and data first if you need restore or renewal. Remove the portable tree only after verifying the backup; a correct non-root installation has no other SPOT paths to clean.

Quick troubleshooting​

SymptomCheck
Agent exits before startupRun license-check and inspect license.err
Bootstrap failsCheck URL, authentication mode, CA, namespace, and ILM permissions
A portable change is ignoredStop the agent and regenerate only run/spot-agent-sap.yaml
Service stops after logoutAsk for linger on the runtime user
SAP library is missingRecheck the checksum; do not replace nwrfcsdk or wrappers
Documents exist but dashboards are emptyCheck read scope+namespace, schema_version=2, tenant_id=onprem, exact source_id, and select that SAP target
Target reports a conflictThe same source_id exists in two scopes or publishes different SID/client values; correct the connector, not the alias
User quality is partial/unknownCheck enabled sources and freshness; it is not a process failure
No local UI or port 8080 existsThis is correct connector-only behavior

Do not include configuration, credentials, or complete license responses when collecting evidence. Use sanitized status output and the documented logs.