canmove, Confirmed users, Bureaucrats and Sysops emeriti
4,714
edits
Platform/Integration/InjectEject/Launcher Process/: Difference between revisions
Platform/Integration/InjectEject/Launcher Process/ (view source)
Revision as of 08:50, 10 May 2022
, 10 May 2022→Starting Firefox via Automation / Scripting: It also applies for the `remote-debugging-port` command line argument
(→Considerations for Developers: Added -launcher command line option) |
(→Starting Firefox via Automation / Scripting: It also applies for the `remote-debugging-port` command line argument) |
||
| (9 intermediate revisions by 2 users not shown) | |||
| Line 19: | Line 19: | ||
The Launcher Process selects one of multiple techniques for dropping the privileges of the browser process: | The Launcher Process selects one of multiple techniques for dropping the privileges of the browser process: | ||
* When UAC is enabled, the launcher process requests that Explorer starts the browser. This ensures that the browser runs under the privileges of the user whose desktop we are currently running in. As an example of a scenario where this might be useful, suppose that a user is starting Firefox from within their command prompt, but they accidentally used their elevated command prompt instead of their normal command prompt. | * When UAC is enabled, the launcher process requests that Explorer starts the browser. This ensures that the browser runs under the privileges of the user whose desktop we are currently running in. As an example of a scenario where this might be useful, suppose that a user is starting Firefox from within their command prompt, but they accidentally used their elevated command prompt instead of their normal command prompt. | ||
* When UAC is disabled, the launcher process | * When UAC is disabled, the launcher process duplicates the user's token and drops the duplicate token's integrity level from high to medium. The launcher process then creates the browser process using that medium-integrity token. | ||
** Firefox will not have write access to directories that are configured with a high-integrity ACL. By default, this includes root directories, <code>\Program Files</code>, <code>\windows\system32</code>, among others. | ** Firefox will not have write access to directories that are configured with a high-integrity ACL. By default, this includes root directories, <code>\Program Files</code>, <code>\windows\system32</code>, among others. | ||
** Firefox will be affected by User Interface Privilege Isolation (UIPI); the Firefox UI is not allowed to communicate with other UI running at higher integrity levels. Since the user's desktop and other applications are most likely still running at high integrity level, the Firefox UI will not be able to communicate with them. This means that certain GUI features such as drag-and-drop will not work. | ** Firefox will be affected by User Interface Privilege Isolation (UIPI); the Firefox UI is not allowed to communicate with other UI running at higher integrity levels. Since the user's desktop and other applications are most likely still running at high integrity level, the Firefox UI will not be able to communicate with them. This means that certain GUI features such as drag-and-drop will not work. | ||
** We have an [https://support.mozilla.org/en-US/kb/windows-administrator-launcher-process-error-fix article in the SUMO Knowledge Base] instructing users on how to mitigate these issues. | ** We have an [https://support.mozilla.org/en-US/kb/windows-administrator-launcher-process-error-fix article in the SUMO Knowledge Base] instructing users on how to mitigate these issues. | ||
*** Note: '''Do not''' advise users to attempt these suggestions unless it is known for a fact that they are running as Administrator with UAC disabled. | *** Note: '''Do not''' advise users to attempt these suggestions unless it is known for a fact that they are running as Administrator with UAC disabled! It is not a "catch-all" solution for launcher process problems. | ||
=== Starting Firefox via Automation / Scripting === | === Starting Firefox via Automation / Scripting === | ||
| Line 33: | Line 33: | ||
* Firefox is started with the <code>-marionette</code> command line option; | * Firefox is started with the <code>-marionette</code> command line option; | ||
* Firefox is started with the <code>-headless</code> command line option; | * Firefox is started with the <code>-headless</code> command line option; | ||
* Firefox is started with the <code>-remote-debugging-port</code> command line option; | |||
* Firefox is started with the <code>MOZ_AUTOMATION</code> environment variable set; | * Firefox is started with the <code>MOZ_AUTOMATION</code> environment variable set; | ||
* Firefox is started with the <code>MOZ_HEADLESS</code> environment variable set; | * Firefox is started with the <code>MOZ_HEADLESS</code> environment variable set; | ||
| Line 38: | Line 39: | ||
'''''Why does the Launcher Process not wait for the browser by default?''''' | '''''Why does the Launcher Process not wait for the browser by default?''''' | ||
* Over the course of a Firefox browsing session, the launcher process | * Over the course of a Firefox browsing session, the launcher process would lie dormant and its private virtual memory would eventually be paged out to disk. However, it would still be visible as yet another <code>firefox.exe</code> process in the operating system's process list. | ||
** To avoid the launcher process being charged against Firefox's overall resource usage (and the public perceptions that doing so would entail), we let the launcher process exit. | ** To avoid the launcher process being charged against Firefox's overall resource usage (and the public perceptions that doing so would entail), we let the launcher process exit. | ||
** We also do not want launcher process VM to be unnecessarily occupying space in the page file on machines where there is limited page file space. | ** We also do not want launcher process VM to be unnecessarily occupying space in the page file on machines where there is limited page file space. This is not uncommon - see our various OOM crash reports if you don't believe it! | ||
* This would not work with the scenario where an elevated launcher process asks Explorer to restart the browser as a normal user; Explorer does not return any process ID or handle information to the launcher process, so there is nothing for the launcher process to wait on. This would introduce an undesirable inconsistency in the command-line behavior of the launcher process. By explicitly opting into waiting for the browser process, the launcher process adjusts its behavior to avoid this scenario, but uses a less desirable mechanism for restarting the browser. | * This would not work with the scenario where an elevated launcher process asks Explorer to restart the browser as a normal user; Explorer does not return any process ID or handle information to the launcher process, so there is nothing for the launcher process to wait on. This would introduce an undesirable inconsistency in the command-line behavior of the launcher process. By explicitly opting into waiting for the browser process, the launcher process adjusts its behavior to avoid this scenario, but uses a less desirable mechanism for restarting the browser. | ||
== Considerations for Developers == | == Considerations for Developers == | ||
* The launcher process is enabled by default both in local and CI builds. | * The launcher process is enabled by default both in local and CI builds. In local builds, the launcher process may be disabled by default by specifying the <code>--disable-launcher-process</code> option in <code>mozconfig</code>. Leaving this as its default is preferred to ensure that the launcher process receives just as much testing as our other processes. | ||
** If you have disabled the launcher process by default in your local build, but would like to run it during a test, use the <code>-launcher</code> command-line option. | ** If you have disabled the launcher process by default in your local build, but would like to run it during a test, use the <code>-launcher</code> command-line option. | ||
* Both <code>mach run</code> and <code>mach gtest</code> automatically specify the <code>-wait-for-browser</code> option when starting Firefox. Visual Studio projects generated by the build system also automatically include this flag when running Firefox. | * Both <code>mach run</code> and <code>mach gtest</code> automatically specify the <code>-wait-for-browser</code> option when starting Firefox. Visual Studio projects generated by the build system also automatically include this flag when running Firefox. | ||
| Line 57: | Line 58: | ||
== Other Troubleshooting == | == Other Troubleshooting == | ||
If the launcher process fails and telemetry is enabled, the launcher process generates and sends a telemetry ping containing an error code and the source code location of the failure. If telemetry is disabled, or if for some reason the launcher process was unable to successfully send its telemetry ping, the launcher process will log the failure to the Windows event log. | If the launcher process fails and telemetry is enabled, the launcher process generates and sends [https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/data/launcher-process-failure-ping.html a telemetry ping] containing an error code and the source code location of the failure. If telemetry is disabled, or if for some reason the launcher process was unable to successfully send its telemetry ping, the launcher process will log the failure to the Windows event log. | ||
The submitted telemetry is available in [https://iodide.telemetry.mozilla.org/notebooks/219/?viewMode=report this dashboard]. It's important to keep the failure numbers low. | |||
To view launcher process failure events in the system event viewer, open the <code>Control Panel</code> [''Note: this must be the legacy <code>Control Panel</code> app, not the new <code>Settings</code> app found in Windows 8 and Windows 10''], select <code>Administrative Tools</code>, and double-click on <code>Event Viewer</code>. Looking at the tree in the left pane, expand the <code>Windows Logs</code> branch, and click <code>Application</code>. | To view launcher process failure events in the system event viewer, open the <code>Control Panel</code> [''Note: this must be the legacy <code>Control Panel</code> app, not the new <code>Settings</code> app found in Windows 8 and Windows 10''], select <code>Administrative Tools</code>, and double-click on <code>Event Viewer</code>. Looking at the tree in the left pane, expand the <code>Windows Logs</code> branch, and click <code>Application</code>. | ||
It is also possible to force the launcher process to always log failures to the Windows event log by adding the <code>-log-launcher-error</code> option to the command line. This may be useful when assisting specific users who are experiencing launcher process failures. | It is also possible to force the launcher process to always log failures to the Windows event log by adding the <code>-log-launcher-error</code> option to the command line. This may be useful when assisting specific users who are experiencing launcher process failures. | ||