Ubuntu Wiki

This is an incomplete and in-progress specification for Ubuntu’s networking features, beginning with the networking settings in Ubuntu Netbook Edition 11.04.

Ubuntu will integrate Connection Manager (a.k.a. ConnMan), with a human interface — a settings window and a network menu — designed to cover networking in general, including network setup, proxy, and firewall settings.

For instructions on testing the new implementation, see ConnMan.

Artwork requirements

• Mobile signal strength icons (0%, 25%, 50%, 75%, 100%)
• Wireless strength icons (off, 0%, 25%, 50%, 75%, 100%)
• Wired connection icon
• 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)

Use cases

“Network Settings” window

The “Network settings” window should have a tab for “Connections”. In future it will also have tabs for “VPNs”, “Proxies”, “Firewall”, and “Sharing”.

Network status menu

People will usually open the 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

When there is networking, the title of the menu should consist of an icon:

• If there is an active mobile broadband connection, the mobile broadband icon for the current signal strength;
• otherwise, if there is an active wireless connection, the wireless icon for the current signal strength;
• otherwise, if there is an active wired connection, the wired connection icon;
• otherwise, if a mobile device is connected, the mobile disconnected icon;
• otherwise, if a wireless card is turned on, the wireless disconnected icon;

• otherwise, a red icon.

When there is no networking

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.)

Structure otherwise

When there is networking, the menu should consist of some combination of sections, in order:

1. wired (off by default)

2. wireless (on by default for each wireless card present)

3. mobile (on by default for each mobile device present)

4. Bluetooth (on by default for each Bluetooth device present)

5. VPNs (off by default)

6. connection sharing (off by default)

7. the “Network Settings…” item (always present).

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. Any two adjacent sections should have a separator between them, except that “Share Connection…” and “Network Settings…” should not have a separator between them.

Toggle items

Inside the network menu, a toggle item uses a switch with ON and OFF values. Activating a toggle item should visibly toggle the switch before closing the menu as normal.

Connections

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

Connections in the “Network Settings” window

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.

Dialog prompting for a new connection

Wired connections

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}.

Wireless connections

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
  • WEP key
    • ? need to manually specify hexadecimal or Ascii
  • WPA key
    • minimum of 8 characters

    • ? <=63 characters is Ascii

    • ? 64 is hexadecimal
  • optionally show the password in plaintext
• 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)
• what happens when there's a connection error?
  • you enter the wrong password

Wireless cards in the Network Settings window

Wireless section of the network status menu

For each wireless card detected, the network status menu should have a wireless section if the card’s “Show ______ in the network menu” checkbox is checked.

The toggle item, “Wireless”, should power the card on and off. It also serves as a heading. In the rare case that the computer has more than one wireless card, it should be labelled “Wireless ({kernel ID})”, e.g. “Wireless (wl0)”.

For each wireless card, there should be:

• A toggle item for powering the card on and off. In the usual case where there is only one wireless card, this item’s label should be simply “Wireless”. In the rare case where there is more than one wireless card, it should be “Wireless N”, where N = the kernel ID for the card, e.g. “Wireless wl0”.

• If the card is powered on, up to five items representing known wireless networks, sorted alphabetically:
  • up to one item representing the network this card is connected to (or currently trying to connect to), if any;
  • up to three items representing the strongest currently-detected networks that you have previously connected to on this computer;
  • the remainder representing the strongest other broadcast networks currently detected.

• An “Other Network…” item that opens the “Connect to Wireless Network” dialog. If the card does not currently detect any 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)”.

The item for any wireless network should consist of:

• a checkmark if the card is connected to (or currently trying to connect to) this network;
• an icon indicating signal strength, at the leading end;
• the name of the network;
• a computer icon representing a computer-to-computer network, if appropriate;
• a padlock icon representing an encrypted network, if applicable, at the trailing end.

Selecting the item for a wireless network that is currently connected should disconnect from that network.

Setting up a wireless connection, prompted #

Setting up a wireless connection, unprompted #

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

Mobile connections

These are the parameters for mobile broadband connections:

• PIN for SIM card
  • may prompt each time or optionally remember it (but no remembering for Maverick)
  • 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]

Mobile devices in the Network Settings window

Mobile section of the network status menu

If any mobile devices are connected, or if the computer has any Bluetooth cards turned on, the next section should be for mobile connections. (We deliberately exclude from this menu the interface for turning Bluetooth as a whole on or off.)

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

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

Setting up a mobile connection, prompted #

If, while you are logged in, you connect a mobile device to the computer, a “Mobile Connection” dialog should appear. If you disconnect the device, or connect the device to the Internet some other way, the dialog should close.

Should the dialog open even if you’re already connected to the Internet some other way?

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.

Bluetooth connections

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)

“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.

...

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

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.

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.

Unresolved issues

• How to turn the menu on or off.
• We need a thorough test suite for which wireless networks are shown in the menu.
• How to show the connection/disconnection process.
  • Showing it with the icon (like in the old connection manager) should do the job imho?
• We should have a single “Flight Mode” that turns off wireless, Bluetooth, and 3G.
• 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.