Ubuntu Wiki

This is an incomplete, in-progress, and partly-implemented specification for Ubuntu’s networking features on PC and phone.

Ubuntu lets you connect to the Internet and other networks in various ways, including Wi-Fi, Ethernet (PC only), PBX (phone only), cellular data, and Bluetooth. This is implemented using NetworkManager (upstream, Ubuntu package, Ubuntu bug reports) and oFono (upstream, Ubuntu package, Ubuntu bug reports).

If you need help with networking in Ubuntu, see Ubuntu Help “Internet and Networking”.

Overall interface structure

On all form factors, the networking interface is based on System Settings panels and indicator menus. On a phone or tablet, both the settings panels and the menus are broader (showing more at the top level) than on a PC, because network connection is usually more variable and more expensive than it is on a PC.

On all form factors, there are also occasional dialogs (for example, for Wi-Fi suggestions or captive portals) and notification bubbles.

Settings

On a PC, networking settings should be shown in a single System Settings “Network” panel, with tabs for “Connections”, “VPNs”, “Proxies”, “Firewall”, and “Sharing”. At the bottom left of the panel should be a “Show network status in the menu bar” checkbox (fixing bug 829673).

because cellular and Bluetooth connections are networking settings should be split across the System Settings “Flight Mode” top-level item, and the “Wi-Fi”, “Cellular”, and “Bluetooth” screens.

Network activity menu (phone/tablet)

On a phone or tablet, it is useful to know when apps are using the network, for several reasons:

• You may want to check that nothing important is using the network before turning on Flight Mode.
• Since the device is highly mobile and does not have a wired connection, you may want to check before moving into a space that has no networking (such as a lift/elevator or subway).
• Data can be expensive, and even Wi-Fi data may be subject to a bandwidth limit.
• On a phone, screen real estate is at a premium, and apps may not have room for custom progress feedback.
• Often an app’s developer will have a faster connection than their users, and so may not provide enough custom feedback when a task is waiting on the network.

All these reasons apply much more to a mobile device than to a PC.

Therefore on the phone and tablet only, the “Network activity” indicator, a spinner, should be present whenever any process has used the network in the past five seconds. Its menu should list all applications that have used the network in the past five seconds, most recent first but updating only once every five seconds.

Network menu (all form factors)

People will usually open the Network menu when something is wrong with their Internet connection. The menu should let you see at a glance whether you are connected to the network, and if so how; switch quickly between likely connection methods; and access more detailed network information and settings.

Title

On the PC, the title of the menu should show the most unusual method by which the computer is currently connected to the Internet, or that it is not connected at all. So it should consist of an icon:

• if the computer is in Flight Mode, a Flight Mode icon; ✈

• otherwise, if there is an active mobile broadband connection, the mobile broadband icon for the current signal strength;

• otherwise, if there is an active wired connection, the wired connection icon;

• otherwise, if there is an active wireless connection, the wireless icon for the current signal strength;

• otherwise, if a mobile device is connected but has no network connection, the mobile disconnected icon (because a PC needs to distinguish this state from “no mobile device connected”, which a phone doesn’t need to do);

• otherwise, if a wireless card is turned on but has no network connection, the wireless disconnected icon;

• otherwise, if there is a wired networking device but it is not detected, the wired disconnected icon;

• otherwise, a red icon.

The accessible name for the title should consist of the word “Network”, a space, and then bracketed text equivalent to the icon. For example, “Network (Flight Mode on)”, “Network (mobile, 1 bar)”, “Network (wireless, 70%)”, “Network (wired)”, “Network (mobile, disconnected)”, “Network (wireless, disconnected)”, or “Network (none)”, respectively.

On the phone, because there are more connection types and they are more variable, the title should have three components. The first component should be:

• the Flight Mode icon if Flight Mode is on; otherwise
• “No SIM” if no SIM is detected; otherwise

• “SIM locked” if a SIM is present but locked; otherwise

• “SIM error” if a SIM is present but otherwise unusable; otherwise
• “No service” if no cellular network has been chosen; otherwise
• from 0 to 5 bars representing the call signal strength, if wi-fi is on; otherwise
• from 0 to 5 bars representing the cellular data signal strength, if cellular data is on; otherwise
• from 0 to 5 bars representing the call signal strength, if there is no current data connection.

The second component should be 🌐 a roaming icon if you are currently using data roaming. Otherwise it should not be present at all.

The third component should be:

• an animated wi-fi icon if wi-fi is connecting; otherwise
• from 0 to 4 arcs representing the wi-fi signal strength if wi-fi is on; otherwise
• “3G” if the current data connection is 3G
• “EV” if it is EV-DO
• “H+” if it is HSPA+
• “L” if it is LTE

• “E” if it is EDGE (up to 236 kbit/s)

• a tortoise if it is slower than EDGE, for example GPRS (up to 20 kbit/s) or 1xRTT (up to 153 kbit/s)

• “×” if there is no current data connection.

(Because wi-fi is displayed instead of cellular data connection, you may be unaware that you have lost the cellular data connection necessary to send an MMS. This is the tradeoff for the space saved by showing just one at a time.)

Structure

On the PC, if the networking service cannot be found, is in the process of being restarted, or no networking devices are available (e.g. no Ethernet card or wireless card), the menu should contain only an insensitive “Networking not available” item (deliberately sentence case), a separator, and “Network Settings…”. (This should hardly ever happen.)

Otherwise, the menu should consist of some combination of sections, in order:

1. Flight Mode (absent by default on PC, always present on phone/tablet)

2. wired (absent by default)

3. Wi-Fi (present by default for each wi-fi card present)

4. cellular (present by default for each cellular device present)

5. Bluetooth (present by default for each Bluetooth device present)

6. VPNs (absent by default)

7. connection sharing (absent by default)

8. “Cellular Settings…” (present on any device with a SIM (bug 1252801), except at the login screen on PC)

9. “Network Settings…” (always present, except at the login screen on PC).

Most of the time, only a few of these sections will appear — depending on what kinds of cards are fitted, what devices are connected, and other settings as specified later. On the PC, any two adjacent sections should have a separator between them, except that “Share Connection…” and “Network Settings…” should not have a separator between them.

On a device with a locked SIM, the “Network” menu should include an “Unlock SIM…” item immediately before “Cellular settings…”, and that item should be insensitive whenever the unlock UI is currently being shown. Regardless, when wi-fi is on, the menu should list wi-fi networks in the same way as the Wi-Fi screen of System Settings, without the “Other network…” item, and with an insensitive item “No networks detected” instead of the placeholder text.

Session variations

This is a summary only; the specifications of individual items are authoritative.

In the guest session, live session, and standalone installer session, the indicator and menu should be present as normal.

In the login screen, you should still be able to connect to networks so that you can use remote login. Therefore, the indicator and menu should be present as normal, but on the PC, any items that lead to System Settings should be insensitive.

When an app tries to use the Internet

(bug 1275761)

TBD

Connections

Flight Mode

Flight Mode is an easy way to turn off all radio functions in a hurry, for example when you are on a flight that requires this. But it is not draconian; for example if you are on a flight that offers Wi-Fi, you may turn on Wi-Fi individually, while Flight Mode continues ensuring that other connections are off.

When you turn on Flight Mode:

1. If a phone or Voip call is in progress, an alert should appear, “Turning on Flight Mode will end your call.”, with buttons “Cancel” and “End Call”. The alert should close automatically if the call finishes by itself. Then, or if you choose “End Call” yourself, or if no call was in progress in the first place:
2. If an upload or download is in progress, an alert should appear, “Turning on Flight Mode will stop all uploads and downloads.”, with buttons “Cancel” and “Stop”. The alert should close automatically if all transfers finish while it is open. Then, or if no transfers were in progress in the first place:
3. All radio transmitting/receiving functions should turn off, including Wi-Fi, Bluetooth, GPS, and cellular connections.

While Flight Mode is on, you may individually turn Wi-Fi and/or Bluetooth back on again, leaving Flight Mode itself turned on.

When you turn off Flight Mode:

• Any transmitting/receiving functions that you changed, since Flight Mode was turned off, should remain as they are.
• Any other transmitting/receiving functions should return to the state they were in immediately before Flight Mode was turned on.

Test case: Turn on Wi-Fi and Bluetooth. Start a phone call. Turn Flight Mode on; the alert should appear. Have the other party hang up; the alert should disappear, Flight Mode should turn on, and Wi-Fi and Bluetooth should both be off. Turn Wi-Fi back on; Flight Mode should remain on. Turn Wi-Fi back off again; nothing else should change. Turn Flight Mode off; Bluetooth should turn on but Wi-Fi should stay off.

Flight Mode in System Settings

Erratum: The item should be at the top of the pane, not the bottom.

On the PC, at the top of the Network panel connection type pane should be a “Flight Mode” item, with a ✈ icon. The “Show Flight Mode in the network menu” checkbox should be insensitive whenever “Show network status in the menu bar” is unchecked.

On the phone and tablet, the quick access area should include a “Flight mode” switch, because it is the sort of setting you need to change quickly, and because it alters the state of settings in multiple category screens (and therefore does not belong in any of them alone). Its icon should represent the current Flight Mode state. Whenever you toggle Flight Mode in either direction, the icon should become a spinner until all connections have stopped or resumed as appropriate.

Flight Mode in the network menu

On the phone and tablet, and whenever “Show Flight Mode in the network menu” is checked on the PC, the network menu should begin with a “Flight Mode” toggle item followed by a separator.

Whenever Flight Mode is on, the title of the network menu should also be a ✈ icon.

Common behavior across connection types

PC: Connections in the PC “Network” panel

In the “Connections” tab, the device pane should list each device or card through which you could make a network connection. The items in the list should be, in this default order:

1. If the machine has any Ethernet cards, one item for each Ethernet card.
2. If the machine has any wireless cards, one item for each wireless card.
3. If the machine has any connected mobile broadband devices, one item for each device.
4. If the machine has any connected Bluetooth devices, one item for each Bluetooth device.

Each item in the list should have four elements:

• a colored bead icon representing whether the device’s state — powered off (grey), offline (red), connected but not on the Internet (yellow), or online (green);
• an icon representing the type of device (e.g. the Bluetooth icon);
• a label for the type of device (e.g. “Wired” or “Bluetooth”)
• a caption for the connection state — “Off”, “Not connected”, “Connected”, or “Online”.

The state icon and device type icon should both have empty “” accessible labels, because the same information is conveyed in the adjacent text.

The order of the items should determine in which order Ubuntu tries to use them, when turned on, to establish an Internet connection. Each item should be reorderable by dragging it (hinted at by switching to a drag cursor on mousedown), or by using Ctrl Up or Ctrl Down when the item is selected.

At the bottom of the panel should be a checkbox, “Prompt whenever a new connection requires Web login”, checked by default for new user accounts. Changing it from unchecked to checked state (even by unchecking it then re-checking it) should immediately check the current connection (fixing bug 1072675).

Connection progress in the network/wi-fi menu

While Ubuntu for PC is trying to establish any network connection, the title of the network menu should be a spinner. Similarly, while Ubuntu Phone is trying to establish a wi-fi connection, the wi-fi indicator should be an animated wi-fi icon.

In both cases, the item for that connection should have a spinner too. If the connection is successful, the latter spinner should be replaced by a radio mark or checkmark as appropriate.

Connecting to a captive portal

Whenever Ubuntu makes a new network connection, if “Prompt whenever a new connection requires Web login” is checked, it should perform HTTP and DNS checks that the connection is valid. If it is not, a “Log In to {connection name}” dialog (on PC) or full-screen dialog (on phone) should open with a Web frame for the login page.

In the dialog, the Back and Forward buttons should behave as for a Web browser. The connection check should run again five seconds after you navigate to each page in the dialog, or 30 seconds * 2ⁿ since the nth connection check while the dialog has been open, whichever is sooner.

The dialog should close if a connection check succeeds, if you choose “Disconnect” in the dialog itself, or if you disconnect anywhere else (such as from the menu).

<xnox> e.g. in the installer we already are doing connectivity check against a known document http://start.ubuntu.com/connectivity-check.html
<xnox> which should have md5sum 4589f42e1546aa47ca181e5d949d310b

<xnox> mpt: the most silly thing about captive portals, is that some of them don't require one to login at all - just open it & look at advertisement. E.g. Virgin WiFi on the underground, after the first login, simply auto-redirects you to a ad.
<xnox> So one can try opening any page in the background to see if it's enough to establish connection ;-)
...
<xnox> mpt: it's reasonable to try this hack without pooping anything up, and if it fails then poop up the OpenZone dialog.
<mpt> xnox, as in make two HTTP requests and discard the first?
<mpt> That could work.
<xnox> yeah.

Disconnection

If you stop any connection from software (e.g. by choosing “Disconnect” in the menu), no notification bubble should appear (fixing bug 345824).

If a connection ends in any other way, a notification bubble should appear with the icon of the connection, “Disconnected” as primary text, and the name of the connection as secondary text. If the end result is no active connections, the primary text should be “Disconnected — offline”.

Wi-Fi

Summary: Wi-Fi networks are listed in System Settings, where you can reconfigure or reprioritize previously-used networks, and in the network menu. If Ubuntu does not connect to a previous network automatically, you can connect to a broadcast or hidden network from either of those places, or from a “Wi-Fi Available” dialog if Wi-Fi is on but you are not online. If connecting requires authentication details at any time, you are prompted for these in a dialog too. Whenever any of those dialogs is involved, connection success or failure is shown inside the dialog. If no dialog is involved, and the connection is not an automatic one to the previous network, connection success or failure is shown in a notification bubble instead.

Naming and listing Wi-Fi networks

Wi-Fi networks are listed in the network menu, System Settings, and Wi-Fi suggestion prompt. They are also mentioned by name in notification bubbles and dialogs.

For consistency across all these sites, except where otherwise specified:

• The network name should be the SSID, assumed to be UTF-8, with any line-break and direction-changing characters ignored.

• The signal strength icon should be a Wi-Fi icon showing from one to four bars for any currently broadcast or connected network. A network that is neither broadcast nor connected should have no signal strength icon at all.

• The signal strength accessible label should be “(Very weak)”, “(Weak)”, “(Moderate)”, “(Strong)”, or “(Not in range)”.

• The network type icon should be a picture of a PC (a bit out of date with tethering) if the network is ad-hoc, or else nothing at all.

• The network type accessible label should be “(Ad-hoc)” or else nothing at all.

• The network authentication icon should be a padlock if the network is encrypted, otherwise nothing at all.

• The network authentication accessible label should be “(Encrypted)” or else nothing at all.

Wherever networks are listed, except where otherwise specified:

• Each network’s visible label should consist of its signal strength icon, then its network type icon, then its network name (ellipsized in the middle if necessary), and at the trailing end of the space available, its network authentication icon.

• Each network’s accessible label should consist of its network name (not ellipsized), then its network type accessible label, then its signal strength accessible label, then its network authentication accessible label. For example, “calamari (Ad-hoc) (Moderate) (Encrypted)”.

Wi-Fi in “Network” settings (PC)

System Settings “Network” screen “Connections” tab should have a list item for each Wi-Fi card. In the usual case where there is only one, it should be labelled “Wi-Fi”. In the rare case that there are two or more, they should be labelled “Wi-Fi ({kernel ID})”, e.g. “Wi-Fi (wl0)”.

Each network detectable by the selected Wi-Fi card should be listed in the standard format, except that signal strength should be in its own “Signal” column, and there should be an extra “Last used” column, giving the time (if today) or date (if not today) that the PC most recently connected (manually or automatically) to that network.

By default, the list should be sorted most recently used first. Test case: From System Settings, connect to a network other than the most recent one; as soon as it connects, it should move to the top of the list.

Whenever the selected network requires authentication details that aren’t already stored, the “Connect” button should be “Connect…”, without the button changing width.

TBD: Include “Connect automatically”, “Prompt when not connected”, and reordering for parity with the phone.

At the bottom of the panel for each card should be a checkbox, “Let other users connect to these networks automatically”, checked by default.

“Wi-Fi” settings (phone)

Regardless of whether Wi-Fi is on, the System Settings “Wi-Fi” screen should contain a “Wi-Fi” switch, and “When Wi-Fi is on:” section (bug 1287249) with “Auto-join previous networks” checkbox, “Previous networks” item, and “Prompt when not connected” checkbox.

Whenever “Wi-Fi” is on and “Auto-join previous networks” is checked, Ubuntu should connect automatically to any remembered network when it is available. If you are disconnected and a scan shows more than one remembered network available, Ubuntu should prefer the one that has higher priority in the “Previous networks” list.

Whenever “Auto-join previous networks” is unchecked, Ubuntu should connect to a Wi-Fi network only if you explicitly choose it. For example, if you are disconnected, you should not be connected automatically to another remembered network. (This is so that, for example, you can be sure you are doing work on a work network and not the network of a nearby coffeeshop or the hotel where you’re staying.)

Whenever Wi-Fi is on, the screen should also contain an “Available networks:” section.

Whenever you enter the screen (either by navigating to it, or by switching back to System Settings), “Available networks:” should have a spinner opposite, and be followed by a radio list of networks:

• If you are currently connected to a network, that connected network followed by any other networks so far detected.
• If you are not, any networks so far detected, or the placeholder text “None detected yet” if there are none.

Networks should be listed in the standard format, except that for any network requiring authentication details that are not currently stored, its name should end in an ellipsis.

Once scanning completes, the spinner should disappear. If no networks were detected, “None detected yet” should change to “None detected”. The list should update every 10 seconds, with the spinner reappearing above the about-to-be-updated list.

Choosing a network should attempt to connect to it. And regardless of whether any other networks are detected, the list should end with a “Connect to other network…” item, which opens the “Connect to Other Network” dialog.

“Previous networks”

The “Previous networks” screen should list all remembered previously-used wi-fi networks by network name, in the order in which they would be chosen. Pressing on a network should make it draggable so that you can reorder the list.

On the dialog for an individual network, “Revert” and “Save” should be sensitive whenever you have made any changes since the details were last saved. If you choose “Forget This Network”, you should be returned to the “Previous networks” screen with that network removed from the list.

Wi-Fi in the network menu

Regardless of form factor, the network menu should have a section for each Wi-Fi card present. (Most devices have exactly one Wi-Fi card.) The section should consist of:

1. A toggle item for powering the card on and off. As with the Network Settings, in the usual case where there is only one wireless card, this item’s label should be simply “Wi-Fi”. In the rare case where there is more than one wireless card, it should be “Wi-Fi X”, where X = the kernel ID for the card, for example “Wi-Fi wl0”.

2. If the card is powered on, up to 6 (phone) or 20 (PC) radio items (bug 1322490) representing known Wi-Fi networks, all sorted alphabetically:

   • up to one item representing the network this card is connected to (or currently trying to connect to), if any;
   • the strongest of the currently-detected networks that this card has previously connected to, if any;
   • if any slots remain, the strongest of the other broadcast networks currently detected.

3. An “Other Network…” item that opens the “Connect to Wi-Fi Network” dialog. If the card does not currently detect any other broadcast networks, the name of the item should instead be “Hidden Network…”. If more broadcast networks have been detected than are shown in the menu, the item text should end with a count of all detected networks in brackets, e.g. “Other Network… (11 detected)”.

Wi-Fi networks should be listed in the standard format, with a radio mark if the card is connected to this network, or a spinner if it is currently trying to connect.

Suggesting that you connect to Wi-Fi

(bug 1287210)

A prompt should appear, suggesting that you connect to Wi-Fi, if all of these conditions are true:

1. “Prompt when not connected” is checked
2. you are not connected to the Internet, or you are connected using cellular data
3. Wi-Fi is on
4. Wi-Fi networks are available
5. The “Wi-Fi” (phone/tablet) or “Network” (PC) panel of System Settings is not currently focused (which would make the prompt redundant)

6. you are on a PC, or a phone/tablet app tries to use the Internet

7. Since you last dismissed the prompt (if ever), either:
   1. you turned Wi-Fi on, or
   2. at least one hour has passed, or
   3. the device has slept.

Test case: Turn on “Prompt when not connected”. Leave/close System Settings. Turn Wi-Fi off. Go to an area where Wi-Fi networks are available. Turn Wi-Fi on; the prompt should appear.

Available networks should be listed in the standard format.

As in System Settings, whenever the selected network is one requiring authentication details that aren’t already stored, the “Connect” button should be “Connect…”, without changing width.

When Ubuntu successfully connects to a wireless network, a notification bubble should appear with the icon of the connection, “Connected” as primary text, and the name of the network as secondary text.

Authenticating to a Wi-Fi network

You may need to authenticate to a Wi-Fi network when connecting to it from from a variety of entry points, including the installer, System Settings, or the network menu (PC) or Wi-Fi menu (phone). You may also be prompted to authenticate when an automatic connection fails because the authentication details no longer work (for example, the shared password has changed). Least often, you may want to change authentication details for a network you are not currently connected to (“Previous networks”), for example when you receive new details over the phone or by secure e-mail.

It is often tempting to design custom authentication UI embedded into those individual entry points. But that has several disadvantages. First, it reduces consistency between the entry points. Second, it reduces consistency between entering authentication details for a broadcast network and a hidden one, if the entry point even gets around to allowing this at all (for example bug 833312). And third, individual entry points often do not have room for showing all the necessary authentication controls: for example, PEAP authentication requires fields for outer identity, CA certificate, user name, and password, as well as the ability to reveal the typed password. And a menu in particular is impractical for selecting a CA certificate, user certificate, or private key, for showing connection progress, and for responding if authentication fails.

Therefore, the UI for entering Wi-Fi authentication details should always be a dialog — regardless of entry point, regardless of whether you are connecting to a broadcast or hidden network, and regardless of whether you are trying to connect to the network for the first time, correcting details to try a subsequent time, or changing details for a previous network.

On both PC and phone, the dialog should have title “Connect to {network name}”, “Connect to Other Network”, or “{network name} Network Details” for a previous network. In the first two cases it should have buttons “Cancel” and “Connect”; for a previous network, “Forget This Network”, “Cancel”, and “Save”. On the PC, the dialog should have the Wi-Fi icon, and for a broadcast network, the primary text ‘The Wi-Fi network “{network name}” requires authentication.’.

Connecting to a hidden or misdetected Wi-Fi network

Sometimes a Wi-Fi network does not broadcast its availability. And very occasionally, a network may broadcast the wrong security or authentication type, so that you need to override these to connect to it. Both these cases should be handled by a “Connect to Other Network” dialog. The dialog should be the same as for authenticating to a normal broadcast network, but with at least two extra controls, “Network name:” and “Wi-Fi security:”.

The “Network name” combo box should default to being empty; its menu should contain all the detected wireless networks, sorted alphabetically. Below the combo box should be a count of the detected networks, equalling non-hidden networks plus hidden APs.

The “Wi-Fi security:” menu should contain, in order, “None”, “WPA Personal”, “WPA Enterprise TLS”, “WPA Enterprise TTLS”, “WPA Enterprise LEAP”, “WPA Enterprise FAST”, “WPA Enterprise PEAP”, “WEP”, and “Dynamic WEP (802.1x)”. (This avoids having a separate menu for WPA Enterprise authentication varieties.) If Ubuntu is confident about which security type the selected network uses, the item for that type should end with “(detected)”, and it should be selected automatically as soon as you type or select that network, while still letting you override it.

Whenever a “Wi-Fi security:” method is chosen — either automatically or manually — the dialog should morph to show the authentication controls relevant to that method, replacing any authentication controls relevant to the previously chosen method (without forgetting any values you had typed into them, just in case you change back).

The fields following “Wi-Fi security:” should be whichever are appropriate for the chosen security type, as follows.

Authentication variations

In both the ‘Connect to “{network name}”’ and “Connect to Other Network” dialogs, the contents of the dialog, and the behavior of the “Connect” button, should vary depending on the authentication method.

“Connect” should be sensitive whenever the current values for those fields are plausible. When you choose it, a spinner should appear on its leading side until connection is complete. If authentication fails, the first authentication field (e.g. “Password”) should be focused and have error highlight. If there is any other error, the “Network” field should be focused and have error highlight. If connection succeeds, Ubuntu should return to the “Wi-Fi” screen, with the network list scrolled enough to show the connected network as a newly-added item.

Notification of successful connection

Whenever you connect to a Wi-Fi network via the “Connect to {network name}” dialog (whether invoked manually, from a suggestion, or from an error), or by the “Connect to Other Network” dialog, successful connection is confirmed by the “✔ Connected” appearing in the corner of the dialog. Any other notification would be redundant.

Whenever Ubuntu connects automatically to the same network as it was connected to previously, this is not a surprise. Most likely it is your home network, office network, or network of somewhere you left briefly. Again, notification would be redundant.

Therefore, a notification bubble should appear when Wi-Fi connects only if it is an automatic connection to a network different from the one you were last connected to.

The bubble should have a Wi-Fi icon representing the signal strength, primary text “Connected”, and secondary text the SSID of the network.

Cancelling a connection

If you cancel a Wi-Fi connection at any point, Ubuntu should resume its previous connection state — whether that was connected to another network, or to no network at all.

Wi-Fi network data

Settings for a wireless connection:

• Network (SSID)
  • usually chosen from a list
  • manually entered for a hidden network
  • we can detect how many hidden networks are available
• Authentication method: None / WEP Open Key / WEP Shared Key / WPA / WPA2
  • correctly auto-detected ~98% of the time (maybe hide it by default)
• password
• feedback on connection process
  • with WEP, you have to wait for a long timeout to tell that the password was wrong
  • with other security types, you can tell immediately
• IPv4 mode: DHCP (Renew DHCP Lease) or Manual
• network settings (with DHCP, all are automatic but overridable)
  • Name servers (zero or more, but without one you can't use domain names)
  • Domains (zero or more, e.g. "millbank")
  • IPv4 address
  • IPv4 netmask
  • IPv4 gateway
  • (IPv6: not implemented yet)
  • passphrase
  • autoconnect
    • enabled/disabled
  • nameservers
    • list of servers, in priority order
    • if empty, automatic servers used
  • domains
    • list of domain names
    • if empty, automatic domains used
  • ipv4
    • method:
      • dhcp
      • manual
        • address
        • netmask
        • gateway
      • off
  • ipv6
    • method:
      • dhcp
      • manual
        • address
        • netmask
        • gateway
      • off
  • proxy
    • method:
      • direct
      • auto
        • url (if empty wpad is used)
      • manual
        • servers
        • excludes

Wired connections (PC only)

Connecting to a wired network, in general

When Ubuntu tries to connect to a wireless network, in addition to the standard connection feedback:

If connection is successful, a notification bubble should appear, with a wired icon, primary text “Connected”, and secondary text the connection name e.g. “Wired connection 2”.

Wired devices in the Network Settings window

Wired section of the network status menu

If the computer has any Ethernet cards, the menu should begin with a wired section. This section should consist of a toggle item for each wireless card, where toggling the item controls both whether it is powered on and being used.

In the usual case where there is only one Ethernet card, its label should be simply “Wired Connection”. In the rare case where there is more than one Ethernet card, the label for each should be “Wired Connection N”, where N = the kernel ID for the card, e.g. “Wired Connection eth1”. If there is no link (e.g. the cable is unplugged), the item should be disabled but not hidden.

We may need to distinguish between {power off, power on but not connected, connected}.

Data

• autoconnect
  • enabled/disabled
• nameservers
  • list of servers, in priority order
  • if empty, automatic servers used
• domains
  • list of domain names
  • if empty, automatic domains used
• ipv4
  • method:
    • dhcp
    • manual
      • address
      • netmask
      • gateway
    • off
• ipv6
  • method:
    • dhcp
    • manual
      • address
      • netmask
      • gateway
    • off
• proxy
  • method:
    • direct
    • auto
      • url (if empty wpad is used)
    • manual
      • servers
      • excludes

Cellular connections

SIM identifier

A cellular device on a PC, and a SIM slot on a phone, is interesting only if it contains a SIM. When there are multiple SIMs, they should be distinguished to users using a SIM identifier that has two segments with a space between them: for example, “Slot A (01632123456)” or “SIM 2 (310150123456789)”.

• On a phone, the first segment should be customizable by the hardware vendor, for example “Front Slot” and “Rear Slot”. If it has not been customized, it should be “SIM 1”, “SIM 2”, etc.

• The second segment should be in brackets: the phone number, if it is available, otherwise the IMSI.

“Cellular” settings on phone

• Blueprint: https://blueprints.launchpad.net/ubuntu/+spec/client-1303-telephony-stack

At the top level of System Settings, “Cellular” should be present only when the device contains cellular hardware (bug 1258210).

On a single-SIM phone, “Cellular data:” (1) should be followed by radio options for “Off”, “2G only”, and “2G/3G/4G (faster)”, with the last option being present only if it is possible with the SIM (bug 1211804). On a dual-SIM phone, “Cellular data:” should be followed instead by radio options for “Off” and each SIM. Whenever the selected SIM allows multiple data connection types, there should then be another radio list containing those choices.

“Data roaming” (2) should be both off and insensitive whenever “Cellular data:” is “Off” (bug 1287260). When you turn “Cellular data:” to any other value (bug 1211804), “Data roaming” should become sensitive and return to its previous value.

“Data usage statistics” (3) should navigate to the “Data usage” screen.

“For outgoing calls, use:” (4) should be present only on a dual-SIM phone.

On a single-SIM phone, “Call roaming” (5) should be a single switch. On a dual-SIM phone, “Call roaming:” should be a list of switches, one for each SIM.

“Carrier”/“Carriers” (6) should navigate to the “Carrier”/“Carriers” screen.

“Data usage“

(bug 1287267)

“Data usage statistics” should navigate to a “Data usage” screen. On this screen, “Reset Statistics…” should display an alert with the text “All data usage statistics will be set to zero.”, and “Reset” and “Cancel” buttons.

“Carrier”/“Carriers”

When the phone has a single SIM card inserted, the “Cellular” settings screen should include a “Carrier” item, with the name of the current carrier (or “None” otherwise) as its value (bug Bug:). When the phone has two SIM cards inserted, the item should instead be “Carriers” and should have no value.

When there is single SIM card, “Carrier” should be a single screen.

Whenever “Choose carrier:” is set to “Automatic”, that choice should be followed (bug 1319044) by an insensitive list item with the name of the automatically selected carrier (or “None” otherwise).

Whenever you switch “Choose carrier:” from “Automatic” to “Manually”, or enter the screen when it is already set to “Manually”, instead of or replacing that list item, a spinner should appear below with the caption “Searching” (bug 1287269). These should be replaced by an alphabetical list of detected carriers once it is available (bug 1287271). Should we show the signal strength of each? If the list is longer than the rest of the screen, the list should scroll, and its initial scroll position should be such that the currently selected carrier is visible.

When you choose a carrier, the radio mark preceding the previous carrier (if any) should be replaced by a spinner preceding the newly-selected carrier (as in menu layout), and the amount of time the registration has taken so far should be shown at the trailing end in the form “M:SS”. If registration succeeds, that duration should disappear, and the newly-selected carrier should gain its radio mark. If registration fails, the list should revert to its previous display, and an alert should appear with the title “Error”, text “Registration failed. Try again later, or contact the carrier.”, and an “OK” button (bug 1211808).

When there are two or more SIM cards, “Carriers” should have a page stack item for each SIM card, with the SIM ID as its introductory label, and the name of the current carrier (or “None” otherwise) as the label of the item itself. Choosing a SIM card item should navigate to a screen that has the SIM ID as its header, but otherwise behaves exactly the same as the “Carrier” screen for a single SIM.

“APN”

(bug 1225174)

The “Internet APN:” and “MMS APN:” radio lists should include an item with the Name of each applicable APN known for the current carrier+country, followed by an item with the domain name of the current APN if you are currently using a custom one, followed by a a “Custom…” item for specifying a different one. If you change from a custom APN back to one of the preset APNs, any custom settings should be remembered (so you don’t need to retype them if you changed the setting by accident), but not used.

“Reset APN Settings…” should open an alert, “Are you sure you want to reset APN settings?”, with “Cancel” and “Reset” buttons. If you choose “Reset”, Ubuntu should discard any custom settings and restart the process of finding suitable APNs automatically.

Choosing “Custom…” in either list should open the relevant sheet.

“Internet APN”, “MMS APN”, “MMSC”, and “Proxy” should be URL fields (using the URL OSK and ignoring non-URL characters), assuming http:// if no protocol is entered. In the “Proxy” field, typing “:” in the domain should not enter that character, but should automatically navigate to the “Proxy port” field.

“Proxy port” should be a whole number field (using the number OSK and ignoring non-digit characters). In addition, if you paste a colon-delimited proxy:port combination into the “Proxy” field, the port should replace the existing contents of the “Proxy port” field, while the rest of the URL ends up in the “Proxy” field.

The “Authentication” menu, once implemented, should contain “None” (the default), “PAP or CHAP”, “PAP only”, and “CHAP only”.

The “Protocol” menu, present once IPv6 has been implemented, should contain “IPv4”, “IPv6”, and “IPv4v6”.

In the “Custom MMS APN” sheet, whenever “Same APN as for Internet” is checked, the “MMS APN”, “User name”, “Password”, “Authentication”, and “Protocol” fields should all be insensitive and set to the values for the Internet APN.

In both sheets, “Set” should be insensitive whenever any of the fields does not have a valid value.

Cellular devices on PC

If any cellular devices are connected to a PC, or if it has any Bluetooth cards turned on, the network menu should have a cellular section. (We deliberately exclude from this menu the interface for turning Bluetooth as a whole on or off.)

The cellular section should begin with a “Cellular Setup…” item that opens the “Cellular Setup” window.

Following this, if a cellular device is connected or a Bluetooth modem is connected and configured, and any cellular connections have previously been configured, these connections should be listed as switch items. Toggling an item should connect or disconnect.

These are the parameters for mobile broadband connections:

• PIN for SIM card
  • may prompt each time or optionally remember it
  • 4~8 digits [3GPP TS 11.11 V8.14.0 (2007-06), 9.3 Definitions and coding]
  • If you enter the wrong PIN 3 times, the SIM will lock you out
  • the hardware may tell Ofono that a PIN isn't necessary
• APN (access point name)
  • e.g. "INTERNET", "bam.entelpcs.cl"

  • hook into an existing database of APNs by country -> provider (-> plan)

  • also allow manual typing
  • maximum of 100 characters [3GPP TS 23.003 V9.2.0, 9.1 Structure of APN]
  • autoconnect
    • enabled/disabled
  • apn
  • nameservers
    • list of servers, in priority order
    • if empty, automatic servers used
  • domains
    • list of domain names
    • if empty, automatic domains used
  • ipv4
    • method:
      • fixed (user can't edit)
  • ipv6
    • method:
      • fixed (user can't edit)
  • proxy
    • method:
      • direct
      • auto
        • url (if empty wpad is used)
      • manual
        • servers
        • excludes

Setting up a cellular connection, prompted

If, while you are logged in, you connect a cellular device to a PC, a “Cellular Connection” dialog should appear. If you disconnect the device, the dialog should close automatically.

The dialog’s primary text should be “You’ve connected a mobile device. Do you want to use it to connect to the Internet?” If the device requires a PIN, there should be a “Device PIN:” field, a “Show PIN” checkbox, and an “Authorize” button.

The “Device PIN:” field should be a password field whenever the “Show PIN” checkbox is unchecked, and a normal text field whenever “Show PIN” is checked. Entering any non-digit character, in any way, should produce an alert sound instead of accepting the character.

Test case: Check “Show PIN”. Copy these characters “1 2 3 4” to the clipboard. Paste them into the “Device PIN:” field. The field should contain “1234”.

The “Authorize” button should be the default button whenever the “Device PIN:” field is focused. It should be sensitive whenever the “Device PIN:” field contains from 4 to 8 digits inclusive.

All other controls in the dialog should initially be insensitive, except for the “Cancel” button.

Activating the “Authorize” button should make it insensitive, and make a spinner with the text “Authorizing…” appear at the trailing end of the dialog below the button, for as long as it is trying to authorize with the entered PIN.

If the PIN was incorrect, the primary text of the alert should change to: “The PIN was incorrect. If you enter an incorrect PIN too many times, the device SIM may become locked.” The PIN field should then be focused, and the “Authorize” button should resume sensitivity.

If the authorization succeeded, the “Device PIN:” field should also become insensitive, the “Authorize” button should become an “✔ Authorized” label, the access point controls should become sensitive, and “Connect” should become the default button.

The access point controls should begin with “Access point:” radio buttons: “Automatic” (the default) and “Manual”.

Whenever “Automatic” is selected, the radio buttons should be followed by “Region:” and “Provider:” option menus, populated by the Service Provider Database, and an “APN:” caption displaying the APN for the selected region and provider.

Whenever “Manual” is selected, the radio buttons should be followed by an “APN:” text field. This field should accept a maximum of 100 characters; entering any more should produce an alert sound instead of accepting them.

What other server/domain settings do we need?

The “Connect” button should be sensitive whenever either a provider is chosen from the “Provider:” menu, or if the “APN:” field is non-empty. Activating the button should make a spinner and the caption “Connecting…” appear in the bottom leading corner of the dialog, change the “Cancel” button to “Stop” (without changing its width), and desensitize the access point controls and the “Connect” button, while trying to connect.

If you activate “Stop”, the connection attempt should stop, the button should desensitize for two seconds (to ignore you if you double-clicked it by mistake), it should turn back into a sensitive “Cancel” button, and the access point controls and the “Connect” button should resume sensitivity.

Setting up or changing a mobile connection, unprompted

In the “Network Settings” window, the pane for a mobile device should consist of controls that look and behave identically as in the “Mobile Connection” dialog, except that:

• The top of the pane should be a status panel, with text of one of these forms:
  • Not connected.
  • ❊ Connecting…

  • Could not connect to {provider}. Can we be more specific?

  • You’re connected to the Internet on {provider}.
  • You’re connected to {provider}, but not on the Internet.
  The name of a provider should be surrounded by “” quotes if it is a raw APN.

• There should be no “Cancel” or “Connect” buttons. Instead, at the trailing end of the status panel, should be a switch that is sensitive if settings are sufficient to attempt a connection. The switch should be ON whenever the device is connected or attempting a connection, and OFF otherwise.

• All the controls, except the status panel and the “Show PIN” checkbox, should be insensitive whenever you are connected.

So, the process for setting up a mobile connection without using the dialog is:

1. Open the Network Settings.
2. Select the mobile device in the left pane.
3. In the right pane, enter the device PIN and activate “Authorize”.

4. Once authorized, enter the access point details, and switch the connection ON.

And the process for changing a connected mobile connection is:

1. Open the Network Settings.
2. Select the mobile device in the left pane.

3. In the right pane, turn the switch OFF.

4. Change the access point details, then turn the switch back ON.

“Mobile Setup” window

So that you can easily connect to the Internet using a Bluetooth phone that you may not have paired yet, the “New Mobile Broadband Connection” window should be altered to provide easy access to pairing.

...

Bluetooth connections (PC only)

Things to expose:

• shouldn't need to enter anything after pairing Bluetooth device
• from iPhone, is triggered from the phone, then appears in Mac OS X as a wired connection
• connection type: PAN/DUN (usually automatic, occasionally wrong)
  • PAN (Personal Area Networking) [some phones, e.g. iPhones]
  • DUN (dial-up networking) [other phones] - not yet implemented
• manual settings
  • IP address, DHCP, DNS (usually automatic)

Data

• autoconnect
  • enabled/disabled
• nameservers
  • list of servers, in priority order
  • if empty, automatic servers used
• domains
  • list of domain names
  • if empty, automatic domains used
• ipv4
  • method:
    • dhcp
    • manual
      • address
      • netmask
      • gateway
    • off
• ipv6
  • method:
    • dhcp
    • manual
      • address
      • netmask
      • gateway
    • off
• proxy
  • method:
    • direct
    • auto
      • url (if empty wpad is used)
    • manual
      • servers
      • excludes

To do

Settings to expose:

• Wireless
  • Removing stored wireless networks
• Any combination of these can be used simultaneously
  • One is the "main connection" (default route)
    • sends and receives your Internet traffic ("You're connected to the Internet using this connection")
    • affects your IP address
    • shown in the menu title
    • drag and drop -- top one in a list is the default route?
    • Do we want to convey it inside the menu too?
  • others are only for local network
• DNS
  • usually the same regardless of connection
  • often automatic, from DHCP lease
  • sometimes automatic from PPP

Spec: http://git.kernel.org/?<p=network/connman/connman.git;a=blob;f=doc/service-api.txt;hb=HEAD

VPNs

VPN section of the network status menu

The VPN section should be present whenever at least one VPN is set up. The section should begin with a “VPN Setup…” item that opens the Network Settings window to the VPNs tab.

Following that item, the configured VPNs should be listed as toggle items. Toggling an item should connect or disconnect from that VPN.

Proxies

Firewall (PC only)

See also Oneiric desktop networking enhancements.

The “Firewall” panel should start with status in one of these forms:

If “The firewall is on with custom settings” (for example, it is blocking any outgoing connections at all), all other controls in the panel should be insensitive, except for the “Advanced Settings…” and “Reset All…” buttons.

The list of applications should be sensitive only when “When the firewall is on, allow incoming connections to:” is set to “Essential services and these others:”.

If you choose “+” (which should have the accessible label “Add an Exception”), an “Add Exception” dialog should appear giving you the option of adding an application, service, or port.

Choosing “Advanced Settings…” should open a text editor to the ufw configuration file. Choosing “Reset All…” should open a confirmation alert of the form “Are you sure you want to delete all custom firewall settings?”. If you choose “Delete”, the ufw configuration file should be deleted and settings return to the “Essential services only” defaults.

Sharing

So you can easily share your connection regardless of whether it is wired, wireless, or mobile, there should be a single “Create/Share Connection” window.

PC-specific designs (to be integrated above)

Ubuntu’s networking interface should consist mostly of a “Network” panel in System Settings to cover networking in general, including connection setup, VPN, proxy, and firewall settings; and a network menu for quick access to connection settings.

Some of this interface is implemented in indicator-network on top of Connection Manager (a.k.a. ConnMan). The interface could also be implemented on top of Network Manager.

Artwork requirements

• Mobile connection icons (off, 0%, 20%, 40%, 60%, 80%, 100%)

• Wireless connection icons (off, 0%, 20%, 50%, 75%, 100%)

• Wired connection icons (off, on)

• Computer-to-computer network icon

• Padlock icon for encrypted networks
• Colored light icons for “connected”, “on but not connected”, and “off” (these are drawn dynamically using cairo and so are not needed as files)
• Flight mode icon

Future work

• Following the general principle that people open this menu for the purpose of fixing something wrong with their network connection, we should include, in the menu, items for turning off background tasks (such as Ubuntu One file syncing, or torrent seeding) that are consuming lots of bandwidth.

Locations

Above the tabs in the settings panel should be a “Location:” menu with a radio item for each location profile, followed by a separator and items ‘New Location…’, ‘Rename “{name of current location}”…’, and ‘Delete “{name of current location}”…’. By default, there should be only one location, “Anywhere”; when it is selected, the “Rename” and “Delete” items should be insensitive.

Optional extra: At the bottom of the “Location:” menu should be another separator, and finally a “Location Menu in Menu Bar” checkmark item. When it is checked, a location menu should appear in the menu bar, immediately on the leading side of the networking menu (or if the networking menu is turned off, immediately on the leading side of where it would be). This menu should have a globe icon as its title, and should contain a radio item for each location profile, followed by a separator and a “Network Settings…” item that opens the Network panel of System Settings.

Whichever way it is selected, choosing a location should change all networking settings to those that were last configured in that location.

Creating a location

Choosing “New Location…” should open a “New Location” dialog containing:

• a “Choose a name for the new location:” field that, if possible, is pre-filled with the GeoName nearest your current location;

• a “Based on:” menu listing the existing locations, with “Anywhere” as the default;
• “Cancel” and “Create” buttons.

The “Create” button should be insensitive whenever the current value of the “Choose a name for the new location:” field is identical to one of the existing locations.

When a new location is created, it should start out with the same settings as whichever location it was “Based on”.

Renaming a location

Choosing ‘Rename “{name of current location}”…’ should open a “Rename Location” dialog, containing only a ‘Choose a new name for “{name of current location}”:’ field (pre-filled with the existing name), and “Cancel” and “Rename” buttons.

The “Rename” button should be insensitive whenever the current value of the “Choose a name for the new location:” field is identical to one of the other existing locations.

Deleting a location

Choosing ‘Delete “{name of current location}”…’ should open a confirmation alert with primary text ‘Are you sure you want to delete “{name of current location}” and all its settings?’, secondary text “You last used this location on {date}”, and “Cancel” and “Delete” buttons.

Unresolved issues

• We need a thorough test suite for which wireless networks are shown in the menu.
• When showing networks in the menu, prioritize open networks.

• Compare with OpenSolaris equivalent: http://hub.opensolaris.org/bin/view/Project%20nwam/Phase1

• How is shown that Wired connection is ready (cable plugged in, DHCP settings received) compared to case that cable isn't plugged in or DHCP hasn't answered? Should the ON/OFF switch reflect the state or is it only for user controlling the power of that device? The question also applies to 3G.
• How to handle network updates while menu is open? In some cases networks might change a lot.
• What about usb connections (e.g. USB tethering with a cellphone or USB ethernet modems? They show up as "wired connections" or "generated ethernet connections" atm, what they might not be.

settings:

• edit connections functionality based on the connections property table, for all connection types
• connman doesn't support "last used" property, at least not yet
• how to show which wifi connection is connected? should we also show connecting states?
• how to disconnect connections from settings window?
• need to show which connections are saved or have details (connman's term is favorite). "Forget Details" button will remove the settings stored for these connections.
• wired settings window missing from the spec
• there should be a separate dialog for mobile PIN

icons:

• what icon to use as indicator icon in the panel when bluetooth connection is the default connection, otherwise there are two bluetooth icons on the panel (bluetooth and indicator-network)
• icon animation for each technology? (wired, wireless, mobile, bluetooth)
• strength icons for mobile and bluetooth as well

mobile wizard:

• when user plugs in a new modem, in some cases, we can automatically detect APN, but should we always ask for confirmation from the user?
• if we can't detect APN automatically, we need to ask from the user by showing a country/provider. how to show that?

dialogs:

• passphrase dialog
• PIN dialog

other:

• connection information dialog
  • IP settings
  • statistics
  • hardware information?
    • driver name
    • modem name and info
    • driver, firmware, hw versions