Corenil Relay Operations

The relay receives public HTTPS callbacks, stores them safely in a spool, forwards them into Corenil, and exposes relay health for monitoring. The relay does not post to the ledger directly.

Hostname: relay.corenil.com

Endpoint: /inbound/c2b_confirmation

Status JSON: /relay_status.json

/var/www/cgi-bin/c2b_confirmation
/usr/local/bin/c2b_forwarder
/usr/local/bin/c2b_replay_one
/usr/local/bin/c2b_quarantine_one
/usr/local/bin/c2b_cleanup_old
/usr/local/bin/relay_status
/usr/local/bin/c2b_worker
/usr/local/bin/relay_statusd

/etc/rc.d/c2b_worker
/etc/rc.d/relay_statusd

/var/www/spool/c2b
/var/www/spool/c2b_done
/var/www/spool/c2b_failed
/var/www/spool/c2b_quarantined

/var/log/c2b_forwarder.log
/var/www/htdocs/relay_status.json

doas rcctl check httpd
doas rcctl check slowcgi
doas rcctl check c2b_worker
doas rcctl check relay_statusd

All should report ok.

Forwarding and relay status generation are handled by service daemons, not by per-minute cron jobs. Only retention cleanup remains in cron.

c2b_worker      → drains /var/www/spool/c2b and forwards into Corenil
relay_statusd   → regenerates /var/www/htdocs/relay_status.json
cron            → runs daily retention cleanup only

Healthy relay state:

doas ls -l /var/www/spool/c2b
doas ls -l /var/www/spool/c2b_failed
doas tail -20 /var/log/c2b_forwarder.log
cat /var/www/htdocs/relay_status.json

Expected:

pending = 0 or low
done increases over time
failed = 0
recent log lines show [OK]
last_log reflects the most recent forward outcome

doas /usr/local/bin/c2b_forwarder
doas /usr/local/bin/relay_status

Use this after testing, after network recovery, or when checking backlog clearance. The daemon services normally do this automatically, but manual runs remain valid for operator use.

List failed files:

doas ls -l /var/www/spool/c2b_failed

Replay one file:

doas /usr/local/bin/c2b_replay_one /var/www/spool/c2b_failed/<file>.json

Success means:

file moves to c2b_done
log shows REPLAY_OK

Use quarantine when a failed file has been reviewed and should not be retried.

doas /usr/local/bin/c2b_quarantine_one /var/www/spool/c2b_failed/<file>.json

Success means:

file moves to c2b_quarantined
log shows QUARANTINED

Remove old files from c2b_done and c2b_quarantined.

doas /usr/local/bin/c2b_cleanup_old 30

This keeps 30 days of retained files. Cleanup is intentionally kept under cron because it is low-frequency housekeeping.

doas /usr/local/bin/relay_status
cat /var/www/htdocs/relay_status.json

This regenerates the relay health JSON from current spool state. Normally relay_statusd keeps it current automatically.

{
  "pending": 0,
  "done": 5,
  "failed": 0,
  "last_log": "[OK] FORWARD_TEST_002"
}

The relay status JSON is the current operator view of spool and forward state.

curl -k -X POST \
  -H 'Host: relay.corenil.com' \
  -H 'Content-Type: application/json' \
  --data '{"TransID":"TEST001","TransAmount":"100.00","MSISDN":"254700000001"}' \
  https://192.168.8.2/inbound/c2b_confirmation

Expected response:

{"ResultCode":0,"ResultDesc":"Accepted"}

Public HTTPS
  ↓
c2b_confirmation CGI
  ↓
/var/www/spool/c2b
  ↓
c2b_worker
  ↓
c2b_forwarder
  ↓
Corenil /api/inbox_ingest
  ↓
core.inbox_event
  ↓
queue runner
  ↓
receipt
  ↓
ledger

Services:
  httpd
  slowcgi
  c2b_worker
  relay_statusd

Cron:
  PATH=/bin:/usr/bin:/usr/sbin:/usr/local/bin
  15 2 * * * /usr/local/bin/c2b_cleanup_old 30

doas rcctl enable c2b_worker
doas rcctl enable relay_statusd

doas rcctl start c2b_worker
doas rcctl start relay_statusd

doas rcctl restart c2b_worker
doas rcctl restart relay_statusd

doas rcctl stop c2b_worker
doas rcctl stop relay_statusd

Accepted response, but nothing reaches Corenil

doas ls -l /var/www/spool/c2b
doas ls -l /var/www/spool/c2b_failed
doas tail -50 /var/log/c2b_forwarder.log
doas rcctl check c2b_worker
doas /usr/local/bin/c2b_forwarder
doas /usr/local/bin/relay_status

Failed count is nonzero

doas ls -l /var/www/spool/c2b_failed
doas cat /var/www/spool/c2b_failed/<file>.json

Then either replay or quarantine.

Public endpoint unreachable

doas rcctl check httpd
doas rcctl check slowcgi
doas pfctl -f /etc/pf.conf

Status file stale

doas rcctl check relay_statusd
doas /usr/local/bin/relay_status
cat /var/www/htdocs/relay_status.json

Worker not draining backlog

doas rcctl check c2b_worker
doas ls -l /var/www/spool/c2b
doas tail -50 /var/log/c2b_forwarder.log
doas /usr/local/bin/c2b_forwarder

Do not edit payload files unless absolutely necessary. Prefer replaying or quarantining the original file. Corenil ingest is idempotent, so replay with the same TransID is safe.

Open this page at:

https://relay.corenil.com/relay_ops.html