Connector-only

Connector-only instala únicamente spot-agent-sap, el validador local de licencia y el SAP NetWeaver RFC SDK necesario. No incluye backend, interfaz web ni Elasticsearch. Úsalo cuando SPOT y Elasticsearch vivan en otro host o cuando el agente deba quedar cerca de SAP.

Elige el método de instalación

Método	Artefacto	Privilegios	Gestión recomendada
RPM/DEB	`spot-agent-sap`	root para instalar	systemd del sistema
Portable	`spot-agent-sap-portable`	usuario sin root	`systemd --user` o supervisor

Ambos métodos ejecutan el mismo agente y producen el mismo contrato de datos. No instales connector-only encima de una suite SPOT ni mezcles sus directorios. Consulta también Matriz de instalación.

Antes de instalar

Prepara:

un host Linux x86_64 con reloj sincronizado;
conectividad RFC desde el host hasta cada SAP;
conectividad HTTPS hasta el Elasticsearch donde escribirá el agente;
un usuario SAP de sólo lectura con las autorizaciones de las familias que quieras recopilar;
una clave online o un fichero offline de licencia válido;
el artefacto y SHA256SUMS de la misma SPOT Release.

El artefacto oficial ya contiene el SDK expandido y las librerías de compatibilidad validadas. No extraigas otro SDK dentro del paquete ni sustituyas sus binarios.

Instalar con RPM o DEB

Verificar e instalar

Desde el directorio donde descargaste el paquete y SHA256SUMS:

sha256sum -c --ignore-missing SHA256SUMS

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

El paquete crea el usuario de servicio y deja el destino Elasticsearch vacío y deshabilitado. Configúralo antes de iniciar el agente.

Contenido	Ruta system
Binarios y SDK	`/opt/spot`
Configuración editable	`/etc/spot/.spot-agent-sap.yaml`
Estado incremental	`/var/lib/spot-agent-sap`
Licencia e histórico	`/var/lib/spot/license`
Log del agente	`/var/log/spot/spot-agent-sap.log`

Instalar portable sin root

Descargar, verificar y extraer

El nombre oficial es spot-agent-sap-portable_X.Y.Z_linux_amd64.tar.gz. Para usar sin cambios las unidades systemd --user incluidas, extrae el contenido en la ruta recomendada:

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"

Comprueba el tipo de paquete antes de configurarlo:

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 no crea usuarios, servicios del sistema ni ficheros en /opt, /etc o /var. Todo pertenece al usuario runtime:

Contenido	Ruta portable
Configuración editable	`$SPOT_HOME/config/spot-agent-sap.yaml`
Configuración runtime generada	`$SPOT_HOME/run/spot-agent-sap.yaml`
Estado incremental	`$SPOT_HOME/data/spot-agent-sap`
Licencia e histórico	`$SPOT_HOME/data/license`
Logs	`$SPOT_HOME/log`
SDK incluido	`$SPOT_HOME/nwrfcsdk`

Si eliges otro $SPOT_HOME, los scripts manuales siguen funcionando. Las unidades incluidas deben adaptarse a esa ruta antes de copiarlas.

Configurar el agente

Edita el fichero de configuración de tu método de instalación. El ejemplo portable se entrega inicialmente con elasticsearch.enabled: false; completa el destino y actívalo sólo después de revisar TLS y autenticación.

elasticsearch:
  url: https://elastic.example.local:9200
  transport_profile: external
  namespace: production
  apikey: "<credencial-elastic>"
  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:<secreto-cifrado>"
    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}

Usa exactamente un modo de autenticación Elasticsearch: apikey o username/password. Si el clúster usa una CA privada, copia únicamente el certificado público a la configuración y define ca_file con una ruta absoluta. insecure_skip_verify mantiene el cifrado pero no valida la identidad del servidor; resérvalo para una excepción temporal y documentada.

El campo SAP passwd debe contener un valor cifrado enc:v1: generado para la misma instalación. No guardes la contraseña en claro ni la pases como argumento de un proceso. En portable, preserva junto con la configuración $SPOT_HOME/config/spot-sap-secret.key; perder o sustituir esa clave impide descifrar las credenciales existentes.

Generar `enc:v1:` de forma segura

En RPM/DEB, ejecuta el comando como el usuario del servicio. Pedirá la contraseña SAP sin mostrarla y escribirá únicamente el valor cifrado:

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

Copia la única línea enc:v1:... en sapconnection[].passwd. Para una automatización que ya entrega el secreto mediante un stream protegido, usa --stdin; no escribas el valor literal en la línea de comandos:

IFS= read -r -s -p 'Contraseña SAP: ' 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

También puedes usar un fichero temporal regular, sin symlinks y privado:

sudo install -o spot -g spot -m 0600 /ruta/protegida/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

En portable invoca el wrapper del propio artefacto; este deriva su raíz y usa la clave bajo config/:

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

La clave del sistema es /etc/spot/spot-sap-secret.key; la portable es $SPOT_HOME/config/spot-sap-secret.key. El ciphertext queda ligado a esa clave. Inclúyela en el backup protegido de configuración y restáurala junto con sus valores enc:v1:. No la borres, regeneres ni copies desde otra instalación: una clave distinta no puede descifrar las contraseñas existentes. Si una clave portable preexistente no tiene modo 0600, el comando falla sin modificarla.

Con manage_data_streams_ilm: false, bootstrap sólo verifica conectividad y no crea recursos. Con true, el agente necesita permisos de administración y gestiona exclusivamente los Data Streams metrics y logs. El namespace debe coincidir con el que lee el backend SPOT; un destino o namespace distinto produce dashboards vacíos aunque la extracción funcione.

SPOT 2.0 no admite índices separados para Jobs, Events o WPInfo. Los tres nombres se derivan de namespace: telemetría metrics, telemetría logs y el stream operativo aislado del agente.

Activar o instalar la licencia

El agente no ejecuta elastic-bootstrap ni run sin una licencia válida. Los avisos por consumo no detienen el connector; una licencia ausente, inválida, caducada o revocada sí.

RPM/DEB

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

# Activación online mediante prompt oculto
sudo -u spot /opt/spot/bin/spot-agent-sap license-activate

Para una licencia offline:

sudo install -o spot -g spot -m 0600 /ruta/recibida/licencia /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 con `systemd --user`

Las unidades incluidas apuntan a $HOME/spot-agent-sap-portable. Instálalas y arranca primero el validador:

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
# o: "$SPOT_HOME/bin/spot-agent-sap" license-install /ruta/protegida/licencia
"$SPOT_HOME/bin/spot-agent-sap" license-check

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

Solicita al administrador del host que habilite linger para el usuario runtime si el servicio debe seguir activo al cerrar la sesión. No ejecutes a la vez las unidades de usuario y los scripts manuales.

Portable con arranque manual

Para una validación controlada o si usas otro 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
# o: "$SPOT_HOME/bin/spot-agent-sap" license-install /ruta/protegida/licencia
"$SPOT_HOME/bin/spot-agent-sap" license-check

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

run-agent.sh mantiene el agente en primer plano para que lo supervise el proceso padre. Si no detecta el validador local, lo inicia y escribe sus salidas en $SPOT_HOME/log/license.out y license.err.

No pases la clave online como argumento posicional. Para automatización usa --stdin o --key-file con un fichero regular 0600. Consulta Licencias y renovación para estado, histórico y exportación del paquete cifrado sin interfaz web.

Aplicar cambios de configuración

En RPM/DEB, edita /etc/spot/.spot-agent-sap.yaml y reinicia el servicio. En portable, run-agent.sh crea $SPOT_HOME/run/spot-agent-sap.yaml sólo si no existe. Para aplicar un cambio al fichero editable:

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

Si no usas systemd, detén primero el proceso supervisado, elimina únicamente el fichero runtime generado y vuelve a ejecutar run-agent.sh. No borres config/spot-sap-secret.key, data/license ni data/spot-agent-sap.

Verificar la instalación

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

El launcher portable ejecuta elastic-bootstrap antes del daemon. Si la conectividad, autenticación, TLS o mappings no son válidos, termina con error y no inicia la extracción.

Comprueba después en el SPOT remoto Landing/Metrics, Events, Job Monitoring, Certificates y RFC & Integrations. Un backend 2.0 muestra Agent upgrade required ante un productor anterior y no interpreta documentos legacy.

Capacidades y seguridad

El probe de cada conexión marca cada familia como supported, unauthorized, unavailable o error. Una familia no disponible no bloquea las demás. El usuario RFC debe ser de sólo lectura:

dumps: error, programa, usuario, mandante, host y texto técnico; nunca memoria ni datos de negocio;
RFC: estado, destino, cola, función y error; nunca payload;
certificados: subject, issuer, serial, fingerprint, PSE/aplicación y validez; nunca claves privadas.

El agente conserva watermarks, solape y deduplicación. El backfill inicial de Jobs, dumps y RFC cubre 24 horas.

Backup, actualización y rollback

Para RPM/DEB, reinstala el mismo nombre de paquete con rpm -Uvh o dpkg -i; la configuración, licencia, journal y estado incremental se preservan. Sigue Upgrade, backup, restore y uninstall.

Para portable:

Detén el agente y el validador o sus unidades de usuario.
Haz un backup privado y verificado de config y data.
Verifica el nuevo tar y extráelo en un directorio distinto; nunca encima del árbol activo.
Migra sólo config/spot-agent-sap.yaml, config/spot-sap-secret.key, data/license y data/spot-agent-sap de esa misma instalación.
No copies bin, nwrfcsdk, scripts, share ni run desde la versión anterior.
Mantén la ruta estable $HOME/spot-agent-sap-portable si usas las unidades incluidas, recarga systemd y arranca primero licencia y después agente.
Valida licencia, bootstrap, ingesta y continuidad del histórico antes de retirar la versión anterior.

No clones data/license a otra instalación: contiene la identidad verificable local. Para rollback, vuelve al binario anterior y restaura su backup compatible completo.

Desinstalar portable

Deshabilita y detén las unidades de usuario, elimina sus copias de $HOME/.config/systemd/user y ejecuta systemctl --user daemon-reload. Archiva antes config y data si necesitas restaurar o renovar. Elimina el árbol portable sólo después de verificar el backup; no hay otros paths SPOT que limpiar en una instalación non-root correcta.

Resolución rápida de problemas

Síntoma	Comprobación
El agente termina antes de arrancar	Ejecuta `license-check` y revisa `license.err`
Bootstrap falla	Revisa URL, modo de autenticación, CA, namespace y permisos ILM
Un cambio portable no se aplica	Detén el agente y regenera sólo `run/spot-agent-sap.yaml`
El servicio se detiene al cerrar sesión	Solicita linger para el usuario runtime
Falta una librería SAP	Revalida el checksum; no sustituyas `nwrfcsdk` ni los wrappers
Hay documentos pero dashboards vacíos	Alinea destino y `namespace` entre agente y backend
Calidad de usuarios parcial/desconocida	Comprueba fuentes habilitadas y frescura; no es un fallo del proceso
No existe UI local ni puerto `8080`	Es el comportamiento correcto de connector-only

No incluyas configuraciones, credenciales ni respuestas completas de licencia al recopilar evidencias. Usa salidas de estado saneadas y los logs indicados.

Elige el método de instalación​

Antes de instalar​

Instalar con RPM o DEB​

Verificar e instalar​

Instalar portable sin root​

Descargar, verificar y extraer​

Configurar el agente​

Generar enc:v1: de forma segura​

Activar o instalar la licencia​

RPM/DEB​

Portable con systemd --user​

Portable con arranque manual​

Aplicar cambios de configuración​

Verificar la instalación​

RPM/DEB​

Portable​

Capacidades y seguridad​

Backup, actualización y rollback​

Desinstalar portable​

Resolución rápida de problemas​

Elige el método de instalación

Antes de instalar

Instalar con RPM o DEB

Verificar e instalar

Instalar portable sin root

Descargar, verificar y extraer

Configurar el agente

Generar `enc:v1:` de forma segura

Activar o instalar la licencia

RPM/DEB

Portable con `systemd --user`

Portable con arranque manual

Aplicar cambios de configuración

Verificar la instalación

RPM/DEB

Portable

Capacidades y seguridad

Backup, actualización y rollback

Desinstalar portable

Resolución rápida de problemas