Skip to content

NSCA — Nagios migration

NSCA (Nagios Service Check Acceptor) is the legacy protocol where send_nsca clients send passive check results to a central server. Vesana can accept those packets — letting existing Nagios installations migrate to Vesana without complete rebuild.

Concept

flowchart LR
    NC1[send_nsca] -->|Port 5667| NR[Vesana NSCA receiver]
    NC2[send_nsca] -->|Port 5667| NR
    NR --> P[Pipeline: receiver → Redis → worker → DB]
    P --> UI[Frontend shows status]

Existing clients just point to the Vesana server instead of the old Nagios. No code changes on the client side.

Activate

In .env:

NSCA_RECEIVER_ENABLED=true
NSCA_PORT=5667
NSCA_PASSWORD=<shared secret from old nsca.cfg>
NSCA_DECRYPTION_METHOD=2     # 0 = none, 1 = XOR, 2 = DES, 14 = AES-128, ...

NSCA_DECRYPTION_METHOD and NSCA_PASSWORD must be identical to the values in the old nsca.cfg, otherwise incoming packets are rejected as corrupt.

Restart stack:

docker compose -f /opt/vesana/docker-compose.prod.yml up -d

The NSCA receiver runs as its own service (Go daemon) accepting UDP/TCP packets on 5667.

Migration path

Preparation

# On the old Nagios server:
grep decryption_method /etc/nsca.cfg
grep ^password        /etc/nsca.cfg
grep server_port      /etc/nsca.cfg
grep host_name        /etc/nagios/objects/hosts.cfg | sort -u

These values are needed for Vesana config and host import.

Import hosts

Per Nagios host, create an Vesana host with:

  • name exactly like Nagios host_name (NSCA packets contain host_name as identifier — no match, no result lands)
  • monitoring_mode = nsca
  • Profile: specific or generic „NSCA host"

Importer script in scripts/nsca_import_nagios.py parses objects/hosts.cfg and creates hosts.

Import services

Per Nagios service create a host service with:

  • display_name = service_description from Nagios
  • check_mode = passive_nsca
  • check_type = nsca_passive

Once the first send_nsca call arrives, Vesana should find the host + service via (host_name, service_description) and append the result.

When an NSCA packet arrives but host/service can't be found: audit entry with unmatched_nsca. Visible in the discovery UI as „NSCA packets for unknown hosts/services" → manually create or set up auto-create rules.

Auto-create rule

/admin/nsca/auto-create:

  • Auto-create hosts for unknown host_name (default: no, safer)
  • Auto-create services analogously
  • Choose default profile for auto-created hosts

Useful when the Nagios install grows continually and you don't want to port every config manually.

Parallel operation

During migration you can configure send_nsca to send to multiple targets (wrapper script):

#!/bin/bash
# /usr/local/bin/send_nsca_dual
INPUT=$(cat)
echo "$INPUT" | send_nsca -H old-nagios.example.com -c /etc/send_nsca.cfg
echo "$INPUT" | send_nsca -H vesana.example.com  -c /etc/send_nsca-vesana.cfg

Both systems run in parallel, status comparison reveals mismatches.

Cut-over

When Vesana sees and shows all packets:

  1. Switch DNS / IP → send_nsca clients send only to Vesana
  2. Old Nagios server in read-only for a week (backup)
  3. When confident: shut down Nagios

What features come along

Works immediately

  • Status display (OK/WARN/CRIT/UNKNOWN — same model as Nagios)
  • Error overview / problem dashboard
  • Alert rules + channels
  • Downtimes, ACK, audit log
  • Multi-tenant

Works with perfdata parsing

Nagios plugins return perfdata after |. Vesana parses it automatically into check_results.perfdata (JSONB) — charts and heatmaps work for gauge metrics.

Format: label=value[UOM];warn;crit;min;max.

Doesn't work from NSCA alone

These features need agent or collector:

Feature Why
Agent heartbeat / auto-update NSCA clients are „dumb" — no pull
Service discovery Agent detects services automatically
Log collection Agent gathers logs
Active SNMP/ping/SSH/HTTP checks Collector
Retry interval (faster failure detection) Server doesn't drive polling
Soft/hard state with retry Server doesn't drive polling

The gradual upgrade path: NSCA → agent (CPU/memory/disk locally) → collector (SNMP/ping/HTTP) — service by service.

What you tell the Nagios admin

„Just put vesana.example.com as server in your send_nsca.cfg. Everything else stays the same."

The rest is on Vesana side — create hosts and services, document migration plan.

Limitations

  • Nagios plugins themselves don't migrate — they still run on the machines, only the sender target changes
  • Active Nagios checks (active_checks_enabled = 1) need separate migration (agent or collector)
  • Nagios notification setup (email templates, escalations) doesn't auto-migrate — recreate alert rules in Vesana
  • PNP4Nagios / NagVis have no direct equivalent — custom dashboards are the alternative

Next