summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJukka Rissanen <jukka.rissanen@linux.intel.com>2012-11-12 14:07:17 +0200
committerPatrik Flykt <patrik.flykt@linux.intel.com>2012-11-23 12:58:50 +0200
commitd20247d3b3074b7c5937540ce5dbc8f020c79907 (patch)
tree861bab1ba84b89921bcdfeac75ced7fe2fb26faa /doc
parent99e49dd2add20aecafe79b24effb4b87353449f9 (diff)
downloadconnman-d20247d3b3074b7c5937540ce5dbc8f020c79907.tar.gz
connman-d20247d3b3074b7c5937540ce5dbc8f020c79907.tar.bz2
connman-d20247d3b3074b7c5937540ce5dbc8f020c79907.zip
doc: VPN daemon API descriptions
Diffstat (limited to 'doc')
-rw-r--r--doc/vpn-connection-api.txt165
-rw-r--r--doc/vpn-manager-api.txt50
-rw-r--r--doc/vpn-overview.txt60
3 files changed, 275 insertions, 0 deletions
diff --git a/doc/vpn-connection-api.txt b/doc/vpn-connection-api.txt
new file mode 100644
index 00000000..5fe39d34
--- /dev/null
+++ b/doc/vpn-connection-api.txt
@@ -0,0 +1,165 @@
+vpn connection
+==============
+
+Service net.connman.vpn
+Interface net.connman.vpn.Connection
+Object path [variable prefix]/{connection0,connection1,...}
+
+Method void SetProperty(string name, variant value) [experimental]
+
+ Changes the value of the specified property. Only
+ properties that are listed as read-write are
+ changeable. On success a PropertyChanged signal
+ will be emitted.
+
+ Possible Errors: [connection].Error.InvalidArguments
+ [connection].Error.InvalidProperty
+
+ void ClearProperty(string name) [experimental]
+
+ Clears the value of the specified property.
+
+ Possible Errors: [connection].Error.InvalidArguments
+ [connection].Error.InvalidProperty
+
+ void Connect() [experimental]
+
+ Connect this VPN connection. It will attempt to connect
+ to the VPN connection. The Connect() will wait until
+ the connection is created or there is an error. The
+ error description is returned in dbus error.
+
+ Possible Errors: [connection].Error.InvalidArguments
+ [connection].Error.InProgress
+
+ void Disconnect() [experimental]
+
+ Disconnect this VPN connection. If the connection is
+ not connected an error message will be generated.
+
+ Possible Errors: [connection].Error.InvalidArguments
+
+Signals PropertyChanged(string name, variant value) [experimental]
+
+ This signal indicates a changed value of the given
+ property.
+
+Properties string State [readonly]
+
+ The connection state information.
+
+ Valid states are "idle", "failure", "configuration",
+ "ready", "disconnect".
+
+ string Type [readonly]
+
+ The VPN type (for example "openvpn", "vpnc" etc.)
+
+ string Name [readonly]
+
+ The VPN name.
+
+ string Domain [readonly]
+
+ The domain name used behind the VPN connection.
+ This is optional for most VPN technologies.
+
+ string Host [readonly]
+
+ The VPN host (server) address.
+
+ int Index [readonly]
+
+ The index of the VPN network tunneling interface.
+ If there is no tunneling device, then this value
+ is not returned.
+
+ dict IPv4 [readonly]
+
+ string Address
+
+ The current configured IPv4 address.
+
+ string Netmask
+
+ The current configured IPv4 netmask.
+
+ string Gateway
+
+ The current configured IPv4 gateway.
+
+ string Peer
+
+ The current configured VPN tunnel endpoint
+ IPv4 address.
+
+ dict IPv6 [readonly]
+
+ string Address
+
+ The current configured IPv6 address.
+
+ string PrefixLength
+
+ The prefix length of the IPv6 address.
+
+ string Gateway
+
+ The current configured IPv6 gateway.
+
+ string Peer
+
+ The current configured VPN tunnel endpoint
+ IPv6 address.
+
+ array{string} Nameservers [readonly]
+
+ The list of nameservers set by VPN.
+
+ array{dict} UserRoutes
+
+ int ProtocolFamily
+
+ Protocol family of the route. Set to 4
+ if IPv4 and 6 if IPv6 route.
+
+ string Network
+
+ The network part of the route.
+
+ string Netmask
+
+ The netmask of the route.
+
+ string Gateway
+
+ Gateway address of the route.
+
+ The list of currently active user activated
+ routes.
+
+ array{dict} ServerRoutes [readonly]
+
+ int ProtocolFamily
+
+ Protocol family of the route. Set to 4
+ if IPv4 and 6 if IPv6 route.
+
+ string Network
+
+ The network part of the route.
+
+ string Netmask
+
+ The netmask of the route.
+
+ string Gateway
+
+ Gateway address of the route.
+
+ The VPN server activated route.
+
+ There can be other properties also but as the VPN
+ technologies are so different, they have different
+ kind of options that they need, so not all options
+ are mentioned in this document.
diff --git a/doc/vpn-manager-api.txt b/doc/vpn-manager-api.txt
new file mode 100644
index 00000000..66c5beef
--- /dev/null
+++ b/doc/vpn-manager-api.txt
@@ -0,0 +1,50 @@
+vpn manager
+===========
+
+Service net.connman.vpn
+Interface net.connman.vpn.Manager
+Object path /
+
+Method object Create(dict settings) [experimental]
+
+ Create a new VPN connection and configuration using
+ the supplied settings.
+
+ void Remove(object vpn) [experimental]
+
+ Remove the previously created VPN configuration.
+
+ array{object,dict} GetConnections() [experimental]
+
+ Returns a list of tuples with VPN connection object
+ path and dictionary of their properties.
+
+ Possible Errors: [manager].Error.InvalidArguments
+
+ void RegisterAgent(object path) [experimental]
+
+ Register new agent for handling user requests.
+
+ Possible Errors: [manager].Error.InvalidArguments
+
+ void UnregisterAgent(object path) [experimental]
+
+ Unregister an existing agent.
+
+ Possible Errors: [manager].Error.InvalidArguments
+
+Signals ConnectionAdded(object path, dict properties) [experimental]
+
+ Signal that is sent when a new VPN connection
+ is added.
+
+ It contains the object path of the VPN connection
+ and also its properties.
+
+ ConnectionRemoved(object path) [experimental]
+
+ Signal that is sent when a VPN connection
+ has been removed.
+
+ The object path is no longer accessible after this
+ signal and only emitted for reference.
diff --git a/doc/vpn-overview.txt b/doc/vpn-overview.txt
new file mode 100644
index 00000000..42b6e94a
--- /dev/null
+++ b/doc/vpn-overview.txt
@@ -0,0 +1,60 @@
+VPN daemon overview
+*******************
+
+
+Manager interface
+=================
+
+Manager interface described in vpn-manager-api.txt is to be used
+by both the connectivity UI and by ConnMan. The Create(),
+Remove(), RegisterAgent() and UnregisterAgent() functions are for
+UI usage. The GetConnections() method and ConnectionAdded() and
+ConnectionRemoved() signals are for ConnMan VPN plugin to use.
+
+The UI should use the methods like this:
+- Ask VPN properties (like certs, usernames etc) from the user.
+- Call Manager.Create() to create a VPN connection (note that
+ the system does not yet try to connect to VPN at this point)
+- Register an agent to vpnd so that vpnd can ask any extra
+ parameters etc from the user if needed.
+- If the user wants to connect to VPN gateway, then the
+ connection attempt should be done in ConnMan side as
+ there will be a service created there.
+- If the user wishes to remove the VPN configuration, the UI
+ can call the Manager.Remove() which removes the VPN connection.
+ If the VPN was in use, the VPN connection is also disconnected.
+- When UI is terminated, the UI should call the UnregisterAgent()
+
+The ConnMan calls VPN daemon like this:
+- There is a VPN plugin which at startup starts to listen the
+ ConnectionAdded() and ConnectionRemoved() signals.
+- The VPN plugin will call GetConnections() in order to get
+ available VPN connections. It will then create a provider service
+ for each VPN connection that is returned.
+- User can then connect to the VPN by calling the service Connect()
+ method
+- The existing ConnMan Manager.ConnectProvider() interface can still
+ work by calling vpn.Manager.Create() and then call vpn.Connection.Connect()
+ but this ConnectProvider() interface will be deprecated at some
+ point.
+
+
+
+Connection interface
+====================
+
+The Manager.Create() will return the object path of the created
+vpn.Connection object and place it in idle state. Note that
+vpn.Connection.PropertyChanged signal is not called when Connection
+object is created because the same parameters are returned via
+vpn.Manager.ConnectionAdded() signal.
+The vpn.Connection object can be connected using the Connect() method
+and disconnected by calling Disconnect() method. When the connection
+is established (meaning VPN client has managed to create a connection
+to VPN server), then State property is set to "ready" and PropertyChanged
+signal is sent. If the connection cannot be established, then
+State property is set to "failure".
+After successfull connection, the relevant connection properties are sent
+by PropertyChanged signal; like IPv[4|6] information, the index of the
+VPN tunneling interface (if there is any), nameserver information,
+server specified routes etc.