Fax
MonoPbx sends and receives fax over SIP. Users send a PDF from the web client and receive faxes by e-mail as a PDF. The T.30 fax protocol runs in a separate engine process (mpbx-faxd, built on SpanDSP), so nothing of it is linked into the PBX.
Install the fax engine
The engine ships as its own image and shares the PBX container's network, because the media ports the PBX allocates for a fax call are bound there.
# From deploy/compose/prod: start the PBX with the fax engine next to it.
docker compose -f compose.yaml -f compose.fax.yaml up -d
docker compose -f compose.yaml -f compose.fax.yaml ps
compose.fax.yaml sets the three [fax] settings of the PBX for you:
| Setting | Environment | Meaning |
|---|---|---|
engine | MPBX__FAX__ENGINE | tcp://127.0.0.1:7310 (the engine's control port, loopback only, not authenticated) or the absolute path of the engine program. |
spool | MPBX__FAX__SPOOL | Directory shared with the engine for received pages and documents to send. |
media_ip | MPBX__FAX__MEDIA_IP | Address the engine binds its media on; it must be reachable from the media relay. |
The PBX also needs its SIP stack and file storage configured (the PDFs are kept in the company's file store). The engine may start after the PBX: the PBX keeps retrying, and checks the engine every 10 seconds. While it is down, queued faxes wait instead of failing, and inbound fax calls are refused. The metric mpbx_fax_engine_up is 1 while the engine answers and 0 while it is down; mpbx_fax_engine_restarts_total counts reconnections. Alert on mpbx_fax_engine_up == 0 for more than a few minutes.
The engine runs with all capabilities dropped, a read-only file system, 256 MB of memory and one CPU. It handles at most 16 calls at the same time, 30 minutes and 200 pages each, and 64 MB per document.
Fax lines
Under Admin, Fax lines add one line per fax number:
- Number: the
+E.164number. It must be a DID of one of the company's trunks, because an inbound call to it is answered by the fax engine. A number can belong to one line only. - Send to: up to 10 e-mail addresses; each receives every fax of this line.
- T.38 and G.711 fallback: see the next section.
- Enabled: a disabled line is not answered.
A user who may send faxes (permission fax:write) uses Fax in the web client: enter the destination, pick a PDF (up to 10 MiB) and send. The list shows the faxes the user sent; an administrator sees every fax of the company. Each fax with a document has a Download button, and a queued fax can be cancelled. Plain users have no fax permission until an administrator grants fax:read or fax:write to a role.
T.38 or G.711
- G.711 (audio) pass-through works with every carrier that keeps the audio clean: no echo cancellation, no jitter-buffer tricks, no transcoding. It is slower to start and sensitive to packet loss.
- T.38 sends the fax as data packets (UDPTL) and survives packet loss much better. It needs a trunk that supports T.38. The PBX offers T.38 by a re-INVITE when the line allows it and the other side advertises it, and never over SRTP or WebRTC legs.
With both options on (the default), the PBX tries T.38 first and falls back to G.711 when the carrier refuses it or does not answer the re-INVITE. Turn G.711 fallback off only when the carrier guarantees T.38; then a refusal fails the fax with t38_refused. Turn T.38 off for a carrier that answers the re-INVITE badly. Outbound faxes are dialled through the normal dial plan as the sending user, so toll-fraud and outbound rules apply.
Limits
| What | Limit |
|---|---|
| Document | PDF, at most 10 MiB (MPBX-FAX-DOCUMENT-INVALID otherwise) |
| Resolution | The PDF is rasterised to 204 x 196 dpi, black and white (threshold) |
| Pages per fax | 200 |
| Call length | 30 minutes |
| Parallel calls | 16 per engine |
| Retries | 3 attempts, 5 and 15 minutes apart, for busy, no answer and line errors; faults that retrying cannot fix (bad document, no common mode, T.38 refused) fail at once |
| Storage | Faxes count against the company's fax storage quota; a received fax over quota is refused |
Retention
The PDF of every finished fax (sent and received) is kept for 365 days by default, then deleted; the fax stays in the history with a note that its document is gone (MPBX-FAX-DOCUMENT-GONE). Set MPBX_FAX_RETENTION_DAYS for another install-wide default (0 keeps everything). A company administrator can set its own period under Calls and routing > Trunks > Fax lines, in the Document retention form (1 to 3650 days; 0 keeps everything for that company; empty follows the install default). Deletions are counted in the audit log. Downloads of a fax PDF are audited too.
Mail delivery
A received fax is converted to one PDF, stored in the company's file store and mailed to every address of the line, with the PDF attached and the sender number, pages and time in the text. Mail goes out through the company's mail settings. If the mail provider is down the fax is not lost: it is stored and listed as delivered with the note mail_failed, and users download it from the web client. Each received fax raises the event fax.received, each sent one fax.sent, and each failure fax.failed; subscribe with a webhook or the events WebSocket.
Troubleshooting
| Symptom | Check |
|---|---|
| Faxes stay queued | mpbx_fax_engine_up is 0: check docker compose ps and the engine's logs; see MPBX-FAX-ENGINE-UNAVAILABLE. A fax with a retry time waits for it. |
| Inbound call is not answered as a fax | The number must match an enabled line exactly (+E.164) and be a DID of a trunk of the same company. |
Fails with t38_refused or no_t38_media | The carrier does not support T.38: allow the G.711 fallback. |
Many t30_timeout or garbled pages on G.711 | Packet loss or audio processing in the path. Use T.38, disable echo cancellation and codecs other than PCMU/PCMA on the trunk, and make sure media_ip is reachable from the media relay. |
Fails with rasterize_failed or document_error | The PDF is damaged or password protected. Print it to a new PDF and send again. |
| Fax received but no mail | The mail settings of the company; the fax shows mail_failed. The PDF is still in the list. |
| Download says the document is gone | Retention removed it. |
Proof that the whole path works is the loopback test deploy/faxd/tests/e2e.sh: it sends a PDF as a user, rasterises and transmits it through two real engines, receives it on a second line, and checks the stored PDF, the mails, the events and the download. Tests with a real fax machine or a carrier's T.38 are done in your lab.
In the console
Open Numbers and trunks, Fax lines (/admin/fax-lines). You need settings:read to see the page and settings:write to change it.
- Add a fax line, edit one (name, number, e-mail recipients, T.38, G.711 fallback and whether the line answers calls) or delete it.
- The Document retention form sets how long the PDF of a finished fax is kept. The fax itself stays in the history.