Skip to main content
Version: 1.0.x

HTTP Proxy Route Configuration

Overview​

Lunar.dev's API Consumption Gateway now supports configuring an HTTP proxy route with a defined list of allowed_domains. This feature enables secure forwarding of HTTPS requests while ensuring that only traffic to specified domains is permitted.

By leveraging this configuration, you can enforce domain-level restrictions for outbound traffic without inspecting the content of the requests, maintaining end-to-end encryption.

note

Currently, features like discover or any other flow-based configurations are not supported in this setup. This limitation arises because the transparent proxy operates at Layer 4, bypassing the Layer 7 processing required for such features.

Use Case​

This feature is particularly useful for scenarios where outbound traffic is restricted by default, and specific external requests need to be proxied securely through Lunar. The proxy operates transparently, forwarding HTTPS traffic based on the configured allowed domains list.

How It Works​

When configured, Lunar's gateway:

  1. Forwards HTTPS requests using the HTTP CONNECT method.
  2. Validates the target domain against the configured allowed domains list.
  3. Allows or blocks the request based on the validation outcome.

Key Features​

  • Layer 4 (TCP) Forwarding: Traffic is forwarded without inspection of the application layer, preserving encryption.
  • Allowed Domains Enforcement: Requests are validated against a pre-defined list of permitted domains.
  • Transparency: Operates as a blind intermediary for encrypted traffic, ensuring minimal latency and no content modification.

Configuration Steps​

To enable HTTP proxying with allowed_domains, follow these steps:

1. Enable HTTP Proxying in Lunar Gateway​

Set the following environment variables in your Lunar Gateway configuration:

TLS_PASSTHROUGH_ON=true  # Enable transparent proxying.
TLS_PASSTHROUGH_PORT=8880  # Define the port for TLS passthrough.

These settings enable the transparent proxying functionality.

2. Define Allowed Domains​

Configure the allowed domains in your gateway configuration file. Note that the domains should be specified as regular expressions (regex), not plain text. For example:

/etc/lunar-proxy/gateway_config.yaml
allowed_domains:
  - "^catfact\\.ninja$"
  - "^api\\.example\\.com$"

Refer to the System Level Domain Restriction documentation for additional details on crafting regex patterns and ensuring they match the intended domains.

3. Proxy Requests via Lunar​

To route traffic through the Lunar proxy, set the HTTP_PROXY environment variable on the client system:

HTTP_PROXY=http://<lunar-proxy-domain>:8880

Alternatively, you can specify the proxy directly in your request, as shown:

curl -p -x http://<lunar-proxy-domain>:8880 https://catfact.ninja/fact

4. Testing the Configuration​

Verify the setup by making a request to an allowed domain. For example:

curl -p -x http://<lunar-proxy-domain>:8880 https://catfact.ninja/fact

Expected Response:

{"fact":"A cat can sprint at about thirty-one miles per hour.","length":52}

If a request is made to a domain not on the allowed list, it will be blocked.

Troubleshooting​

  • Blocked Requests: Ensure the target domain matches the regex in the allowed domains list.
  • Connectivity Issues: Verify that the TLS_PASSTHROUGH_ON variable is set correctly and the port is accessible.
  • Restart Behavior: In case of proxy service restarts, logs will indicate:
TLS Passthrough process exited with code $1. Restarting...