NAT-AGT-001 — SCP timeout when connecting to the OXE

PBX unreachable (network split or firewall). The agent retries with exponential backoff (30s, 1min, 5min, 30min, 1h, 6h max). After 1h of continuous failure, an email alert is sent to the tenant admin.

NAT-AGT-002 — Taxation over IP license missing on OXE

Without the Taxation over IP license, the OXE does not produce icals/ocals files in /usr4/account/. Ask your Alcatel-Lucent integrator to add the license, then check with spadmin -l | grep -i account.

NAT-AGT-003 — SCP Permission denied

Two possible causes: /etc/shells missing /bin/bash, or the read ACL on /usr4/account/ too restrictive. Fix: grep bash /etc/shells || echo /bin/bash >> /etc/shells AND setfacl -R -m u:natalia-collector:r /usr4/account/.

NAT-AGT-004 — SSH connection refused

SSH not enabled on the OXE. From the V24 console as root, run netadmin -m, open the Security menu and enable SSH (or /etc/init.d/sshd start).

NAT-AGT-005 — Path /usr4/account not found

Non-standard OXE install. Run find /usr -name TAXA*.DAT -type f 2>/dev/null on the OXE to locate the CDR folder, then update the agent configuration.

NAT-AGT-006 — OXO JWT expired

Polling interval too long versus the JWT TTL (1 hour). Reduce polling to 30 min in the agent settings.

NAT-AGT-007 — Agent disk buffer above 80%

The agent buffers files locally for 3 days if the API is unreachable. Above 80% disk, an alert fires. Above 95% (NAT-AGT-008), polling stops to avoid corruption. The OXE itself keeps 31 days, so no data is lost.

NAT-AGT-008 — Agent disk buffer above 95% — polling paused

Cloud API unreachable for ~3 days. Restore connectivity to api.getnatalia.com:443, polling resumes automatically.

NAT-AGT-009 — I lost the admin password of the agent

Without vTPM on the VM, the encrypted config is unrecoverable by design. Redeploy a fresh OVA and re-enter the config. With vTPM (vSphere, Proxmox, recent Hyper-V), the key is sealed to the TPM and the agent boots without prompting.

NAT-AGT-010 — CDR parser failed (unexpected format)

The .DAT file is a Lempel-Ziv compressed binary, not a CSV. The agent tried to read it raw. Check that gunzip is available on the agent and the file is decompressed before parsing.

Cloud Edition See On-Premise Edition →

Natalia Analytics troubleshooting

Name: Natalia
Author: Natalia

Operational guide for the most frequent errors. Every entry maps to an error code documented in the complete reference. Case not listed? Contact [email protected].

Ports & firewall matrix

Reference for the network team. The agent VM never opens an inbound port. All traffic is outbound, initiated by the agent.

Source	Destination	Port	Protocol	Direction	Mandatory?
Agent VM	PBX OXE	`22`	TCP / SSH	Outbound	YES (OXE mode)
Agent VM	PBX OXO	`443` or `30443`	TCP / HTTPS	Outbound	YES (OXO mode)
Agent VM	`api.getnatalia.com`	`443`	TCP / HTTPS	Outbound	YES
No inbound port required on the Agent VM		—	—	—	Security best practice

→ Full threat model in the security architecture.

Operational errors by code (NAT-AGT-001 → 010)

Quick-fix table. Full reference (API codes included): error codes.

Code	Symptom	Cause	Resolution
NAT-AGT-001	SCP timeout to the PBX	Network split or firewall blocking 22	Auto retry (exponential backoff). Check firewall.
NAT-AGT-002	Taxation license missing on OXE	`spadmin -l` does not list the account package	Contact your Alcatel-Lucent integrator
NAT-AGT-003	SCP Permission denied	`/etc/shells` or ACL on /usr4/account/	`setfacl -R -m u:natalia-collector:r /usr4/account/`
NAT-AGT-004	SSH connection refused	SSH not enabled on the OXE	`netadmin -m` → Security → SSH
NAT-AGT-005	`/usr4/account` path not found	Non-standard OXE install	`find /usr -name "TAXA*.DAT"`
NAT-AGT-006	OXO JWT expired	Polling > 60 min (TTL JWT)	Set polling to 30 min
NAT-AGT-007	Disk buffer > 80%	API unreachable or polling too frequent	Wait for API recovery, or drain queue
NAT-AGT-008	Disk buffer > 95% — polling PAUSED	Cloud API unreachable ~3 days	Restore API, polling resumes automatically
NAT-AGT-009	Admin password lost	vTPM absent on the host	Redeploy a fresh OVA (irrecoverable by design)
NAT-AGT-010	CDR parser failed	`.DAT` not decompressed before parsing	`gunzip` on the agent, requeue file

OXE SCP errors — raw shell messages

Reverse lookup: shell error message to root cause and fix. Useful when you reproduce the SCP call manually from the agent VM (scp natalia-collector@<OXE-IP>:/usr4/account/...).

Shell error message	Root cause	Resolution
`ssh: connect to host ... port 22: Connection refused`	SSH not enabled on OXE	`netadmin -m` → Security → SSH → enable
`Permission denied (publickey,password)`	Wrong login/password	Check `/etc/passwd` + trusted hosts
`scp: No such file or directory`	Taxation license missing — no .DAT files produced	`spadmin -l \| grep -i account`
`scp: ... Permission denied`	Restrictive ACL on /usr4/account/	`setfacl -R -m u:natalia-collector:r /usr4/account/`
`ssh_exchange_identification: Connection closed`	Agent IP not in /etc/hosts.allow on OXE	Add agent IP via netadmin
`Warning: Remote host identification has changed`	OXE was replaced / rekeyed	`ssh-keygen -R <OXE-IP>` on agent VM
Connection OK but 0 .DAT files	Accounting not configured in OMC	Verify Accounting setup in OMC
`.DAT` file not parseable	Compressed binary read as CSV	`file TAXA*.DAT` then `gunzip`

Buffer & retention behavior

Agent behavior when the Natalia Cloud API is down for hours/days

The agent buffers up to 3 days on disk and retries with exponential backoff. The web UI shows a "Sync delayed" badge with the queued file count. Past 3 days, the PBX still holds its CDR (OXE keeps 31 days in /usr4/account/), so no data is lost even in the worst case.

Agent behavior when its own buffer fills up

Above 80% disk (NAT-AGT-007), an email alert fires. Above 95% (NAT-AGT-008), polling stops to avoid corruption. The PBX retention takes over until connectivity is restored.

More context: the glossary (SCP, vTPM, JWT, WMC...) or the complete error code reference.

Last updated : May 24, 2026

Suggest an edit