smtpd-tables-scripts

Utility helpers for OpenSMTPD table backend debugging.

Files

• table-spy: transparent proxy for table backends; logs live protocol traffic between smtpd and a real backend.
• table-debug: test helper for manual protocol debugging through a local TCP listener.

table-spy

What it does

• Starts the real backend as a child process.
• Forwards bytes both ways:
  • smtpd stdin -> backend stdin
  • backend stdout -> smtpd stdout
• Logs both directions with source prefixes (smtpd: and backend name).
• Also logs backend stderr as <backend>-stderr:.

This is transparent for smtpd and the real backend and supports asynchronous table protocol traffic.

Usage

./table-spy /etc/mail/spy.conf

Config format (/etc/mail/spy.conf)

Required keys:

backend /usr/local/libexec/smtpd/table-postgres
backend_config /etc/mail/postgres.conf
logfile /var/log/table-spy.log

Accepted separators: whitespace, :, or =.

OpenSMTPD config example

table vdomains spy:/etc/mail/spy-vdomains.conf

Then create one spy config per table (spy-vdomains.conf, etc.) that points to the real backend and backend config.

table-debug

What it does

• Reads table protocol lines from smtpd on stdin.
• Forwards them to a hardcoded local TCP listener at 127.0.0.1:25252.
• Forwards lines received from that listener back to smtpd on stdout.

Use this when you want to manually emulate a backend or inspect/alter protocol exchanges in a controlled test setup.

Usage

1. Start a local listener (example):

nc -l 127.0.0.1 25252

2. Configure a table to use debug: backend, for example:

# table my_debug debug:/etc/mail/anything

3. Interact through the listener and observe request/response flow.

Install instructions

Install both scripts to OpenSMTPD helper directory:

doas install -o root -g wheel -m 0755 smtpd-tables-scripts/table-spy /usr/local/libexec/smtpd/table-spy
doas install -o root -g wheel -m 0755 smtpd-tables-scripts/table-debug /usr/local/libexec/smtpd/table-debug

For table-spy logging:

doas touch /var/log/table-spy.log
doas chown _smtpd:_smtpd /var/log/table-spy.log
doas chmod 0640 /var/log/table-spy.log

For spy config readability:

doas chmod 0644 /etc/mail/spy-*.conf

Validate and reload:

doas smtpd -n
doas rcctl restart smtpd

Notes

• table-spy wraps executable helper backends (such as table-postgres).
• Built-in backends like file: are not external helper binaries and are not wrapped by table-spy unless replaced by an executable backend.