Revision 7 as of 2008-01-28 19:21:50

Clear message
  • Launchpad Entry: coming soon...

  • Packages affected: network-manager, network-manager-applet, gnome-system-tools


This blueprint proposes a set of functional changes to NetworkManager and its associated applications / infrastructure for the purpose of making networking just work on mobile devices. The focus is Ubuntu Mobile, and driven in part by a MID ( Mobile Internet Device ) customer's requirements, however many of the proposed changes also could be leveraged on the desktop. Also please note that this blueprint should not be considered a design document, however at times it may be necessary to dive deeper in order to illustrate why certain things don't work.

Release Note

As there has not yet been an official release of Ubuntu Mobile, end-user impact is not applicable.


The changes proposed fall into a few categories:

  • Simplify the UI for the average consumer
  • Add missing features
  • Next-gen networking support
  • Make it just work!

Simplify The UI

The aim here is to re-work the NetworkManager related user interfaces such that non-technical users can easily operate them. The default UI should strive to reduce usage of technical terms like ASCII, BSSID, Hex, or WPA2 when at all possible.

Add Missing Features

Certain features are missing from the current version of Ubuntu Mobile and are expected to exist in a mobile consumer device. The primary example of a missing feature is the ability to turn off the Wi-Fi radio from the UI. Some devices also may have an actual hardware control to toggle Wi-Fi radio power which will also needs to be supported. Another example of a missing feature is the lack of an interface to change or delete a saved passphrase / key of a previously connected Wi-Fi access point.

Next-Gen Networking

Support for next-generation networking technologies like 3G and WiMax need to be added. Not much more to say...

Make it Just Work!

Some areas that need improvement:

  • Suspend / Resume -- consumers cannot be expect to have to re-start NetworkManager after a device wakes from sleep;

  • Better User Feedback -- if something fails, there needs to be better feedback to the user ( eg. association to the AP failed, couldn't get an IP address )
  • Gnome Keyring -- should it be a requirement for MIDs?

It should be noted that some of the problems seen on Ubuntu Mobile today are due to architectural problems. One major problem is the fact that MIDs are designed to run as a single hard-coded user with no login nor password required. This coupled with the fact that MIDs run a hybrid of the Gnome and Hildon the desktops as opposed to a vanilla Gnome desktop causes a variety of problems related to Gnome applications such as gnome-keyring and network-admin ( part of gnome-system-tools package ).

One last note... NetworkManager 0.7 is currently in mid-development cycle. Some of the ideas presented in this blueprint have been mentioned in the outlined plans for the 0.7 release. Hopefully this blueprint will generate discussion with the NetworkManager developers and lead to co-operation on some the features described herein.

Use Cases

1. Ozzy tries to connect his new mobile device to his nephew's home access point, who scribbled a WEP key value on a piece of paper before leaving for vacation. Ozzy doesn't know the difference between a passphrase, an ASCII key or Hex key. He selects the access point, and is prompted for a Passphrase / Key; the dialog figures out the type and does validity checking without making Ozzy select the type.

2. Sheila boards an airplane with her new mobile device, to turn off all radios on her device, she clicks the Airplane Mode icon on the Network Settings page; all radios ( eg. Bluetooth, Wi-Fi, 3G ) are turned off and the icon changes to show that Airplane Mode is active. Upon landing, Sheila clicks the Airplane Mode icon, each radio is enabled, and if possible, the device re-connects to the Internet without manual intervention.

3. Zach decides to revoke his neighbor's usage of his access point due to his neighbor downloading too many torrents of old TV shows. He changes the passphrase of his access point and wants to update his mobile device to use the new key. He opens the Connection Manager and changes the passphrase.

4. Maria decides to change here access point so that it doesn't broadcast it's ESSID. She does so, and uses "Join Other Network", this connects her mobile device to the Internet. Maria then inadvertently lets the battery run out on her mobile device. When she plugs it and boots the device, it automatically connects to her home access point.

5. Phil is a providing support for mobile devices using Unbuntu Mobile; while reviewing the daemon.log file from a device, he no longer needs to wade through HAL events which aren't relevant to networking.

7. Alice uses a mobile device running an OEM-customized version of Ubuntu Mobile. In order to connect to a 3G network, she selects 3G from the nm-applet's menu. If she hasn't yet entered the credentials for the 3G provider, she's prompted to do so.


The remainder of this blueprint consists of application specific sections with the exception of the final two sections:

  • Gnome NetworkManager Applet

  • Connection Manager
  • Make It Just Work!
  • Design Notes

Gnome NetworkManager Applet

This section covers changes to the Gnome NetworkManager applet including:

  • Simplified Key / Passphrase Required Dialog
  • Association Failed Behavior
  • Connect to Other Wireless Network
  • Refresh Scan / Scan Notification
  • Connection Information
  • Other Wireless Technologies
  • Miscellaneous Changes

Simplified Key / Passphrase Required Dialog

When a user selects a Wi-Fi network from the nm-applet menu, and the selected network requires a passphrase or encryption key, a dialog titled Wireless Network Key Required is displayed. This dialog displays a different set of widgets depending on the type of access point selected. Currently, there are three different versions of this dialog corresponding to the following Wi-Fi security schemes:

  • WEP
  • WPA / WPA2 - Personal
  • WPA / WPA2 - Enterprise

Each of the versions of this dialog require the user to select the type of key / passphrase entered from a combo-box labelled Wireless Security, and enter the corresponding key or passphrase. Each of the dialogs also have scheme-specific settings which can be changed via additional dialog widgets. All versions of the dialog include a checkbox labelled Show Password, a Cancel button, and a Login to Network button.


The WEP version's Wireless Security combo-box options are:

  • WEP 128-bit Passphrase ( default )
  • WEP 64/128-bit Hex
  • WEP 64/128-bit ASCII
  • LEAP

An additional combo box labelled Authentication is also present with the options:

  • Open Key ( default )
  • Shared Key

WPA Personal

The WPA Personal version's Wireless Security combo-box options are:

  • WPA Personal
  • WPA2 Personal
  • LEAP

An additional combo box labelled Type is also present with the options:

  • Automatic ( Default )
  • TKIP

Note - I also believe it's not possible to use a full 256-bit WPA Personal key with the current implementation which I believe only supports WPA Personal passphrases only. I need to do some testing to verify...

WPA Enterprise


Simplified Dialog

The new simplified version of the dialog will remove the Wireless Security combo altogether for all three versions of the dialog. The justification for this is that most consumers really don't understand the meaning of terms like ASCII, Hex, WEP or WPA, let alone the difference between WPA and WPA2. Futhermore LEAP is a proprietary Cisco security scheme, and WEP 128-bit passphrase is an out-dated passphrase scheme which is rarely used these days. With the removal of LEAP and 128-bit passphrase from the WEP version, it's possible to determine the key type by examining the text entered into the key / passphrase dialog. One only needs to take a look at the equivalent dialogs in OS X or Windows XP.

The second change involves hiding the additional settings widgets ( Eg. WEP Authentication ) via an Advanced button which would toggle the visibility of the advanced widgets.

TBD - add screen capture of new dialog here

If there is strong opposition to removing the ability to use LEAP and WEP 128-bit passphrases from Ubuntu Mobile, then an option would be to include a Wireless Security over-ride combo box in the Advanced panel. This technique could also be used to support WPA / WPA2 - Enterprise security methods.


One other minor point is that the term Wireless Network is too generic, especially when MIDs may included 3G or WiMax radios ( other examples of Wireless Networks ). Other terminology changes include:

  • WPA Personal - Password should be re-labelled Passphrase / Key

Association Failed Behavior

The current behavior of nm-applet if manual association ( ie. the user clicks on the AP in the nm-applet's menu ) fails is to re-display the Key / Passphrase Required dialog with the previously entered key cleared. There's no text indicating what exactly failed ( eg. association failed, DHCP failed to get an IP address, etc... ), just the re-display of the dialog. Note - I haven't exhaustively tested all of the failure cases, so I could be wrong with respect to the fact that the Passphrase Required dialog is re-displayed in all cases.

From looking at the NetworkManager code, the Passphrase Required dialog is re-displayed if authentication fails for a WEP access point configured for Shared-Key authentication or any WPA-PSK AP. I haven't tested to see if the dialog is re-displayed for a WEP AP configured for Open-Key authentication if DHCP fails.

MBU/UME Bug -- the dialog display doesn't happen on the latest customer-specific images built by Canonical's MBU. This may be related to the hard-coded keyring password hack. It also takes a long time ( ~60 seconds ) on the Crown Beach system for the nm-applet connecting icon to transition to the disconnected icon. Connect to Other Wireless Network... Connect to Other Wireless Network... is an item found in the main menu which launches a dialog of the same name which allows a user to manually specify the settings of a network ( hereafter referred to as a manual network ) and connect to the network. It typically is used to connect to an access point that isn't broadcasting its ESSID, and therefore doesn't appear in the list of networks visible after a scan. Dialog Changes This dialog by default displays with a text field labelled Network Name and combo-box labelled Wireless Security ( default is None ). The combo-box options are a super-set of all the possible options for all three variations of the Wireless Network Key Required dialog.

Again in the spirit of simplification, the Wireless Security combo-box options should be reduced to the following:

  • None
  • WEP
  • WPA/WPA2 Personal
  • WPA/WPA2 Enterprise *
  • LEAP *

* TBD whether or not these methods should be supported on MIDs.

Also, as with the Key Required dialog, optional settings are also displayed based on the security type chosen. As with that dialog, these optional settings should be hidden via an Advanced tab/button.

Finally, this dialog has a Cancel and Connect buttons. For consistency sake, Connect should be re-labelled Login to Network. Behavior Change If the user enters settings for a manual network and clicks Connect, the new network's settings are saved, and a connect attempt is made. If the device goes through a suspend / resume cyle, NetworkManager will attempt to re-connect to the manual network again. If the user then switches network connections, or the device is re-booted, the manual network is effectively orphaned. If the user again wishes to connect to this network, they're required to click Connect to Other Wireless Network... again and re-enter the network settings and login again.

Here are proposals for new behavior:

  • any existing manual networks are always shown in the nm-applet menu's list of available networks
  • an alternative would cause specific SSID-specific scans to be done for any manual networks in addition to the periodic broadcast scans; if responses are received from the networks, they are added to the list of available networks
  • after switching networks or re-booting the device, the user must use the Connection Manager to connect to any manual networks

Refresh Scan / Networks One of the things that's very frustrating about the current implementation of NetworkManager is that user is not given any control over the Wi-Fi scanning process, nor is much feedback given to the user other than the list of networks being updated periodically.

Two suggestions are:

  • Refresh Scan / Networks menu item - this item would force an active scan to occur. This could alternately be added to the Connection Manager application instead of the applet's menu.
  • Active Scan Notification - if an active scan is in progress, some sort of visual feedback would let the user know that something was going.

Simplified Connection Information If the device is connected to a network, when the user right-clicks the nm-applet icon and then clicks the Connection Information menu item, a dialog titled Connection Information is displayed. This dialog is read-only and displays the following information:

  • Interface:
    • o Wired Ethernet ( eth0 ) * o Wireless Etherenet ( ath0 )
  • Speed ( eg. 24Mb/s )
  • Driver ( eg. asix - Ethernet, sdhci - Wi-Fi )
  • IP Address, Broadcast Address, Subnet Address, Default Route, Pri/Sec DNS
  • Hardware Address ( ie. MAC / BSSID )

This dialog should be simplified. Consumers don't care about drivers and/or device names. Also terminology needs to be fixed, Wireless Etherent should be replaced with Wi-Fi and/or 802.11a/b/g. Other Wireless Technologies Currently nm-applet displays a menu item for Wired Ethernet ( if an Ethernet cable is plugged in with hot carrier ) and Wireless Ethernet. If a device has additional wireless capabilities ( eg. WiMax, 3G, etc... ) in addition to Wi-Fi, then dynamic menu items should be added for these connections. In addition, as with Wi-Fi, if credentials are needed to connect, then protocol-specific dialogs need to be added for gathering credentials.

In addition to the main menu and credential dialogs, the Connection Information dialog will need to support any additional wireless protocols. Miscellaneous Changes

  • What happens when the number of visible networks is large ( ie. more than 20? ); does the current nm-applet implementation gracefully handle this?
  • Insecure Access Point Filtering - a preference to hide / prevent insecure access points from appearing in a scan list
  • Refresh nm-applet menu on state changes - if the nm-applet main menu is displayed, and some state change occurs, the menu sometimes doesn't update until it's dismissed and re-displayed ( Note - need to check the NetworkManager bug list to see if this is already a bug ).




Test/Demo Plan

It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during CD testing, and to show off after release.

This need not be added or completed until the specification is nearing beta.

Outstanding Issues

BoF agenda and discussion

Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.