mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-11-05 19:03:31 +00:00
361351d803
* vpn-daemons/README: Add some documentation git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@800 4912f4e0-d625-0410-9fb7-b9a5a253dbdc
156 lines
6 KiB
Text
156 lines
6 KiB
Text
|
|
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
|
|
|