# Proxy Harness reference

BEL provides a mesh expansion proxy harness component that works along the BEL
autoregistration controller to automate configuration and lifecycle management
for external workloads. The harness is a component that is installed on a host
machine. Upon installation, a configuration file is automatically created on the
file system. This configuration file contains sensible defaults. Furthermore, it
allows for configuring certain aspects of the harness behavior.

## Default configuration

Upon installing the harness package, the configuration file is placed in
`/var/lib/linkerd/linkerd-proxy-harness.cfg` and contains the following config:

```json
{
  "ProxyUserID": 997,
  "InboundPortsToIgnore": [
    "4567",
    "4568"
  ],
  "OutboundPortsToIgnore": [
    "4567",
    "4568"
  ],
  "IPv6": false,
  "IPTablesMode": "legacy",
  "InboundListenAddress": "0.0.0.0:4143",
  "OutboundListenAddresses": [
    "127.0.0.1:4140"
  ]
  "AdminAddress": "127.0.0.1:4192",
  "Identity": {
    "SpireSocketAddress": "/tmp/spire-agent/public/api.sock",
    "Backoff": {
      "Min": "100ms",
      "Max": "1s",
      "Jitter": 0.1
    }
  },
  "Dns": {
    "MinTTL": "10s",
    "MaxTTL": "10m",
    "ResolvConfPath": "/etc/resolv.conf"
  },
  "LogLevel": "info",
  "LogFormat": "plain"
}
```

## Harness Configuration reference

### Network related configuration

| Field                     | Description                                                                                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ProxyUserID`             | User id under which the proxy runs (automatically derived based on the ID of the `proxyharness` user, which is created as part of the package installation).                                                        |
| `PortsToRedirect`         | Ports to redirect to proxy, if no port is specified then ALL ports are redirected.                                                                                                                                  |
| `SubnetsToIgnore`         | Subnets to ignore and not redirect to proxy. This has higher precedence than any other parameters.                                                                                                                  |
| `InboundPortsToIgnore`    | Inbound ports and/or port ranges (inclusive) to ignore and not redirect to proxy. This has higher precedence than any other parameters.                                                                             |
| `OutboundPortsToIgnore`   | Outbound ports and/or port ranges (inclusive) to ignore and not redirect to proxy. This has higher precedence than any other parameters.                                                                            |
| `IPv6`                    | Set to true to enable IPv6 networking                                                                                                                                                                               |
| `IPTablesMode`            | Variant of iptables command to use (`legacy` or `nft`).                                                                                                                                                             |
| `InboundListenAddress`    | Address on which the proxy listens for incoming traffic. Should be consistent with the IPv6 setting.                                                                                                                |
| `OutboundListenAddresses` | Address(es) on which the proxy listens for outbound traffic. When IPv6 is false, it must be a single IPv4 address. When IPv6 is true it can be either a single IPv6 address or an IPv4 address and an IPv6 address. |
| `AdminAddress`            | Address on which the admin server of the harness is served.                                                                                                                                                         |

### .Identity - TLS Identity related config

| Field                | Description                                                                          |
| -------------------- | ------------------------------------------------------------------------------------ |
| `SpireSocketAddress` | Address of the SPIRE agent Workload API (default: /tmp/spire-agent/public/api.sock). |
| `Backoff`            | Backoff configuration for the SPIRE GRPC client.                                     |

### .Control - Control plane connection related config

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| `Address`    | Address of the autoregistration controller.      |
| `ServerId`   | TLS Identity of the autoregistration controller. |
| `ServerName` | SNI of the autoregistration controller.          |

### .Dns - DNS resolver config (used by the control plane client)

| Field            | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `MinTTL`         | Minumum TTL for DNS results (defaults to `10s`).              |
| `MaxTTL`         | Max TTL for DNS results (defaults to `10m`).                  |
| `ResolvConfPath` | Path to the resolv.conf file (defaults to `/etc/resolv.conf`) |

### Logging config

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `LogLevel`  | The level of logging (defaults to `info`).   |
| `LogFormat` | The format of logging (defaults to `plain`). |

### Workload group association config

| Field            | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| `GroupName`      | The name of the `WorkloadGroup` resource that will own this workload.      |
| `GroupNamespace` | The namespace of the `WorkloadGroup` resource that will own this workload. |

### .InboundNetwork - configuration related to resolving the inbound address of the workload

This piece of configuration controls the way the harness determines its own
address. This address will be used when traffic is sent from the cluster to the
harness and therefore should be reachable from within the cluster. If no
configuration is provided, the harness lookups up the default interface on the
host and picks the first address for the interface. If more specific
configuration is needed, only one of the following options need to be specified.
Note that in host machines with dual-stack networking, the default address will
likely be IPv4, so if you like to only use IPv6 (and the IPv6 entry above is
true), make sure to specify the interface/address here.

| Field           | Description                                                                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InterfaceName` | The name of the network interface that will be used for inbound traffic (the harness will pick the default address on the interface).                                                          |
| `Addresses`     | Address(es) used to reach the workload. When IPv6 is false, it must be a single IPv4 address. When IPv6 is true it can be either a single IPv6 address or an IPv4 address and an IPv6 address. |

### Proxy configuration overrides

By default the configuration that the proxy is run with is provided by the
autoregistration controller (with the exception of Inbound and Outbound proxy
addresses). If the is further need to modify the config per workload basis, the
following parameter can be used to explicitly override any proxy environment
variable.

| Field                  | Description                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ProxyConfigOverrides` | An object containing key,value pairs where the key is the env variable that is used for proxy configuration. |

## Harness Control CLI reference

As part of the harness installation a minimal CLI is provided. Its purpose is to
allow for ergonomic manipulation of certain aspects of the config. Currently it
mainly serves to configure the way the external workload connects to the Linkerd
control plane.

### Usage

```bash
harnessctl set-config
```

### Flags

| Flag                         | Usage                                                                                    |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `--workload-group-name`      | Name of the WorkloadGroup resource.                                                      |
| `--workload-group-namespace` | Namespace of the WorkloadGroup resource.                                                 |
| `--control-plane-address`    | Address of the autoregistration controller.                                              |
| `--control-plane-identity`   | TLS Identity of the autoregistration controller.                                         |
| `--control-plane-sni`        | SNI of the autoregistration controller (defaults to `--control-plane-identity`).         |
| `--config-file`              | Harness config file location (defaults to `/var/lib/linkerd/linkerd-proxy-harness.cfg`). |
