todo: add notes about ethernet connection autodetection
[NetworkManager.git] / TODO
1 So you're interested in hacking on NetworkManager?  Here's some cool
2 stuff you could do...
3
4 * Internet Connectivity Detection
5
6 This feature would consist of attempting to make an HTTP request to a known
7 DNS address and compare the response to a well-known string, like Windows does.
8 This feature and the server address should be configurable via an option in the
9 /etc/NetworkManager/NetworkManager.conf config file.
10
11 Once the device has successfully gotten an IPv4 or IPv6 address, it should
12 enter the state NM_DEVICE_STATE_IP_CHECK, where this HTTP request would be
13 performed.  After the check was done, the device would set a property in
14 NMDevicePrivate to indicate whether Internet access was successful or not, and
15 advance to the NM_DEVICE_STATE_ACTIVATED state.
16
17 The NMManager object, when determining the overall NM_STATE_* state in the
18 nm_manager_update_state() function, would query this property and set
19 NM_STATE_CONNECTED_LOCAL, NM_STATE_CONNECTED_SITE, or NM_STATE_CONNECTED_GLOBAL
20 based on it and the device's state.
21
22 Ideally this feature would not require linking to an HTTP library like libcurl,
23 but would use open-coded simple HTTP or libsoup for the request.  The request
24 must be done asynchronously, of course.
25
26
27 * ADSL support
28
29 NetworkManager should natively support ADSL modems using one of the 3 main
30 connection methods, PPP over ATM (pppoa), PPP over Ethernet (pppoe), or
31 IP over ATM (ipoatm).  Initial support could be targeted at just pppoa and
32 pppoe, and there is some code in NetworkManager already for pppoe.  More info
33 about ADSL configuration on Linux in general is here:
34
35 http://atm.eagle-usb.org/wakka.php?wiki=UeagleAtmDoc
36
37 Big thanks to Pantelis Koukousoulas for getting ADSL working for PPPoA and PPPoE
38 methods in the 'adsl' branch in NetworkManager git.  We need more testing, IPv6
39 PPP support, and also support for multiple ADSL devices (by reading the "atmindex"
40 attribute from the sysfs directory for the ATM interface on 2.6.38.8 and later
41 kernels).
42
43
44 * Convert WEXT code to nl80211
45
46 There's still some WEXT code in NetworkManager for signal strength reporting,
47 mode, frequency, BSSID, etc.  This should all get converted to nl80211 code,
48 possibly using libnl as a base.  It's not particularly hard, but some
49 investigation on how to talk to netlink and how to use nl80211 and netlink
50 attributes will need to be done.  Tools like 'iw' already do much of this work,
51 but we *cannot* copy & paste code from them since the 'iw' license is not
52 compatible with NetworkManager's GPL license.  For exmaple, the following code
53 does the job, but should be reworked a bit to use the internal synchronous
54 netlink connection from src/nm-netlink-manager.c instead of doing the
55 netlink communication on its own with genl_connect() and such:
56
57 http://mail.gnome.org/archives/networkmanager-list/2009-September/msg00214.html
58
59 The same approach should be taken for signal strength reporting, etc.
60
61
62 * Real Access Point mode support
63
64 Now that NetworkManager requires wpa_supplicant 0.7.x or later, we can add
65 full Access Point (AP) mode support.  NetworkManager currently implements
66 connection sharing via AdHoc mode support, which has some limitations.  Instead,
67 we should check whether the wifi device supports AP mode, and if so, use
68 that mode instead.  wpa_supplicant has support for a "lightweight AP" mode which
69 we should use.  Witold Sowa started this support a while ago and wrote the new
70 D-Bus API for wpa_supplicant that makes all this possible, but some NM pieces
71 are still missing.  If the wifi driver supports AP mode, then in
72 src/supplicant-manager/ NM should send an AP-mode config instead of sending
73 the adhoc config.
74
75 Note that some devices (airo, ipw2100, ipw2200, iwl3945, iwl4965, atmel, zd1201)
76 will never support AP mode due to firmware limitations, so we clearly must still
77 provide Ad-Hoc connection sharing support for those devices and switch between
78 Ad-Hoc and AP mode depending on device capabilities.
79
80
81 * On-Demand WiFi Scan support
82
83 Single-user and embedded devices often use a continuous wifi scan when the
84 networking configuration interface is open to quickly allow users to find their
85 wifi network.  NM periodically scans, but this could take as long as 2 mintues
86 to update the list.  Note that WiFi scans require 2 - 10 seconds to complete,
87 and during this time normal traffic (video, VOIP, streaming music, downloads,
88 etc) is not transmitted, so a WiFi scan is a disruptive operation to the user.
89
90 A D-Bus method should be added to the NMDeviceWifi device to allow user
91 applications to request a scan.  This request should be rate-limited to no
92 more than once every 10 seconds to give time for traffic to resume when the
93 scan is done, and to lessen the effect of any DDoS by malicious user
94 applications.  This request should also be restricted by one or more PolicyKit
95 permissions like org.freedesktop.NetworkManager.network-control.
96
97 To begin, a new method definition should be added to the
98 introspection/nm-device-wifi.xml for a method called "RequestScan" which takes
99 an argument called "options" of type of "a{sv}".  This argument will be used
100 later.  An annotation (like the other functions have) should be added so that
101 the method will be called "impl_device_request_scan".
102
103 Next, the corresponding method implementation should be added to
104 src/nm-device-wifi.c by adding the prototype for impl_device_request_scan
105 near the top of the file, and implementing it below.  The implementation will
106 recieve a GHashTable corresponding to the "a{sv}" argument list from the XML
107 file, but we can ignore that for now.
108
109 The incoming request should be authenticated using nm_auth_get_caller_uid()
110 and additionally starting a PolicyKit authentication check with
111 with nm_auth_chain_new().  See the function manager_device_disconnect_request()
112 in src/nm-manager.c for an example of this.
113
114 Only after the caller is authorized to scan should the request be checked
115 against the last scan timestamp, and if the last scan was 10 seconds or more
116 ago, a new scan should be requested.
117
118
119 * Reconnect to WiFi Networks Only If They Succeeded Once
120
121 Currently, NetworkManager will attempt to connect to a previously attempted
122 WiFi network even if that network was never successfully connected to.  This
123 causes confusion because sometimes users will randomly try various WiFi networks
124 hoping to find an open AP, and then wonder why NM tries to reconnect to any of
125 those APs later when none of them worked originally due to AP-side MAC filtering
126 or other failures.  What should happen is that NetworkManager should set a flag
127 on a connection when that connection is successfully connected at least once,
128 and only autoconnect the wifi network if that flag is present *and* the
129 NMSettingConnection's 'autoconnect' property is TRUE.
130
131 This is a bit tricky because we want to consider all connections that don't have
132 this flag as having succeeded so that we don't break users' existing connections,
133 while holding all newly created connections to this policy.  This flag should
134 be determined and set for all connections, even if we only use it to determine
135 WiFi behavior for now.
136
137 This flag should be a new gboolean property on the NMSettingConnection object
138 called "connect-success", with a default value of TRUE.  It should default to
139 TRUE to ensure that existing connections are assumed to have connected
140 successfully in the past.  New connections created via the AddConnection and
141 AddAndActivateConnection D-Bus method calls should have the 'connect-success'
142 property explicitly set to FALSE.  Then, in nm-device.c's device_state_changed()
143 function where the NM_DEVICE_STATE_ACTIVATED state is handled, the
144 'connect-success' property should be set to TRUE.
145
146 For WiFi then, in nm-device-wifi.c's get_best_auto_connection() method, the
147 'connect-success' property should be checked and if it is FALSE, the connection
148 is not considered for auto-activation.
149
150
151 * Implement NM_DEVICE_STATE_DISCONNECTING
152
153 To allow for "pre-down" scenarios, this state should be implemented before a
154 device is taken down while it still has connectivity.  If the device is
155 taken down because it's ethernet carrier was dropped, or because the WiFi
156 connection was terminated by the supplicant, this state is pointless and should
157 be skipped.  But if the user requested a manual "disconnect", or NM is dropping
158 connections on exit, etc, then this state should be entered.  In the future
159 this state should hook into a new dispatcher action in src/NetworkManagerUtils.c
160 to exectue dispatcher scripts during the disconnection, and to wait a limited
161 amount of time for each script to complete before allowing the device to
162 proceed to the NM_DEVICE_STATE_DISCONNECTED state, fully implementing pre-down.
163
164
165 * Ethernet Network Auto-detection
166
167 There are various methods we can use to autodetect which wired network connection
168 to use if the user connects to more than one wired network on a frequent basis.
169 First, 802.1x enterprise switches broadcast frames which can be used to indicate
170 that the switch supports 802.1x and thus allow NetworkManager to select an
171 802.1x connection instead of blindly trying DHCP.  Second, NetworkManager could
172 listen for traffic from a list of MAC addresses.  Third, NetworkManager could
173 integrate 'arping' functionality to determine if a given IP address matches a
174 given MAC address, and thus automatically select that connection.  All these
175 methods can co-exist and be used in parallel.
176
177 One small caveat is that MAC addresses are trivial to spoof, so just because
178 NetworkManager has discovered a certain MAC address does not mean the network
179 is authenticated; only 802.1x security can assure that a network is the network
180 the user expects it to be.
181
182 In any case, a new 'anchor-addresses' property of type string-array should be
183 added to the NMSettingWired setting.  Each string element of this property
184 should be of the format "<ip>/<mac>" or simply "<mac>".  The first format with
185 an IP address would indicate that "arping"-type behavior should be used to
186 actively detect the given MAC address; obviously if the given MAC address is
187 used for passive discovery as well.  The second format simply lists a MAC
188 address to passively listen for.
189
190 One drawback of listening or probing for known MAC addresses is an increase in
191 latency during connections to ethernet networks.  The probing/listening delay
192 should be a reasonable amount of time, like 4 - 5 seconds or so, and should
193 only be used when a visible connection has anchor addresses.
194
195 Next a gboolean 'anchor-probing' variable should be added to the
196 NMDeviceEthernetPrivate structure in src/nm-device-ethernet.c.  This variable
197 should be set to TRUE whenever the device's carrier turns on *and* there are
198 visible NMConnections with anchor addresses (ie, connections which are system-
199 wide or where one of the allowed users of that connection is logged in).  Then
200 probing and listening are started, which involves opening a low-level socket
201 on the interface and starting the arping run or listening for MAC addresses.
202 A timer is also started (don't forget to cache the timer's source ID in the
203 NMDeviceEthernetPrivate data, and to cancel the timer whenever the device
204 transitions to any state other than DISCONNECTED).
205
206 If a known MAC address is discovered as a result of probing or listening, the
207 probe/listen socket, timeout, and data are cleaned up, and NetworkManager
208 would begin activation of the NMConnection that specified the found MAC address
209 in the 'anchor-addresses' property.  If two or more connections specify the
210 same MAC address, the connection with the most recent timestamp should be
211 preferred.
212
213 Similarly, if the probing/listening process detects 802.1x frames the device
214 should be marked as requring 802.1x authentication until the carrier drops.
215 This would be accomplished by adding a new property to the NMDeviceEthernet
216 object and exporting that property through the
217 introspection/nm-device-ethernet.xml file.  This would allow clients like
218 applets to ensure that users are aware that the device will not allow
219 un-authenticated connections and that additional credentials are required to
220 successfully connect to this network.
221
222
223 * VPN re-connect
224
225 NM should remember whether a VPN was connected if a connection disconnects
226 (like WiFi drops out or short carrier drop) or if the laptop goes to sleep.
227 Upon reconnect, if the same Connection is again active, the previously
228 connected VPN should be activated again as well.  Basically, don't just drop
229 the VPN because WiFi choked for 10 seconds, but reconnect the VPN if it was
230 connected before the drop.
231
232
233 * VPN autoconnect
234
235 We should add a property to the NMSettingConnection object in
236 libnm-util/nm-setting-connection.c called "vpns" that is a string list,
237 containing a list of Connection UUIDs that should be activated when the base
238 connection itself is activated.  This will allow a VPN connection to be
239 started every time another connection is started, so that if you choose you're
240 always on the VPN in your favorite coffee shop.
241
242 The NM_DEVICE_STATE_SECONDARIES state was added specifically for cases like
243 this.  Thus, after the base device has IP connectivity, but before it has
244 signaled that it's fully activated, the device should enter the SECONDARIES
245 state and kick off activation of the given VPN connection.  Only after this
246 VPN connection has successfully connected should the base device to the
247 NM_DEVICE_STATE_ACTIVATED state.
248
249
250 * VPN and IPv6
251
252 The internal VPN capability should support IPv6.  Essentially, the D-Bus
253 interface between NetworkManager and the VPN service daemons should be extended
254 with an IP6Config signal that passes up the IPv6 addressing and routing details
255 if the VPN daemon is IPv6 capable.  NM should then process those details like it
256 does with IPv4.  include/NetworkManagerVPN.h should be updated with key/value
257 pairs defining the various IPv6 attributes much like the IPv4 ones are defined.
258
259
260 * VPN IP Methods
261
262 Some VPNs (openvpn with TAP for example) require that DHCP is run on a
263 pseudo-ethernet device to obtain addressing information.  This is not currently
264 possible, but NM already has all the code for DHCP.  Thus, a new "method"
265 key should be defined in include/NetworkManagerVPN.h to allow for DHCP to
266 be performed if the VPN service daemon requests it in the IP4Config or IP6Config
267 signals.  A patch here:
268
269 http://cgit.freedesktop.org/NetworkManager/NetworkManager/commit/?h=vpn-ip-method
270
271 shows that.  In nm-vpn-connection.c, upon receipt of the D-Bus Ip4Config signal
272 from the VPN plugin, NetworkManager would inspect the "method" property of the
273 ip4 config dictionary.  If that property was present and set to "auto" then
274 DHCP would be started using the network interface returned in the dict.  The
275 nm_vpn_connection_ip4_config_get() function should be split up into two
276 functions, one containing the existing code for static configuration, and a
277 second for handling DHCP kickoff.  Minimal parsing of the response should be
278 handled in the newly reduced nm_vpn_connection_ip4_config_get() function.
279
280 To handle DHCP, the NMVPNConnectionPrivate structure should have two members
281 added:
282
283     NMDHCPManager *dhcp_manager;
284     NMDHCPClient  *dhcp4_client;
285
286 which would be initialized in the new DHCP handler code split off from
287 nm_vpn_connection_ip4_config_get().  These new members would be disposed of in
288 both vpn_cleanup() and dispose(), though remember to stop any ongoing DHCP
289 transaction when doing so (see dhcp4_cleanup() in nm-device.c for example code).
290 For basic code to start the DHCP transaction, see dhcp4_start() in nm-device.c
291 as well.  After calling nm_dhcp_manager_start_ip4() and connecting the signals
292 to monitor success and failure, the VPN IP4 config handler would simply return
293 without changing VPN state, unless a failure occurred.
294
295 Then, when the DHCP transaction succeeds, which we'd know by checking the
296 DHCP client state changes in the "state-changed" signal handler we attached to
297 the DHCP client object returned from nm_dhcp_manager_start_ip4(), the code
298 would retrieve the completed NMIP4Config object from the DHCP client using the
299 nm_dhcp_client_get_ip4_config() function, and then proceed to execute
300 essentially the bottom-half of the existing nm_vpn_connection_ip4_config_get()
301 function to merge that config with user overrides and apply it to the VPN
302 tunnel interface.  Other state changes from the DHCP client might trigger a
303 failure of the VPN connection, just like DHCP timeouts and lease-renewal
304 failures do for other devices (see dhcp_state_changed() in nm-device.c).
305
306
307 * WPS
308
309 wpa_supplicant has support for WPS (Wifi Protected Setup, basically Bluetooth-
310 like PIN codes for setting up a wifi connection) and we should add support for
311 this to NetworkManager too.  APs that support WPS will say so in their beacon
312 IEs which are contained in the "WPA" and "RSN" properties of the BSS object
313 exported by the supplicant, and can be processed in src/nm-wifi-ap.c's
314 foreach_property_cb() function.  We should add some private fields to the
315 NMAccessPoint object (defined in nm-wifi-ap.c) to remember whether a specific
316 AP supports WPS and what WPS methods it supports, and expose that over D-Bus to
317 GUI clients as well.
318
319 There are two common WPS setup methods: PIN and button.  For PIN, the router
320 either displays a random PIN on an LCD or the router's web UI, or a static PIN
321 is printed on the router itself.  The user enters that PIN instead of a PSK
322 when connecting.  For the "button" method, the router has a physical button that
323 when pushed, allows any client to connect for a short period of time.
324
325 We'll then need to add some properties to the NMSettingWirelessSecurity setting
326 for the WPS PIN code so that when the user enters it through the GUI, it can
327 be passed back to NM.  And we'll need to figure out some mechanism for passing
328 back an indication that the user pushed the button on the router for the
329 pushbutton method.
330
331 When connecting to a new access point that supports WPS, the GUI client would
332 call the AddAndActivateConnection method and wait for NM to request secrets.
333 NM would determine that the AP supports WPS, and request WPS secrets from the
334 applet.  The applet would ask the user for a PIN, or to push the button on the
335 AP, instead of asking for a passphrase or PSK.  When the user has entered the
336 PIN or pushed the button, the applet returns this information to NM, which
337 proceeds with the connection.
338
339 NM sends the correct wpa_supplicant config for WPS to the supplicant, and waits
340 for the connection to occur.  WPS can only be used the *first* time, so after a
341 first successfull connection, NM must request the actual hexadecimal PSK from 
342 wpa_supplicant via D-Bus, and store that PSK in the connection, clear any WPS
343 PIN code from the connection, and save the connection to backing storage.
344
345 Any applet GUI should also allow the user to enter the PSK instead of completing
346 association using WPS, since quite a few routers out there are broken, or
347 because the user has no physical access to the router itself, but has been given
348 as passphrase/PSK instead.
349
350
351 * Proxies
352
353 HTTP and other proxies are per-connection configuration.  It's highly unlikely
354 that the same proxy you need to use at work is used at home or in a coffee shop.
355 Thus, it makes sense that which proxy settings to use should be updated when
356 network connections change.  NetworkManager is a perfect place to do this since
357 it tracks which network connections are active, and it already queries the
358 network for automatic proxy configuration via DHCP and WPAD.
359
360 We should add a new NMSetting subclass called NMSettingProxy that holds
361 necessary proxy configuration.  The properties of this setting should be a
362 superset of what is provided in the Firefox proxy configuration screen and the
363 various desktop environment proxy configuration tools like the GNOME Network
364 Proxy control panel; this should include at a minimum:
365
366   method: "auto", "manual", "none"
367   default-proxy: string
368   default-proxy-port: uint
369   default-always: boolean (use default proxy for all protocols)
370   ssl-proxy: string
371   ssl-proxy-port: uint
372   ftp-proxy: string
373   ftp-proxy-port: uint
374   socks-proxy: string
375   socks-proxy-port: uint
376   socks-version: uint, either 4 or 5
377   no-proxy-for: array of strings (things not to use the proxy for, ie ".foobar.com",
378                  "192.168.0.1/24", an IPv6 address, etc)
379   pac-url: string (URL of PAC file, overrides DHCP-provided WPAD value)
380   (FIXME: proxy authentication?  do we need separate user/pass properties for
381     each protocol type?  should NM handle proxy auth or should it be punted
382     to each application?)
383
384 After completing IP configuration but still during the NM_DEVICE_STATE_IP_CONFIG
385 activation stage, NetworkManager would merge the automatically supplied proxy
386 configuration (from DHCP's WPAD option) with user-provided overrides from the
387 NMSettingProxy and send the results to the system.  The 'default' connection's
388 proxy configuration would be preferred, so we'd have to update proxy
389 configuration from nm-policy.c the same time we update DNS information and the
390 default route.
391
392 The merged proxy configuration would then be sent to the system.  There is no
393 canonical proxy daemon in-use, so we should have plugins (if not separate
394 shared libraries, then certainly encapsulated source files that implement a
395 common glib GInterface or are subclasses of eg a parent NMProxyHandler class)
396 that handle different system proxy handlers.  Some of the proxy handlers are:
397
398   libproxy: need to figure out how it gets proxy info and have NM write merged
399              proxy config out to that location
400   pacrunner: a D-Bus enabled daemon, NM would call D-Bus methods of the
401                pacrunner service with the proxy information
402   GNOME/KDE: how do these desktop environments retrieve proxy configuration?
403
404
405 * Bridging and Bonding Support
406
407 The largest complication here is that NetworkManager normally operates on
408 physical interfaces, while bridging and bonding involve tying multiple physical
409 interfaces together into a logical interface.  This has interesting implications
410 for the D-Bus API and the NM device model.  The first complication is that
411 we may need to do 802.1x port authentication on an interface before it can
412 communicate with the other side of the link, and those credentials may be
413 different for each interface; thus we may need to do separate 802.1x
414 operations on each interface that is part of a bridge/bond before adding each
415 one to the master bridge/bond interface.
416
417 In this way bridge/bond interfaces may be treated the same way as NetworkManager
418 treats VPN interfaces already; one or more physical interface NMConnections must
419 be activated before the master bridge/bond interface's NMConnection can be
420 activated, though this all happens internally.
421
422 To enable bridging and bonding in the NMConnection itself, we should create
423 new NMSettingBridge and NMSettingBond classes that contain information specific
424 to each.  Both settings would contain a 'components' property with an
425 'array of string' type which would contain the UUIDs of the Connections of
426 physical interfaces that compose the bridge or bond.  Thus NetworkManager would
427 have the necessary information to tie lower-level interface configuration
428 (802.1x, MTU, MAC address locking, duplex mode, speed, etc) to each physical
429 interface that will be part of the bridge/bond, configure the interface with
430 it, and then configure the master bridge/bond interface at upper layers using
431 configuration specific for the bridge/bond interface (like IP details).  Thus
432 for a single active bridge, two or more NMConnections would be activated; one
433 for each physical interface component of the bridge/bond, and one for the master
434 bridge/bond interface itself.
435
436 NMSettingBridge would contain at least the following keys:
437
438   components: (array of string) UUIDs of component connections
439   stp:        (boolean) on to enable STP, off to disable
440
441 NMSettingBond would contain at least the following keys:
442
443   components: (array of string) UUIDs of component connections
444   mode:       (string) one of "balance-rr", "active-backup", "balance-xor",
445                   "broadcast", "802.3ad", "balance-tlb", or "balance-alb"
446   monitor-interval: (uint) Specifies link monitoring interval (in milliseconds);
447                        NM will always enable netlink carrier monitoring if this
448                        value is non-zero so this property only affects speed and
449                        duplex checking
450
451 In the future we may consider adding other bonding parameters like "up-delay"
452 and "down-delay".
453
454 Then we'd add a 'component' (boolean) property to NMSettingConnection to
455 indicate that the component interface connections were in fact components of
456 a bridge or bond and shouldn't be automatically started by NetworkManager or
457 displayed as separate connections in the user interface.
458
459 TO BE CONTINUED