session_manager is responsible for managing the lifecycle of the Chrome process. It confusingly lives in the login_manager directory and is installed by the chromeos-login package.
session_manager communicates with other processes using D-Bus. It owns the service name org.chromium.SessionManager at service path /org/chromium/SessionManager and exports an interface named org.chromium.SessionManager.
This document contains an overview of what session_manager does. See the docs directory for more information.
The ui Upstart job is responsible for running session_manager. Before executing it, it runs ui-pre-start to create necessary files and directories.
session_manager constructs a command line for running Chrome and fork-execs it. The command line is built by chrome_setup.cc ChromiumCommandBuilder class. The command line's contents are dependent on the presence of various USE flags. The libchromeos-use-flags package lists a number of USE flags in its IUSE variable; at build-time, it writes all of the set flags to /etc/ui_use_flags.txt. session_manager then reads this file at startup. (Generating ui_use_flags.txt in a tiny ancillary package rather than in chromeos-login avoids the need to build a different copy of the chromeos-login package for every board.)
Developers should take note of /etc/chrome_dev.conf, a configuration file that may be modified on-device to add or remove flags from Chrome's command line. The file contains documentation about its format.
After Chrome has displayed its login prompt, it calls session_manager's EmitLoginPromptVisible D-Bus method. session_manager writes a login-prompt-visible bootstat event, emits a LoginPromptVisible D-Bus signal on its interface, and makes an asynchronous D-Bus call to Upstart to tell it to emit a login-prompt-visible event; this latter event is used to trigger other jobs.
When the user successfully logs in within Chrome, Chrome calls session_manager‘s StartSession D-Bus method and emits a start-user-session upstart signal. session_manager makes an asynchronous D-Bus call to Upstart’s StartUserSession method and emits a SessionStateChanged D-Bus signal on its own interface.
Additional SessionStateChanged signals are emitted if additional users are added to the session.
Other processes on the system may decide to lock the screen after the user has logged in:
To do this, these processes call session_manager‘s LockScreen D-Bus method. session_manager records the locked state internally, triggers the screen-locked upstart signal, and calls Chrome’s ShowLockScreen D-Bus method via org.chromium.ScreenLockService. Once Chrome has successfully displayed the lock screen it calls session_manager's HandleLockScreenShown D-Bus method. session_manager then emits a ScreenIsLocked D-Bus signal.
After the user successfully types their password to unlock the screen, Chrome calls session_manager's HandleLockScreenDismissed D-Bus method. session_manager updates its internal state to record that the screen is no longer locked and emits both a screen-unlocked upstart event and a ScreenIsUnlocked D-Bus signal. Note that the lock events are not necessarily followed by unlock events because the active session can crash in which case the device is no longer locked.
When the user signs out, Chrome calls session_manager's StopSession D-Bus method. session_manager sends SIGTERM to the browser process and waits (3 seconds, by default) for it to exit. If the process is still running, it sends SIGABRT. session_manager then exits.
At this point, the ui-post-stop script runs. It writes a ui-post-stop bootstat event and forcibly cleans up by sending SIGKILL to any remaining chronos processes and killing orphaned containers.
The ui-respawn Upstart job then executes the ui-respawn script, which is responsible for restarting the ui job.
If Chrome exits unexpectedly, session_manager typically restarts it (without the --login-manager flag). If the screen was locked at the time of the crash, session_manager instead ends the session to avoid exposing a logged-in desktop on a potentially-unattended system.
If Chrome crashes repeatedly, ui-respawn reboots the system. If the crashes continue, it stops rebooting the system with the hope that it‘ll eventually be autoupdated to a new version that doesn’t crash. See the ui-respawn script for specifics.