mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-09-06 09:04:55 +00:00
![]() git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@4242 4912f4e0-d625-0410-9fb7-b9a5a253dbdc |
||
---|---|---|
.. | ||
openvpn | ||
pptp | ||
vpnc | ||
.cvsignore | ||
README |
0. Overview ----------- NetworkManager features a set of extension points for integrating VPN software in a seamless way such that it integrates into the network selection code and the user interface. 1. Design goals --------------- The goal is to have a vendor-independent interface so an ISV (which include prominent open source projects too) can easily integrate with NetworkManager whilst preserving a familiar user interface, behaviour and while being aware the automatic network switching enforced by NetworkManager. For example, if the user switches from e.g. a wired to a wireless connection (say, the user pulls out the network cable), routing tables needs to be reconfigured, DNS lookup services needs to be tweaked, interfaces may need to be brought or down and, often, the VPN connection needs to be restarted. Another useful feature is that the VPN software should be able to configure the DNS lookup service of the system to use name servers behind the VPN concentrator for only certain hostnames; e.g. it should be possible to say "For domain names of the form *.corp.company.biz use the DNS servers 10.1.2.3, 10.1.2.4 and 10.1.2.5". FIXME: write more stuff here 2. Interface for configuring VPN connection settings ---------------------------------------------------- NetworkManager ships with nm-vpn-properties which is a GNOME application for adding, removing, importing, exporting and editing VPN connection details. For each VPN connection type, a shared library is loaded which must export the method NetworkManagerVpnUI* nm_vpn_properties_factory (void) which returns a pointer to a structure with function pointers set by the shared library. Each of these functions are defined and documented in /usr/include/NetworkManager/nm-vpn-ui-interface.h Basically, the idea is that the shared library can return a GtkWidget that is used for editing connection details such as gateway address, domain for authentication, what addresses to route and so forth. Note that nm-vpn-properties store this in the GConf2 configuration system so passwords and other sensitive information should not be stored here (see section 3.) FIXME: actually document the methods in NetworkManagerVpnUI 3. Interface for retrieving authentication details -------------------------------------------------- In order to establish a VPN connection, sometimes one or more secrets are needed in order successfully connect. The secrets (what secret (password or one-time key, how many) are very dependent on both the VPN connection type and how it's configured. Each VPN type thus provides a binary that NetworkManager will launch to retrieve the passwords from the user. The communication protocol is very simple; if the binary can retrieve the passwords it writes them on stdout and exits with exit code 0. If the passwords cannot be retrieved, the auth dialog binary must exit with exit code 1. The auth-dialog may, at it's own discretion, store the secrets in e.g. the GNOME keyring (or any other secure location) thus not even needing to prompt the user for the secrets. However, NetworkManager may pass the --reprompt option to the auth-dialog to signal that the user must be reprompted for the secrets. This is useful when e.g. the secret needed for establishing the VPN connection changes on the server and the user needs to put in a new secret. At this time of writing, NetworkManager will automatically pass the --reprompt option if the connection was unsuccessful the last time. 4. Interface for setting up and tearing down VPN connections ------------------------------------------------------------ FIXME: write this 5. Summary of files needed for each VPN connection type --------------------------------------------------------------- The following files are needed for registering a new type of VPN connection. In the following, the notation <vpnname> is used in place of the actual name, e.g. vpnc, openvpn, openswan and so forth. a. /etc/NetworkManager/VPN/nm-<vpnname>-service.name This file describes the locations of the components implemented the interfaces described in section 2. through 4. Here's the example for vpnc with annotations [VPN Connection] name=vpnc # name of VPN connection type service=org.freedesktop.NetworkManager.vpnc # D-BUS service name program=/usr/bin/nm-vpnc-service # Binary for D-BUS service [GNOME] auth-dialog=/usr/libexec/nm-vpnc-auth-dialog # Binary for auth dialog properties=/usr/lib/libnm-vpnc-properties # Shared library for conn. prop - /etc/dbus-1/system.d/nm-<vpnname>-service.conf D-BUS policy file to allow ownership of the D-BUS service mentioned in a. 6. Registering MIME-types for files with VPN connection details --------------------------------------------------------------- If the VPN connection type supports exporting/important connection settings it should register with the MIME-system. This is a multi-step process a. First, make sure that the freedesktop.org shared MIME info knows about the file-type (see e.g. https://bugs.freedesktop.org/show_bug.cgi?id=3560) b. Create and ship a .desktop file that associates the MIME type with the nm-vpn-properties program. Here's the example for vpnc [Desktop Entry] Encoding=UTF-8 Name=VPN Connection Manager (vpnc) Exec=nm-vpn-properties --import-service org.freedesktop.NetworkManager.vpnc --import-file %f Terminal=false Type=Application DocPath= Categories=; MimeType=application/x-cisco-vpn-settings 7. Status of the interfaces --------------------------- As of July 2005 the interfaces are UNSTABLE and can and will change in the future. At some point the interfaces will be freezed. To acknowledge that the interfaces are subject to change, developers will have to define NM_VPN_API_SUBJECT_TO_CHANGE to include the headers 8. References ------------- - Screencast of vpnc integration with NM http://people.redhat.com/davidz/nm-vpn/nm-vpn.html - NetworkManager mailing list mailto:networkmanager-list@gnome.org - vpnc integration in NetworkManager CVS vpn-daemons/vpnc