# DNS

This reference covers all of Pomerium's **DNS Settings**:

- [Failure Refresh Rate](#failure-refresh-rate)
- [Lookup Family](#lookup-family)
- [Query Timeout](#query-timeout)
- [Query Tries](#query-tries)
- [Refresh Rate](#refresh-rate)
- [Resolvers](#resolvers)
- [UDP Max Queries](#udp-max-queries)
- [Use TCP](#use-tcp)

## Failure Refresh Rate

**Failure Refresh Rate** sets the DNS refresh rate when requests are failing.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `dns_failure_refresh_rate` | `DNS_FAILURE_REFRESH_RATE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | none (Envoy default) |

#### Examples

```yaml
dns_failure_refresh_rate: 10s
```

**Enterprise:**

Set **Failure Refresh Rate** in the Console:

\[Set Failure Refresh Rate in the Console]

**Kubernetes:**

```yaml
dns:
  failureRefreshRate: 10s
```

## Lookup Family

**Lookup Family** sets the DNS IP address resolution policy.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default**    |
| :------------------- | :------------------------ | :------- | :------------- |
| `dns_lookup_family`  | `DNS_LOOKUP_FAMILY`       | `string` | `V4_PREFERRED` |

#### Examples

```yaml
dns_lookup_family: AUTO
```

```bash
DNS_LOOKUP_FAMILY=V6_ONLY
```

**Enterprise:**

Set **Lookup Family** in the Console:

\[Set Lookup Family in the Console]

The **Default** option leaves the setting unset, in which case the Core option setting will apply.

**Kubernetes:**

```yaml
dns:
  lookupFamily: V6_ONLY
```

### Options

If `dns_lookup_family` is unset, Pomerium applies `V4_PREFERRED`.

| **Options** | **Description** |
| :-- | :-- |
| `AUTO` | DNS resolver will perform a lookup using the system's default behavior, which typically attempts resolution for both IPv4 and IPv6 addresses |
| `V4_ONLY` | DNS resolver will only perform a lookup for addresses in the IPv4 family |
| `V6_ONLY` | DNS resolver will only perform a lookup for addresses in the IPv6 family |
| `V4_PREFERRED` | DNS resolver will first perform a lookup for addresses in the IPv4 family and fallback to a lookup for addresses in the IPv6 family |
| `ALL` | DNS resolver will perform a lookup for both IPv4 and IPv6 families, and return all resolved addresses |

See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html#enum-config-cluster-v3-cluster-dnslookupfamily) for more information about these options.

## Query Timeout

**Query Timeout** sets the timeout for DNS queries.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `dns_query_timeout` | `DNS_QUERY_TIMEOUT` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | none (Envoy default) |

#### Examples

```yaml
dns_query_timeout: 10s
```

**Enterprise:**

Set **Query Timeout** in the Console:

\[Set Query Timeout in the Console]

**Kubernetes:**

```yaml
dns:
  queryTimeout: 10s
```

## Query Tries

**Query Tries** sets the number of times a DNS query will be re-tried.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `dns_query_tries` | `DNS_QUERY_TRIES` | `integer` | none (Envoy default) |

#### Examples

```yaml
dns_query_tries: 7
```

**Enterprise:**

Set **Query Tries** in the Console:

\[Set Query Tries in the Console]

**Kubernetes:**

```yaml
dns:
  queryTries: 7
```

## Refresh Rate

**Refresh Rate** sets the DNS refresh rate.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `dns_refresh_rate` | `DNS_REFRESH_RATE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | none (respects DNS record TTL) |

#### Examples

```yaml
dns_refresh_rate: 10s
```

**Enterprise:**

Set **Refresh Rate** in the Console:

\[Set Refresh Rate in the Console]

**Kubernetes:**

```yaml
dns:
  refreshRate: 10s
```

## Resolvers

**Resolvers** allows you to specify a list of custom DNS resolvers for Pomerium to use instead of the system default. Each resolver should be specified as a URL in the format `udp://<ip>:<port>` or `tcp://<ip>:<port>`.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `dns_resolvers` | `DNS_RESOLVERS` | `array of strings` | System DNS resolvers |

#### Examples

```yaml
dns_resolvers:
  - udp://1.1.1.1:53
  - udp://8.8.8.8:53
```

```yaml
dns_resolvers:
  - tcp://1.1.1.1:53
```

**Enterprise:**

`dns_resolvers` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

```yaml
dns:
  resolvers:
    - udp://1.1.1.1:53
    - udp://8.8.8.8:53
```

## UDP Max Queries

**UDP Max Queries** sets the maximum number of queries before a new UDP port is opened.

### How to Configure

**Core:**

| **Config file keys**  | **Environment variables** | **Type**  | **Default** |
| :-------------------- | :------------------------ | :-------- | :---------- |
| `dns_udp_max_queries` | `DNS_UDP_MAX_QUERIES`     | `integer` | `100`       |

#### Examples

```yaml
dns_udp_max_queries: 100
```

**Enterprise:**

Set **UDP Max Queries** in the Console:

\[Set UDP Max Queries in the Console]

**Kubernetes:**

```yaml
dns:
  udpMaxQueries: 100
```

## Use TCP

**Use TCP** configures Pomerium to use TCP instead of UDP for DNS queries.

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type**  | **Default** |
| :------------------- | :------------------------ | :-------- | :---------- |
| `dns_use_tcp`        | `DNS_USE_TCP`             | `boolean` | `false`     |

#### Examples

```yaml
dns_use_tcp: true
```

**Enterprise:**

Set **Use TCP** in the Console:

\[Set Use TCP in the Console]

**Kubernetes:**

```yaml
dns:
  useTcp: true
```