http-smtp-rele 0.14.0

Minimal, secure HTTP-to-SMTP submission relay
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# Reverse Proxy Setup

`http-smtp-rele` binds to a loopback address and relies on a reverse proxy
for TLS termination, access control, and public-facing HTTP.

> **Alternative:** For direct TLS without a proxy, build with
> `--features tls` and configure `[server].tls_cert` / `tls_key`.
> See [Configuration Reference](../guides/configuration.md).

---

## nginx

### Basic TLS termination

```nginx
server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate     /etc/ssl/relay.example.com.crt;
    ssl_certificate_key /etc/ssl/relay.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
        proxy_pass       http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Restrict internal-only endpoints
    location /readyz {
        allow 10.0.0.0/8;
        allow 127.0.0.1;
        deny  all;
        proxy_pass http://127.0.0.1:8080;
    }

    location /metrics {
        allow 10.0.0.0/8;   # monitoring network only
        deny  all;
        proxy_pass http://127.0.0.1:8080;
    }
}

# Redirect HTTP → HTTPS
server {
    listen 80;
    server_name relay.example.com;
    return 301 https://$host$request_uri;
}
```

### IP-based client restriction

If your callers are known services:

```nginx
location /v1/ {
    allow 203.0.113.0/24;   # production app servers
    allow 198.51.100.5;     # staging
    deny  all;
    proxy_pass http://127.0.0.1:8080;
}
```

### Trusted proxy headers

When nginx passes `X-Forwarded-For`, configure the relay to trust it:

```toml
[security]
trust_proxy_headers  = true
trusted_source_cidrs = ["127.0.0.1/32"]
```

---

## Caddy

```caddy
relay.example.com {
    reverse_proxy 127.0.0.1:8080

    @internal {
        path /readyz /metrics
        not remote_ip 10.0.0.0/8
    }
    respond @internal 403
}
```

---

## relayd (OpenBSD)

```
table <relay> { 127.0.0.1 }
table <monitors> { 10.0.0.1 10.0.0.2 }

http protocol "rele_http" {
    # Forward real client IP
    header append "X-Forwarded-For" value "$REMOTE_ADDR"

    # Block external access to monitoring endpoints
    block request path "/readyz"
    block request path "/metrics"
    pass  request from <monitors> path "/readyz"
    pass  request from <monitors> path "/metrics"

    pass
}

relay "rele_relay" {
    listen on egress port 443 tls
    protocol "rele_http"
    forward to <relay> port 8080
}
```

The TLS certificate is configured at the `relayd` level; `http-smtp-rele`
does not need to handle TLS when using `relayd`.

---

## HAProxy

```haproxy
frontend rele_front
    bind :443 ssl crt /etc/ssl/relay.pem
    default_backend rele_back
    acl is_internal src 10.0.0.0/8
    acl is_monitor  path /readyz /metrics
    http-request deny if is_monitor !is_internal

backend rele_back
    server relay1 127.0.0.1:8080 check
```

---

## Securing the monitoring endpoints

`/readyz` reveals SMTP reachability. `/metrics` exposes request and SMTP
counters. Both should be restricted to your internal monitoring network.

`/healthz` is a simple liveness probe and may be safely exposed publicly
if your load balancer requires it.