DebTik/docs/ReverseProxy.md

DebTik Reverse Proxy & Application Gateway

DebTik features an enterprise-grade, high-performance Reverse Proxy & Application Gateway engine integrated natively into the appliance controller.

It enables transparent reverse proxying of incoming HTTP and HTTPS traffic matching specific domain names, hostnames, IP addresses, or path prefixes, terminating SSL/TLS certificates issued or managed by the DebTik Certificate Manager, and forwarding requests to internal or external backend services while preserving complete subfolder hierarchies and query strings.

---

Key Capabilities

1. Protocol Flexibility:

   • Terminate and route HTTP, HTTPS, or dual HTTP/HTTPS.
   • Built-in HTTP-to-HTTPS redirect engine (301 Moved Permanently).
   • WebSocket and HTTP Upgrade transparent tunneling.

2. Domain, Hostname & IP Matching:

   • Match exact domains (e.g., app.example.com, nextcloud.home).
   • Match wildcard subdomains (e.g., *.example.com).
   • Match router or virtual IP addresses (e.g., 192.168.1.1, 10.99.1.1).
   • Global catch-all matching (*).

3. Path-Based Routing & Subfolder Preservation:

   • Match by path prefix (e.g., /app1, /api/v1, or root /).
   • Automatically and seamlessly preserves deep nested subfolder paths:
     • Request to http://example.com/app1/module1/attribute1?filter=active
     • Forwarded to backend with complete subpath /module1/attribute1 and query parameters.
   • Supports both root and subpath backend targets:
     • Target: http://example.com/app1 (target has subpath)
     • Target: http://10.0.0.5:8080 (root target)

4. Strip Path Prefix:

   • Optional toggle (strip_path: true).
   • When enabled, strips the incoming frontend path prefix before sending the request to the backend.
   • Example: Frontend path /service1, Request /service1/users -> Backend receives /users.

5. Integrated SSL/TLS & Dynamic SNI:

   • Fully integrated with the DebTik Certificate Manager (/certificate).
   • Select any certificate (Let's Encrypt, internal CA-signed, or imported PEM) per rule.
   • Dynamic SNI (Server Name Indication) automatically serves the designated certificate for each domain on port 443.
   • Configurable fallback default certificate for unmatched HTTPS handshakes.

6. Backend Insecure TLS & Host Preservation:

   • insecure_tls: Allows proxying to HTTPS backends using self-signed or internal certificates.
   • preserve_host: Forwards original client Host header instead of target backend hostname when needed.

---

Configuration Architecture

Configuration is stored in /etc/debtik/reverse_proxy.json.

{
  "enabled": true,
  "http_port": 80,
  "https_port": 443,
  "default_cert": "ns0-eparmak-eu",
  "rules": [
    {
      "id": "proxy-1793627577980971773",
      "name": "App1 Gateway",
      "enabled": true,
      "domains": ["example.com", "app.example.com"],
      "path": "/app1",
      "target_url": "http://example.com/app1",
      "strip_path": false,
      "preserve_host": false,
      "protocol": "both",
      "certificate": "ns0-eparmak-eu",
      "http_to_https": true,
      "insecure_tls": false,
      "comment": "Production App1 backend forwarding"
    }
  ]
}

---

RouterOS CLI Syntax

DebTik provides full RouterOS CLI commands for the reverse proxy:

1. View Rules & Engine Status

/ip reverse-proxy print
/ip reverse-proxy status

2. Add a Proxy Rule

/ip reverse-proxy add name=Nextcloud domains=cloud.example.com path=/ target=http://10.0.0.25:8080 protocol=https certificate=cloud-cert http-to-https=yes
/ip reverse-proxy add name=Microservice1 domains=example.com path=/app1 target=http://10.0.0.50:3000/app1 protocol=both

3. Toggle Rule State

/ip reverse-proxy enable <id>
/ip reverse-proxy disable <id>

4. Remove a Rule

/ip reverse-proxy remove <id>

---

REST API Reference

Method	Endpoint	Description
GET	/api/proxy/config	Get global engine settings
POST	/api/proxy/config	Update global engine settings
GET	/api/proxy/rules	List all proxy rules
POST	/api/proxy/rules	Create a new proxy rule
GET	/api/proxy/rules/{id}	Get specific rule details
PUT	/api/proxy/rules/{id}	Update existing rule
DELETE	/api/proxy/rules/{id}	Delete proxy rule
POST	/api/proxy/rules/{id}/state	Toggle rule enabled/disabled state
GET	/api/proxy/status	Runtime status, ports, and telemetry