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}

sapconnection[].id es obligatorio, no vacío y único dentro del proceso. Es el source_id escrito en cada documento y el targetId que seleccionará el usuario; no se genera sap-N, no se resuelve el alias y no hay migración automática. Debe cumplir ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ después de recortar espacios; la comparación es case-sensitive. Puedes añadir N bloques SAP: todos escriben en este único Elasticsearch+namespace. Para repartirlos entre clusters, ejecuta otra instancia de connector con su propio fichero y servicio. Un SAP no debe estar en dos connectors.

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

Construir una imagen Docker privada con la contraseña temporal

Si preparas una imagen privada de connector-only, el Dockerfile puede consumir la contraseña mediante el secreto BuildKit sap_password y ejecutar spot-agent-sap encrypt --password-file /run/secrets/sap-password durante el build. En ese caso no necesitas crear file-passwd-sap ni añadirlo a .dockerignore: pasa el valor directamente desde una variable temporal:

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

El Dockerfile debe montar ese secreto con RUN --mount=type=secret,id=sap_password,target=/run/secrets/sap-password,required=true. BuildKit no lo incorpora a las capas de la imagen. El valor literal sí puede quedar en el historial del shell local, por lo que usa este método únicamente en un equipo de construcción controlado. No declares la contraseña mediante ARG o ENV en el Dockerfile. Mantén la imagen en un registro privado si también contiene la licencia offline y la clave de cifrado de la instalación.

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 un read scope del backend SPOT. El backend descubre cada SAP mediante tenant_id=onprem + source_id; un scope equivocado o un ID duplicado entre scopes produce un diagnóstico de binding, no un fallback silencioso.

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, cada ejecución de run-agent.sh deriva de nuevo $SPOT_HOME/run/spot-agent-sap.yaml desde el fichero editable, lo publica de forma atómica con modo 0600 y usa la misma copia para bootstrap y daemon.

Si cambias la configuración desde la interfaz de una suite portable local, SPOT serializa el guardado y el reinicio. Un cambio idéntico no reinicia un agente sano. Si el agente no puede detenerse o arrancar, la interfaz informa del fallo y puedes repetir el mismo guardado; no inicies otro agente mientras exista un PID no verificable. Con systemd --user o arranque manual, reinicia el proceso supervisado después de editar. No borres config/spot-sap-secret.key, data/license ni data/spot-agent-sap, y no necesitas eliminar el runtime generado.

Al recargar una configuración RPM/DEB, el agente prepara primero los Data Streams del nuevo namespace. Sólo después inicia la evidencia de licencia y la extracción SAP. Si el bootstrap falla, el servicio queda en error sin crear un índice normal incompatible; corrige el target y reinícialo.

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

El primer arranque puede tardar hasta 3 minutos mientras el bootstrap espera a Elasticsearch y completa sus validaciones. Durante ese intervalo systemd mantiene el servicio en estado de activación.

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. El backend sólo interpreta documentos con schema_version=2; los documentos legacy se ignoran. Si el target seleccionado no tiene una señal v2 genuina, la vista muestra Sin datos o UNKNOWN según su contrato. En modo remote, el journal de un conector local no autoriza ni bloquea las lecturas de un standalone.

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 descripción genérica del error de ejecución tomada de SNAPT; nunca el texto largo de una instancia ST22, 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.

Tras actualizar un conector afectado, SPOT ejecuta una sola reparación acotada de las descripciones de dumps retenidos durante los 30 días anteriores. La reparación se separa de la colección actual, se limita a cada source/mandante y añade una nueva observación determinista: no modifica ni elimina documentos históricos. Si se reinicia, reintenta con las mismas identidades y los conflictos create-only se tratan como deduplicación. El progreso se conserva en /var/lib/spot-agent-sap/dump-description-repair-v2.json o, en portable, en $SPOT_HOME/data/spot-agent-sap/dump-description-repair-v2.json; inclúyelo en el backup del estado y no lo edites para forzar una repetición.

Las colecciones usan frecuencia fija con fases deterministas y un dispatcher acotado a dos ejecuciones. Metrics, Work Processes y el snapshot de long-running jobs conservan prioridad; los ciclos atrasados se consolidan sin backlog. Jobs y CCMS se procesan por páginas y Elasticsearch recibe bulks de como máximo 500 documentos o 8 MiB. La unidad limita el agente a dos cores, avisa a 640 MiB y lo detiene antes de superar 768 MiB.

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:

1. Detén el agente y el validador o sus unidades de usuario.
2. Haz un backup privado y verificado de config y data.
3. Verifica el nuevo tar y extráelo en un directorio distinto; nunca encima del árbol activo.
4. 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.
5. No copies bin, nwrfcsdk, scripts, share ni run desde la versión anterior.
6. 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.
7. 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	Comprueba read scope+namespace, schema_version=2, tenant_id=onprem y source_id exacto; selecciona ese target SAP
El target aparece con conflicto	El mismo source_id está en dos scopes o publica SID/client distintos; corrige el connector, no cambies el alias
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.