[RFC] doc: Extended tethering API

Samuel Ortiz sameo at linux.intel.com
Tue Jan 25 08:59:55 PST 2011

Hi folks,

So I've been thinking about how ConnMan could support the DUN server case.
I gathered that the ConnMan requirements for that use case are the following:

- Provide a free IP range for oFono's ppp gateway address. The address range
should be a /24 one, in which oFono can freely pick a couple IPs (for the
local and peer addresses).

- Enable NAT and IP forwarding between the ppp interface created by oFono and
our default service one.

Even though we could certainly create some ad-hoc net.connman.Manager methods
for that, I think the DUN case can easily be seen as a tethering corner case.
It's basically what we're currently doing with the tethering implementation,
except that:
a) We don't want to put the ppp interface on a bridge and 
b) We don't want a DHCP server to be listening on the ppp interface (although
we could, but that's useless in most cases).

So what I propose is to define a more generic tethering API for ConnMan,
starting from the Manager one, and would look like that:

diff --git a/doc/manager-api.txt b/doc/manager-api.txt
index 743ba18..f8ca93d 100644
--- a/doc/manager-api.txt
+++ b/doc/manager-api.txt
@@ -192,6 +192,52 @@ Methods		dict GetProperties()
 			Possible Errors: [service].Error.InvalidArguments
+		object RequestTether(dict settings)
+			This method will request a tethering object.
+			Valid settings for tethering objects are:
+			string Interface [optional]
+			       Interface name to be used as the tethering link.
+			string Technology [optional]
+			       The technology that should act as the tethering
+			       link. This value is only valid when Interface is
+			       not specified.
+			       If the Technology value is not specified, all
+			       technologies supporting tethering will be used
+			       as tethering links.
+			string Bridge [optional]
+			       The bridge name tethering clients will belong to.
+			       This value is only valid when Interface is not
+			       specified.
+			       If the Bridge value is not specified but the
+			       Technology one is, then a default bridge named
+			       "tether" will be used.
+			boolean DynamicIP [optional]
+				This value specifies if a DHCP server should run
+				on the tethering bridge or interface. When set
+				to FALSE, a specific IP range will be reserved.
+			When successful this method will return the object
+			path of the corresponding tether.
+			Possible Errors: [service].Error.InvalidArguments
+		void ReleaseTether(object tether)
+			Release a tethering object.
+			The tethering link is brought down if it was still up.
+			Possible Errors: [service].Error.InvalidArguments
 Signals		PropertyChanged(string name, variant value)
 			This signal indicates a changed value of the given
@@ -249,13 +295,6 @@ Properties	string State [readonly]
 			the limited usage of WiFi or Bluetooth devices might
 			be allowed in some situations.
-		boolean Tethering [readwrite]
-			This option allows to enable or disable the support
-			for tethering. When tethering is enabled then the
-			default service is bridged to all client where
-			connection sharing is supported.
 		object ActiveProfile [readwrite]
 			Object path of the current active profile.
diff --git a/doc/tether-api.txt b/doc/tether-api.txt
new file mode 100644
index 0000000..589d1c4
--- /dev/null
+++ b/doc/tether-api.txt
@@ -0,0 +1,37 @@
+Tether hierarchy
+Service		net.connman
+Interface	net.connman.Tether
+Object path	/
+Methods		dict GetProperties()
+			Returns properties for the tether object. See
+			the properties section for available properties.
+			Possible Errors: [service].Error.InvalidArguments
+		void Start()
+			Possible Errors: [service].Error.InvalidArguments
+		void Stop()
+			Possible Errors: [service].Error.InvalidArguments
+Properties	dict IPv4 [readonly]
+			string Address [readonly]
+				The current reserved IPv4 address
+				range.
+			uint8 PrefixLength [readonly]
+				The prefix length of the IPv4 address
+				range.
+			array{string} Nameservers [readonly]
+				The IPv4 namesevers array.

And the current Manager Tethering property would be replaced by calling
Start()/Stop on a tether object we'd get from Manager.RequestTether(NULL,

oFono usage of this interface for DUN would look like that:

1) Manager.RequestTether("ppp0", NULL, NULL, FALSE)
2) Tether.GetProperties() would give oFono the IP range it could use for the
ppp gateway and client addresses, along with the nameservers to pass to the
3) Tether.Start() once the IPCP link is up. That would enable IP forwarding
and NATing.

Comments appreciated.


Intel Open Source Technology Centre

More information about the connman mailing list