In this article
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 five minutes to detect available updates and identify offline agents.
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.
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. See the MDM provider's documentation for platform-specific steps. Additional deployment guides are available in the DNSFilter Help Center, including examples for Jamf Pro and Intune.
The iOS agent applies MDM settings first. If a setting in the DNSFilter dashboard conflicts with the MDM configuration, the MDM setting applies.
To install the iOS Roaming Client:
- From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients.
- Select Install Roaming Client.
- Select the Site.
- Select iOS.
- Copy the Site Key.
- Enable Auto Registration if applicable.
-
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.
Caution: The
dnsfilter.mobileconfigprofile has been updated to include the DNSFilter Root CA G1 certificate. If this profile was already deployed to the fleet, redeploy the updated file to avoid certificate trust issues after upgrading to iOS Roaming Client v1.4.5. -
Replace the
REPLACE_WITH_SITE_KEYvalue 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.For Shared iPad deployments,
host_nameis required. See Deploy to Shared iPad. -
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
ProviderConfigurationblock in the.mobileconfigfile. The file includes inline comments for each key. The following table describes each key in full.<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_keyRequired. The Site Key from the DNSFilter dashboard host_nameSets the Client Name as it appears in the DNSFilter dashboard. Accepts MDM device variables such as {{serial_number}}. Settinghost_nameis 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 dashboarduser_namePopulates 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_tagsApplies one or more tags to the agent in the DNSFilter dashboard. Separate multiple tags with commas dns_over_tls_enabledControls whether DNS over TLS is used to communicate with DNSFilter resolvers. Set to falseto 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 screenDevice-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.
- Create an MDM profile and upload the file.
- Download the DNSFilter Roaming Client from the App Store.
- Push the app to devices.
After the app is pushed, devices register in the DNSFilter dashboard and the filtering policy associated with the Site applies.
Deploy to Shared iPad
On Apple Shared iPad, iPadOS clears each user's app data when they sign out. Each new session then registers as a new Roaming Client unless the profile supplies a value that is unique to the physical device.
For Shared iPad deployments, host_name is required. In the downloaded .mobileconfig file, replace REPLACE_WITH_HOST_NAME with the MDM's device serial number variable before uploading the file to the MDM. Each iPad then reports the same identity across every user session.
For example, in Mosyle:
<key>host_name</key> <string>%SerialNumber%</string>
Other MDMs use their own variable syntax for the serial number. See the MDM provider's documentation for profile variables, and confirm any setting required to enable variable substitution in uploaded custom profiles.
Remove duplicate records
If Shared iPads were deployed before host_name was configured and already have duplicate records, use Clean Up to remove them. From the DNSFilter dashboard, navigate to Deployments and select Roaming Clients. For details, see Clean Up in the Manage Roaming Client settings article.
DNS over TLS default behavior
DNS over TLS (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.
Note: Values set through 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.
Comments
4 comments
Thank you for providing an alternative solution.
I have been waiting for a long time to get this resolved!
So glad this update helps you out, Lok ! The team was definitely excited to get this fix into everyone's hands, so they appreciate the feedback.
I have some questions about this article. The Avoid filtering interruptions by encrypting DNS (DoT) article says:
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.
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!
Please sign in to leave a comment.