Skip to content

Latest commit

 

History

History
270 lines (217 loc) · 13 KB

architecture.md

File metadata and controls

270 lines (217 loc) · 13 KB

Shill Architecture

Updated June 2021

Shill

DaemonTask

The DaemonTask class is a singleton owned by the ShillDaemon class singleton.

It creates the following singleton classes (along with a few support/utility classes).

Manager

The Manager class is the "top-level" singleton class in Shill, created and owned by DaemonTask.

  • Manager is associated with the org.chromium.flimflam.Manager DBus API documented in manager-api.txt.
  • Manager includes a number of global properties, some of which are included in the DBus API, and some of which come from command-line switches.
  • Manager owns a DeviceInfo singleton which tracks network instances and creates corresponding Device instances.
    • Manager also owns a ModemInfo singleton for observing ModemManager1.Modem DBus objects.
    • Manager keeps its own list of Device instances and handles Registration, power management, and enabling/disabling network technologies (e.g. WiFi, Cellular).
    • The paths of available Device objects are available in the Manager.Devices DBus property.
  • Manager owns ServiceProvider instances for managing the creation and lifetime of Service instances.
    • Manager also keeps its own list of Service instances and handles Registration, power management, and AutoConnect.
    • The paths of visible Service objects are available in the Manager.Services DBus property, sorted by State and priority as described in manager-api.txt.
    • The paths of all Service objects, including saved (favorite) service configurations that are not visible, are available in the Manager.ServiceCompleteList DBus property, sorted as per Services.
  • Manager maintains the stack of Profile instances.

DeviceInfo

The DeviceInfo class is a singleton owned by Manager.

  • DeviceInfo listens to network interface and address-configuration events using RTNL.
  • On startup, DeviceInfo requests a dump of existing network interface and address-configuration information in order to be in sync with the current kernel state.
  • When DeviceInfo has enough information about a network interface for a technology backed by a Device, it creates an instance of the proper type. See CreateDevice in device_info.cc.
    • Some network interfaces are explicitly ignored by shill and managed by other entities: TAP devices and virtual ethernet interfaces are managed by patchpanel, some TUN devices may be created and managed by third-party VPN clients directly.
  • DeviceInfo also updates existing Device instances with new information that it receives about the corresponding network interface.
  • DeviceInfo is used by some VPN drivers for creating the virtual interface (TUN device, WG device) used by third party VPN clients.

Device

The Device class is a base::RefCounted class representing a network interface.

Device Inheritance

  • Device instances are managed by DeviceInfo.
    • Exception: VirtualDevice instances corresponding to virtual interfaces (for use-cases like VPN, and cellular dongles).

ServiceProvider

The ProviderInterface class is a common interface for singleton instances owned by Manager.

  • Each ServiceProvider is responsible for creating Service instances on startup and as required by the associated Device.
  • A separate ServiceProvider singleton exists for each primary Technology:
  • ServiceProvider instances create new Services from the persisted state in the Profile and/or properties from the D-Bus interface.
    • See CellularServiceProvider for CellularService provisioning.
    • The EthernetProvider by default has a single EthernetService, which the first Ethernet instance will use. Additional Ethernet instances will cause the EthernetProvider to create additional EthernetService instances.
    • For WiFiProvider, Services are also created based on network scans performed by wpa_supplicant, which leads to the reception of BSSAdded D-Bus signals that trigger WiFiProvider to create a corresponding WiFiService.

Service

The Service class is a base::RefCounted class representing a network configuration and a connection through an associated Device.

Service Inheritance

  • A Service has an associated Device instance, stored as a type specific RefPtr in the subclass.
  • Service lifetime is managed by the associated ServiceProvider singleton.

Profile

The Profile class represents a set of persisted data and is used for both Device and Service properties, as well as a handful of global properties. Shill keeps a Profile instance for shared/default properties, and a per-user Profile when a user is logged in.

  • Device and Service classes and their subclasses handle loading from and saving to the underlying storage used by the current Profile.
  • Shill allows for a stack of Profile instances. The Profile stack is owned by Manager.
    • On startup, the Profile stack contains a single DefaultProfile, which provides pre-login (shared) configuration data.
      • In addition to the regular Profile behavior of persisting Service properties, a DefaultProfile will also persist Device properties and a subset of Manager properties.
    • On user login, specifically when Chrome instructs session_manager to emit the load-shill-profile upstart event, the shill_login_user script is run.
      • This creates a Profile for the user and pushes that Profile onto the Profile stack.
    • On user logout, shill_logout_user removes the user's Profile from the Profile stack.
    • When a guest user logs in, a Profile is created and pushed onto the stack as usual, but the persisted data is deleted on logout.
      • An EphemeralProfile (see below), is not used for guest users. This allows persistence of properties after a shill crash within a guest user session.
  • Every Service has exactly one Profile associated with it, which is theProfile most recently pushed onto the Profile stack. The Profile contains persisted data for the Service.
  • An EphemeralProfile is used exclusively for Service instances that are created but that have no Profile in the Profile stack, e.g., a WiFiService that was created from a WiFi scan but that the user has never attempted to configure or connect to.

Profile Inheritance{inl}

  • A Service can be "linked" to a different Profile through the use of the Service kProfileProperty D-Bus property, which is how Service instances currently using the EphemeralProfile can be moved over to a Profile that allows its configuration parameters to be persisted.
  • Note Shill's D-Bus clients (aside from Autotest/Tast) do not create additional Profiles, so the Profile stack in non-test cases contains only the DefaultProfile and potentially a user Profile. The EphemeralProfile is not part of the Profile stack.

IP Configuration

TODO: Document the IPConfig class and IP configuration.

Connection

AutoConnect

TODO

Power Management

TODO

DBus

Glossary