Skip to content
StormTrust Developer Docs

Connect a private hostname

Last updated View as MarkdownAgent setup

Instead of managing static IP lists and routes, you can connect users to private HTTP and non-HTTP applications using their hostnames (for example, wiki.internal.local). Private hostname routes are especially useful when the application has an unknown or ephemeral IP, which often occurs when infrastructure is provisioned by a third-party cloud provider.

  1. Client device

    Requests wiki.internal.local

  2. DNS query
  3. Cloudflare Gateway

    Returns a token IP, then rewrites the destination to the real IP.

    172.64.128.0/20
  4. Hostname route
  5. Cloudflare Tunnel

    Forwards traffic to your private network, or egresses it to the public Internet

  6. Private host

    wiki.internal.local · 10.0.0.50

When a user requests a private hostname, Cloudflare Gateway assigns an initial resolved IP to route the traffic through your tunnel to the correct private IP address. By default, this IP is drawn from a Cloudflare-owned public IPv4 range (172.64.128.0/20) rather than Carrier-Grade NAT (CGNAT) space, so it does not trigger Google Chrome's Local Network Access restrictions. You can also configure a custom range if it conflicts with your existing network. For a deep dive into the architecture and packet flow, refer to our announcement blog post ↗.

Supported on-ramps/off-ramps

The table below summarizes the Cloudflare One products that are compatible with private hostname routing. Refer to the table legend for guidance on interpreting the table.

✅ Product works with no caveats
🚧 Product can be used with some caveats
❌ Product cannot be used

Device connectivity

End users can connect to private hostnames using the following traffic on-ramps:

On-ramp method Compatibility
Cloudflare One Client ✅
PAC files ✅
Browser Isolation ✅
Cloudflare Mesh ✅
Cloudflare WAN 🚧1

Feature availability

Client modes
Traffic and DNS mode
System Availability Minimum client version
Windows ✅ 2025.4.929.0
macOS ✅ 2025.4.929.0
Linux ✅ 2025.4.929.0
iOS ✅ 1.11
Android ✅ 2.4.2
ChromeOS ✅ 2.4.2

Footnotes

  1. Not compatible with ECMP routing. For hostname-based routing to work, DNS queries and the resulting network traffic must reach Cloudflare over the same IPsec/GRE tunnel.
    ↩

Private network connectivity

Private hostname routing works with the off-ramps below. Other traffic off-ramps require IP-based routes.

Connector Compatibility Minimum version
cloudflared ✅ 2025.7.0
Cloudflare Mesh ✅ 2026.6.822.0 (Linux)
Cloudflare WAN ❌

Connect a private hostname

This section covers how to enable remote access to a private hostname application using cloudflared.

Prerequisites

Before you can connect to private hostnames, you must enable the Gateway proxy.

  1. Go to Traffic policies > Traffic settings.
  2. In Proxy and inspection, turn on Allow Secure Web Gateway to proxy traffic.
  3. Select TCP.
  4. Select UDP (required to proxy traffic to internal DNS resolvers).
  5. (Recommended) To proxy traffic for diagnostic tools such as ping and traceroute, select ICMP. You may also need to update your system to allow ICMP traffic through cloudflared.

  1. Add the following permission to your cloudflare_api_token ↗:

    • Zero Trust Write

  2. Turn on the TCP and/or UDP proxy using the cloudflare_zero_trust_device_settings ↗ resource:

    resource "cloudflare_zero_trust_device_settings "global_warp_settings" {
	account_id            = var.cloudflare_account_id
  gateway_proxy_enabled = true
	gateway_udp_proxy_enabled = true
}

Cloudflare will now proxy traffic from enrolled devices, except for the traffic excluded in your split tunnel settings. For more information on how Gateway forwards traffic, refer to Gateway proxy.

Your devices must also forward the following traffic to Cloudflare:

  • Initial resolved IPs:
    • IPv4: 172.64.128.0/20
    • IPv6: 2606:4700:0cf1:4000::/64

    This is the default range. You can configure a custom initial resolved IP range for IPv4 if it conflicts with your existing network.

  • DNS queries for your private hostname

Configuration steps vary depending on your device on-ramp:

Cloudflare One Clients

  1. In your WARP device profile, configure Split Tunnels such that the initial resolved IPs route through the WARP tunnel. Configuration depends on your Split Tunnels mode:

    • Exclude mode: Delete 100.64.0.0/10 from your Split Tunnels list. We recommend adding back the IP ranges that are not explicitly used for Cloudflare One services. This reduces the risk of conflicts with existing private network configurations that may use the CGNAT address space.
    • Include mode: Add Split Tunnel entries for the following IP addresses:
      • IPv4: 172.64.128.0/20
      • IPv6: 2606:4700:0cf1:4000::/64

      This is the default range. You can configure a custom initial resolved IP range for IPv4 if it conflicts with your existing network.

  2. In Local Domain Fallback, delete the top-level domain for your private hostname. This configures WARP to send the DNS query to Cloudflare Gateway for resolution.

Cloudflare Mesh

To attract a hostname's traffic to a Mesh node instead of a cloudflared tunnel, add a hostname route to the node. The initial resolved IP listed above must route through Cloudflare on both the Mesh node and client device profiles, and — for a private hostname — the node must be able to resolve the hostname (via its local hosts file or a Gateway resolver policy). Refer to Hostname routes.

Cloudflare WAN

  1. Ensure that the initial resolved IP listed above route through Cloudflare WAN to Cloudflare.
  2. Point the DNS resolver for your Cloudflare WAN network to Cloudflare Gateway.

1. Connect the application to Cloudflare

  1. Log in to the Cloudflare dashboard and go to Networking > Tunnels.

    Go to Tunnels ↗

  2. Select Create a tunnel.

  3. Enter a name for your tunnel. We suggest choosing a name that reflects the type of resources you want to connect through this tunnel (for example, enterprise-VPC-01).

  4. Select Create Tunnel.

  5. Choose your operating system, then copy the installation command and run it in a terminal on your origin server.

  6. Wait for the tunnel to connect. Once the connection is established, select Continue.

  1. After the tunnel is connected, go to the tunnel's Routes tab and select Add route, then select Private hostname.

  2. Enter the fully qualified domain name (FQDN) that represents your application (for example, wiki.internal.local).

    Hostname format restrictions

    • Character limit: Must be less than 255 characters.
    • Supported wildcards: A single wildcard (*) is allowed, and it must represent a full DNS label. Example: *.internal.local
    • Unsupported wildcards: The following wildcard formats are not supported:
      • Partial wildcards such as *-dev.internal.local or dev-*.internal.local.
      • Wildcards in the middle, such as foo*bar.internal.local or foo.*.internal.local.
      • Multiple wildcards in the hostname, such as *.*.internal.local.
    • Wildcard trimming: Leading wildcards (*) are trimmed off and an implicit dot (.) is assumed. For example, *.internal.local is saved as internal.local but will match all subdomains at the wildcard level (covers foo.internal.local but not foo.bar.internal.local).
    • Dot trimming: Leading and ending dots (.) are allowed but trimmed off.

  3. Select Save.

2. Configure DNS resolution

When Gateway receives a request for your private hostname, it must resolve the hostname to a private IP address. There are two ways to configure this, depending on your network topology.

Scenario A: Use the system resolver (Default)

By default, cloudflared uses the private DNS resolver configured on its host machine (for example, in /etc/resolv.conf on Linux).

If the machine running cloudflared can already resolve wiki.internal.local to its private IP using the local system resolver, no further configuration is required. You can skip to Step 3.

Scenario B: Use a specific private DNS server (Advanced)

If you need cloudflared to use a specific internal DNS server that is different from the host's default resolver, you must explicitly connect that DNS server to Cloudflare via an IP/CIDR route. You will also need to configure a Gateway resolver policy to route queries to this specific private DNS server.

  1. To create an IP/CIDR route for the DNS server:

    1. Go to Networking > Routes.

      Go to Routes ↗

    2. Select Add CIDR route.

    3. Enter the private IP address of your internal DNS resolver.

    4. Select the Cloudflare Tunnel that connects to the network where this DNS server resides.

    5. Select Create.

  2. To create a resolver policy:

    1. Go to Traffic policies > Resolver policies.
    2. Select Create a policy.
    3. Create an expression that matches the private hostname:
      SelectorOperatorValue
      Hostinwiki.internal.local
    4. Under Configure custom DNS resolvers, enter the private IP address of your internal DNS server.
    5. From the dropdown menu, select the - Private routing option and the virtual network assigned to the tunnel you selected in the previous step.
    6. Select Create policy.

By default, all devices enrolled in your Zero Trust organization can connect to your private network through Cloudflare Tunnel. You can configure Gateway to inspect your network traffic and either block or allow access based on user identity and device posture. To learn more about policy design, refer to Secure your first application.

To prevent Cloudflare One Client users from accessing your entire private network, we recommend creating a catch-all Gateway block policy for your private IP space. You can then layer on higher priority Allow policies (in either Access or Gateway) which grant users access to specific applications or IPs.

You can create an Access self-hosted application for your private hostname and configure Access policies within that application. This option allows you to manage user access alongside your SaaS and other web apps.

Option 2: Gateway firewall policies

If you prefer to secure the application using a traditional firewall model, you can build Gateway network policies using the SNI or SNI Domain selector. For an additional layer of protection, add a Gateway DNS policy to allow or block the Host or Domain from resolving.

Example network policies

The following example consists of two policies: the first allows specific users to reach your application, and the second blocks all other traffic.

  1. Allow company employees
Selector Operator Value Logic Action
SNI in wiki.internal.local And Allow
User Email matches regex .*@example.com
  1. Catch-all block policy
Selector Operator Value Action
Destination IP in 10.0.0.0/8 Block

Example DNS policy

Selector Operator Value Logic Action
Host in wiki.internal.local And Allow
User Email matches regex .*@example.com

4. Test the connection

End users can now reach the application by going to its private hostname. For example, to connect to a private web application, open a browser and go to wiki.internal.local.

Troubleshooting

If you cannot connect, verify the following:

  1. Confirm DNS resolution - From the device, confirm that you can successfully resolve the private hostname:

    nslookup wiki.internal.local
    Server:		127.0.2.2
Address:	127.0.2.2#53

Non-authoritative answer:
Name:	wiki.internal.local
Address: 172.64.128.48

    The query should resolve using WARP's DNS proxy and return a Gateway initial resolved IP. If the query fails to resolve or returns a different IP, check your Local Domain Fallback configuration and Gateway resolver policies.

  2. Check Gateway logs - Review your Gateway network logs to see if the connection is being blocked by a policy.

  3. Verify tunnel status - Confirm that your tunnel is healthy and connected by checking tunnel status.

  4. Test connectivity to initial resolved IP - When you connect to the application using its private hostname, the device should make a connection to the initial resolved IP:

    curl -v4 http://wiki.internal.local
    * Trying 172.64.128.48:80...
* Connected to wiki.internal.local (172.64.128.48) port 80
...

    If the request fails, confirm that the initial resolved IP routes through the WARP tunnel. You can also check your tunnel logs to confirm that requests are routing to the application's private IP.

Limitations

Google Chrome restricts access to private hostnames

Starting with Chrome 142 ↗, Local Network Access (LNA) restricts requests from websites to local IP addresses. LNA is implemented at the Chromium engine level, so this affects all Chromium-based browsers (for example, Microsoft Edge, Brave, and Opera), not only Google Chrome. This can affect accounts whose Gateway initial resolved IP range is still drawn from Carrier-Grade NAT (CGNAT) address space (100.64.0.0/10) — for example, the legacy default range 100.80.0.0/16, or a custom range configured within CGNAT space. These browsers categorize such addresses as belonging to a local network. When a website loaded from a public IP makes subrequests to a domain resolved through an initial resolved IP in this space, the browser treats this as a public-to-local network request and displays a prompt asking the user to allow access to devices on the local network. The browser blocks requests to these domains until the user accepts this prompt.

This commonly occurs when an Egress policy matches broadly used domains (such as cloudfront.net or github.com), causing subrequests from public pages to resolve into CGNAT space.

Accounts using the current default initial resolved IP range (172.64.128.0/20) are not affected, because this range is public Cloudflare address space rather than CGNAT. If your account was created before this default changed, or if you configured a custom CGNAT-space range, refer to Configure initial resolved IPs to move to a non-CGNAT range instead of relying on the following browser workarounds.

The workarounds below use Google Chrome Enterprise policies. If your organization manages a different Chromium-based browser, consult that browser's enterprise policy documentation for an equivalent control.

Iframes

If the affected request originates from within an iframe (for example, an application embedded in a third-party portal), the iframe must declare the local-network-access permission for the browser prompt to appear in the parent frame:

  • Chrome 142-144: Use the allow="local-network-access" attribute on the iframe element.
  • Chrome 145+: The permission was split into allow="local-network" and allow="loopback-network".

If iframes are nested, every iframe in the chain must include the appropriate attribute. Since third-party applications control their own iframe attributes, this may not be configurable by the end user.

Workarounds

To avoid this issue, choose one of the following options:

  • Override IP address space classification (Chrome 146+): Use the LocalNetworkAccessIpAddressSpaceOverrides ↗ Chrome Enterprise policy to reclassify your CGNAT-space initial resolved IP range (for example, 100.80.0.0/16) as public. This is the most targeted fix because it only changes the classification for the initial resolved IP range rather than disabling security checks entirely.
  • Allow specific URLs (Chrome 140+): Use the LocalNetworkAccessAllowedForUrls ↗ Chrome Enterprise policy to exempt specific websites from Local Network Access checks. Note that https://* is a valid entry to disable checks for all URLs.
  • Allow specific URLs (Chrome 146+): Use the LocalNetworkAllowedForUrls ↗ Chrome Enterprise policy, which replaces LocalNetworkAccessAllowedForUrls starting in Chrome 146.
  • Opt out of Local Network Access restrictions (Chrome 142-152): Use the LocalNetworkAccessRestrictionsTemporaryOptOut ↗ Chrome Enterprise policy to completely opt out of Local Network Access restrictions. This is a temporary policy and will be removed after Chrome 152.
  • Disable the Chrome feature flag: Go to chrome://flags and set the Local Network Access Checks flag to Disabled. This approach is suitable for individual users but not for enterprise-wide deployment.

Was this helpful?

StormTrust Developer Docs