dom/docs/ipc/process_model.rst

   1 Process Model
   2 =============
   3
   4 The complete set of recognized process types is defined in `GeckoProcessTypes <https://searchfox.org/mozilla-central/source/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py>`_.
   5
   6 For more details on how process types are added and managed by IPC, see the process creation documentation :ref:`Gecko Processes`.
   7
   8 Diagram
   9 -------
  10
  11 .. digraph:: processtypes
  12     :caption: Diagram of processes used by Firefox. All child processes are spawned and managed by the Parent process.
  13
  14     compound=true;
  15     node [shape=rectangle];
  16
  17     launcher [label=<Launcher Process>]
  18     parent [label=<Parent Process>]
  19
  20     subgraph cluster_child {
  21         color=lightgrey;
  22         label=<Child Processes>;
  23
  24         subgraph cluster_content {
  25             color=lightgrey;
  26             label=<Content Processes>;
  27
  28             web [
  29                 color=lightgrey;
  30                 label=<
  31                     <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black">
  32                         <TR><TD BORDER="0" CELLPADDING="0" CELLSPACING="0">Web Content</TD></TR>
  33                         <TR><TD BORDER="1">Shared Web Content<BR/>(<FONT FACE="monospace">web</FONT>)</TD></TR>
  34                         <TR><TD BORDER="1">Isolated Web Content<BR/>(<FONT FACE="monospace">webIsolated=$SITE</FONT>)</TD></TR>
  35                         <TR><TD BORDER="1">COOP+COEP Web Content<BR/>(<FONT FACE="monospace">webCOOP+COEP=$SITE</FONT>)</TD></TR>
  36                         <TR><TD BORDER="1">ServiceWorker Web Content<BR/>(<FONT FACE="monospace">webServiceWorker</FONT>)</TD></TR>
  37                     </TABLE>
  38                 >
  39             ]
  40
  41             nonweb [
  42                 shape=none;
  43                 label=<
  44                     <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black">
  45                         <TR><TD BORDER="1">Preallocated Content<BR/>(<FONT FACE="monospace">prealloc</FONT>)</TD></TR>
  46                         <TR><TD BORDER="1">File Content<BR/>(<FONT FACE="monospace">file</FONT>)</TD></TR>
  47                         <TR><TD BORDER="1">WebExtensions<BR/>(<FONT FACE="monospace">extension</FONT>)</TD></TR>
  48                         <TR><TD BORDER="1">Privileged Content<BR/>(<FONT FACE="monospace">privilegedabout</FONT>)</TD></TR>
  49                         <TR><TD BORDER="1">Privileged Mozilla Content<BR/>(<FONT FACE="monospace">privilegedmozilla</FONT>)</TD></TR>
  50                     </TABLE>
  51                 >
  52             ]
  53         }
  54
  55         helper [
  56             color=lightgrey;
  57             label=<
  58                 <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black">
  59                     <TR><TD BORDER="0" CELLPADDING="0" CELLSPACING="0">Helper Processes</TD></TR>
  60                     <TR><TD BORDER="1">Gecko Media Plugins (GMP) Process</TD></TR>
  61                     <TR><TD BORDER="1">GPU Process</TD></TR>
  62                     <TR><TD BORDER="1">VR Process</TD></TR>
  63                     <TR><TD BORDER="1">Data Decoder (RDD) Process</TD></TR>
  64                     <TR><TD BORDER="1">Network (Socket) Process</TD></TR>
  65                     <TR><TD BORDER="1">Utility Process</TD></TR>
  66                     <TR><TD BORDER="1">Remote Sandbox Broker Process</TD></TR>
  67                     <TR><TD BORDER="1">Fork Server</TD></TR>
  68                 </TABLE>
  69             >
  70         ]
  71     }
  72
  73     subgraph { rank=same; launcher -> parent; }
  74
  75     parent -> web [lhead="cluster_content"];
  76     parent -> helper;
  77
  78 .. _parent-process:
  79
  80 Parent Process
  81 --------------
  82
  83 :remoteType: *null*
  84 :other names: UI Process, Main Process, Chrome Process, Browser Process, Default Process, Broker Process
  85 :sandboxed?: no
  86
  87 The parent process is the primary process which handles the core functionality of Firefox, including its UI, profiles, process selection, navigation, and more. The parent process is responsible for launching all other child processes, and acts as a broker establishing communication between them.
  88
  89 All primary protocols establish a connection between the parent process and the given child process, which can then be used to establish additional connections to other processes.
  90
  91 As the parent process can display HTML and JS, such as the browser UI and privileged internal pages such as ``about:preferences`` and ``about:config``, it is often treated as-if it was a content process with a *null* remote type by process selection logic. The parent process has extra protections in place to ensure it cannot load untrusted code when running in multiprocess mode. To this effect, any attempts to load web content in the parent process will lead to a browser crash, and all navigations to and from parent-process documents immediately perform full isolation, to prevent content processes from manipulating them.
  92
  93 .. _content-process:
  94
  95 Content Process
  96 ---------------
  97
  98 :primary protocol: `PContent <https://searchfox.org/mozilla-central/source/dom/ipc/PContent.ipdl>`_
  99 :other names: Renderer Process
 100 :sandboxed?: yes (content sandbox policy)
 101
 102 Content processes are used to load web content, and are the only process type (other than the parent process) which can load and execute JS code. These processes are further subdivided into specific "remote types", which specify the type of content loaded within them, their sandboxing behavior, and can gate access to certain privileged IPC methods.
 103
 104 The specific remote type and isolation behaviour used for a specific resource is currently controlled in 2 major places. When performing a document navigation, the final process to load the document in is selected by the logic in `ProcessIsolation.cpp <https://searchfox.org/mozilla-central/source/dom/ipc/ProcessIsolation.cpp>`_. This will combine information about the specific response, such as the site and headers, with other state to select which process and other isolating actions should be taken. When selecting which process to create the initial process for a new tab in, and when selecting processes for serviceworkers and shared workers, the logic in :searchfox:`E10SUtils.sys.mjs <toolkit/modules/E10SUtils.sys.mjs>`_ is used to select a process. The logic in ``E10SUtils.sys.mjs`` will likely be removed and replaced with ``ProcessIsolation.cpp`` in the future.
 105
 106 .. note::
 107
 108     The "Renderer" alternative name is used by Chromium for its equivalent to content processes, and is occasionally used in Gecko as well, due to the similarity in process architecture. The actual rendering & compositing steps are performed in the GPU or main process.
 109
 110 Preallocated Content
 111 ^^^^^^^^^^^^^^^^^^^^
 112
 113 :remoteType: ``prealloc``
 114 :default count: 3 (``dom.ipc.processPrelaunch.fission.number``, or 1 if Fission is disabled)
 115
 116 To avoid the need to launch new content processes to host new content when navigating, new content processes are pre-launched and specialized when they are requested. These preallocated content processes will never load content, and must be specialized before they can be used.
 117
 118 The count of preallocated processes can vary depending on various factors, such as the memory available in the host system.
 119
 120 The ``prealloc`` process cannot be used to launch ``file`` content processes, due to their weakened OS sandbox. ``extension`` content processes are also currently not supported due to `Bug 1637119 <https://bugzilla.mozilla.org/show_bug.cgi?id=1638119>`_.
 121
 122 File Content
 123 ^^^^^^^^^^^^
 124
 125 :remoteType: ``file``
 126 :default count: 1 (``dom.ipc.processCount.file``)
 127 :capabilities: File System Access
 128
 129 The File content process is used to load ``file://`` URIs, and is therefore less sandboxed than other content processes. It may also be used to load remote web content if the browser has used a legacy CAPS preference to allow that site to access local resources (see `Bug 995943 <https://bugzilla.mozilla.org/show_bug.cgi?id=995943>`_)
 130
 131 WebExtensions
 132 ^^^^^^^^^^^^^
 133
 134 :remoteType: ``extension``
 135 :default count: 1 (``dom.ipc.processCount.extension``)
 136 :capabilities: Extension APIs, Shared Memory (SharedArrayBuffer)
 137
 138 The WebExtension content process is used to load background pages and top level WebExtension frames. This process generally has access to elevated permissions due to loading privileged extension pages with access to the full WebExtension API surface. Currently all extensions share a single content process.
 139
 140 Privileged extensions loaded within the extension process may also be granted access to shared memory using SharedArrayBuffer.
 141
 142 .. note::
 143
 144     ``moz-extension://`` subframes are currently loaded in the same process as the parent document, rather than in the ``extension`` content process, due to existing permissions behaviour granting content scripts the ability to access the content of extension subframes. This may change in the future.
 145
 146 Privileged Content
 147 ^^^^^^^^^^^^^^^^^^
 148
 149 :remoteType: ``privilegedabout``
 150 :default count: 1 (``dom.ipc.processCount.privilegedabout``)
 151 :capabilities: Restricted JSWindowActor APIs
 152
 153 The ``privilegedabout`` content process is used to load internal pages which have privileged access to internal state. The use of the ``privilegedabout`` content process is requested by including both ``nsIAboutModule::URI_MUST_LOAD_IN_CHILD`` and ``nsIAboutModule::URI_CAN_LOAD_IN_PRIVILEGEDABOUT_PROCESS`` flags in the corresponding ``nsIAboutModule``.
 154
 155 As of August 11, 2021, the following internal pages load in the privileged content process: ``about:logins``, ``about:loginsimportreport``, ``about:privatebrowsing``, ``about:home``, ``about:newtab``, ``about:welcome``, ``about:protections``, and ``about:certificate``.
 156
 157 Various ``JSWindowActor`` instances which provide special API access for these internal about pages are restricted to only be available in this content process through the ``remoteTypes`` attribute, which will block attempts to use them from other content processes.
 158
 159 Privileged Mozilla Content
 160 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 161
 162 :remoteType: ``privilegedmozilla``
 163 :default count: 1 (``dom.ipc.processCount.privilegedmozilla``)
 164 :domains: ``addons.mozilla.org`` and ``accounts.firefox.com`` (``browser.tabs.remote.separatedMozillaDomains``)
 165 :capabilities: Restricted Addon Manager APIs
 166
 167 The ``privilegedmozilla`` content process is used to load specific high-value Mozilla-controlled webpages which have been granted access to privileged features. To provide an extra layer of security for these sites, they are loaded in a separate process from other web content even when Fission is disabled.
 168
 169 This separate remote type is also used to gate access at the IPC boundary to certain high-power web APIs, such as access to the ability to interact with installed extension APIs.
 170
 171 Web Content Processes
 172 ^^^^^^^^^^^^^^^^^^^^^
 173
 174 These processes all have remote types beginning with ``web``, and are used to host general untrusted web content. The different variants of web content processes are used at different times, depending on the isolation strategy requested by the page and the browser's configuration.
 175
 176 Shared Web Content
 177 """"""""""""""""""
 178
 179 :remoteType: ``web``
 180 :default count: 8 (``dom.ipc.processCount``)
 181
 182 The shared web content process is used to host content which is not isolated into one of the other web content process types. This includes almost all web content with Fission disabled, and web content which cannot be attributed to a specific origin with Fission enabled, such as user-initiated ``data:`` URI loads.
 183
 184 Isolated Web Content
 185 """"""""""""""""""""
 186
 187 :remoteType: ``webIsolated=$SITE``
 188 :default count: 1 per-site (``dom.ipc.processCount.webIsolated``)
 189
 190 Isolated web content processes are used to host web content with Fission which can be attributed to a specific site. These processes are allocated when navigating, and will only load content from the named site. When Fission is disabled, isolated web content processes are not used.
 191
 192 A different ``webIsolated=`` remote type, and therefore a different pool of processes, is used for each site loaded, with separation also being used for different container tabs and private browsing.
 193
 194 COOP+COEP Web Content
 195 """""""""""""""""""""
 196
 197 :remoteType: ``webCOOP+COEP=$SITE``
 198 :default count: 1 per-site (``dom.ipc.processCount.webCOOP+COEP``)
 199 :capabilities: Shared Memory (SharedArrayBuffer)
 200
 201 When loading a top level document with both the ``Cross-Origin-Opener-Policy`` and ``Cross-Origin-Embedder-Policy`` headers configured correctly, the document is requesting access to Shared Memory. For security reasons, we only provide this API access to sufficiently-isolated pages, and we load them within special isolated content processes.
 202
 203 Like Isolated Web Content, these processes are keyed by the site loaded within them, and are also segmented based on container tabs and private browsing.
 204
 205 .. note::
 206
 207     Another name for this process may be "Cross-Origin Isolated Web Content", to correspond with the ``window.crossOriginIsolated`` attribute which is set for documents loaded with these headers set. Unfortunately that may be confused with Fission's "Isolated Web Content" processes, as the attribute was named after the ``webIsolated`` remote type was already in use.
 208
 209     In ``about:processes``, COOP+COEP Web Content processes will be listed with a "cross-origin isolated" note after the PID, like ``https://example.com (12345, cross-origin isolated)``.
 210
 211 ServiceWorker Web Content
 212 """""""""""""""""""""""""
 213
 214 :remoteType: ``webServiceWorker=$SITE``
 215 :default count: 1 per-site using ServiceWorkers
 216
 217 ServiceWorker web content processes are used to host ServiceWorkers on a per-site basis, so that ServiceWorker operations aren't impacted by MainThread event latency whenrunning in the same process as the content for the page.   ServiceWorkers are usually transitory, and will disappear if unused for a short period of time.
 218
 219 .. _gecko-media-plugins-process:
 220
 221 Gecko Media Plugins (GMP) Process
 222 ---------------------------------
 223
 224 :primary protocol: `PGMP <https://searchfox.org/mozilla-central/source/dom/media/gmp/PGMP.ipdl>`_
 225 :sandboxed?: yes (GMP sandbox policy)
 226
 227 The GMP process is used to sandbox third-party "Content Decryption Module" (CDM) binaries used for media playback in a sandboxed environment. This process is only launched when DRM-enabled content is loaded.
 228
 229 .. _gpu-process:
 230
 231 GPU Process
 232 -----------
 233
 234 :primary protocol: `PGPU <https://searchfox.org/mozilla-central/source/gfx/ipc/PGPU.ipdl>`_
 235 :other names: Compositor Process
 236 :sandboxed?: no (`bug 1347710 <https://bugzilla.mozilla.org/show_bug.cgi?id=1347710>`_ tracks sandboxing on windows)
 237
 238 The GPU process performs compositing, and is used to talk to GPU hardware in an isolated process. This helps isolate things like GPU driver crashes from impacting the entire browser, and will allow for this code to be sandboxed in the future. In addition, some components like Windows Media Foundation (WMF) are run in the GPU process when it is available.
 239
 240 The GPU process is not used on all platforms. Platforms which do not use it, such as macOS and some Linux configurations, will perform compositing on a background thread in the Parent Process.
 241
 242 .. _vr-process:
 243
 244 VR Process
 245 ----------
 246
 247 :primary protocol: `PVR <https://searchfox.org/mozilla-central/source/gfx/vr/ipc/PVR.ipdl>`_
 248 :sandboxed?: no (`bug 1430043 <https://bugzilla.mozilla.org/show_bug.cgi?id=1430043>`_ tracks sandboxing on windows)
 249
 250 VR headset libraries require access to specific OS level features and other requirements which we would generally like to block with the sandbox in other processes. In order to allow the GPU process to have tighter sandboxing rules, these VR libraries are loaded into the less-restricted VR process. Like the GPU process, this serves to isolate them from the rest of Firefox and reduce the impact of bugs in these libraries on the rest of the browser. The VR process is launched only after a user visits a site which uses WebVR.
 251
 252 .. _data-decoder-process:
 253
 254 Data Decoder (RDD) Process
 255 --------------------------
 256
 257 :primary protocol: `PRDD <https://searchfox.org/mozilla-central/source/dom/media/ipc/PRDD.ipdl>`_
 258 :sandboxed?: yes (RDD sandbox policy)
 259
 260 This process is used to run media data decoders within their own sandboxed process, allowing the code to be isolated from other code in Gecko. This aims to reduce the severity of potential bugs in media decoder libraries, and improve the security of the browser.
 261
 262 .. note::
 263
 264     This process is in the process of being restructured into a generic "utility" process type for running untrusted code in a maximally secure sandbox. After these changes, the following new process types will exist, replacing the RDD process:
 265
 266     * ``Utility``: A maximally sandboxed process used to host untrusted code which does not require access to OS resources. This process will be even more sandboxed than RDD today on Windows, where the RDD process has access to Win32k.
 267     * ``UtilityWithWin32k``: A Windows-only process with the same sandboxing as the RDD process today. This will be used to host untrusted sandboxed code which requires access to Win32k to allow decoding directly into GPU surfaces.
 268     * ``GPUFallback``: A Windows-only process using the GPU process' sandboxing policy which will be used to run Windows Media Foundation (WMF) when the GPU process itself is unavailable, allowing ``UtilityWithWin32k`` to re-enable Arbitrary Code Guard (ACG) on Windows.
 269
 270     For more details about the planned utility process architecture changes, see `the planning document <https://docs.google.com/document/d/1WDEY5fQetK_YE5oxGxXK9BzC1A8kJP3q6F1gAPc2UGE>`_.
 271
 272 .. _network-socket-process:
 273
 274 Network (Socket) Process
 275 ------------------------
 276
 277 :primary protocol: `PSocketProcess <https://searchfox.org/mozilla-central/source/netwerk/ipc/PSocketProcess.ipdl>`_
 278 :sandboxed?: yes (socket sandbox policy)
 279
 280 The socket process is used to separate certain networking operations from the parent process, allowing them to be performed more directly in a partially sandboxed process. The eventual goal is to move all TCP/UDP network operations into this dedicated process, and is being tracked in `Bug 1322426 <https://bugzilla.mozilla.org/show_bug.cgi?id=1322426>`_.
 281
 282 .. _remote-sandbox-process:
 283
 284 Remote Sandbox Broker Process
 285 -----------------------------
 286
 287 :platform: Windows on ARM only
 288 :primary protocol: `PRemoteSandboxBroker <https://searchfox.org/mozilla-central/source/security/sandbox/win/src/remotesandboxbroker/PRemoteSandboxBroker.ipdl>`_
 289 :sandboxed?: no
 290
 291 In order to run sandboxed x86 plugin processes from Windows-on-ARM, the remote sandbox broker process is launched in x86-mode, and used to launch sandboxed x86 subprocesses. This avoids issues with the sandboxing layer, which unfortunately assumes that pointer width matches between the sandboxer and sandboxing process. To avoid this, the remote sandbox broker is used as an x86 sandboxing process which wraps these plugins.
 292
 293 .. _fork-server:
 294
 295 Fork Server
 296 -----------
 297
 298 :platform: Linux only
 299 :pref: ``dom.ipc.forkserver.enable`` (disabled by default)
 300 :primary protocol: *none*
 301 :sandboxed?: no (processes forked by the fork server are sandboxed)
 302
 303 The fork server process is used to reduce the memory overhead and improve launch efficiency for new processes. When a new supported process is requested and the feature is enabled, the parent process will ask the fork server to ``fork(2)`` itself, and then begin executing. This avoids the need to re-load ``libxul.so`` and re-perform relocations.
 304
 305 The fork server must run before having initialized XPCOM or the IPC layer, and therefore uses a custom low-level IPC system called ``MiniTransceiver`` rather than IPDL to communicate.
 306
 307 .. _launcher-process:
 308
 309 Launcher Process
 310 ----------------
 311
 312 :platform: Windows only
 313 :metabug: `Bug 1435780 <https://bugzilla.mozilla.org/show_bug.cgi?id=1435780>`_
 314 :sandboxed?: no
 315
 316 The launcher process is used to bootstrap Firefox on Windows before launching the main Firefox process, allowing things like DLL injection blocking to initialize before the main thread even starts running, and improving stability. Unlike the other utility processes, this process is not launched by the parent process, but rather launches it.
 317
 318 IPDLUnitTest
 319 ------------
 320
 321 :primary protocol: varies
 322
 323 This test-only process type is intended for use when writing IPDL unit tests. However, it is currently broken, due to these tests having never been run in CI. The type may be removed or re-used when these unit tests are fixed.
 324
 325 .. _utility-process:
 326
 327 Utility Process
 328 ---------------
 329
 330 :primary protocol: `PUtilityProcess <https://searchfox.org/mozilla-central/source/ipc/glue/PUtilityProcess.ipdl>`_
 331 :metabug: `Bug 1722051 <https://bugzilla.mozilla.org/show_bug.cgi?id=1722051>`_
 332 :sandboxed?: yes, customizable
 333
 334 The utility process is used to provide a simple way to implement IPC actor with some more specific sandboxing properties, in case where you don't need or want to deal with the extra complexity of adding a whole new process type but you just want to apply different sandboxing policies. Details can be found in :ref:`Utility Process`.