NetworkManager/vpn-daemons

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