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)
• Flight mode icon

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”. Ctrl W should close the window.

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

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.

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 (mobile, 1 bar)”, “Network (wireless, 70%)”, “Network (wired)”, “Network (mobile, disconnected)”, “Network (wireless, disconnected)”, or “Network (none)”, respectively.

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. flight mode (not present by default)

2. wired (not present by default)

3. wireless (present by default for each wireless card present)

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

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

6. VPNs (not present by default)

7. connection sharing (not present by default)

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

A list of user editable settings per connection, created from the table and spec above:

Wifi

• 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

Ethernet

• 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

Bluetooth

• 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

• 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

Connection progress in the network menu

While Ubuntu is trying to establish any network connection, the title of the network menu should be a spinner, and so should the item for that connection inside the menu. If the connection is successful, the latter spinner will be replaced by a radio mark or checkmark as appropriate.

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: exactly 5, 10, 13, or 26 characters
  • 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

Connecting to a wireless network, in general

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

If the network requires authentication details you haven’t provided before, a dialog should open for you to authenticate.

Then, Ubuntu should attempt to connect to that network.

TBD: Specify error handling.

Wireless cards in the Network Settings window

For each wireless card detected, there should be an item in the connection type pane of the “Connections” tab of the Network Settings window. In the usual case where there is only one card, the item should be labelled “Wireless”. In the rare case that the computer has more than one wireless card, it should be labelled “Wireless ({kernel ID})”, e.g. “Wireless (wl0)”.

Wireless section of the network status menu

For each wireless card detected, the network status menu should have a wireless section.

The section’s first item should be a toggle item that powers the card on and off. (It also serves as a heading.) As with the Network Settings window, in the usual case where there is only one card, the item should be labelled “Wireless”. 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 20 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 ten items representing the strongest currently-detected networks that you have previously connected to on this computer, if any;
  • 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

• an accessible name of the form “(strength) (encrypted) name”, for example “(22%) edsel” or “(91%) (encrypted) Tachbrook Street”.

Re-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

There are three ways for you, unprompted, to connect the computer to a wireless network:

• by choosing it from the network menu
• by selecting it and choosing “Connect”, or by double-clicking it, in the Network Settings window
• by using the “Connect to Wireless Network” dialog accessed from either the menu or the Network Settings window.

Specifying a network any of these ways should cause Ubuntu to try connecting to it.

In the “Connect to Wireless Network” dialog, 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.

This should be followed by a “Wireless security:” option menu, listing all the types of wireless authentication knows about, in alphabetical order except that “None” should be first. If Ubuntu is confident about which authentication type the selected network uses, the item for that type should end with “(detected)”, and the menu should change to select it automatically when you choose that network.

Whenever a “Wireless 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.

Erratum: The “Hexadecimal” and “Ascii” radio buttons should not be present.

• For WEP, these controls should be a “WEP key:” field, and a “Show key” checkbox controlling whether the field contents are readable. Any non-Ascii characters entered in the field should be ignored with a beep. The “Connect” button should be sensitive only when the field contains exactly 5, 10, 13, or 26 characters.
• For WPA, the controls should be a “WPA key:” field, and a “Show key” checkbox controlling whether the field contents are readable. The “Connect” button should be sensitive only when the field contains from 8 to 64 characters.

Should we indicate an incorrect number of characters more obviously than by desensitizing the button?

When you choose “Connect”, the dialog should not close immediately. Instead, in addition to the standard wireless connection progress feedback:

• While Ubuntu is trying to connect:
  • A spinner and the text “Connecting…” should appear at the bottom leading corner of the dialog.
  • All controls in the dialog, except for the “Cancel” button, should become insensitive.
  • The “Cancel” button should change to “Stop” without changing size. If you choosing “Stop”, Ubuntu should stop connecting, and all the controls should resume sensitivity, so that you can revise the connection details.
• Once Ubuntu has connected successfully:
  • The spinner and “Connecting…” should change to a checkmark icon and the text “Connected”.
  • The “Stop” button should become insensitive too.
  • The dialog should close two seconds later.

Changing details for an existing connection

What do we need this dialog for?

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.

...

Flight mode

At the end of the 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.

Whenever “Show Flight Mode in the network menu” is checked, the network menu should begin with a “Flight Mode” toggle item followed by a separator.

Turning on Flight Mode should turn off all transmitting connection types — wireless, mobile, and Bluetooth. Turning off Flight Mode itself should resume whichever of those connections were on before Flight Mode was activated.

However, if you turn on any transmitting connection type while Flight Mode is on, Flight Mode should turn off automatically, but this should not turn on any of the other connection types. For example, if you turn on Flight Mode on an airplane that offers wireless Internet, turning on wireless later should not also turn on Bluetooth.

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

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