Nginx Configuration Patches

How cdk8s-mailu patches nginx configuration for Traefik TLS termination.

Introduction

When using TLS_FLAVOR=notls with Traefik TLS termination, the Front nginx container requires configuration patches to:

  1. Add mail protocol listeners for ports 587, 465, 993, 995

  2. Configure auth_http to use Admin service instead of localhost

This document explains the patching mechanism and what changes are applied.

Note: In cdk8s-mailu, Traefik routes HTTP traffic directly to Admin and Webmail services, bypassing Front nginx entirely. Therefore, HTTP location blocks and redirects are not needed and not applied.

Patch Architecture

Why Patching is Needed

Mailu’s Default Behavior:

  • TLS_FLAVOR=notls only configures HTTP on port 80

  • Mail protocol ports (587, 465, 993, 995) are NOT created

  • Assumes TLS handled internally or not needed

  • auth_http points to localhost:8000 (doesn’t work in Kubernetes multi-pod architecture)

cdk8s-mailu Requirements:

  • Traefik terminates TLS and forwards plaintext to nginx (for mail protocols only)

  • nginx must listen on mail protocol ports to receive from Traefik

  • nginx must authenticate via Admin service (separate pod)

  • nginx must proxy to backend services after authentication (Postfix, Dovecot)

Solution: Wrapper script patches generated nginx.conf before nginx starts.

HTTP Traffic: Traefik routes HTTP directly to Admin and Webmail services, bypassing nginx completely.

Patch Delivery Mechanism

ConfigMap → Init Container → Shared Volume:

  1. NginxPatchConfigMap construct creates ConfigMap with wrapper script

  2. Front Deployment mounts ConfigMap at /patch/entrypoint-wrapper.sh

  3. Init Container copies script to shared volume and makes executable:

    initContainers:
- name: copy-entrypoint
  image: busybox
  command: ['sh', '-c', 'cp /patch/entrypoint-wrapper.sh /entrypoint/entrypoint-wrapper.sh && chmod +x /entrypoint/entrypoint-wrapper.sh']
  volumeMounts:
  - name: entrypoint-volume
    mountPath: /entrypoint
  - name: nginx-patch
    mountPath: /patch

  4. Main Container runs wrapper script instead of original entrypoint:

    command: ['/entrypoint/entrypoint-wrapper.sh']

Why Init Container?

  • ConfigMap files are read-only (cannot chmod +x directly)

  • Shared emptyDir volume allows executable script

  • Clean separation: init copies once, main container runs

Patch Script Workflow

The wrapper script executes in three phases:

Phase 1: Generate Base Configuration

# Run Mailu's config.py to generate nginx.conf from templates
python3 /config.py

What config.py does:

  • Reads environment variables (TLS_FLAVOR, HOSTNAMES, etc.)

  • Generates /etc/nginx/nginx.conf from Jinja2 templates

  • Creates base mail protocol listeners (port 25 only with TLS_FLAVOR=notls)

  • Creates base HTTP server block for port 80

Output: /etc/nginx/nginx.conf with basic configuration

Phase 2: Apply Patches

Two patches are applied to the generated nginx.conf:

Patch 1: Fix auth_http Endpoint

Problem: Default config points to http://127.0.0.1:8000/auth/email

  • Doesn’t work in Kubernetes (Admin is separate pod)

  • Wrong endpoint path

Patch:

sed -i "s|auth_http http://127.0.0.1:8000/auth/email;|auth_http http://\${ADMIN_ADDRESS}:8080/internal/auth/email;|g" "$NGINX_CONF"

Changes:

  • 127.0.0.1:8000 → ${ADMIN_ADDRESS}:8080 (Kubernetes service DNS)

  • /auth/email → /internal/auth/email (correct Mailu endpoint)

Result:

auth_http http://admin-service.mailu.svc.cluster.local:8080/internal/auth/email;

Patch 2: Inject Mail Protocol Listeners

Problem: TLS_FLAVOR=notls doesn’t create listeners for 587, 465, 993, 995

Patch: Inserts four server blocks into mail{} section after port 25 block:

# Submission (port 587) for Traefik TLS termination
server {
  listen 587;
  protocol smtp;
  smtp_auth plain;
  auth_http_header Auth-Port 587;
  auth_http_header Client-Port $remote_port;
}

# SMTPS (port 465) for Traefik TLS termination
server {
  listen 465;
  protocol smtp;
  smtp_auth plain;
  auth_http_header Auth-Port 465;
  auth_http_header Client-Port $remote_port;
}

# IMAPS (port 993) for Traefik TLS termination
server {
  listen 993;
  protocol imap;
  imap_auth plain;
  auth_http_header Auth-Port 993;
  auth_http_header Client-Port $remote_port;
}

# POP3S (port 995) for Traefik TLS termination
server {
  listen 995;
  protocol pop3;
  pop3_auth plain;
  auth_http_header Auth-Port 995;
  auth_http_header Client-Port $remote_port;
}

Key Configuration:

  • protocol smtp/imap/pop3: nginx mail module protocol handlers

  • smtp_auth plain / imap_auth plain / pop3_auth plain: Enable PLAIN authentication

  • auth_http_header Auth-Port: Tells Admin which port client connected to

  • auth_http_header Client-Port: Passes client’s source port for logging

Authentication Flow:

  1. Client sends credentials (username/password)

  2. nginx extracts credentials and sends to auth_http endpoint

  3. Admin validates and returns backend address

  4. nginx proxies connection to backend (Postfix or Dovecot)

Phase 3: Verify and Start

# Verify patches were applied
if ! grep -q "# Submission (port 587) for Traefik TLS termination" "$NGINX_CONF"; then
  echo "ERROR: Mail protocol patches not found in $NGINX_CONF"
  exit 1
fi

echo "Patch verification: OK - All patches applied successfully"

# Start nginx in foreground
exec /usr/sbin/nginx -g "daemon off;"

Verification checks:

  • Mail protocol listeners added (ports 587, 465, 993, 995)

  • Fails with error if patches not found

Failure handling: Exit immediately if patches not applied (fail-fast approach)

Configuration File Structure

Before Patching (config.py output)

# nginx.conf generated by Mailu config.py with TLS_FLAVOR=notls

mail {
    server {
        listen 25;
        protocol smtp;
        auth_http http://127.0.0.1:8000/auth/email;  # Wrong: localhost
    }
    # No 587, 465, 993, 995 listeners
}

http {
    server {
        listen 80;
        # HTTP server (not used - Traefik routes directly to services)
    }
}

After Patching (wrapper script output)

# nginx.conf after cdk8s-mailu patches applied

mail {
    server {
        listen 25;
        protocol smtp;
        auth_http http://admin-service.mailu.svc.cluster.local:8080/internal/auth/email;  # Fixed
    }

    # NEW: Submission listener
    server {
        listen 587;
        protocol smtp;
        smtp_auth plain;
        auth_http_header Auth-Port 587;
    }

    # NEW: SMTPS listener
    server {
        listen 465;
        protocol smtp;
        smtp_auth plain;
        auth_http_header Auth-Port 465;
    }

    # NEW: IMAPS listener
    server {
        listen 993;
        protocol imap;
        imap_auth plain;
        auth_http_header Auth-Port 993;
    }

    # NEW: POP3S listener
    server {
        listen 995;
        protocol pop3;
        pop3_auth plain;
        auth_http_header Auth-Port 995;
    }
}

http {
    server {
        listen 80;
        # HTTP server (not used - Traefik routes directly to services)
    }
}

Integration with Kubernetes

Service Port Exposure

Front Service exposes only TLS-terminated mail protocol ports (no HTTP or plaintext mail ports):

apiVersion: v1
kind: Service
metadata:
  name: front-service
spec:
  ports:
  # TLS-terminated SMTP ports (Traefik terminates TLS, forwards plaintext to Front)
  - name: smtps
    port: 465
    targetPort: 465
  - name: submission
    port: 587
    targetPort: 587
  # TLS-terminated IMAP port
  - name: imaps
    port: 993
    targetPort: 993
  # TLS-terminated POP3 port
  - name: pop3s
    port: 995
    targetPort: 995

Not exposed (routed differently by Traefik):

  • Port 25 (SMTP): Traefik routes directly to Postfix:25

  • Port 80/443 (HTTP/HTTPS): Traefik routes directly to Admin:8080 and Webmail:80

  • Port 143/110 (IMAP/POP3): Plaintext protocols disabled (use IMAPS/POP3S instead)

Traefik Configuration

Required Traefik EntryPoints (configured in cluster infrastructure):

  • smtps (465) - SMTPS with TLS termination

  • smtp-submission (587) - Submission with TLS termination (or passthrough)

  • imaps (993) - IMAPS with TLS termination

  • pop3s (995) - POP3S with TLS termination

Example IngressRouteTCP (created by TraefikIngressConstruct):

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRouteTCP
metadata:
  name: mailu-submission
spec:
  entryPoints:
    - smtp-submission  # 587
  routes:
  - match: HostSNI(`*`)
    services:
    - name: front-service
      port: 587
  # Note: Submission (587) typically uses STARTTLS, not TLS wrapping
  # So TLS section may be omitted (passthrough)

Example with TLS termination (SMTPS/IMAPS/POP3S):

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRouteTCP
metadata:
  name: mailu-smtps
spec:
  entryPoints:
    - smtps  # 465
  routes:
  - match: HostSNI(`*`)
    services:
    - name: front-service
      port: 465
  tls:
    secretName: mailu-tls
    options:
      name: mailu-mail-tls

Traffic Flow (TLS-terminated mail protocols):

  1. Mail client connects to Traefik:465/587/993/995 with TLS

  2. Traefik terminates TLS (for 465/993/995; passthrough for 587)

  3. Traefik forwards plaintext to Front:465/587/993/995

  4. Front nginx receives on patched listener

  5. Front nginx authenticates via Admin service

  6. Front nginx proxies to backend (Postfix or Dovecot)

Environment Variables Used

Wrapper script relies on these environment variables:

  • ADMIN_ADDRESS: Admin service DNS name (set by MailuChart)

  • TLS_FLAVOR: Must be “notls” for patches to make sense

  • HOSTNAMES: Comma-separated list of domains (used by config.py)

Troubleshooting

Patch Not Applied

Symptoms: nginx fails to start, or mail clients get “connection refused”

Check:

  1. Verify ConfigMap exists:

    kubectl get configmap -n mailu mailu-nginx-patch-configmap

  2. Check wrapper script is executable:

    kubectl exec -n mailu deployment/front-deployment -- ls -l /entrypoint/entrypoint-wrapper.sh

  3. Check init container logs:

    kubectl logs -n mailu deployment/front-deployment -c copy-entrypoint

  4. Check main container logs for patch verification:

    kubectl logs -n mailu deployment/front-deployment | grep "Patch verification"

Authentication Fails on Mail Protocols

Symptoms: Mail clients get “Authentication failed” on ports 587/993/995

Check:

  1. Verify auth_http endpoint is correct:

    kubectl exec -n mailu deployment/front-deployment -- cat /etc/nginx/nginx.conf | grep auth_http

    Should show: auth_http http://admin-service....:8080/internal/auth/email;

  2. Test Admin endpoint from Front pod:

    kubectl exec -n mailu deployment/front-deployment -- wget -O- http://admin-service:8080/internal/auth/email

nginx Configuration Syntax Error

Symptoms: nginx fails to start with “configuration file test failed”

Check:

  1. View full nginx configuration:

    kubectl exec -n mailu deployment/front-deployment -- cat /etc/nginx/nginx.conf

  2. Test nginx configuration manually:

    kubectl exec -n mailu deployment/front-deployment -- nginx -t

Common issues:

  • sed pattern didn’t match (Mailu version changed template structure)

  • Escaping issues in patch script

  • Duplicate server blocks

HTTP Traffic Not Going Through Front

This is expected behavior in cdk8s-mailu:

  • Traefik routes HTTP directly to Admin:8080 and Webmail:80

  • Front nginx only handles mail protocols (SMTP, IMAP, POP3)

  • This is by design for simplified architecture

  • No HTTP location blocks or redirects are configured in Front nginx

Code Reference

Source: src/constructs/nginx-patch-configmap.ts

Key Components:

  • NginxPatchConfigMap class: Creates ConfigMap with wrapper script

  • wrapperScript variable: Complete bash script with all patches

  • sed patterns: Text transformations applied to nginx.conf

Usage in MailuChart:

// Create nginx patch ConfigMap
this.nginxPatchConfigMap = new NginxPatchConfigMap(this, 'nginx-patch', {
  namespace: this.namespace,
});

// Mount in Front deployment
this.frontConstruct = new FrontConstruct(this, 'front', {
  config: this.config,
  namespace: this.namespace,
  sharedConfigMap: this.sharedConfigMap,
  nginxPatchConfigMap: this.nginxPatchConfigMap.configMap,
});

See Also