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}

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

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 the one read by the SPOT backend; a different destination or namespace produces empty dashboards even when extraction succeeds.

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, run-agent.sh creates $SPOT_HOME/run/spot-agent-sap.yaml only when it does not exist. To apply a change to the editable file:

systemctl --user stop spot-agent-sap.service
rm -f "$SPOT_HOME/run/spot-agent-sap.yaml"
systemctl --user start spot-agent-sap.service

Without systemd, stop the supervised process first, remove only the generated runtime file, and run run-agent.sh again. Do not delete config/spot-sap-secret.key, data/license, or data/spot-agent-sap.

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

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. A 2.0 backend displays Agent upgrade required for an older producer and does not interpret legacy documents.

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 errors, program, user, client, host, and technical text, never 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.

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 emptyAlign destination and namespace between agent and backend
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.