From 361351d803eebb42fcc0b02bdb1108afabe10a4a Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Tue, 19 Jul 2005 20:41:45 +0000 Subject: [PATCH] 2005-07-19 David Zeuthen * vpn-daemons/README: Add some documentation git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@800 4912f4e0-d625-0410-9fb7-b9a5a253dbdc --- vpn-daemons/README | 156 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/vpn-daemons/README b/vpn-daemons/README index 8138178c96..e571a1ab79 100644 --- a/vpn-daemons/README +++ b/vpn-daemons/README @@ -1,2 +1,156 @@ -The API for the VPN extensions points should be mentioned here +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 is used in place +of the actual name, e.g. vpnc, openvpn, openswan and so forth. + + a. /etc/NetworkManager/VPN/nm--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--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 +