]>
Commit | Line | Data |
---|---|---|
9d5aa1d8 RC |
1 | # Installing WireGuard tunnels using Configuration Profiles |
2 | ||
3 | WireGuard configurations can be installed using Configuration Profiles | |
4 | through .mobileconfig files. | |
5 | ||
6 | ### Top-level payload entries | |
7 | ||
8 | A .mobileconfig file is a plist file in XML format. The top-level XML item is a top-level payload dictionary (dict). This payload dictionary should contain the following keys: | |
9 | ||
10 | - `PayloadDisplayName` (string): The name of the configuration profile, visible when installing the profile | |
11 | ||
12 | - `PayloadType` (string): Should be `Configuration` | |
13 | ||
14 | - `PayloadVersion` (integer): Should be `1` | |
15 | ||
16 | - `PayloadIdentifier` (string): A reverse-DNS style unique identifier for the profile file. | |
9d5aa1d8 RC |
17 | If you install another .mobileconfig file with the same identifier, the new one |
18 | overwrites the old one. | |
19 | ||
20 | - `PayloadUUID` (string): A randomly generated UUID for this payload | |
21 | ||
22 | - `PayloadContent` (array): Should contain an array of payload dictionaries. | |
9d5aa1d8 RC |
23 | Each of these payload dictionaries can represent a WireGuard tunnel |
24 | configuration. | |
25 | ||
26 | Here's an example .mobileconfig with the above fields filled in: | |
27 | ||
fbac282b | 28 | ```xml |
9d5aa1d8 RC |
29 | <?xml version="1.0" encoding="UTF-8"?> |
30 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> | |
31 | <plist version="1.0"> | |
32 | <dict> | |
33 | <key>PayloadDisplayName</key> | |
34 | <string>WireGuard Demo Configuration Profile</string> | |
35 | <key>PayloadType</key> | |
36 | <string>Configuration</string> | |
37 | <key>PayloadVersion</key> | |
38 | <integer>1</integer> | |
39 | <key>PayloadIdentifier</key> | |
40 | <string>com.your-org.wireguard.FCC9BF80-C540-44C1-B243-521FDD1B2905</string> | |
41 | <key>PayloadUUID</key> | |
42 | <string>F346AAF4-53A2-4FA1-ACA3-EEE74DBED029</string> | |
43 | <key>PayloadContent</key> | |
44 | <array> | |
45 | <!-- An array of WireGuard configuration payload dictionaries --> | |
46 | </array> | |
47 | </dict> | |
48 | </plist> | |
fbac282b | 49 | ``` |
9d5aa1d8 RC |
50 | |
51 | ### WireGuard payload entries | |
52 | ||
53 | Each WireGuard configuration payload dictionary should contain the following | |
54 | keys: | |
55 | ||
56 | - `PayloadDisplayName` (string): Should be `VPN` | |
57 | ||
58 | - `PayloadType` (string): Should be `com.apple.vpn.managed` | |
59 | ||
60 | - `PayloadVersion` (integer): Should be `1` | |
61 | ||
62 | - `PayloadIdentifier` (string): A reverse-DNS style unique identifier for the WireGuard configuration profile. | |
63 | ||
64 | - `PayloadUUID` (string): A randomly generated UUID for this payload | |
65 | ||
66 | - `UserDefinedName` (string): The name of the WireGuard tunnel. | |
9d5aa1d8 RC |
67 | This name shall be used to represent the tunnel in the WireGuard app, and in the System UI for VPNs (Settings > VPN on iOS, System Preferences > Network on macOS). |
68 | ||
69 | - `VPNType` (string): Should be `VPN` | |
70 | ||
71 | - `VPNSubType` (string): Should be set as the bundle identifier of the WireGuard app. | |
72 | ||
73 | - iOS: `com.wireguard.ios` | |
74 | - macOS: `com.wireguard.macos` | |
75 | ||
76 | - `VendorConfig` (dict): Should be a dictionary with the following key: | |
77 | ||
78 | - `WgQuickConfig` (string): Should be a WireGuard configuration in [wg-quick(8)] / [wg(8)] format. | |
9d5aa1d8 RC |
79 | The keys 'FwMark', 'Table', 'PreUp', 'PostUp', 'PreDown', 'PostDown' and 'SaveConfig' are not supported. |
80 | ||
81 | - `VPN` (dict): Should be a dictionary with the following keys: | |
82 | ||
83 | - `RemoteAddress` (string): A non-empty string. | |
9d5aa1d8 RC |
84 | This string is displayed as the server name in the System UI for |
85 | VPNs (Settings > VPN on iOS, System Preferences > Network on macOS). | |
86 | ||
87 | - `AuthenticationMethod` (string): Should be `Password` | |
88 | ||
89 | Here's an example WireGuard configuration payload dictionary: | |
90 | ||
fbac282b JD |
91 | ```xml |
92 | <!-- A WireGuard configuration payload dictionary --> | |
93 | <dict> | |
94 | <key>PayloadDisplayName</key> | |
95 | <string>VPN</string> | |
96 | <key>PayloadType</key> | |
97 | <string>com.apple.vpn.managed</string> | |
98 | <key>PayloadVersion</key> | |
99 | <integer>1</integer> | |
100 | <key>PayloadIdentifier</key> | |
101 | <string>com.your-org.wireguard.demo-profile-1.demo-tunnel</string> | |
102 | <key>PayloadUUID</key> | |
103 | <string>44CDFE9F-4DC7-472A-956F-61C68055117C</string> | |
104 | <key>UserDefinedName</key> | |
105 | <string>Demo from MobileConfig file</string> | |
106 | <key>VPNType</key> | |
107 | <string>VPN</string> | |
108 | <key>VPNSubType</key> | |
109 | <string>com.wireguard.ios</string> | |
110 | <key>VendorConfig</key> | |
111 | <dict> | |
112 | <key>WgQuickConfig</key> | |
113 | <string> | |
114 | [Interface] | |
115 | PrivateKey = mInDaw06K0NgfULRObHJjkWD3ahUC8XC1tVjIf6W+Vo= | |
116 | Address = 10.10.1.0/24 | |
117 | DNS = 1.1.1.1, 1.0.0.1 | |
118 | ||
119 | [Peer] | |
120 | PublicKey = JRI8Xc0zKP9kXk8qP84NdUQA04h6DLfFbwJn4g+/PFs= | |
121 | Endpoint = demo.wireguard.com:12912 | |
122 | AllowedIPs = 0.0.0.0/0 | |
123 | </string> | |
124 | </dict> | |
125 | <key>VPN</key> | |
126 | <dict> | |
127 | <key>RemoteAddress</key> | |
128 | <string>demo.wireguard.com:12912</string> | |
129 | <key>AuthenticationMethod</key> | |
130 | <string>Password</string> | |
131 | </dict> | |
132 | </dict> | |
133 | ``` | |
9d5aa1d8 | 134 | |
61f5e017 JD |
135 | ### Caveats |
136 | ||
137 | Configurations added via .mobileconfig will not be migrated into keychain until the WireGuard application is opened once. | |
138 | ||
ba1c968c JD |
139 | [wg-quick(8)]: https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8 |
140 | [wg(8)]: https://git.zx2c4.com/wireguard-tools/about/src/man/wg.8 |