# How to Configure Custom DNS Servers and Options for Containers in Apple Container

> Learn how to configure custom DNS servers and options for containers using the apple/container CLI. Master DNS settings for your containerized applications.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The `apple/container` CLI provides five DNS-specific flags—`--dns`, `--dns-domain`, `--dns-search`, `--dns-option`, and `--no-dns`—that map to the `Flags.DNS` structure and persist into `ContainerConfiguration.DNSConfiguration`, defaulting to Cloudflare's `1.1.1.1` nameserver when unspecified.**

The `apple/container` repository offers granular control over DNS resolution for containerized workloads through command-line interface options. When you configure custom DNS servers and options for containers, the system validates your input against strict mutual exclusion rules before persisting the configuration into the container model. This implementation ensures predictable name resolution behavior whether you are running ephemeral workloads or configuring persistent builder environments.

## Available DNS Configuration Flags

The `container` command supports the following flags to customize resolver behavior inside containers:

- **`--dns <ip>`** — Specify one or more nameserver IP addresses. The default value is `1.1.1.1` when omitted.
- **`--dns-domain <domain>`** — Set the default search domain for the container's resolver.
- **`--dns-search <domain>`** — Append additional search domains as comma-separated values.
- **`--dns-option <option>`** — Pass resolver options such as `debug` or `ndots:5` to the container's DNS configuration.
- **`--no-dns`** — Disable all DNS configuration entirely. This flag **cannot** be combined with any other DNS-related flags.

## Runtime DNS Configuration Examples

Use the `container run` command to apply custom DNS settings to ephemeral containers. The flags populate the `ContainerConfiguration.DNSConfiguration` struct before the container starts.

Configure multiple nameservers and a default domain:

```bash
container run \
  --dns 8.8.8.8 \
  --dns 8.8.4.4 \
  --dns-domain mycorp.local \
  alpine:latest \
  cat /etc/resolv.conf

```

Add search domains and resolver options while retaining the default nameserver:

```bash
container run \
  --dns-option ndots:5 \
  --dns-search dev.example.com,svc.example.com \
  ubuntu:latest \
  sh -c 'cat /etc/resolv.conf'

```

Attempting to mix `--no-dns` with other flags triggers a validation error:

```bash

# This command will fail

container run \
  --no-dns \
  --dns-search dev.example.com \
  alpine:latest

```

## Builder Container DNS Settings

DNS configuration applies consistently to builder containers via the `container builder start` command, utilizing the same `Flags.DNS` parsing logic:

```bash
container builder start \
  --dns 10.0.0.53 \
  --dns-domain internal \
  --dns-search svc.internal,apps.internal

```

## Source Code Implementation

### CLI Flag Parsing

The DNS flag definitions reside in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) at lines 129–151, where the `Flags.DNS` struct captures user input. This structure gathers arrays for nameservers and search domains alongside individual option strings.

Validation logic at lines 350–363 enforces mutual exclusion: when `--no-dns` is present, the code verifies that no other DNS flags appear in the command invocation. If conflicting flags are detected, the parser raises a validation error before container creation proceeds.

### Container Configuration Model

Parsed DNS values transfer into [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift), specifically into the optional `dns` property defined at lines 30–38. The `ContainerConfiguration.DNSConfiguration` struct stores four fields:

- `nameservers`: Array of IP address strings
- `domain`: Single default search domain string
- `searchDomains`: Array of additional search domains
- `options`: Array of resolver option strings

The default nameserver constant appears at line 31 as `["1.1.1.1"]`, which the system applies when the configuration object is absent or uninitialized.

## Validation Constraints and Defaults

The implementation enforces two critical constraints:

1. **Mutual Exclusion**: The `--no-dns` flag validates in isolation. Supplying `--no-dns` alongside `--dns`, `--dns-domain`, `--dns-search`, or `--dns-option` causes immediate command failure.
2. **Default Fallback**: Without any DNS flags, containers automatically receive a `DNSConfiguration` instance containing only `1.1.1.1` as the nameserver.

## Summary

- The `apple/container` CLI exposes five flags for DNS customization: `--dns`, `--dns-domain`, `--dns-search`, `--dns-option`, and `--no-dns`.
- Flag parsing occurs in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift), with validation preventing `--no-dns` from combining with other DNS options.
- Configuration persists into `ContainerConfiguration.DNSConfiguration` defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).
- The default nameserver is hardcoded as `1.1.1.1` and applies when no DNS flags are provided.
- DNS settings work identically for both `container run` and `container builder start` commands.

## Frequently Asked Questions

### What is the default DNS server if I don't specify any flags?

According to the source code in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift) at line 31, the system defaults to `["1.1.1.1"]` (Cloudflare DNS) when no DNS configuration flags are present. This value populates the `nameservers` array automatically.

### Can I use --no-dns with other DNS flags?

No. The validation logic in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (lines 350–363) explicitly checks for this combination and raises a validation error if `--no-dns` appears alongside `--dns`, `--dns-domain`, `--dns-search`, or `--dns-option`.

### How do I add multiple search domains to a container?

Use the `--dns-search` flag with comma-separated domain values. For example: `--dns-search dev.example.com,svc.example.com`. These values populate the `searchDomains` array within the `ContainerConfiguration.DNSConfiguration` struct.

### Where is the DNS configuration stored in the container model?

The DNS configuration is stored in the optional `dns` property of the container configuration object, typed as `ContainerConfiguration.DNSConfiguration`. This struct is defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift) at lines 30–38 and contains the `nameservers`, `domain`, `searchDomains`, and `options` fields.