This is an Alpha. I know there are bugs, and I want to find them. I also don't want folks to be afraid to help test, because that will allow us to reach an acceptable quality level as rapidly as possible. I recommend performing a backup before you start to experiment; on PocketPC devices this only take a couple minutes so it shouldn't be a hassle.
I have never had to hard-reset the device during development (even in the early phases of the driver portion), but you'll have at least the peace-of mind knowing you have that fallback position should you think you need it, and you should be only out a few minutes time in restoring back to the machine's original state.
I have, however, had to soft-reset. Don't forget that the uninstall is code, too, and may have bugs as well that preclude a full uninstall. I do try to test the uninstall well before publishing a build, but I have seen different behaviour on different OS versions in some cases.
The binaries are pre-built as a CAB file. You can copy the CAB file to any spot on your device (like \). You can use the ActiveSync Explore feature to do the copying. Then, with File Explorer on the device you can find the CAB file and click it. It will install and the device will delete the CAB when done.
Upon installing the CAB file, some files are copied to the system. Most of it is copied into:
And the TAP driver and help file (for technical reasons) are copied to:
A default instance (TAP1) is created and started, and the 'connection manager' application is started up. It is also set up to start automatically upon device reset via a shortcut in the startup folder.
The connection manager starts up as an icon in the lower right-hand corner:
This icon may be tapped to present the menu:
Exit quits the Connection Manager application, and Help lets you open the help file or the about box.
The item labeled (recent config) is a most-recently-used configuration menu and will get populated as you start using configurations.
Start From Config opens a menu of OpenVPN configuration files found on the system. These are standard openvpn configuration files. You can build them on a desktop machine and copy them over. In fact, I recommend you do just that as diagnosis is much easier on a desktop machine.
When you select this item the sub-menu is presented, e.g.:
In this example I have three configuration files. Sample comes out of the install and is provided as a pattern for testers. It is the config file I have been testing with though obviously you will need to modify it to point to your server and keys and whatnot. The other two are ones I created but aren't in the distribution package. Stuff you create and put on your device will show up in this list.
The contents of the Start From Config menu are dynamically built from configuration files found on the device. The files are located in a 'config' directory. By default, this directory is located at:
The files must have the extension .ovpn to be recognized. In this example there were three such files located in the config directory named:
As mentioned, I recommend creating your creating of config files on a desktop machine and testing them there. It is so much easier to test configurations on a desktop than to try to do so on the PocketPC -- largely due to the keyboard, a console, and a big screen. You can then copy the knwon-to-be-working file to the PocketPC device using whatever means; e.g. I use the Explore feature of Active Sync to do so. It's completely feasible to create a file on the PocketPC and use it, though, if you're very config-saavy (which I'm not). Additionally in the future I plan to have a 'config wizard' that you can create typical configs by clicking through some options. For now, though, it's file-based only.
When you click one of these file, an instance of openvpn.exe is started with the command-line of --config specifying the file. Additionally, two items are specified that will effectively override those in the config file: the named termination event, and the management interface and port. The values for these come from the settings page.
The currently running instances of openvpn.exe may be viewed on the VPN Instances page. Before I get to that I will discuss some of the configuration options.
This opens a sub-menu with options for accessing the Settings, TAP Instances, and VPN Instances pages.
This page contains various applications settings.
Creates a startup shortcut to start the connection manager upon soft-reset.
When the connection manager starts, it will enumerate all registered TAP devices and try and get them started if they aren't already. This is particularly useful on WM5 devices because the TAP driver will not be automatically loaded from NDIS for application trust reasons.
Prior to starting a VPN instance, try to ping at least one of the servers listed in the configuration file. This is particularly useful on PocketPC because networking is usually provided via a wireless connection that is typically off. Failure to ping usually means that you need to turn your wireless on first. Servers can be configured not to respond to ping requests, however, so this isn't proof positive that a connection will fail.
the openvpn.exe has no user-interface and relies upon the connection manager to provide it.
This is done through the management connection. Typically it is sufficient and secure to leave the interface (the IP address) to be a localhost address. This prevents network connections to the management interface and only allows processes running on the device to use them. For testing purposes it can be handy to open this up to network connections. Then you can connect with, say, telnet from a desktop machine. You can provide an explicit IP address of a NIC on the device, or you can specific 0.0.0.0 which means 'any NIC'.
The port is actually a base port address. The specific port used is the first available after that address and is assigned on-the-fly at connection time.
It is possible to have openvpn.exe instances use a named event to signal application shutdown. The connection manager uses this feature to provide a 'global shutdown' event for all running instances (individual instances are shutdown via management connection).
This is the location where the configuration files are kept. Files in this location, with the .ovpn extension, are used to populate the Start From Config menu. The ellipses button (...) is used to browse for a new location. The default location is the 'config' subdirectory of the install location (default is \Program Files\OpenVPN).
This is the location where the log files are kept. The ellipses button (...) is used to browse for a new location. The default location is the 'log' subdirectory of the install location (default is \Program Files\OpenVPN).
Some more settings; pertinent to the Windows Connection Manager. This is experimental and may change. Also, it's mostly of interest to those using phone (GPRS, GSM, EVDO, etc.) networks to make data connections.
[WiFi users can probably ignore all of this]
The Windows Connection Manager is a mechanism created to simplify the process of connecting to network resources. It attempts to automatically start and stop network connections based upon perceived cost, and applications' requests. Since OpenVPN creates a virtual network adapter, it appears as another networking resource that Windows Connection Manager considers in it's connection planning decisions. Connection Manager can at times believe that it is safe to disconnect the phone network when the virtual NIC provided by openvpn is present.
To help with this, this page has the following options:
When this is checked, the application will request a connection from Windows Connection Manager prior to starting the vpn process, openvpn.exe. This will cause Windows Connection Manager to automatically start a connection if one is not present.
By unchecking this option, nothing will be done with Windows Connection Manager.
[I put this in since this feature is experimental, and so by unchecking it there is a way to return to previous behaviour. I expect no one will need or want to uncheck it.]
When using Windows Connection Manager, an application can request to use a specific connection provider. The user can create these through the Settings interface, but usually there will be some that ship out-of-box, especially with phone-based devices that have pre-configured connection settings.
If you use a phone or dialup network to connect, you should select the provider that you want to use to make the basic internet connection through which openvpn will be tunneling.
In the example shown above, my mobile operator is Sprint, and so I have selected 'Sprint'. Choose the one appropriate to your device. WiFi users can ignore this setting and leave it at the default of <any>.
[Pick the one that looks sensible to your device, depending on your mobile operator. This seems to be important.]
An application can specify that a connection is to be made for it's exclusive use.
[Checking this, and selecting an appropriate item in 'Use this provider' seem to be the essential things in not having the original phone network connection dropped when another application uses Windows Connection Manager]
This page shows TAP virtual NIC instances on the system in any of their various states.
Upon installation a single default instance is created. It is probably all you'll ever need unless you're doing something terribly fancy. Due to a limitation in CE, you are restricted to 10 such instances (and practically 9 in this application for no good reason). I provided the capability in the wildly offhanded chance that someone else in the world has a device called TAP that needs to co-exist on the system. You can have two distinct device drivers service the same base name so long as the distinguishing digit is different. Then again maybe someone wants a couple simultaneous tunnels. Regardless of the need the capability is there. I've only ever tested with one running tunnel, however.
The adapter can be in any of various states:
There are several buttons that operate on the currently selected TAP instance.
This will create a new TAP adapter registration for those who wish it. It is not expected to be needed. This does not load the driver, and the driver will initially be in the 'not loaded' state.
The delete button will delete the NDIS registration for the selected TAP instance. This does not unload the driver, but rather places it into the 'orphan' state. 'Orphaned' drivers are technically usable, but will evaporate when the system has been soft-reset. This is an unusual state for a TAP instance except when preparing for an uninstall.
This will cause the OS to load the selected adapter (if it's not already loaded). For example, selecting the' TAP Device 2' created earlier, and selecting Start will cause the instance to become 'available'.
This button opens the TAP instance (if available) and issues and ioctl() to query for it's build version. This can only be done if the instance is loaded and available. It doesn't serve much purpose other than as a sanity check for testing.
The VPN instance tab shows running (and presumably connected) instances of openvpn.exe. Initially it looks like this:
The 'Signal Stop' button will ask the selected running instance (when there are some there) to exit. The 'Signal Stop All' button will signal all running instances to exit. The 'Signal Stop All' does not use the management interface, but rather uses the termination event.
When you start an instance for the 'Start From Config' menu, the wait cursor appears while the instance is starting:
If the 'Try to ping servers on connect' setting is checked, then a ping will be issued before actually connecting. If it fails the following will be shown:
This typically means that you don't have a route to access the server. PocketPC devices usually have wireless network cards that you must manually turn on. If you haven't turned it on and connected to an access point, you will get this message. Check that first. That's why I put this in: because I always forget. It can also happen if the server is configured not to respond to ping requests, so keep that in mind.
If there is a password needed for server authentication, or for the private key, then a dialog is presented prompting for such:
The text at the top of the dialog indicates the instance you just started (it is derived from the config filename), and the type of password OpenVPN wants. I believe there are only two types: 'Private Key' for the local client private key, and 'Auth' for the server-side user authentication.
If the instance runs, then its process id and state are shown:
If one were to switch to the TAP tab, you can see the TAP device that this VPN instance is currently using.
While connected, a pane is added to this view dynamically which provides detailed information pulled from the OpenVPN 'management interface':
The name on this tab is derived from the file name of the config file used to start the instance.
In this case the 'State' button was pressed. Details of this information can be found in the OpenVPN documentation.
The 'End' button is provided as a convenience and works the same as the 'Signal Stop' button on the VPN tab.
Whilst connected, the visible aspect of the icon on the Today screen changes to provide an obvious indication that at least one VPN instance is running:
At this point you should be ready to use the connection in some way.
You should be able to access network resources through the tunnel with whatever client application is relevant. For example, here is a web page served by a web server inside the private network being displayed by PocketIE. This web server is known internally as 192.168.1.10, but is also the remote VPN endpoint 10.8.0.1.
The Exit menu option exits the OpenVPN Connection Manager application. It also checks to see if there are any VPN instances running and prompts the user to terminate them (it uses the global termination event specified on the settings page).
It is wise to stop all the instances because, if not, the connection manager will forget the mappings of assigned management ports to pids and not not be able to control pre-existing VPN instances upon running the connection manager again. I would recommend only choosing Yes or Cancel for this warning. If for some reason you have a stray instance running when you re-start the Connection Manager, you can use the 'Signal Stop All' button and that should cause pre-existing instances to exit.
The OpenVPN Connection Manager can be restarted from its icon in the Programs list. It's expected that the connection manager would need to be exited explicitly only when doing an uninstall anyway.
Uninstalling the application from the PocketPC device has a slight challenge. Principally, there are three executable components: the openvpn.exe, the ovpncmgr.exe, and the tap-ce.dll. None of these may be loaded during uninstall or the uninstaller will be unable to delete the files from the system. The uninstaller will issue a warning if you try. The ovpncmgr.exe is easy: you just use the menu and select Exit. This should also signal any openvpn.exe instances to exit as well. The TAP driver (tap-ce.dll) is a little trickier. The deal is that this is loaded by NDIS into device.exe. Furthermore, NDIS will automatically load this driver upon bootup. Here's the way I prepare a device for uninstallation:
Now you can uninstall in the normal fashion (Settings->Remove Programs).
If you don't do this, uninstall will delete all the stuff it can, and you won't have fully uninstalled everything. In particular the TAP driver may be left behind.
I added a 'stop' method in the TAP instances page. You can uninstall now with less trouble by taking the following alternative steps:
Since all the binaries are now unloaded, you can uninstall in the normal fashion (Settings->Remove Programs). Also, this way avoids the need to soft-reset.
It appears that Windows Mobile 2005 has improved the uninstaller such that it knows how to deal with loaded files. In that case you can forget about having to do all the legerdemain mentioned above and just go straight to the uninstaller. The uninstaller will know that you have to reset the device and will present a dialog asking if it is OK to do so. After resetting, there is a deferred action that will delete the previously locked files. So there's a nice thing with WM5!