How to configure

This guide explains how to configure the aproxy charm to control how traffic is intercepted and forwarded through a target proxy.

Overview

The aproxy charm provides several configuration options that control how outbound traffic is handled, which addresses bypass the proxy, and which ports are intercepted.

These configurations can be applied:

• During deployment (using juju deploy --config), or
• After deployment (using juju config).

Example:

juju deploy aproxy --config proxy-address="1.2.3.4:8080"

Configuration options

There are three configuration options available: proxy-address, exclude-addresses-from-proxy, and intercept-ports.

proxy-address

Specifies the target proxy IP address and port for traffic forwarding.

• Format: "IP:PORT" or "IP"

• Example:

  • 1.2.3.4:8888
  • 1.2.3.4 (defaults to port 80)

If no value is provided:

• The charm will attempt to use the juju-https-proxy or juju-http-proxy Juju model configuration data.
• If the proxy relation is unavailable, the charm will remain in a BlockedStatus until a valid configuration is provided.

Usage Example:

juju config aproxy proxy-address="10.0.0.5:8080"

exclude-addresses-from-proxy

Comma-separated list of IP addresses or hostnames that should bypass the proxy. When this option is set, nftables rules are updated so that outbound traffic to the specified addresses is exempted from proxy interception.

• Default: "127.0.0.1"
• Useful for excluding local or internal addresses that should bypass the proxy.

Usage example:

juju config aproxy exclude-addresses-from-proxy="127.0.0.1,example.local"

intercept-ports

Defines which ports are intercepted and forwarded through the proxy.

This field supports flexible input patterns:

• Default: "80,443"

Usage example:

juju config aproxy intercept-ports="80,443,8080-8090"

Example: full configuration

Below is a sample configuration command that sets all options explicitly:

juju config aproxy \
  proxy-address="10.10.10.5:8080" \
  exclude-addresses-from-proxy="127.0.0.1,10.10.10.0/24" \
  intercept-ports="80,443,8080-8090"

After applying the configuration, the charm will:

1. Validate the provided settings.
2. Configure the Aproxy snap.
3. Apply nftables rules to redirect outbound traffic as specified.
4. Report an ActiveStatus once setup completes successfully.

Troubleshoot

If the configuration is invalid or incomplete, the charm may enter a BlockedStatus with an error message such as:

BlockedStatus: Invalid charm configuration: missing proxy address

Common fixes:

• Verify that the proxy-address and exclude-addresses-from-proxy consist of valid IP or hostname.
• Ensure that the intercept-ports field uses valid syntax (no spaces, only commas and dashes).
• Check that your model configuration data is correctly set if you’re relying on juju-http-proxy or juju-https-proxy.