--- title: "Migrating DNS settings" slug: "migrating-dns-settings-v7-0" description: "Migrate your DNS settings in AppGate ZTNA systems with auto-configuration or manually, and validate their functionality post-migration." tags: ["DNS Configuration", "DNS Setting Migration"] updated: 2026-06-05T19:17:37Z published: 2026-06-05T19:17:37Z canonical: "support.appgate.com/migrating-dns-settings-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Migrating DNS settings Configuring DNS settings within identity providers (IdPs) has been deprecated in AppGate ZTNA systems. This section describes how to migrate these settings using auto-configuration or manually, and how to confirm your DNS settings are working after migration. These steps assume you already have the necessary entitlements in place. --- ## Migrating using auto-configuration Users with one IdP and DNS configuration can migrate their settings to their Site configuration. To migrate your settings: 1. Go to **Sites** (System > Sites). 2. Select the Site that the DNS server is on, which would be the Site that the existing entitlement is using. 3. In the **DNS Resolving** section, add the settings from your IdP to the fields provided: > [!NOTE] > NOTE > > If you previously used search domains instead of match domains, you do not have to move them over unless you want to use your DNS server for a specific domain. Search domains are a Windows-specific legacy feature to support short domain resolution.To migrate using a search domain, contact [AppGate Support](/v1/docs/contact-support). - Click **+Add** under *DNS Servers* to add the address of your server. - Select *Enable auto-configuration* and click **+Add** next to *Match Domains*. - Add the domain of your server to the *Domain* field. If you have multiple match domains, use the copy-paste function to copy them from the IdP and paste them here. If you want to use your DNS server for every domain, enter `default` in this field. - Click **Save**. 4. Return to your IdP and select it to edit the settings. 5. Remove the DNS settings and click **Save.** --- ## Validating the migration using auto-configuration If you used auto-configuration to migrate your DNS settings, confirm they are working by completing the following steps: 1. Wait for clients to connect to the system. 2. Go to **Active Sessions** (Usage > Active Sessions). 3. Select your session. 4. In the **Active Session Details** page, the automatic entitlement for the DNS resolver appears in the **Entitlements** tab. 5. Follow the steps in [Validating the manual DNS policy migration](/v1/docs/migrating-dns-settings-v7-0#validating-the-manual-dns-policy-migration). Once this is complete, you no longer need the entitlement to the DNS server or the access policy for that entitlement. > [!NOTE] > NOTE > > For these settings to take effect, users must obtain new entitlement tokens. Go to **Active Sessions** (Usage > Active Sessions) or **Registered Devices** (Usage > Registered Devices) and select *Renew Tokens*. --- ## Migrating DNS settings manually with a DNS policy Several situations make auto-configuration a poor fit for migrating DNS settings. For example: - If you have multiple IdPs with different DNS configurations, create a DNS policy for each IdP and remove the DNS settings from the IdPs. - If you have a single IdP or multiple IdPs with the same DNS configuration, but you have DNS policies already. For instance, one that allows one user or group of users access to a resource, and a second policy for a different group of users to a different resource. If the existing DNS policies already cover all your users, then you do not need to alter the DNS settings in the policies. If you have DNS policies that cover only some of your users, with IdP settings for the remainder. In that case you will need to create a new policy to cover that remainder. - If you have a single IdP or multiple IdPs with the same DNS configuration, and *Block local DNS requests* enabled in the IdP, create DNS policies with those settings and select *Block local DNS requests* in the policy instead. To configure DNS settings in a policy: 1. Go to **Policies** (Access > Policies). 2. Create a new DNS policy or select one to edit. 3. In the **Edit Policy** page, go to **DNS Settings**. 4. Add the entitlement that allows traffic to the DNS server (same as for IDP DNS). 5. Select **+Add** next to **DNS Configurations** to add your match domains and DNS servers. Enter `default` in the ***Match Domain*** field if you want to use your DNS server for every domain. > [!NOTE] > NOTE > > If you previously used search domains instead of match domains, you do not have to move them over unless you want to use your DNS server for a specific domain. Search domains are a Windows-specific legacy feature to support short domain resolution.To migrate using a search domain, contact [AppGate Support](/v1/docs/contact-support). 1. Optionally, check the ***Block local DNS requests*** checkbox. 2. Complete any other configuration fields and click **Save**. --- ## Validating the manual DNS policy migration To confirm the DNS settings migration was successful: 1. Wait for clients to connect to the system. 2. If you are using the built-in LogServer OpenSearch dashboard, navigate to **Audit Logs** (Usage > Audit Logs). 3. In your OpenSearch dashboard, select **Open** from the top menu and select *Controller Audit logs*. 4. In the **event_type** column, look for items with the “authorization_succeeded” event type. 5. Select a result with that event type. In the **Field** column, scroll to find “dns_settings.domain” and “dns_settings.servers” and confirm that the domain and servers originate from your DNS policies. 6. If dns_settings.domain and dns_settings.servers are empty, the migration was unsuccessful. If some users have content in those fields but other users do not, the migration was also unsuccessful. > [!NOTE] > NOTE > > Some users may not have access to **Audit Logs** if they lack privileges for the built-in LogServer OpenSearch dashboard or are using their own SIEM through the LogForwarder. When you have confirmed that your migration is successful: 1. Go to **Identity Providers** (Identity > Identity Providers). 2. Remove the DNS settings from the IdPs from which they were migrated and click **Save**.