Configuring Mail Proxy
1. Enabling Mail Module
The Nginx mail proxy module is not compiled by default and must be enabled during compilation.
| Directive | Values | Description |
|---|---|---|
on |
Enables the mail proxy module |
Example: Enabling Mail Module in Nginx Configuration
mail {
auth_http 127.0.0.1:8080/mail/auth;
capabilities "STARTTLS" "AUTH PLAIN";
server_name mail.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
}
Note: The mail module requires the
nginx-mail package or manual compilation with the --with-mail flag.
2. Configuring SMTP Proxy
| Directive | Description | Values | Default |
|---|---|---|---|
| smtp_client_cert | Path to the client certificate file used for authentication | /path/to/client.crt |
none |
| smtp_client_key | Path to the client key file used for authentication | /path/to/client.key |
none |
| smtp_client_verify | Controls whether to verify the server's certificate | on, off |
off |
| smtp_proxy_bind | Specifies the local address and port to bind to | address, address:port |
any |
| smtp_proxy_connect_timeout | Timeout for connecting to the SMTP server | time |
60s |
| smtp_proxy_error_page | Custom error page for SMTP proxy errors | url |
none |
| smtp_proxy_pass | Specifies the SMTP server to forward requests to | address, unix:socket |
none |
| smtp_proxy_read_timeout | Timeout for reading from the SMTP server | time |
60s |
| smtp_proxy_send_timeout | Timeout for sending to the SMTP server | time |
60s |
| smtp_proxy_ssl | Enables or disables SSL for the SMTP proxy connection | on, off |
off |
| smtp_proxy_ssl_verify | Controls whether to verify the server's certificate | on, off |
off |
Example: Basic SMTP Proxy Configuration
server {
listen 25;
proxy_pass smtp://127.0.0.1:1025;
smtp_proxy_read_timeout 30s;
smtp_proxy_send_timeout 30s;
}Example: SMTP Proxy with SSL
server {
listen 465 ssl;
proxy_pass smtp://127.0.0.1:1025;
smtp_proxy_ssl on;
smtp_proxy_ssl_verify on;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
}Example: SMTP Proxy with Authentication
server {
listen 587 ssl;
proxy_pass smtp://127.0.0.1:1025;
smtp_client_cert /path/to/client.crt;
smtp_client_key /path/to/client.key;
smtp_proxy_ssl on;
}3. Configuring IMAP Proxy
| Directive | Values | Description |
|---|---|---|
| imap_client_buffer_size | 4k|8k |
Size of buffer for reading client requests |
| imap_capabilities | IMAP4rev1, LITERAL+, STARTTLS |
IMAP capabilities to announce to clients |
| imap_timeout | 60s |
Timeout for IMAP operations |
Example: Basic IMAP Proxy Configuration
server {
listen 143;
protocol imap;
proxy_pass imaps://backend-imap-server:993;
proxy_timeout 60s;
imap_client_buffer_size 4k;
imap_capabilities IMAP4rev1 LITERAL+ STARTTLS;
}
Note: Ensure that the backend IMAP server supports TLS if using
imaps protocol.
Warning: IMAP proxying requires proper SSL/TLS handling to avoid security issues.
4. Configuring POP3 Proxy
| Directive | Values | Description |
|---|---|---|
| pop3_proxy | on | off |
Enables or disables POP3 proxy functionality. |
| pop3_proxy_pass | host:port |
Specifies the POP3 server to which requests are proxied. |
| pop3_proxy_timeout | time |
Timeout for POP3 proxy connections. Default is 60s. |
| pop3_proxy_auth | on | off |
Enables or disables authentication for POP3 proxy. |
Example: Basic POP3 Proxy Configuration
server {
listen 110;
pop3_proxy on;
pop3_proxy_pass mail.example.com:110;
pop3_proxy_timeout 60s;
}
Note: The POP3 proxy module must be enabled at compile time. It is not part of the default Nginx build.
5. Setting Auth HTTP Backend
| Directive | Values | Description |
|---|---|---|
| auth_http | http://example.com/auth |
Specifies the HTTP server to use for authentication. |
| auth_http_header | Authorization: Bearer $token |
Additional headers to send with the auth request. |
| auth_http_timeout | 10s |
Timeout for the HTTP authentication request. |
Example: Basic Auth HTTP Configuration
server {
listen 25;
protocol mail;
auth_http http://auth.example.com/auth;
auth_http_header Authorization: Bearer $token;
auth_http_timeout 10s;
}
Note: The
auth_http directive requires a valid HTTP endpoint that returns a 200 OK for successful authentication or 403 Forbidden for failed authentication.
6. Configuring SSL for Mail
| Directive | Values | Description |
|---|---|---|
| ssl_protocols | ssl_protocols TLSv1.2 TLSv1.3 |
Enables TLS protocols for mail proxy SSL connections |
| ssl_ciphers | ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384 |
Specifies the SSL ciphers allowed for mail proxy connections |
| ssl_certificate | ssl_certificate /path/to/mail-cert.pem |
Path to the SSL certificate file for mail proxy |
| ssl_certificate_key | ssl_certificate_key /path/to/mail-key.pem |
Path to the private key file for mail proxy SSL |
Example: Basic SSL Configuration for Mail Proxy
server {
listen 993 ssl;
mail {
auth_http 127.0.0.1:8080/auth;
xclient on;
}
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384;
ssl_certificate /etc/ssl/certs/mail-cert.pem;
ssl_certificate_key /etc/ssl/private/mail-key.pem;
}7. Setting Mail Timeouts
| Directive | Values | Description |
|---|---|---|
| proxy_timeout | 60s |
Timeout for proxying mail requests to the backend server |
| proxy_read_timeout | 60s |
Timeout for reading a response from the backend server |
| proxy_send_timeout | 60s |
Timeout for sending a request to the backend server |
| proxy_connect_timeout | 60s |
Timeout for establishing a connection to the backend server |
Example: Configuring Mail Proxy Timeouts
mail {
auth_http http://127.0.0.1:8080/mail/auth;
proxy_on on;
proxy_timeout 30s;
proxy_read_timeout 30s;
proxy_send_timeout 30s;
proxy_connect_timeout 30s;
}8. Using STARTTLS
| Directive | Values | Description |
|---|---|---|
| mail_proxy_starttls | on | off |
Enables or disables the use of STARTTLS for secure connections. Default is off. |
| ssl_protocols | SSLv2 | SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2 | TLSv1.3 |
Enables the specified SSL/TLS protocols for secure connections. |
| ssl_ciphers | String | Specifies the list of ciphers to be used for secure connections. |
Example: Enabling STARTTLS in Nginx Mail Proxy
mail {
auth_http 127.0.0.1:8080/auth;
capability imap4 pop3;
starttls on;
server {
listen 993 ssl;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
}
}
Note: STARTTLS must be enabled in the server block to allow secure connections over IMAP or POP3.
9. Configuring Mail Server Pools
| Directive | Description | Values | Notes |
|---|---|---|---|
| upstream | Defines a group of mail servers | name |
Used in mail context |
| server | Defines a mail server in the pool | address |
Can specify port and options |
| weight | Weight for load balancing | number |
Default is 1 |
| fail_timeout | Time to consider server as failed | time |
Default is 10s |
| max_fails | Number of failed requests before marking server as down | number |
Default is 1 |
Example: Basic Mail Server Pool Configuration
upstream mail_backend {
server 192.168.1.10:143;
server 192.168.1.11:143 weight=2;
server 192.168.1.12:143 max_fails=3 fail_timeout=30s;
}
server {
listen 110;
protocol pop3;
proxy_pass mail_backend;
}
Note: The
upstream directive is used to define a group of mail servers that can be load balanced. The server directive within an upstream block specifies a mail server in the pool.
Warning: Ensure that all mail servers in the pool support the same protocols and configurations to avoid unexpected behavior.
10. Logging Mail Proxy Activity
| Directive | Description | Default | Notes |
|---|---|---|---|
| mail_log_format | Defines the format for logging mail proxy activity. | main |
Can be customized using log_format. |
| mail_log | Enables logging of mail proxy activity to a file. | off |
Can be set to a file path or stderr. |
Example: Configuring Mail Proxy Logging
mail {
auth_http http://127.0.0.1:80/auth;
capabilities "STARTTLS" "AUTH PLAIN";
server_name mail.example.com;
ssl_certificate /etc/ssl/certs/mail.crt;
ssl_certificate_key /etc/ssl/private/mail.key;
# Enable logging to a file
mail_log /var/log/nginx/mail_proxy.log;
mail_log_format main "$remote_addr - $remote_user [$time_local] $request";
}
Note: The
mail_log_format directive allows you to define custom log formats, similar to HTTP logging in Nginx. You can include variables like $remote_addr, $remote_user, and $time_local to capture relevant information about mail proxy activity.
Mail Proxy Logging Configuration Summary
mail_log: Controls where mail proxy logs are written.mail_log_format: Allows customization of log format for mail proxy activity.- Logging can be enabled to a file or
stderr.
11. Implementing Mail Routing
| Directive | Description | Example |
|---|---|---|
| proxy_pass | Specifies the address of the mail proxy server to which the request should be passed. | proxy_pass imap://localhost:143; |
| proxy_protocol | Enables the use of the PROXY protocol for incoming connections. | proxy_protocol on; |
| proxy_timeout | Sets the timeout for proxying a request to the mail server. | proxy_timeout 1m; |
Example: Basic Mail Routing Configuration
server {
listen 25;
protocol smtp;
proxy_pass smtp://localhost:2525;
proxy_timeout 1m;
}Example: IMAP Mail Routing with Protocol Support
server {
listen 143;
protocol imap;
proxy_protocol on;
proxy_pass imap://localhost:143;
}12. Handling Mail Authentication Failures
| Directive | Description | Default | Notes |
|---|---|---|---|
| auth_http | Specifies the HTTP server to which authentication requests are sent. | none | Required for mail proxy authentication |
| auth_http_header | Specifies a custom header to be sent with the authentication request. | none | Can be used to pass additional context to the auth server |
| auth_http_timeout | Defines the timeout for the HTTP authentication request. | 1m | Controls how long Nginx waits for a response from the auth server |
Example: Configuring Authentication with HTTP
mail {
auth_http http://auth.example.com/auth;
auth_http_header X-User-Email $user;
auth_http_timeout 30s;
server {
listen 25;
protocol smtp;
auth_http http://auth.example.com/auth;
}
}
Note: If the authentication server returns a 403 status code, Nginx will reject the client connection.
Warning: Ensure that the authentication server is secure and uses HTTPS to prevent credential exposure.