in modern times, private companies and intelligence agencies collect more and more data on our daily living, the use of your smartphones and want to know where we are, what we eat, what we buy, how we spend our free time, and much more. those companies use these data for any kind of marketing, like personalised advertising, and even individual pricing. yes, you probably spend more money on the exact same product, than your neighbour does. because of all this, the numbers of people using vpn services to improve their online privacy and security is growing.
in this blog post, i will guide you through the basic steps and some more complex on demand rules setting up vpn on demand using a .mobileconfig configuration profiles for iphone and mac
the basic structure
first of all, the configuration file for vpn on demand is a plain text document, with xml markup. to create one, just open up your favourite text editor, and save a new file with extension .mobileconfig. see also the official configuration profile reference.
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
...
</array>
<!-- Universally unique identifier and payload information for the configuration file itself -->
<key>PayloadDisplayName</key>
<string>VPN OnDemand</string>
<key>PayloadIdentifier</key>one.nerd.vpn.a4303bdf-0857-4f61-8eac-76d6e8a81fbf</string>
<key>PayloadRemovalDisallowed</key>
<false/>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>4-712c9be856fe</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>
there are some information already propagated. do you see those payload information? they are mandatory to let the system (ios/macos) correctly identify the configuration profile's contents once imported. feel free to change PayloadDisplayName, PayloadIdentifier and PayloadUUID, but keep in mind to use different uuids for different configuration profiles. read more about uuids on wikipedia.
adding vpn configuration
using the above structure, the actual vpn configuration like vpn type, server settings, and login credentials need to be added. this example configuration profile uses ipsec for an average amount of security and speed (ipsec needs to be supported by your vpn provider and some information may vary). now back to your configuration profile:
<key>PayloadContent</key>
<array>
<dict>
<!-- Configuration for VPNType "IPSec" -->
<key>IPSec</key>
<dict>
<!-- AuthenticationMethod can either be "SharedSecret" or "Certificate" -->
<!-- Configuration for AuthenticationMethod "SharedSecret" -->
<key>AuthenticationMethod</key>
<string>SharedSecret</string>
<key>LocalIdentifierType</key>
<string>KeyID</string>
<!-- RemoteAdress should be the VPN server's IP or DNS name -->
<key>RemoteAddress</key>
<string>remote.example.com</string>
<!-- SharedSecret must be base64 encoded -->
<key>SharedSecret</key>
<data>YXJlZCBTZWNyZXQgSGVyZQ==</data>
<!-- XAuth Configuration -->
<key>XAuthEnabled</key>
<integer>1</integer>
<!-- XAuthName is the login name used for authentication -->
<!-- Remove the following two lines if you don't want the username to be stored in this file -->
<key>XAuthName</key>
<string>Insert Username Here</string>
<!-- XAuthPassword is the password used for authentication -->
<!-- Remove the following two lines if you don't want the password to be stored in this file -->
<key>XAuthPassword</key>
<string>Insert Password Here</string>
<!-- Enabling OnDemand – This can be toggled on/off via System Settings/Network [macOS] and Settings/VPN [iOS] -->
<key>OnDemandEnabled</key>
<integer>1</integer>
<!-- OnDemand Rules -->
<key>OnDemandRules</key>
<array>
...
</array>
</dict>
<!-- IPv4 Configuration -->
<!-- Set OverridePrimary to "1" to send all traffic through the VPN interface -->
<key>IPv4</key>
<dict>
<key>OverridePrimary</key>
<integer>1</integer>
</dict>
<!-- Payload information for this configuration-->
<key>PayloadDescription</key>
<string>VPN OnDemand Settings</string>
<key>PayloadDisplayName</key>
<string>VPN</string>
<!-- Universally unique identifier and some more information for the configuration -->
<key>PayloadIdentifier</key>
<string>9cbe-631bd9be35f6</string>
<key>PayloadType</key>
<string>one.nerd.vpn</string>
<key>PayloadUUID</key>
<string>f-55cd6bd8374c</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>Proxies</key>
<dict>
<key>HTTPEnable</key>
<integer>0</integer>
<key>HTTPSEnable</key>
<integer>0</integer>
</dict>
<key>UserDefinedName</key>
<string>VPN OnDemand</string>
<key>VPNType</key>
<string>IPSec</string>
</dict>
</array>
these information needs to be changed:
RemoteAddress should match your vpn provider's server urlSharedSecret is a base64 encoded string (ask your provider for that string), use duckduckgo to encode YourSharedSecretXAuthName is your usernameXAuthPassword is your password
if you prefer not to store the login credentials inside the configuration file, you can easily remove those lines. when importing the profile to your iphone or mac, you will be asked to provide those once.
on demand rules
the on demand rules, is a set (dictionary) of different rules. this dictionary is being used to check the current network configuration. the first rule which matches is being used. based on the action described for the matching rule (action value in brackets), a vpn connection can either be established (Connect), disconnected (Disconnect), evaluated for each connection attempt (EvaluateConnection), or should remain as is (Ignore). this is the structure of an on demand rule:
<dict>
<key>Action</key>
<string>Connect</string>
</dict>
this simple rule--which always matches--consists only of a key (Action) and a value (Connect). to add more spice we can use InterfaceTypeMatch (allowed values are Cellular, Ethernet, and WiFi).
some basic on demand rules for different network interfaces
let's create rules to always connect on wifi and cellular networks, but disconnect on ethernet. since we can define two rules for cellular and wifi, we can safely skip adding InterfaceTypeMatch to the third rule. the resulting code for this scenario is this:
<dict>
<key>Action</key>
<string>Connect</string>
<key>InterfaceTypeMatch</key>
<string>Cellular</string>
</dict>
<dict>
<key>Action</key>
<string>Connect</string>
<key>InterfaceTypeMatch</key>
<string>WiFi</string>
</dict>
<dict>
<key>Action</key>
<string>Disconnect</string>
</dict>
only establish a vpn connection when connected to certain networks
let's say, you want vpn on demand for every new wifi network you connect to, but don't want to have it established on the two wifi networks you have at home and at work. this can be done using the key SSIDMatch. the rule will then look like this:
<dict>
<key>Action</key>
<string>Disconnect</string>
<key>InterfaceTypeMatch</key>
<string>WiFi</string>
<key>SSIDMatch</key>
<array>
<!-- List one or more WiFi networks -->
<string>My Private Home Network</string>
<string>Company WiFi SSID</string>
</array>
</dict>
<dict>
<key>Action</key>
<string>Connect</string>
<key>InterfaceTypeMatch</key>
<string>WiFi</string>
</dict>
reminder: the first rule which matches will be used. therefor it's important to have the rules in the order shown above. if it would be the other way round, the more complex rule to disconnect for certain wifi networks will never be used.
evaluate connection: vpn on demand for specific domains only
maybe you want to establish a vpn connection for some domains only. or you want to make sure, that accessing to those domains will always trigger a vpn connection. the rules for this look like this:
<dict>
<key>Action</key>
<string>EvaluateConnection</string>
<key>ActionParameters</key>
<array>
<dict>
<key>Domains</key>
<array>
<string>example.com</string>
</array>
<key>DomainAction</key>
<string>ConnectIfNeeded</string>
</dict>
</array>
</dict>
now, let me explain what all that means. EvaluateConnection tells the operating system to look for ActionParameters, a list (array) of dictionaries similar to the on demand rules. allowed keys for these dictionaries are:
Domains, required: an array of domains that trigger the evaluationDomainAction, required: ConnectIfNeeded or NeverConnect--self-explanatoryRequiredDNSServers, optional: array of ip addresses for resolving domain names, might be necessary for your company's internal urlsRequiredURLStringProbe, optional: a url to probe, if no connection code is received, a vpn connection will be established
more complex rules
if you want to, you can even merge EvaluateConnection with InterfaceTypeMatch and SSIDMatch:
<dict>
<key>Action</key>
<string>EvaluateConnection</string>
<key>InterfaceTypeMatch</key>
<string>WiFi</string>
<key>SSIDMatch</key>
<array>
<!-- List one or more WiFi networks -->
<string>Company WiFi SSID</string>
</array>
<key>ActionParameters</key>
<array>
<dict>
<key>Domains</key>
<array>
<string>example.com</string>
</array>
<key>DomainAction</key>
<string>ConnectIfNeeded</string>
<key>RequiredURLStringProbe</key>
<string>https://internal.yourawesomecompany.com</string>;
</dict>
</array>
</dict>
feel free to add as many dictionaries to your OnDemandRules array, until all your wishes and needs are mapped.
appendix, or: ConnectIfNeeded not working
what i found out is, that in some circumstances my device does not establish a vpn connection for certain domain, even when i am sure, the EvaluateConnection rule is being used. therefor, i created a workaround (a nice little script on my server) to help me out.
it takes an input ip address or range of ip addresses, then compares it to the connecting client's ip address and sends back a specific http status code. if the client's ip address is equal to the input or is within the range of ip addresses provided, that status code will be HTTP/1.1 200 Ok. if the client's ip can not be described using the input, status code HTTP/1.1 404 Not Found will be returned.
using this and knowing the possible ip addresses your vpn provider assigns, we can use the RequiredURLStringProbe key to make sure, a vpn connection will always be established when connecting to a certain domain, even if resolving the domain name works. the code snipped will look like this:
<dict>
<key>Domains</key>
<array>
<string>nerd.one</string>
</array>
<key>DomainAction</key>
<string>ConnectIfNeeded</string>
<key>RequiredURLStringProbe</key>
<string>https://example.com/12.34.56.78-87</string>
</dict>
assuming the possible ip addresses the vpn provider assigns is from 12.34.56.78 to 12.34.56.87, the string to use will be https://example.com/12.34.56.78-87. if the range is bigger than that, it's possible to change the input to something different. all this would be valid input:
single ip addresses, i.e.:
- 95.143.172.196
- 95.143.172.240
a range or subnet of ip addresses, i.e.:
- 95.143.172.140-250
- 95.143.172.0-255
- 95.143.171-172.0-255
- 95.143.0-255.50-100
feel free to open that url in your browser and check different input, until you are happy with your input ip or range of ip addresses.
a sample configuration file
a sample configuration file is contributed by nerd one (see original article on https://nerd.one/vpn-on-demand-configuration-profiles-for-ios-and-macos-explained/)
