Skip to main content

How can we help you?

Search

help Knowledge Base
forum Community
checklist Release Notes
event Events

iOS Roaming Client deployment guide

Minetta Gould
  • Updated

    In this article

Network administrators with admin permissions or higher use this article to install the iOS Roaming Client on managed iPhone and iPad devices through a mobile device management (MDM) provider. Manual installation via Apple Configurator 2 is not supported.

The iOS Roaming Client operates a VPN that forwards DNS queries to DNSFilter without routing other traffic through DNSFilter servers. This feature is available on Plus and Enterprise plans. The agent checks in every 5 minutes to detect available updates and identify offline agents.

Assign local domains before installing the iOS Roaming Client to avoid internal resource connection interruptions.

Install the iOS Roaming Client

MDM platforms vary in how they manage and deploy apps. Consult the MDM provider's documentation for platform-specific steps.

The iOS agent applies MDM settings first. If a setting in the DNSFilter dashboard conflicts with the MDM configuration, the MDM setting applies.

  1. From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients
  2. Select Install Roaming Client
  3. Select the Site
  4. Select iOS
  5. Copy the Site Key
  6. Enable Auto Registration if applicable

  7. Download the .mobileconfig file

    The profile also installs the root certificates required to display the block page on HTTPS websites. Certificates delivered by MDM are trusted automatically. No end-user prompt or manual trust step is required.

    ✍️ The dnsfilter.mobileconfig profile has been updated to include the DNSFilter Root CA G1 certificate. If you have already deployed this profile to your fleet, redeploy the updated file to avoid certificate trust issues after upgrading to iOS Roaming Client v1.4.5.

  8. Replace the REPLACE_WITH_SITE_KEY value with the Site Key. Optional settings use REPLACE_WITH_* placeholders, each with an inline comment naming the key – fill in or remove the optional ones before deploying.

  9. Add any MDM-specific information such as permissions, groups, or licensing

    To pass additional configuration to the agent via MDM, edit or remove any of the following optional keys in the ProviderConfiguration block in the .mobileconfig file:

    <key>ProviderConfiguration</key>
  <dict>
    <!-- Required. From the DNSFilter dashboard: Deployments > Roaming Clients. -->
    <key>site_key</key>
    <string>REPLACE_WITH_SITE_KEY</string>
    <!-- Optional. Device name shown in the dashboard. Setting this value is recommended. -->
    <key>host_name</key>
    <string>REPLACE_WITH_HOST_NAME</string>
    <!-- Optional. User assigned to this device. Leave blank if not tracking users. -->
    <key>user_name</key>
    <string>REPLACE_WITH_USER_NAME</string>
    <!-- Optional. Comma-separated tags applied to the device. Leave blank for none. -->
    <key>dashboard_tags</key>
    <string>REPLACE_WITH_DASHBOARD_TAGS</string>
    <!-- Optional. Use DNS over TLS to the DNSFilter resolvers. -->
    <key>dns_over_tls_enabled</key>
    <true/>
  </dict>
    Key Description
    site_key Required. The Site Key from the DNSFilter dashboard
    host_name Sets the Client Name as it appears in the DNSFilter dashboard. Accepts MDM device variables such as {{serial_number}}. Setting host_name is recommended. Leaving it blank registers the device without a Client Name and causes the device's identity to change on every app reinstall, producing duplicate Roaming Client entries in the dashboard.
    user_name Populates the Last Logged in User field in the DNSFilter dashboard. Only transmitted if the end user grants iCloud account access on the device. If permission is not granted, the field remains unpopulated
    dashboard_tags Applies one or more tags to the agent in the DNSFilter dashboard. Separate multiple tags with commas
    dns_over_tls_enabled Controls whether DNS over TLS is used to communicate with DNSFilter resolvers. Set to false to prefer standard DNS. DNS over TLS remains available as a fallback. Values set via MDM are not enforced and can be changed by end users in the app's Settings screen.

    Device-specific variable syntax such as {{serial_number}} and {{icloud_username}} differs across MDM providers. Verify the correct variable syntax in the MDM provider's documentation before deploying. See examples for Microsoft Intune and Addigy.

    After the updated profile reaches the device, the Roaming Client applies the change automatically within a few minutes. No reboot or app launch is required. How long the profile takes to reach the device depends on the MDM platform.

  10. Create an MDM profile and upload the file
  11. Download the DNSFilter Roaming Client from the App Store
  12. Push the app to devices

Once the app is pushed, devices register in the DNSFilter dashboard and the filtering policy associated with the Site applies.

DNS over TLS (DoT) default behavior

DoT is enabled by default on iOS devices and may cause DNS conflicts in some environments. To prefer standard DNS, set the dns_over_tls_enabled key that ships in the profile to false:

<key>dns_over_tls_enabled</key>
     <false/>

When set to false, the client prefers standard DNS; DNS over TLS remains available as a fallback.

✍️ Values set via MDM for dns_over_tls_enabled are not enforced. End users can change them in the app's Settings screen. If a deployed setting does not persist, the end user may have changed it on the device.

Additional MDM-specific deployment guides are available in the DNSFilter Help Center, including examples for Jamf Pro and Intune.

Related content

Comments

4 comments

Date Votes
  • Lokken Wong

    Thank you for providing an alternative solution. 
    I have been waiting for a long time to get this resolved!

    0
  • Minetta Gould Community Team DNSFilter Staff

    So glad this update helps you out, Lokken Wong ! The team was definitely excited to get this fix into everyone's hands, so they appreciate the feedback. 

    0
  • Avery Knox

    I have some questions about this article.  The Avoid filtering interruptions by encrypting DNS (DoT) article says:

    With iOS agent version 1.0.8 and higher, DoT is enabled by default, no longer requiring the end-user to configure manually.

    But at the beginning of this article, it mentions disabling DoT, almost as it needs to be done in preparation for installation. To me, that shouldn't be at the top, or perhaps the article should discuss why we would ever want to disable DoT.

    0
  • Minetta Gould Community Team DNSFilter Staff

    Thanks for the feedback! The option to disable DoT is available because some IT admins prefer the option for compatibility with internal DNS setups, easier troubleshooting, or better visibility into DNS traffic for security tools. It’s all about giving admins flexibility based on their network needs. 

    We make recommendations and set defaults, but want to make sure our customers are aware of default updates and changes, hence the callout at the top of the process steps like you see here: DoT wasn't enabled by default until recently. 

    Hope this helps! 

    0

Please sign in to leave a comment.