> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# About DNS Hostname SmartGroups

> DNS Hostname SmartGroups enable you to filter non-HTTP/TLS traffic by fully qualified domain name (FQDN). The gateway proactively resolves hostnames to IP addresses and enforces them as firewall rules in DCF policies.

DNS Hostname SmartGroups let you define <a href={"/docs/enterprise/" +
"10.1" +
"/concepts-architectures/components/dcf/dcf-overview"}>Distributed Cloud
Firewall (DCF)</a> policies using fully qualified domain names (FQDNs) instead
of IP addresses. This is useful when you need to allow or deny traffic to
destinations whose IP addresses change frequently — such as SaaS APIs, cloud
services, or partner endpoints — but the traffic is not HTTP or TLS and
therefore cannot be matched by <a href={"/docs/enterprise/" + "10.1" +
"/concepts-architectures/components/dcf/webgroups-about"}>WebGroups</a>.

When you add a DNS Hostname resource to a SmartGroup, the Aviatrix gateway
resolves the hostname to its current IP addresses and enforces matching traffic
as /32 CIDR rules. The resolved addresses are visible in the SmartGroup detail
view alongside any static CIDR entries.

<img src="https://mintcdn.com/aviatrix-14b37c43/vKpoXYmi49a-T1vW/images/concepts-architectures/components/dcf/hostname-sg-detail.png?fit=max&auto=format&n=vKpoXYmi49a-T1vW&q=85&s=63e427c909f06879299376c1c6b1c510" alt="SmartGroup detail view showing both CIDR and DNS Hostname resource types" width="642" height="630" data-path="images/concepts-architectures/components/dcf/hostname-sg-detail.png" />

<Note>
  You must enter the DNS Hostname resource type as an FQDN (for example,
  `api.example.com`). Entering just a hostname without a domain is not
  supported. The FQDN can only include characters that are valid in DNS
  hostnames. Wildcards are not supported.
</Note>

## How Hostname Resolution Works

Aviatrix gateways resolve hostname SmartGroup entries **proactively** — not at
the time traffic arrives. This means:

1. When a DCF policy containing a hostname SmartGroup is pushed to a gateway,
   the gateway immediately resolves all configured FQDNs using forward DNS (A
   record) lookups.
2. The resolved IP addresses are installed as /32 CIDR entries in the gateway's
   firewall rules.
3. The gateway periodically re-resolves each FQDN before its DNS cache entry
   expires, keeping the firewall rules current as IP addresses change.

This proactive approach ensures that firewall rules are already in place when
traffic arrives. There is no per-packet DNS lookup or inspection — the gateway
simply matches traffic against the pre-resolved IP addresses.

### TTL and Refresh Behavior

The gateway respects DNS TTL (Time to Live) values from the authoritative DNS
server, with the following bounds:

| Parameter      | Value                           |
| -------------- | ------------------------------- |
| Minimum TTL    | 60 seconds                      |
| Maximum TTL    | 3600 seconds (1 hour)           |
| Refresh timing | Before the cached entry expires |

If a DNS server returns a TTL below 60 seconds, the gateway caches the result
for 60 seconds. If the TTL exceeds 3600 seconds, the gateway re-resolves after 1
hour regardless of the advertised TTL.

<Note>
  When a hostname SmartGroup is first deployed to a gateway, there is a brief
  window (typically a few seconds) while the initial DNS resolution completes.
  During this window, traffic to the hostname destination may not yet match the
  DCF rule.
</Note>

### Resolution Limitations

* **A records only** — The gateway resolves IPv4 (A) records. IPv6 (AAAA)
  records are not supported.
* **No CNAME chasing** — If a hostname resolves to a CNAME, only the final A
  record addresses are used for rule enforcement. Intermediate CNAME targets are
  not independently tracked.
* **Forward DNS only** — Reverse DNS (PTR) lookups are not performed.

## DNS Server Configuration

By default, hostname SmartGroup entries are resolved using each gateway's
individually configured management DNS server. You can override this with custom
DNS servers that apply globally to all gateways enforcing hostname SmartGroup
rules.

| Setting                                       | Description                                                                                                                                                                      |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gateway's Management DNS Server** (default) | Each gateway uses its own management DNS server, as configured in the <a href={"/docs/enterprise/" + "10.1" + "/reference/gateways/transit-spoke-dns"}>gateway DNS settings</a>. |
| **Custom DNS Servers**                        | Up to 2 custom DNS server IPv4 addresses. Applied globally to all gateways that enforce hostname SmartGroup rules.                                                               |

To configure the DNS server for hostname resolution:

1. In CoPilot, go to **Groups > Settings**.
2. In the **DNS Server for Hostname Resolution** card, select **Custom DNS
   Servers**.
3. Enter up to 2 DNS server IP addresses.

<img src="https://mintcdn.com/aviatrix-14b37c43/vKpoXYmi49a-T1vW/images/concepts-architectures/components/dcf/hostname-sg-dns-settings.png?fit=max&auto=format&n=vKpoXYmi49a-T1vW&q=85&s=81a447898da796915f0c9b53bc9ba1c2" alt="DNS Server for Hostname Resolution settings" width="425" height="125" data-path="images/concepts-architectures/components/dcf/hostname-sg-dns-settings.png" />

<Warning>
  Custom DNS server settings are global — they apply to all gateways enforcing
  DCF rules that contain hostname SmartGroups. You cannot configure different
  DNS servers for different gateways or different SmartGroups.
</Warning>

<Note>
  Edge gateways use the DNS server configured in their own gateway settings and do not use the custom DNS server setting configured in Groups > Settings.
</Note>

## When to Use Hostname SmartGroups vs WebGroups

Hostname SmartGroups and <a href={"/docs/enterprise/" + "10.1" +
"/concepts-architectures/components/dcf/webgroups-about"}>WebGroups</a> both let
you write DCF policies using domain names, but they work differently and apply
to different traffic types.

|                       | Hostname SmartGroups                                                                                              | WebGroups                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Traffic type**      | Non-HTTP/TLS traffic (SMTP, SSH, database connections, custom protocols)                                          | HTTP, HTTPS, and TLS traffic                                                              |
| **Matching method**   | DNS resolution — FQDN resolved to IP addresses, enforced as /32 CIDRs                                             | SNI/Host header inspection — matches the domain name in the TLS handshake or HTTP request |
| **Wildcard support**  | No                                                                                                                | Yes (`*.example.com`)                                                                     |
| **Protocol scope**    | Any IP protocol                                                                                                   | HTTP/HTTPS/TLS only                                                                       |
| **IPv6 support**      | No                                                                                                                | No                                                                                        |
| **Typical use cases** | SMTP relay to a SaaS mail provider, SSH to a bastion by hostname, database connections to cloud-managed endpoints | Allow/deny web browsing to specific domains, SaaS application access, API gateway egress  |

<Tip>
  If you want to filter web (TLS, HTTP, or HTTPS) traffic, Aviatrix strongly
  recommends using WebGroups instead of hostname SmartGroups. WebGroups inspect
  the SNI or Host header directly, which is more reliable for web traffic than
  DNS-based IP matching.
</Tip>

## Feature Availability

| Version         | Status                   |
| --------------- | ------------------------ |
| Controller 7.2  | Preview                  |
| Controller 8.1+ | Generally Available (GA) |

See <a href={"/docs/enterprise/" + "10.1" +
"/reference/dcf/dcf-capabilities"}>Distributed Cloud Firewall Supported
Capabilities by Controller Version</a> for the full feature matrix.

## Limitations

* **No wildcard support** — You must enter exact FQDNs. Patterns like
  `*.example.com` are not supported.
* **A records only** — Only IPv4 addresses are resolved. AAAA (IPv6) records are
  not supported.
* **Global DNS configuration** — Custom DNS server settings apply to all
  gateways. Per-gateway or per-SmartGroup DNS configuration is not available.
* **Edge gateway DNS** — Edge gateways use their own gateway DNS settings and do
  not use the custom DNS server configured in Groups > Settings.
* **Initial resolution delay** — When a hostname SmartGroup is first deployed,
  there is a brief delay while DNS resolution completes.

## AWS GuardDuty Considerations

If you use AWS GuardDuty in the same account as your Aviatrix gateways,
GuardDuty may generate DNS-related findings (such as
`Trojan:EC2/DNSDataExfiltration` or `Backdoor:EC2/DenialOfService.Dns`) for the
gateway instances. This is expected behavior — the Aviatrix gateway is
performing periodic DNS lookups to resolve the FQDNs configured in your hostname
SmartGroups and keep firewall rules current.

These DNS queries originate from the gateway's elastic network interface (ENI)
and are a normal part of hostname SmartGroup enforcement.

**Recommendations:**

* **Suppress findings** for the Aviatrix gateway ENIs in GuardDuty to reduce
  noise.
* **Use custom DNS servers** — If you configure custom DNS servers for hostname
  resolution, the gateway queries go to your specified servers instead of the
  VPC default resolver, which may reduce GuardDuty findings related to VPC DNS.

## Terraform Support

You can manage hostname SmartGroups using the `aviatrix_smart_group` resource in
the
[Aviatrix Terraform Provider](https://registry.terraform.io/providers/AviatrixSystems/aviatrix/latest/docs).
Use the `fqdn` key in `match_expressions` to specify DNS Hostname entries:

```hcl theme={null}
resource "aviatrix_smart_group" "mail_relay" {
  name = "mail-relay-endpoints"

  selector {
    match_expressions {
      fqdn = "smtp.mailprovider.com"
    }
    match_expressions {
      fqdn = "smtp2.mailprovider.com"
    }
  }
}
```

## Related Topics

* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/smartgroups-about"}>Managing SmartGroups</a>
* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/webgroups-about"}>About WebGroups</a>
* <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/dcf/dcf-overview"}>Distributed Cloud Firewall Overview</a>
* <a href={"/docs/enterprise/" + "10.1" + "/reference/ui/groups"}>
    Groups UI Reference
  </a>
  (create SmartGroups, ExternalGroups, WebGroups; Groups Settings)
* <a href={"/docs/enterprise/" + "10.1" + "/guides/platform-administration/dns-server-general"}>DNS Server Configuration for Aviatrix Services</a>
* <a href={"/docs/enterprise/" + "10.1" + "/reference/gateways/transit-spoke-dns"}>DNS Server Configuration for Aviatrix Gateways</a>
* <a href={"/docs/enterprise/" + "10.1" + "/reference/dcf/dcf-capabilities"}>DCF Supported Capabilities by Controller Version</a>