Configuration

There are a number of configuration options available on the agent that modify the behaviour of the agent.

You can view all the available options and current values on your system by running enclave list-config.

To set a value, use enclave set-config, specifying the name of the configuration option and the new value, like so:

enclave set-config <option> <value>

Environment Variables

In docker containers or when running enclave interactively with enclave run, you can set OS environment variables instead of permanently changing values in the profile. Each configuration option has a corresponding environment variable, for example localport -> ENCLAVE_LOCAL_PORT. All our environment variables start with ENCLAVE_.

General Options

localport

Defines the local binding port used for enclave connectivity. The default value of 0 means enclave will choose a random high port for connectivity each time it re-establishes a route to our platform.

Set this value to a fixed port only if you need to add an exclusion to a local VLAN rule to allow enclave traffic to flow efficiently in your local network.

Allowed Value: A value between 0 and 65535 (inclusive)

Default Value: 0

Environment Variable: ENCLAVE_LOCAL_PORT

loglevel

Defines the log level for enclave. Use [enclave loglevel](/agent/commands/loglevel) to set a temporary log level for an already-running profile.

Allowed Values:

minimal

Always shown; critical problems, startup and shutdown messages.

informational

Operational state changes, some warnings.

networkevents

Enclave connectivity events, including tunnel attempts.

protocolevents

Detailed protocol events, including keep-alives and tunnel negotiation.

debug

Debug tracing, including DNS queries and low-level socket events.

framedata

All network frames to/from this system are traced to the log. Significant performance impact.

Default Value: informational

Environment Variable: ENCLAVE_LOG_LEVEL

stub-resolver

Determines whether enclave runs a stub resolver, bound to the enclave virtual adapter on port 53. Set to 'disabled' if you want an alternate nameserver on this system.

Enclave-defined DNS names will not be resolvable if the stub resolver is disabled.

Allowed Value: 'enabled' or 'disabled'

Default Value: enabled

Environment Variable: ENCLAVE_STUB_RESOLVER

virtual-ip

Sets a static virtual IP address for this enclave system.

Be aware that multiple systems having the same virtual address will lead to network conflicts.

Allowed Value: A valid IPv4 address

Default Value: none

Environment Variable: ENCLAVE_VIRTUAL_IP

virtual-network

Changes the network subnet this enclave system communicates with.

All systems that wish to communicate must share the same virtual network.

Allowed Value: A valid IP Network in CIDR format (for example, 100.64.0.0/10)

Default Value: 100.64.0.0/10

Environment Variable: ENCLAVE_VIRTUAL_NETWORK

Gateway Options

gateway-dns-source-forwarding

Only available on Linux.

When running as a gateway, indicate whether forwarded DNS queries should include the originating enclave virtual IP address as a ClientSubnet OPT record.

This can be useful when using a custom upstream DNS server, to show the originating enclave IP address in DNS logs (provided the upstream server supports the ClientSubnet OPT record).

Allowed Value: 'enabled' or 'disabled'

Default Value: disabled

Environment Variable: ENCLAVE_GATEWAY_DNS_SOURCE_FORWARDING

gateway-dns-upstream-servers

Only available on Linux.

When running as a gateway, explicitly state the list of upstream DNS servers to use, rather than using the os-defined nameservers.

Allowed Value: A list of IP Addresses, separated by spaces, commas, tabs or semi-colons. Provide os-defined for the default empty set.

Default Value: os-defined

Environment Variable: ENCLAVE_GATEWAY_DNS_UPSTREAM_SERVERS

gateway-dns-upstream-timeout-ms

Only available on Linux.

When running as a gateway, define the number of milliseconds a query to an upstream nameserver should take before failing over to the next nameserver.

If all nameservers are exhausted, the response will be SERVFAIL.

Allowed Value: A value between 10 and 10000 (inclusive)

Default Value: 250

Environment Variable: ENCLAVE_GATEWAY_DNS_UPSTREAM_TIMEOUT_MS

gateway-dns-reply-for-all

Only available on Linux.

When running as a gateway, indicate whether the gateway will respond for all DNS queries, not just those with result IPs routable via the gateway (the default). This allows you to provide DNS filtering with this gateway, without tunnelling all of the traffic to resolved addresses through the gateway as well.

Allowed Value: 'enabled' or 'disabled'

Default Value: disabled

Environment Variable: ENCLAVE_GATEWAY_DNS_REPLY_FOR_ALL

Advanced Options

layer2

Only available on x64 Windows.

Indicates whether Enclave should use a layer-2-compatible virtual adapter, rather than the default layer-3 adapter. This makes it possible to run multiple profiles at once.

Allowed Value: 'enabled' or 'disabled'

Default Value: disabled

Environment Variable: ENCLAVE_LAYER2

mtu

Configures the MTU (Maximum Transmission Unit) setting on the enclave virtual adapter. This value controls the size of individual packets that move over the network; the default value is low to ensure compatibility with some internet routers.

Increasing this value may increase throughput in some scenarios, but note that all peers this system communicates with must have the same MTU value, otherwise packet loss will occur.

Allowed Value: A value between 1280 and 9000 (inclusive)

Default Value: 1280

Environment Variable: ENCLAVE_MTU

source-match-policy

Defines the source address matching policy for this agent. By default, enclave will require that the source address of a connecting peer exactly matches the expected source address as determined by the platform.

In certain NAT configurations, clients can get different source ports/addresses for different target addresses, meaning that the source port (or even source IP) of a connection can deviate from the expected value.

In that scenario, setting this option to 'ip' or 'any' may increase the chances of direct connectivity.

Allowed Values:

any

No source address validation is applied; a tunnel negotiation can be initiated from any source address and port.

ip

Source IP address must match the candidate expected by the platform, but the port number may differ.

exact

Source IP address and port number must exactly match the candidate expected by the platform.

Default Value: exact

Environment Variable: ENCLAVE_SOURCE_MATCH_POLICY