# How to Configure Custom DNS for Containers Using Container System DNS Commands

> Configure custom DNS for containers using container system dns commands. Set a system-wide domain in config.toml and map hostnames to IP addresses with container system dns create.

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

---

**You can configure custom DNS for containers by setting a system-wide domain in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) and using `container system dns create` commands to map hostnames to IP addresses that the built-in resolver serves on ports 1053 or 2053.**

The apple/container project includes a built-in DNS resolver that enables automatic container name resolution and custom hostname mappings without external services. You configure custom DNS for containers using container system dns commands and the `[dns]` section in the host-side TOML configuration. This setup allows containers to resolve each other by name and reach external services through custom host entries.

## Understanding the Container DNS Architecture

The container runtime implements a DNS server that operates on port 1053 when the host runs a DNS server, or port 2053 otherwise. According to the implementation in [`Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift), this resolver handles two types of queries: automatic container name resolution with an optional domain suffix, and static host entries created via the CLI.

### System-Wide DNS Domain

The `domain` setting in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) automatically appends a DNS suffix to every container name. When set to `mycluster.local`, the container `my-web-server` becomes reachable as `my-web-server.mycluster.local`. This configuration is parsed by [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### Host-Side DNS Entries

The `container system dns` sub-commands manage static mappings between fully-qualified domain names and specific IP addresses. These entries allow containers to resolve hostnames for services running outside the container network, such as `host.container.internal` pointing to `203.0.113.113`.

## Setting a System-Wide DNS Domain

### Configuring config.toml

Create or edit [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) to include the `[dns]` section. The Swift model in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) reads this configuration during daemon startup:

```toml
[dns]
domain = "example.local"

```

### Reloading the Daemon

Apply the new DNS configuration by reloading the container system:

```bash
sudo container system reload

```

After reloading, any container you start will be reachable as `<container-name>.example.local` from within other containers.

## Managing Host-Side DNS Entries with Container System DNS Commands

### Creating DNS Records

Use `container system dns create` to map a hostname to a specific IP address. This stores the entry in the container runtime's DNS server as described in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md):

```bash
sudo container system dns create my-db.internal --localhost 192.168.1.42

```

The `--localhost` flag specifies the target IP address. You can use any fully-qualified domain name as the hostname.

### Verifying Configuration

Confirm your custom DNS configuration is active using the list command:

```bash
sudo container system dns list

```

This outputs all custom host entries that the container DNS server maintains, showing the mappings created via `container system dns create`.

## Complete Walkthrough Example

Combine both mechanisms to create a fully functional custom DNS environment:

```bash

# 1. Configure the system-wide domain

sudo mkdir -p /etc/container
sudo tee /etc/container/config.toml > /dev/null <<'EOF'
[dns]
domain = "mycluster.local"
EOF

# 2. Apply the configuration

sudo container system reload

# 3. Add a host-side entry for external services

sudo container system dns create host.container.internal --localhost 203.0.113.113

# 4. Run a container

sudo container run --name webapp

# 5. Verify DNS resolution inside a new container

sudo container run --rm alpine sh -c 'ping -c 1 webapp.mycluster.local && ping -c 1 host.container.internal'

# 6. List all custom DNS records

sudo container system dns list

```

Inside containers, `webapp.mycluster.local` resolves to the container's IP, while `host.container.internal` resolves to the host-side IP you configured.

## Summary

- **System-wide domain**: Set the `domain` key in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml) under `[dns]` to enable automatic FQDN resolution for all containers.
- **Host-side entries**: Use `sudo container system dns create <hostname> --localhost <ip>` to map custom hostnames to specific IP addresses.
- **Verification**: Run `sudo container system dns list` to inspect active DNS records stored by the runtime.
- **Implementation**: The DNS server implementation resides in [`Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift), while configuration parsing is handled by [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).

## Frequently Asked Questions

### Where does the container DNS server listen?

The container DNS server listens on port 1053 when the host runs a DNS server, otherwise on port 2053. This behavior is implemented in [`Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/HostDNSResolver.swift).

### Do I need external DNS services to resolve container hostnames?

No. The apple/container project provides a built-in resolver that handles both automatic container name resolution and custom entries created via `container system dns` commands without requiring external DNS configuration or separate DNS servers.

### What file format does the container system use for DNS configuration?

The system uses TOML format in [`/etc/container/config.toml`](https://github.com/apple/container/blob/main//etc/container/config.toml). The `[dns]` section accepts a `domain` key that defines the default search domain for all containers, as parsed by [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) according to the schema in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### How do I remove a custom DNS entry?

While the provided examples demonstrate creating entries, the `container system dns` command family includes management sub-commands documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md). Consult that reference for the specific syntax to delete or modify entries created with `container system dns create`.