Corenil Relay Operations

Relay operations reference for public inbound processing and forwarding into Corenil.

Purpose

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.

Public Endpoint

Hostname: relay.corenil.com

Endpoint: /inbound/c2b_confirmation

Status JSON: /relay_status.json

Important Paths

/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

/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

Services

doas rcctl check httpd
doas rcctl check slowcgi

Both should report ok.

Normal Health

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
failed = 0
recent log lines show [OK]

Manual Forward Run

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

Use this after testing, after network recovery, or when checking backlog clearance.

Replay One Failed File

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

Quarantine One Failed File

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

Cleanup Old Files

Remove old files from c2b_done and c2b_quarantined.

doas /usr/local/bin/c2b_cleanup_old 30

This keeps 30 days of retained files.

Status Refresh

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

This regenerates the relay health JSON from current spool state.

Public Endpoint Test

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"}

Forwarding Flow

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

Current Cron

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

Troubleshooting

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 /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 /usr/local/bin/relay_status
cat /var/www/htdocs/relay_status.json

Operating Rule

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.

Daraja Sandbox Notes

For sandbox C2B testing, the shortcode used during URL registration must match the shortcode used during simulation.

If the shortcodes do not match, the simulator may accept the request, but the callback may not reach the relay endpoint.

Always verify these three together:

Validation URL registered correctly
Confirmation URL registered correctly
The same shortcode used for both registration and simulation

Reference Page

Open this page at:

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