Configure Transparent Proxy on Universal

The default configuration works well for most scenarios, but there are cases where adjustments are needed.

Kuma uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the configuration reference.

In Universal mode, Kuma there are two methods to adjust the configuration. Each can be used on its own or combined with others if needed.

It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the Order of Precedence section to see what the final configuration will look like based on the priority of each setting.

yaml / json

You can provide the configuration in either yaml or json format by using the --config or --config-file flags.

For the configuration schema in yaml format, refer to the Schema section in the configuration reference.

Below are examples of using these flags in different ways:

Providing configuration via the --config-file flag

Assume you have a config.yaml file with the following content:
```
kumaDPUser: dataplane
verbose: true
```
You can install the transparent proxy using:
```
kumactl install transparent-proxy --config-file config.yaml
```

Passing configuration directly via the --config flag

To pass the configuration content directly:

kumactl install transparent-proxy --config "kumaDPUser: dataplane\nverbose: true"

Alternatively:

kumactl install transparent-proxy --config "{ kumaDPUser: dataplane, verbose: true }"

Both formats are valid yaml inputs.

Passing configuration via stdin

If you need to pass the configuration via stdin, set --config-file to - as shown below:
```
echo "
kumaDPUser: dataplane
verbose: true
" | kumactl install transparent-proxy --config-file -
```

Environment Variables

You can customize configuration settings by using environment variables. For example:

KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy

To see all available environment variables, visit the Environment Variables section in the configuration reference.

Order of Precedence

Default Values
Values from --config / --config-file flags
Environment Variables

To understand how the order of precedence works, consider this scenario:

You have a config.yaml file with the following content:
```
redirect:
  dns:
    port: 10001
```

You install the transparent proxy using this command:

KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT="10002" \
  kumactl install transparent-proxy --config-file config.yaml

In this situation, the possible values for redirect.dns.port are:
- 15053 (Default Value)
- 10001 (from config file)
- 10002 (from environment variable)
Since environmental variable have the highest precedence, the final value for redirect.dns.port will be 10002.