Shill

Updated May 2024

Packages

The primary package of the shill directory is shill. There are also additional support / utility packages:

• shill-client
• shill-dbus-client
• shill-test-scripts

Architecture

The Architecture document provides an overview of Shill's architecture.

Subsystem Documentation

• Cellular
• Routing subsystem
• VPN subsystem

Overview

Shill is the connection manager for Chrome OS. It is responsible for such functionality as:

• Setting up network interfaces to behave as desired, which involves:
  • Acquiring link information from the kernel.
  • Handling different logic for different network interface technologies like WiFi, Ethernet, or cellular.
    • For wireless interfaces, there may be many different “connectivity services” that can be connected to (e.g., different 802.11 ESSs within range of the WiFi adapter).
  • Potentially interacting with separate daemons, like wpa_supplicant for WiFi or 802.1X on Ethernet, or ModemManager for cellular, for technology-specific behavior.
  • Acquiring suitable IP configuration parameters, which may involve using DHCP.
• Persisting relevant user information, such as previously connected networks and associated credentials.
• Configuring DNS appropriately on the system.
• Properly handling multiple connected interfaces, including:
  • Prioritizing connected interfaces in a predictable and intuitive manner.
  • Routing traffic to comply with the interface prioritization and ensuring that traffic always goes out of the right interface(s) (traffic may go through multiple interfaces when virtual interfaces are involved).
• Providing VPN support for:
  • Third-party Chrome extensions that support the third-party VPN interface
  • Android VPN apps (which is primarily taken care of by patchpanel; Shill‘s main responsibility is to ensure that traffic which doesn’t originate in Android and should go through the VPN is sent to ARC rather than directly out of a physical interface).
  • Built-in OpenVPN (a very limited subset; it is recommended that OpenVPN users use an Android VPN app for this) and L2TP/IPsec VPNs.
• Detecting connectivity issues and trying to determine potential causes.
• Collecting non-privacy-invasive metrics to allow for a better understanding of user network experience (e.g., which WiFi disconnect reasons are most common? What is the usage of WiFi vs. Ethernet vs. cellular?).

In addition, Shill provides a D-Bus service for use by D-Bus clients. One of the largest clients is Chrome, which provides an actual UI for the underlying network functionality provided by Shill. Chrome both drives some part of Shill state (e.g., a user pressing a Connect button for a WiFi network, which causes Chrome to call the Connect D-Bus method) and reads Shill state (e.g., to display the proper network icon and provide accurate and up-to-date network information). Policy-derived network configuration is also applied to Shill through Chrome.

Brief History

Shill is not the first connection manager that was used on Chrome OS. The first consideration was to use Intel's ConnMan connection manager. Following issues with upstream responsiveness, Chrome OS forked ConnMan into the Flimflam connection manager. A number of remaining issues with the legacy of ConnMan, including a GPL license and a supposedly poor separation of concerns within the project, led to the decision to create a new connection manager and hence Shill was born.

Initially, the intention was for Shill to be D-Bus compatible with Flimflam, allowing for the two to be interchangeable. D-Bus API compatibility with Flimflam is no longer of any interest. Future changes to both the architecture and D-Bus interface of Shill should be made on the basis of suitability to our needs and the maintainability of the project. Ultimately the legacy of ConnMan still lives within Shill to some degree based on that initial decision to design Shill around Flimflam's D-Bus API, and future design decisions must be evaluated with the understanding that the goals and requirements for Shill are not what they were in 2012.

D-Bus Interface Specification

• Manager D-Bus Specification
• Device D-Bus Specification
• Service D-Bus Specification
• Profile D-Bus Specification
• IPConfig D-Bus Specification

Command Line Interface

Shill is controlled exclusively via D-Bus, and currently (see also b/172222930), there is no proper Command Line Interface for it. Instead, there are a patchwork of scripts and utilities that can be useful in a pinch.

• “flimflam” test scripts: these provide many small scripts wrapping parts of the D-Bus API; they are inconsistently maintained and may not all work. Written in Python, and only available on test images.
• /usr/local/autotest/cros/scripts/wifi: useful for connecting to WiFi networks. Written in Python, and only available on test images.
• connectivity: shell script that dumps Device or Service information. Available on all images.
• ff_debug: configures “flimflam” debugging level. See also TESTING docs. Available on all images.
• network_diag: dump general networking and connectivity diagnostics.

There are a variety of other connectivity-related CLI tools which are useful, even if not directly tied to Shill:

• iw: tool for interacting with WiFi devices.
• iproute2: link and routing management tools (such as ip, tc, ss, ...).
• tcpdump: packet capturing and analysis.
• iptables, ip6tables: packet filtering utility.
• ping: generate ICMP traffic.
• traceroute, traceroute6: tool to track the route taken by IP packets from source to destination.
• dig: DNS lookup utility.

Some of these CLI utilities (or wrapper helpers) are also available in crosh. See its help_advanced output for info.