WireGuard
Siri Shortcuts integration for iOS
Add support for Siri Shortcuts (and the Shortcuts app) for iOS.
Three intents have been implemented:
- GetPeers: get the list of peers' public keys in a specific tunnel. Is designed to be used in the Shortcuts app;
- UpdateConfiguration: update the configuration of a tunnel. At the moment, only allows updating peers' Endpoint. Is designed to be used in the Shortcuts app;
- SetTunnelStatus: activate and deactivate a tunnel. Is designed to be used in Shortcuts, with Siri and Siri Suggestions.
The configuration of the Intents Extension was done by looking at the configuration of the Network Extension.
Intents (actions) are fully functional on iOS 14.0+, I will test them on iOS 13 as soon as I can get a device with this iOS version since the Simulator is very limited in this case. Anyway, this integration does not alter the functionality of the app.
UPDATE 07/02/2022 Tested on iOS 12, donated Intents are working correctly (turn on and turn off tunnels). User configurable actions in the Shortcuts app are not available on this iOS version for third-party apps.
Thank you! This is a good solution if your WireGuard server is behind a daily changing public IP and you use dynDNS to update the IP (WG does not resolve endpoint domains after the tunnel has been enabled).
Thank you! This is a good solution if your WireGuard server is behind a daily changing public IP and you use dynDNS to update the IP (WG does not resolve endpoint domains after the tunnel has been enabled).
I needed this integration for the same reason basically: to update the Peers' Endpoint values that change often. On desktop, you can use wgctrl, but on iOS, there was no other way than to manually update the Endpoint field.
It all started with the great and detailed article WireGuard Endpoint Discovery and NAT Traversal using DNS-SD by Jordan Whited that I suggest you read if you need to reach a device behind NAT (or with a dynamic IP, without using third-party services).
To port Whited's solution to iOS, I will also release a very simple (free) app that will take care of getting updated Peers' Endpoints from your server. This
To port Whited's solution to iOS, I will also release (for free) a very simple app that will take care of getting the updated Peers' Endpoint from your server. It will integrate with Wireguard through the Shortcuts app and will be released as soon as the Wireguard update with Shortcuts integration will be available.
Thank you! This is a good solution if your WireGuard server is behind a daily changing public IP and you use dynDNS to update the IP (WG does not resolve endpoint domains after the tunnel has been enabled).
I needed this integration for the same reason basically: to update the Peers' Endpoint values that change often. On desktop, you can use wgctrl, but on iOS, there was no other way than to manually update the Endpoint field.
It all started with the great and detailed article WireGuard Endpoint Discovery and NAT Traversal using DNS-SD by Jordan Whited that I suggest you read if you need to reach a device behind NAT (or with a dynamic IP, without using third-party services). To port Whited's solution to iOS, I will also release a very simple (free) app that will take care of getting updated Peers' Endpoints from your server. This To port Whited's solution to iOS, I will also release (for free) a very simple app that will take care of getting the updated Peers' Endpoint from your server. It will integrate with Wireguard through the Shortcuts app and will be released as soon as the Wireguard update with Shortcuts integration will be available.
That sounds very nice! When do you think the update will be available?
I don’t know when the update will be available: the implementation is complete and ready to be merged, we now have to wait for the maintainers to review the changes, build the app and submit the update to App Store!
Are you meant to send PRs here? The official repo is at https://git.zx2c4.com/wireguard-apple, but I don't see a clear way of submitting patches there
Are you meant to send PRs here? The official repo is at https://git.zx2c4.com/wireguard-apple, but I don't see a clear way of submitting patches there
Ways to contribute are listed on the WireGuard website and I've done whatever needed to be done, in fact, the changes are already published in the main repository, in the dedicated branch. They just need to be merged into the main branch, but I think this can be done by @zx2c4 only.
This is a great addition! I sure hope it gets merged. I don’t know of any other VPN client on iOS with this level of Shortcut integration.
Update 23/02/2022, from maintainers:
There's quite a bit of iOS/macOS backlog. But I'll get to it (or [...] will) eventually.
It has been six months, I hope this gets merged. 👍🏼 It's very useful to have.
Since Apple is releasing a new framework for the integration with Siri and the Shortcuts app - App Intents - I think it makes sense to rewrite this integration with the new framework. Otherwise, we start supporting a new functionality with a framework that is almost deprecated.
Since Apple is releasing a new framework for the integration with Siri and the Shortcuts app - App Intents - I think it makes sense to rewrite this integration with the new framework. Otherwise, we start supporting a new functionality with a framework that is almost deprecated.
I know that they're [apple] still working on the new Framework with new features still to be added, but would this be a relatively quick deployment to production since some of the work appears to have already been done? Thanks!
Wondering why this is marked as a draft? Should I hold off reviewing this?
@zx2c4 Yes, I would like to reimplement the integration using the new AppIntents framework.
The biggest benefit is that we don’t need to open the app anymore to update the configuration because the code of App Intents can be in the Main App Target too.
Could we get it merged in its current state and then follow up later with a new version using the newer App Intents API? I've been waiting for the ability to connect to a VPN via a Siri Shortcut for years now and I feel it was right at our fingertips.
Seeing the demand for this feature, I'll try to take a look at this today.
Could we get it merged in its current state and then follow up later with a new version using the newer App Intents API? I've been waiting for the ability to connect to a VPN via a Siri Shortcut for years now and I feel it was right at our fingertips.
This can be done, but would add a lot of boilerplate code that is more or less already outdated.
Just an FYI, iOS 16.4 added a new Siri Shortcut action that lets you connect/disconnect VPN connections and it works perfect with the Wireguard client. You can pick exactly which profile to connect too.
Just an FYI, iOS 16.4 added a new Siri Shortcut action that lets you connect/disconnect VPN connections and it works perfect with the Wireguard client. You can pick exactly which profile to connect too.
Thank you for the heads up @noelhibbard! I missed this. I’ll check it out and eventually leave out the turn on/off action.
A request for an opinion from the community
Rewriting the Update Tunnel Configuration Intent, that is the one I personally needed the most to automatically update endpoints of the peers, I identified two possible solutions for the implementation. Both have pros and cons.
Solution 1
The configuration is passed to the action as a JSON object that has the peers public keys as object's keys and a nested dictionary with with the fields to update as value, like the following example:
{ "Peer1_Public_Key_(Base64)": { "Endpoint": "1.2.3.4:4321" },
"Peer1_Public_Key_(Base64)": { "Endpoint": "10.11.12.13:6789"} }
This can also be constructed using Dictionary object/actions in the Shortcuts app. The Shortcuts app will take care of converting it to a JSON object when used as input of a text field.
Pros:
- Only needs an action to update the configuration
- Shorter Shortcuts
Cons:
- Very easy to get JSON formatting wrong
- Not very intuitive for non-technical users
Demo - JSON input
https://user-images.githubusercontent.com/17525117/230432784-33b0d304-28ba-4d2d-a24f-f50924bed0c4.mov
Demo - Dictionary object input
https://user-images.githubusercontent.com/17525117/230433050-4bbd2528-0efa-428b-b085-bf5b02dc4dbf.mov
Solution 2
Each peer configuration is build using a dedicated action, and one or more of these configuration can be passed to the "Update Tunnel Configuration" action.
Pros:
- More error-prone than a JSON string
- Do not require knowledge about JSON format
Cons:
- Requires at least two action to update a Tunnel Configuration
- To update multiple peers, something like a for loop is needed where there is the "Build Peer Configuration" action and another action that adds the result to an list.
Demo - Update Tunnel Configuration with Custom Entity Builder
https://user-images.githubusercontent.com/17525117/230433924-fc4287ee-286d-4428-a285-b0f4c1c12c96.mov
If you have a preference between these two solutions:
- React with 🎉 to this comment for Solution 1 (JSON object / Dictionary)
- React with 🚀 to this comment for Solution 2 (dedicated action for Peer Configuration)
If you have further thoughts, just comment.
My vote would be for Solution 1. True, building JSON by hand is prone to typos but as you point out you can use a dict and convert that to JSON. I feel like most users of Siri Shortcuts and Wireguard are above average tech wise so building a JSON string wouldn't be much of a barrier.
Updates aren't atomic anyway, so multiple actions isn't a big deal, and adding an additional config syntax seems unnecessary. Let's keep it simple.
If you want to additionally have a wg setconf ...-like thing, then you should copy the semantics of that command exactly, including the config format, so that there also isn't an additional thing to learn. But that also seems a bit unnecessary.
So I think option 2 is fine.
There was some discussion about iOS itself removing the need for "turn on" and "turn off" actions. Two questions related to this:
- Are shortcut actions beyond "turn on" and "turn off" really desirable and will be used? Or is this programming for programming's sake? IOW, has iOS' new feature obliterated the need for this PR entirely?
- If not, depending on how iOS organizes actions, should we still add our own "turn on" and "turn off" actions, so that they're discovererable as grouped in with the other ones?
@zx2c4 I agree with your reasoning on the type of input.
An additional action (separate from the "Update Configuration" one) that takes the configuration file as an input like wg setconf ... does may be considered in the future.
- Are shortcut actions beyond "turn on" and "turn off" really desirable and will be used? Or is this programming for programming's sake? IOW, has iOS' new feature obliterated the need for this PR entirely?
I find them useful to fill the "gap" left by wgctrl that is missing on iOS. With these actions the user has a way to control the configuration in an automatized way. I have been using these actions for more than one year now to do NAT traversal on iOS with wgsd. If I needed them, probably some else need them too.
- If not, depending on how iOS organizes actions, should we still add our own "turn on" and "turn off" actions, so that they're discovererable as grouped in with the other ones?
WireGuard app's actions can be found in Shortcuts app under Apps > WireGuard while System's Set VPN action can be found under Apps > Settings (Device) and as part of the Scripting category. Therefore at the moment they appear in two different places. Having our own action would duplicate something that’s already there and is quite complete (it allows "Connect" / "Disonnect" / "Toggle" / "Set On Demand" / "Toggle On Demand"). On the other hand, it would allow the action to be executed from Siri without any additional setup by the user.
Here is a demo on iOS of the implementation am submitting for review
https://user-images.githubusercontent.com/17525117/231302823-cb7bf378-2da1-4ca7-a10f-fa810c6fc0e7.MP4
TheApp Intents are available and correctly working with macOS app too
Currently, the App Intents are localized in English only, however they are ready for localization in other languages since all the Strings are in AppIntents.strings file. It has been decided to keep a different file for AppIntents localization due to the nature of AppIntents that are separate from the rest of the app and to make it easier in the future to eventually move the AppIntents to a dedicated Extension.
@alessionossa Some of WireGuard iOS users are on versions lower than 16.4 due to certain compatibility reasons. Connect/Disconnect feature in this implementation would be a great boon for us!
@alessionossa Some of WireGuard iOS users are on versions lower than 16.4 due to certain compatibility reasons. Connect/Disconnect feature in this implementation would be a great boon for us!
@Marvur the framework used for the implementation is only available starting from iOS 16. Are there really big differences in compatibility between iOS 16.0 and iOS 16.4, considering they are in the same major release?
Anyway I think this PR is ready for review, and other Shortcuts actions can be discussed and implemented later.
@alessionossa Some of WireGuard iOS users are on versions lower than 16.4 due to certain compatibility reasons. Connect/Disconnect feature in this implementation would be a great boon for us!
@Marvur the framework used for the implementation is only available starting from iOS 16. Are there really big differences in compatibility between iOS 16.0 and iOS 16.4, considering they are in the same major release?
Anyway I think this PR is ready for review, and other Shortcuts actions can be discussed and implemented later.
Users on iOS 16 - 16.1.2 are the target group. "Connect VPN" shortcut action doesn't exist on these versions of iOS and it will be super helpful to have that inbuilt in Wireguard.