Troubleshooting application access

Prev Next

If users have difficulty connecting through Gateways to protected hosts, work through the DNS and access checks below. For background on how DNS works in AppGate ZTNA, see DNS and name resolution.


Check DNS configuration

Site

Device DNS relies on the Site configuration.Verify that a DNS resolver, a DNS forwarder, or both are correctly configured. It is normal to configure one or both on the Site where the DNS servers are located.

If a user can access services on one Site but not another, the DNS resolver on the failing Site may be misconfigured.

DNS policy

Entitlements set routes to protected networks and rely on DNS to resolve protected hosts. AppGate ZTNA routes only DNS requests that match a specified domain through the tunnel to the specified DNS servers. Verify that the hostnames used in entitlements have a matching domain specified in the DNS policy.

For mobile devices, you must configure a default DNS server.

DNS entitlement

The DNS servers specified in the DNS policy require an entitlement that routes DNS requests through the appropriate tunnel toward the Gateway or Site hosting those servers. Verify that an entitlement provides access to the DNS servers on UDP port 53.

Device DNS

Verify that the user's device is not configured to use Private DNS, which can override match domain settings set by AppGate ZTNA.


Diagnose DNS issues

If a user has an entitlement for a protected host but cannot access it, the issue is likely DNS-related. On the Gateway, check the DNS server IP addresses used by the appliance, the DNS resolver, and the DNS forwarder.

The examples below use DNS Forwarder IPv4 address 100.127.20.30 (generated when the DNS forwarder was configured) and forward DNS queries to DNS server 10.10.10.10.

If the Gateway cannot resolve the protected host, device DNS resolution will also fail.

Check the Gateway's DNS

On the Gateway, run:

dig github.com @10.10.10.10

Replace 10.10.10.10 with the IP address of your DNS server.

Check the response for NOERROR. A NXDOMAIN status means no DNS record exists for the protected host:

;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14058

Then verify the IP address in the answer section:

;; ANSWER SECTION:
github.com.    50    IN    A    140.82.121.4

Check the DNS resolver and DNS forwarder on the Gateway

DNS resolver

On the Gateway the user is connected to, run:

sudo cz-names status

Check the list of resolutions:

dns://siteexample.com: ipv4, ipv6

There is typically one entry for each protected host (defined in the entitlement action) that signed-in users can access.

For more information, run:

sudo cz-console -d cz-gonamed -p

This provides resolver process information for each configured resolver, including hits, misses, insertions, and eviction counts; the update interval; and cache and configuration details such as:

Status: healthy
Update interval: 1m0s
Match domains: [internal.company.com]
Zones transfers: false
AAAA lookups: true
Hostnames: 1

Check cz-gonamed.log on the Gateway for the name being resolved and the resulting IP addresses.

DNS forwarder

On the Gateway the user is connected to, run:

sudo cz-console -d cz-dnsfwd -p

Check for registered rules:

rules registered = 2

The number must match the number of match domains configured in the signed-in user’s DNS policy.

Check for matched rules:

*.example.com: tun IPs

There is typically one entry for each protected host (entitlement action) that each user (tun IP) has attempted to access.

Check cz-dnsfwd.log for:

INFO    [wildcard][total-added=1][total-removed=0] Updating domain rules
INFO    [wildcard][rule=*.bla.bla.com] Domain rule added

Check DNS on the connecting device

DNS behavior differs across operating systems. Two users with identical policies and entitlements but different operating systems may have different access—often because of these DNS differences.

For example, macOS uses the built-in match domain concept. Windows uses the Name Resolution Policy Table (NRPT), which Windows treats separately from standard DNS server configuration. Windows checks the NRPT before sending a DNS query. If a query matches an NRPT entry, Windows handles it according to the table settings; otherwise, Windows uses the configured DNS servers.

If the hostnames in entitlements are not resolving correctly, use the checks below.

Basic DNS check (all platforms)

If a protected host is unreachable through an entitlement, first try connecting using the host's IP address instead of its DNS name.

The most reliable cross-platform method for checking DNS resolution is ping. Ignore whether the ping succeeds or fails—check only the resolved IP address.

NOTE

Do not use nslookup to check AppGate ZTNA DNS configurations. On both macOS and Windows, nslookup bypasses the OS resolver and has no awareness of AppGate ZTNA DNS policies.

Check DNS when a DNS policy is configured

Windows

Standard DNS commands are not appropriate when NRPT is in use.

To check DNS resolution, use the Resolve-DnsName cmdlet, which supports parameters that customize DNS queries.

To check NRPT settings, run: Get-DnsClientNrptPolicy -Effective

In the output, locate the namespace you need and verify that the name server IP address is correct. A correct entry confirms that all requests for that namespace—for example, .github.com—are sent to the DNS forwarder at 100.127.20.30.

Configuration settings for DirectAccess, including DNS servers and encryption options.

NOTE

ipconfig /all does not display NRPT entries added by AppGate ZTNA. Windows treats NRPT entries differently from standard DNS server configurations..

macOS

To check DNS resolution, run:

dscacheutil -q host -a name myapp.myco.com

Expected output:

name: myapp.myco.com
ipv6_address: fd00:ffff:a:1:2:3:4:5
name: myapp.myco.com
ip_address: 10.10.10.10

To check DNS settings, run:

scutil --dns

In the output, locate the domain you need and verify that the nameserver IP address is correct. A correct entry confirms that all requests for that domain—for example, .github.com—are sent to the DNS forwarder at 100.127.20.30.

DNS resolver output showing domain, nameserver, flags, and reachability status.

Check the client logs

Download and unzip the client logs. Open driver.log and search for DNS domain.

You should find entries for each protected host:

Info : DNS domain: github.com --> 100.127.20.30

On Windows, you should also find entries for each NRPT record added:

Info : Added DNS policy entry: .github.com = 100.127.20.30

These entries confirm that the client is aware of the DNS policy and has applied the DNS configuration.

Check Portal user's DNS

The Portal includes a DNS proxy service that ensures each user receives the DNS policy and entitlement configured for them.

NOTE

The Portal requires a default DNS server.

To view the live cache—which maps users to their client IDs and DNS settings—run the following on the Portal:

sudo cz-memcachedump

The output lists: client id, username, status, DNS servers, and DNS domains.

Because this is a live cache view, results may be incomplete on the first run. Run the command more than once if needed.

Find the username and verify that the DNS servers are correct.


Check access issues

At this point, assume DNS is working correctly. If the user still cannot access protected hosts, use the checks below.

User access rights

Only assigned policies provision entitlements to the user. Use dns:// syntax for the DNS resolver or *.domain.com syntax for the DNS forwarder.

Download the client logs from the client's About screen. In log.log, verify the following:

  • The user has the required entitlements:

Info : Entitlements for 'Site': app1, app2, app3

  • Any conditions have been resolved successfully:

Info : Activate <name> remedy.
Info : Sending OTP pin to controller. RemedyProperties: 'ClaimSuffix <name>, ProviderId <ssid>, EntitlementName <Entitlement>, State: '', Timeout: '0'
Info : Successfully got a new claims token with OTP for <name>.

Routes

The client’s About screen displays the assigned IP address of the tun adapter. Use this to verify which IP addresses route through the tunnel.

Windows: Run netstat -rn and verify that the network destination routes to the correct interface (tun IP).

macOS: Run ifconfig and find the network interface name (such as utun2) associated with the tun IP. Then run netstat -rn and verify that the destination routes to the correct network interface.

You can also check routing in the client logs. Download the logs from the About screen and open driver.log.

Windows: Info : [Site] route-add[37 10.10.10.10/32]: OK

macOS: Info : [Site] Running 'route -n add -inet -host 10.10.10.10 -interface utun2'

NOTE

When using the DNS forwarder, routes are written only after access has been attempted.

Portal web clients

Troubleshooting Portal access requires the user's client ID. You can obtain the client ID from cz-memcachedump (covered in the DNS section above), from the live session information (ClientID field), or from cz-webd.log.

Option 1: On the Portal, run:

sudo nc -U /var/run/cz-webd/cz-webd-admin.socket

Then enter:

sessions list

Example output:

ShortID: vvvvvv ClientID: xxxx SrcIP: 1.2.3.4 Dn: CN=yyyyyy,CN=<username>,OU=zzzzzz SignedIn: true

Option 2: Open cz-webd.log in the Portal logs. Search for CN=<user> and find the most recent matching entry:

INFO [session][clientID=xxxx][cookie=wwww][dn=CN=yyyyyy,CN=<username>,OU=zzzzzz][loggedIn=true][srcIP=1.2.3.4] Client connected

Once you have the client ID, open cz-webclient@xxxx.log. This file is the log record for that user's web client and contains information similar to the standard client logs.

Gateway session

If the client-side checks look correct, check the traffic through the Gateway to the protected host.

In the admin UI dashboard, go to the session details for the user. Select the Site where the protected host resides and locate the entitlement. This view shows live information from the Gateway the user is currently connected to. Conditions display in green when satisfied and in red when not yet met. The firewall rules include the port type and hosts.

Access status for various corporate services at Gothenburg site, highlighting access conditions.

For more session details, run the following on the Gateway:

vpn-logcat -S today -u <username> list

This lists all sessions for <username> today. Select the session of interest based on the time, then run:

vpn-logcat -S today -u <username> session <time>

This filters the logs to display only the audit logs for <username> in chronological order.

For more specific information from the VPN daemon, run:

vpn-console --search-user <username>.

The output includes used entitlements, unused entitlements, and URL access details.

If URL access (HTTP up action type) is in use, run the following for more information from NGINX:

curl -v http://127.0.0.1:9202/url_access/print_user_<tun IP>. T

Obtain the tun IP from the client’s About screen or from the user's session details in the system claims.


Protected host health

In the admin UI dashboard, go to the session details for the user. The global details at the top show the number of unreachable hosts the user has encountered. Select the Site where the problematic protected host resides to see the unreachable host count for that Site.

User Gateway statistics for a Site, including bytes read and written over IPv4.

If the user has experienced unreachable hosts, see App Health Reports for more details.