Guide to Configuring the Modular Framework

DEPRECATION WARNING: The Modular framework is being deprecated in favor of the Session Framework.

Requirements

To configure the modular framework, you will need to create a JSON file defining the required configurations for basemgr and sessionmgr as detailed below. The configuration file should be packaged via the build rule modular_config, which will validate your file against a schema. You must then include the modular_config() target in the product's base packages.

The file may contain (non-standard JSON) C-style comments (/* block */ and // inline).

Example

The fields used in the startup configuration depend on whether a session launcher component is specified in the basemgr.session_launcher field.

If basemgr.session is present, all other fields except for basemgr.enable_cobalt are ignored, and the session launcher component is responsible for instructing basemgr to launch a session with a complete configuration file.

Session launcher component

// Fields not specified here are ignored.
{
  "basemgr": {
    "enable_cobalt": false,
    "session_launcher": {
      "url": "fuchsia-pkg://fuchsia.com/custom_session#meta/custom_session.cmx",
      "args": [ "--foo", "--bar" ]
    }
  }
}

Typical configuration

{
  /* This is a block comment.
     Comments are ignored. */
  // This is an inline comment. Comments are ignored.
  "basemgr": {
    "enable_cobalt": false,
    "use_session_shell_for_story_shell_factory": true,
    "base_shell": {
      "url": "fuchsia-pkg://fuchsia.com/auto_login_base_shell#meta/auto_login_base_shell.cmx",
    },
    "session_shells": [
      {
        "url": "fuchsia-pkg://fuchsia.com/dev_session_shell#meta/dev_session_shell.cmx",
        "display_usage": "near",
        "screen_height": 50.0,
        "screen_width": 100.0
      }
    ]
  },
  "sessionmgr": {
    "startup_agents": [
      "fuchsia-pkg://fuchsia.com/startup_agent#meta/startup_agent.cmx"
    ],
    "session_agents": [
      "fuchsia-pkg://fuchsia.com/session_agent#meta/session_agent.cmx"
    ],
    "component_args": [
      {
        "uri": "fuchsia-pkg://fuchsia.com/startup_agent#meta/startup_agent.cmx",
        "args": [ "--foo", "--bar=true" ]
      }
    ],
    "agent_service_index": [
      {
        "service_name": "fuchsia.modular.SomeServiceName",
        "agent_url": "fuchsia-pkg://fuchsia.com/some_agent#meta/some_agent.cmx"
      }
    ],
    "restart_session_on_agent_crash": [
      "fuchsia-pkg://fuchsia.com/some_agent#meta/some_agent.cmx"
    ]
  }
}

Basemgr fields

• base_shell object (optional)
  • WARNING: Basemgr no longer launches base shells. This configuration is used only to start sessions with either a persistent or random session ID.
  • TODO(fxbug.dev/51752): Replace base_shell with use_random_session_id flag
  • url: string (optional)
    • This field is unused.
    • default: fuchsia-pkg://fuchsia.com/auto_login_base_shell#meta/auto_login_base_shell.cmx
  • keep_alive_after_login boolean (optional)
    • This field is unused.
    • default: false
  • args string[] (optional)
    • If this list contains the string --persist_user, the session will be started with a persistent session ID. Otherwise, it will be started with a random ID.
    • default: []
• session_shells array (optional)
  • List of exactly one session shell containing the following fields (is an Array type for backwards compatibility):
    • url: string (required)
      • The fuchsia component url for which session shell to use.
    • display_usage: string (optional)
      • The display usage policy for this session shell.
      • Options:
        • handheld: the display is used well within arm's reach.
        • close: the display is used at arm's reach.
        • near: the display is used beyond arm's reach.
        • midrange: the display is used beyond arm's reach.
        • far: the display is used well beyond arm's reach.
    • screen_height: float (optional)
      • The screen height in millimeters for the session shell's display.
    • screen_width: float (optional)
      • The screen width in millimeters for the session shell's display.
  • default: A single session shell with the following properties:
    • url: fuchsia-pkg://fuchsia.com/dev_story_shell#meta/dev_session_shell.cmx
    • display_usage: unknown
    • screen_height: 0
    • screen_width: 0
• story_shell_url: string (optional)
  • The fuchsia component url for which story shell to use.
  • default: fuchsia-pkg://fuchsia.com/dev_story_shell#meta/dev_story_shell.cmx
• enable_cobalt: boolean (optional)
  • When set to false, Cobalt statistics are disabled.
  • default: true
• use_session_shell_for_story_shell_factory: boolean (optional)
  • Create story shells through StoryShellFactory exposed by the session shell instead of creating separate story shell components. When set, story_shell_url and any story shell args are ignored.
  • default: false
• session_launcher object (optional)
  • When set, basemgr will launch this component instead of sessionmgr on startup and ignore all other configuration properties, except basemgr.enable_cobalt. This component can use the fuchsia.session.Launcher protocol to launch sessionmgr.
    • url: string (required)
      • The Fuchsia component URL for the session component.
    • args string[] (optional)
      • A list of arguments to be passed to the session component specified by url.

Sessionmgr fields

• enable_cobalt: boolean (optional)
  • When set to false, Cobalt statistics are disabled. This is used for testing.
  • default: true
• startup_agents: string[] (optional)
  • A list of fuchsia component urls that specify which agents to launch at startup.
• session_agents: string[] (optional)
  • A list of fuchsia component urls that specify which agents to launch at startup with PuppetMaster and FocusProvider services.
• component_args: array (optional)
  • A list of key/value pairs to construct a map from component URI to arguments list for that component. Presence in this list results in the given arguments passed to the component as its argv at launch.
    • uri: The component's uri.
    • args: A list of arguments to be passed to the component specified by uri. Arguments must be prefixed with --.
• agent_service_index: array (optional)
  • A list of key/value pairs mapping from service name to the serving component's URL. Agents and the session shell are both valid components to specify here. Service names must be unique: only one component can provide any given service. These services are provided to modules, the session shell, and agents, in their incoming namespace (i.e. at the path “/svc/fully.qualified.ServiceName”).
    • service_name: The name of a service offered by agent_url.
    • agent_url: A fuchsia component url that specifies which agent/shell will provide the named service.
• restart_session_on_agent_crash: array (optional)

  • A list of agent URLs that will cause the session to be restarted when they terminate unexpectedly. If an agent is not in this list, sessionmgr will restart it individually, preserving the session.

    The session shell is automatically added to this list.