MozillaWiki - User contributions [en]

Modules/Desktop Firefox

2022-01-14T15:53:36Z

Nhnt11: Downgraded myself to peer-emeritus for the Security and Privacy UI module

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
Owners and peers of the Desktop Firefox module may review code anywhere in the browser and toolkit directories. Reviews should be sent to the more specific submodules below where possible.

{{Module
|name=Desktop Firefox
|description=Standalone Web Browser.
|owner=[mailto:dtownsend@mozilla.com Dave Townsend], [mailto:gkruitbosch@mozilla.com Gijs Kruitbosch]
|fallbackpeers=[mailto:dao@mozilla.com Dão Gottwald], [mailto:jwein@mozilla.com Jared Wein], [mailto:mbonardo@mozilla.com Marco Bonardo], [mailto:mozilla@noorenberghe.ca Matthew Noorenberghe]
|ownersemeritus=
|peersemeritus=[mailto:netzen@gmail.com Brian Bondy], [mailto:lina@mozilla.com Lina Cambridge], [mailto:lchang@mozilla.com Luke Chang], [mailto:rchien@mozilla.com Ricky Chien], [mailto:dolske@mozilla.com Justin Dolske], [mailto:georg.fritzsche@googlemail.com Georg Fritzsche], [mailto:felipc@gmail.com Felipe Gomes], [mailto:tchien@mozilla.com Tim Guan-tin Chien], [mailto:jhofmann@mozilla.com Johann Hofmann], [mailto:rexboy@mozilla.com KM Lee Rex], [mailto:gasolin@mozilla.com Fred Lin], [mailto:ralin@mozilla.com Ray Lin], [mailto:fliu@mozilla.com Fischer Liu], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:mark@moxienet.com Mark Mentovai], [mailto:ted.mielczarek@gmail.com Ted Mielczarek], [mailto:bnicholson@mozilla.com Brian Nicholson], [mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:mano@mozilla.com Asaf Romano], [mailto:msamuel@mozilla.com Marina Samuel], [mailto:jryans@gmail.com J Ryan Stinnett], [mailto:gps@mozilla.com Gregory Szorc], [mailto:ttaubert@mozilla.com Tim Taubert],
|group=firefox-dev
|source_dirs=browser/, toolkit/
|url=[[Firefox/Code_Review|Code Review Guidelines]]
|components=Firefox, Toolkit
}}

== Submodules ==

{{Module
|name=Add-ons Manager
|description=Extension management back-end.
|owner=[mailto:scaraveo@mozilla.com Shane Caraveo]
|ownersemeritus=[mailto:rstrong@mozilla.com Robert Strong], [mailto:aswan@mozilla.com Andrew Swan], [mailto:kmaglione@mozilla.com Kris Maglione]
|peers=[mailto:lgreco@mozilla.com Luca Greco], [mailto:tjovanovic@mozilla.com Tomislav Jovanovic], [mailto:jmathies@mozilla.com Jim Mathies], [mailto:rwu@mozilla.com Rob Wu]
|source_dirs=toolkit/mozapps/extensions/
|url=
|components=
}}

{{Module
|name=Add-ons Manager UI
|description=about:addons.
|owner=[mailto:scaraveo@mozilla.com Shane Caraveo], [mailto:mstriemer@mozilla.com Mark Striemer]
|ownersemeritus=[mailto:rstrong@mozilla.com Robert Strong], [mailto:aswan@mozilla.com Andrew Swan]
|peers=[mailto:lgreco@mozilla.com Luca Greco], [mailto:tjovanovic@mozilla.com Tomislav Jovanovic], [mailto:rwu@mozilla.com Rob Wu]
|source_dirs=toolkit/mozapps/extensions/content/
|url=
|components=
}}

{{Module
|name=Application Update
|description=The application update services.
|owner=[mailto:ksteuber@mozilla.com Kirk Steuber]
|peers=[mailto:mhowell@mozilla.com Molly Howell], [mailto:agashlin@mozilla.com Adam Gashlin]
|source_dirs=toolkit/mozapps/update/
|url=
|components=
}}

{{Module
|name=Bookmarks & History
|description=The bookmarks and history services (Places).
|owner=[mailto:mbonardo@mozilla.com Marco Bonardo]
|peers=[mailto:standard8@mozilla.com Mark Banner], [mailto:adw@mozilla.com Drew Willcoxon]
|source_dirs=browser/components/places/, toolkit/components/places/
|url=
|components=
}}

{{Module
|name=Desktop Theme
|description=The style rules used in the desktop UI.
|owner=[mailto:dgottwald@mozilla.com Dão Gottwald]
|peers=[mailto:htwyford@mozilla.com Harry Twyford], [mailto:itiel_yn8@walla.com Itiel]
|peersemeritus=[mailto:ntim.bugs@gmail.com Tim Nguyen]
|source_dirs=browser/themes/, toolkit/themes/
|url=
|components=Firefox::Theme, Toolkit::Themes
}}

{{Module
|name=Desktop UI
|description=The main browser UI except where covered by more specific submodules.
|owner=[mailto:jwein@mozilla.com Jared Wein]
|peers=[mailto:mconley@mozilla.com Mike Conley], [mailto:florian@queze.net Florian Quèze]
|source_dirs=browser/base/content/
|url=
|components=
}}

{{Module
|name=Download Manager
|description=The downloads UI and service.
|owner=[mailto:mbonardo@mozilla.com Marco Bonardo]
|peers=[mailto:gijskruitbosch@gmail.com Gijs Kruitbosch], [mailto:mtigley@mozilla.com Micah Tigley]
|source_dirs=browser/components/downloads/, toolkit/mozapps/downloads/
|url=
|components=
}}

{{Module
|name=Enterprise Policies
|description=System policies for controlling Firefox.
|owner=[mailto:mkaply@mozilla.com Michael Kaply]
|peers=
|source_dirs=browser/components/enterprisepolicies/
|url=
|components=
}}

{{Module
|name=Form Autofill
|description=Form detection and autocomplete.
|owner=[mailto:tgiles@mozilla.com Tim Giles]
|ownersemeritus=[mailto:mozilla@noorenberghe.ca Matthew Noorenberghe]
|peers=[mailto:sgalich@mozilla.com Sergey Galich], [mailto:dlee@mozilla.com Dimi Lee]
|source_dirs=browser/extensions/formautofill/, toolkit/components/satchel/
|url=
|components=
}}

{{Module
|name=In-product Messaging
|description=The system for delivering in-product messaging.
|owner=[mailto:aoprea@mozilla.com Andrei Oprea]
|peers=[mailto:najiang@mozilla.com Nan Jiang], [mailto:pdahiya@mozilla.com Punam Dahiya], [mailto:edilee@mozilla.com Ed Lee], [mailto:khudson@mozilla.com Kate Hudson],
|source_dirs=toolkit/components/messaging-system/
|url=
|components=Firefox::Messaging System
}}

{{Module
|name=Launcher Process
|description=Windows process for bootstrapping the browser process.
|owner=[mailto:tkikuchi@mozilla.com Toshihito Kikuchi]
|ownersemeritus=Aaron Klotz
|peers=[mailto:mhowell@mozilla.com Molly Howell]
|source_dirs=browser/app/winlauncher
|url=
|components=Firefox::Launcher Process
}}

{{Module
|name=New Tab Page
|description=The new tab/home page.
|owner=[mailto:elee@mozilla.com Ed Lee]
|peers=[mailto:khudson@mozilla.com Kate Hudson], [mailto:aoprea@mozilla.com Andrei Oprea], [mailto:sdowne@getpocket.com Scott Downe]
|source_dirs=browser/components/newtab/
|url=
|components=Firefox::New Tab Page
}}

{{Module
|name=Normandy
|description=The experiments and off-train deployments system.
|owner=[mailto:mcooper@mozilla.com Michael Cooper]
|peers=[mailto:gkruitbosch@mozilla.com Gijs Kruitbosch]
|source_dirs=toolkit/components/normandy/
|url=
|components=Firefox::Normandy
}}

{{Module
|name=Onboarding
|description=The onboarding experience including UI tours.
|owner=[mailto:elee@mozilla.com Ed Lee]
|peers=[mailto:mozilla@noorenberghe.ca Matthew Noorenberghe]
|source_dirs=browser/components/uitour/
|url=
|components=Firefox::Tours
}}

{{Module
|name=Password Manager
|description=Managing, saving and filling logins.
|owner=[mailto:sgalich@mozilla.com Sergey Galich]
|ownersemeritus=[mailto:mozilla@noorenberghe.ca Matthew Noorenberghe]
|peers=[mailto:sfoster@mozilla.com Sam Foster], [mailto:jwein@mozilla.com Jared Wein], [mailto:tgiles@mozilla.com Tim Giles], [mailto:dlee@mozilla.com Dimi Lee]
|peersemeritus=[mailto:bdanforth@mozilla.com Bianca Danforth], [mailto:srudie@mozilla.com Severin Rudie]
|source_dirs=toolkit/components/passwordmgr/, browser/components/aboutlogins
|url=https://wiki.mozilla.org/Toolkit:Password_Manager
|components=Toolkit::Password Manager, Toolkit::Password Manager: Site Compatibility, Firefox::about:logins
}}

{{Module
|name= Picture-in-Picture
|description= A component that allows video elements to be pulled out into an always-on-top window.
|owner=[mailto:mconley@mozilla.com Mike Conley], [mailto:mtigley@mozilla.com Micah Tigley], [mailto:mhowell@mozilla.com Molly Howell]
|peers=[mailto:kpatenio@mozilla.com Katherine Patenio], [mailto:nbaumgardner@mozilla.com Niklas Baumgardner]
|source_dirs=toolkit/components/pictureinpicture, browser/extensions/pictureinpicture
|url=https://firefox-source-docs.mozilla.org/toolkit/components/pictureinpicture/pictureinpicture/index.html
}}

{{Module
|name=Preferences
|description=The front-end preferences system.
|owner=[mailto:jwein@mozilla.com Jared Wein]
|peers=[mailto:mstriemer@mozilla.com Mark Striemer], [mailto:gkruitbosch@mozilla.com Gijs Kruitbosch]
|peersemeritus=[mailto:ntim.bugs@gmail.com Tim Nguyen]
|source_dirs=browser/components/preferences/, browser/themes/*/preferences, toolkit/mozapps/preferences
|url=
|components=
}}

{{Module
|name=Profile Migration
|description=Migrating data from other browsers.
|owner=[mailto:gkruitbosch@mozilla.com Gijs Kruitbosch]
|peers=[mailto:mbonardo@mozilla.com Marco Bonardo], [mailto:mozilla@noorenberghe.ca Matthew Noorenberghe]
|source_dirs=browser/components/migration/
|url=
|components=
}}

{{Module
|name=Screenshots
|description=Code relating to Screenshots functionality
|owner=[mailto:sfoster@mozilla.com Sam Foster]
|peers=[mailto:jhirsch@mozilla.com Jared Hirsch], [mailto:nbaumgardner@mozilla.com Niklas Baumgardner],
|peersemeritus=[mailto:bchen@mozilla.com Barry Chen]
|ownersemeritus=[mailto:emmamalysz@gmail.com Emma Malysz], [mailto:ian@ianbicking.org Ian Bicking]
|source_dirs=browser/extensions/screenshots, browser/components/screenshots/
|components=Firefox::Screenshots
}}

{{Module
|name=Search and Address Bar
|description=The search service, address bar and address bar autocomplete.
|owner=[mailto:standard8@mozilla.com Mark Banner], [mailto:dwillcoxon@mozilla.com Drew Willcoxon]
|peers=[mailto:dharvey@mozilla.com Dale Harvey], [mailto:mbonardo@mozilla.com Marco Bonardo], [mailto:dao@mozilla.com Dão Gottwald], [mailto:htwyford@mozilla.com Harry Twyford]
|peersemeritus=[mailto:info@mikedeboer.nl Michael de Boer]
|source_dirs=browser/components/search/, browser/components/urlbar/, toolkit/components/search/
|url=
|components=Firefox::Address Bar, Firefox::Search
}}

{{Module
|name=Security and Privacy UI
|description=The front-end to our security and privacy features, including Protections UI, Site Identity, Site Permissions and Certificate Errors
|owner=[mailto:pbz@mozilla.com Paul Zühlcke]
|peers=[mailto:prathiksha@mozilla.com Prathiksha]
|peersemeritus=[mailto:ewright@mozilla.com Erica Wright], Nihanth Subramanya
|ownersemeritus=[mailto:jhofmann@mozilla.com Johann Hofmann]
|source_dirs=browser/components/protections/, browser/components/controlcenter/
|url=
|components=Firefox::Security, Firefox::Protections UI, Firefox::Site Identity, Firefox::Site Permissions
}}

{{Module
|name=Session Restore
|description=Restoring a user's session after starting Firefox.
|owner=[mailto:dao@mozilla.com Dão Gottwald], [mailto:dharvey@mozilla.com Dale Harvey]
|peers=[mailto:afarre@mozilla.com Andreas Farre]
|ownersemeritus=[mailto:info@mikedeboer.nl Michael de Boer], Kashav Madan, Anny Gakhokidze
|source_dirs=browser/components/sessionstore/, toolkit/components/sessionstore/
|url=
|components=Firefox::Session Restore
}}

{{Module
|name=Tabbed Browser
|description=The UI component controlling browser tabs.
|owner=[mailto:dgottwald@mozilla.com Dão Gottwald]
|peers=
|source_dirs=browser/base/content/tabbrowser*, browser/modules/AsyncTabSwitcher.jsm
|url=
|components=Firefox::Tabbed Browser
}}

{{Module
|name=Windows Installer
|description=The installer for Windows.
|owner=[mailto:mhowell@mozilla.com Molly Howell]
|peers=[mailto:agashlin@mozilla.com Adam Gashlin], [mailto:nalexander@mozilla.com Nick Alexander]
|source_dirs=browser/installer/, toolkit/mozapps/installer/
|url=
|components=Firefox::Installer
}}

Security/DNS Over HTTPS

2021-03-23T18:21:12Z

Nhnt11: Updated doorhanger screenshot

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

See also:
# https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/

== Opt-out Doorhanger ==

[[File:DoH CFR.png|frameless|DoH CFR message screenshot]]
* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is available.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

Want to see this in action for yourself?
# On a new profile, navigate to about:config
# Set `doh-rollout.enabled` to true
# Close about:config
# Load/reload any website

You'll need to do this in an environment that doesn't trip our heurisitics, i.e. no Canary and no enterprise config.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* doh-rollout.enabled - Turns on heuristics. Prerequisite for enabling sub-features.
* doh-rollout.provider-steering.enabled - Turns on automatic provider steering.
* doh-rollout.provider-steering.provider-list - Provider data for automatic steering (name, CNAME for discovery, and DoH endpoint)
* doh-rollout.trr-selection.enabled - Turns on automatic performance-based default-TRR selection. Dry-run by default.
* doh-rollout.trr-selection.commit-result - Commits and persists TRR selection dry-run result.

TODO: other state prefs

File:DoH CFR.png

2021-03-23T18:20:42Z

Nhnt11:

The DoH consent CFR as of Release 87.

Security/DNS Over HTTPS

2021-03-23T18:18:21Z

Nhnt11: Fix type "anction"->"action", fix list style

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

See also:
# https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is available.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

Want to see this in action for yourself?
# On a new profile, navigate to about:config
# Set `doh-rollout.enabled` to true
# Close about:config
# Load/reload any website

You'll need to do this in an environment that doesn't trip our heurisitics, i.e. no Canary and no enterprise config.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* doh-rollout.enabled - Turns on heuristics. Prerequisite for enabling sub-features.
* doh-rollout.provider-steering.enabled - Turns on automatic provider steering.
* doh-rollout.provider-steering.provider-list - Provider data for automatic steering (name, CNAME for discovery, and DoH endpoint)
* doh-rollout.trr-selection.enabled - Turns on automatic performance-based default-TRR selection. Dry-run by default.
* doh-rollout.trr-selection.commit-result - Commits and persists TRR selection dry-run result.

TODO: other state prefs

Security/DNS Over HTTPS

2021-03-23T18:17:25Z

Nhnt11: Added instructions to trigger doorhanger

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

See also:
# https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is available.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

Want to see this in anction for yourself?
1. On a new profile, navigate to about:config
2. Set `doh-rollout.enabled` to true
3. Close about:config
4. Load/reload any website

You'll need to do this in an environment that doesn't trip our heurisitics, i.e. no Canary and no enterprise config.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* doh-rollout.enabled - Turns on heuristics. Prerequisite for enabling sub-features.
* doh-rollout.provider-steering.enabled - Turns on automatic provider steering.
* doh-rollout.provider-steering.provider-list - Provider data for automatic steering (name, CNAME for discovery, and DoH endpoint)
* doh-rollout.trr-selection.enabled - Turns on automatic performance-based default-TRR selection. Dry-run by default.
* doh-rollout.trr-selection.commit-result - Commits and persists TRR selection dry-run result.

TODO: other state prefs

Security/DNS Over HTTPS

2020-09-18T14:37:38Z

Nhnt11: Add some pref details

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

See also:
# https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is available.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* doh-rollout.enabled - Turns on heuristics. Prerequisite for enabling sub-features.
* doh-rollout.provider-steering.enabled - Turns on automatic provider steering.
* doh-rollout.provider-steering.provider-list - Provider data for automatic steering (name, CNAME for discovery, and DoH endpoint)
* doh-rollout.trr-selection.enabled - Turns on automatic performance-based default-TRR selection. Dry-run by default.
* doh-rollout.trr-selection.commit-result - Commits and persists TRR selection dry-run result.

TODO: other state prefs

Security/DNS Over HTTPS

2020-07-16T21:08:46Z

Nhnt11: add cname-discovery-steering spec link

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

See also:
# https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T20:44:30Z

Nhnt11: update intro

This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* TODO: list all involved prefs and semantics.

Trusted Recursive Resolver

2020-07-16T20:42:26Z

Nhnt11: link to DNS over HTTPS article

DNS-over-HTTPS (DoH) allows DNS to be resolved with enhanced privacy, secure
transfers and [https://blog.mozilla.org/futurereleases/2019/07/31/dns-over-https-doh-update-detecting-managed-networks-and-user-choice/ comparable] performance. This page describes Firefox configuration settings related to DoH in detail, and offers some explanation of internal operations of the implementation.

Mozilla operates a Trusted Recursive Resolver program, whose requirements are documented at [[Security/DOH-resolver-policy]]. All TRRs offered by Firefox conform to the requirements described in the policy, but not vice versa().

For more information, we've created [https://support.mozilla.org/en-US/kb/firefox-dns-over-https documentation about DoH and our plans for deployment]. We also have an [https://support.mozilla.org/en-US/kb/dns-over-https-doh-faqs FAQ], and instructions for [https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https network operators who wish to disable DoH on their networks].

== DNS-over-HTTPS Rollout ==

Main article: [[Security/DNS Over HTTPS]]

== DNS-over-HTTPS Prefs in Firefox ==

All preferences for the DNS-over-HTTPS functionality in Firefox are located under the `network.trr` prefix (TRR == Trusted Recursive Resolver). The support for these were added in Firefox 62.

; network.trr.mode :
The resolver mode. You should not change the mode manually, instead use the UI in the Network Settings section of about:preferences

* 0 - Off (default). use standard native resolving only (don't use TRR at all)
* 1 - Reserved (used to be Race mode)
* 2 - First. Use TRR first, and only if the name resolve fails use the native resolver as a fallback.
* 3 - Only. Only use TRR, never use the native resolver.
** Up to FF >= 73, this mode also requires the bootstrapAddress pref to be set.
** Starting with Firefox 74, setting the bootstrap address is no longer mandatory - the browser will simply bootstrap itself using regular DNS, unless the DoH server domain can't be resolved.
** The native resolver will still be used for portal detection and telemetry ([https://bugzilla.mozilla.org/show_bug.cgi?id=1593873 Bug 1593873])
* 4 - Reserved (used to be Shadow mode)
* 5 - Off by choice. This is the same as 0 but marks it as done by choice and not done by default.

; network.trr.uri :

(default: none) set the URI for your DoH server. That's the URL Firefox will issue its HTTP request to. It must be a HTTPS URL. If "useGET" is enabled, Firefox will append "?dns=...." to the URI when it makes its HTTP requests. For the default POST requests, they will be issued to exactly the specified URI.

Publicly announced servers include:
* https://mozilla.cloudflare-dns.com/dns-query
* https://dns.google/dns-query

For more servers, see this unofficial list of DoH servers: https://github.com/curl/curl/wiki/DNS-over-HTTPS.

; network.trr.resolvers :

A list of potential resolvers for the user interface. When enabled, the TRR service will always use the value of "network.trr.uri".

; network.trr.credentials :

(default: none) set credentials that will be used in the HTTP requests to the DoH end-point. It is the right-hand side content, the value, sent in the Authorization: request header.

; network.trr.wait-for-portal :

(default: false) set this boolean to **true** to tell Firefox to wait for the captive portal detection before TRR is used. (on Android, this will default to **false** since the captive portal handling is done outside of Firefox, by the OS itself.)

; network.trr.allow-rfc1918 :

(default: false) set this to true to allow RFC 1918 private addresses in TRR responses. When set to false, any such response will be considered invalid and won't be used.

; network.trr.useGET :

(default: false) When the browser issues a request to the DoH server to resolve host names, it can do that using POST or GET. By default Firefox will use POST, but by toggling this you can enforce GET to be used instead.

; network.trr.confirmationNS :

(default: example.com) Firefox will check an NS entry at startup to verify that TRR works to ensure proper configuration. This preference sets which domain to check. The verification only checks for a positive answer, it doesn't actually care what the response data says. Set this to `skip` to completely avoid confirmation.

; network.trr.bootstrapAddress :

(default: none) by setting this field to the IP address of the host name used in "network.trr.uri", you can bypass using the system native resolver for it.
Use this to get the IPs of the cloudflare server: https://dns.google/query?name=mozilla.cloudflare-dns.com

Starting with Firefox 74 setting the bootstrap address is no longer required in mode 3. Firefox will attempt to use regular DNS in order to get the IP address of the trusted resolver. However, if DNS resolution of the resolver domain fails, setting the bootstrap address is again necessary.

; network.trr.blacklist-duration :

(default: 60) is the number of seconds a name will be kept in the TRR blacklist until it expires and then will be tried with TRR again. The default duration is one minute.

Entries are added to the TRR blacklist when the resolution fails with TRR but works with the native resolver, or if the subsequent connection with a TRR resolved host name fails but works with a retry that is resolved natively. When a hostname is added to the TRR, its domain gets checked in the background to see if the whole domain should be blacklisted to ensure a smoother ride going forward.

; network.trr.request_timeout_ms :

(default: 1500) is the number of milliseconds a request and the corresponding response from the DoH server is allowed to take until considered failed and discarded.

; network.trr.request_timeout_mode_trronly_ms :

(default: 30000) is the number of milliseconds a request and the corresponding response from the DoH server is allowed to take until considered failed and discarded in TRR-only mode.

; network.trr.early-AAAA :

(default: false) For each normal name resolution, Firefox issues one HTTP request for A entries and another for AAAA entries. The responses come back separately and can come in any order. If the A records arrive first, Firefox will—as an optimization— continue and use them without waiting for the second response. If the AAAA records arrive first, Firefox will only continue and use them immediately if this option is set to **true**.

; network.trr.skip-AAAA-when-not-supported :

(default: true) If Firefox detects that your system does not have IPv6 connectivity, it will not request IPv6 addresses from the DoH server.

; network.trr.wait-for-A-and-AAAA :

(default: true) When true, the DNS request will wait for both A and AAAA responses (if both have been requested) before notifying the listeners. When true, it effectively cancels `network.trr.early-AAAA`

; network.trr.max-fails :

(default: 5) If this many DoH requests fail in a row, consider TRR broken and go back to verify-NS state. This is meant to detect situations when the DoH server dies.

; network.trr.disable-ECS :

(default: true) If set, TRR asks the resolver to disable ECS (EDNS Client Subnet: the method where the resolver passes on the subnet of the client asking the question). Some resolvers will use ECS to the upstream if this request is not passed on to them.

; network.trr.excluded-domains :

(default: ``) Comma separated list of domain names to be resolved using the native resolver instead of TRR. Users may add domains they wish to exclude from TRR to this pref.

This pref can be used to make /etc/hosts works with DNS over HTTPS in Firefox. Setting network.trr.excluded-domains to include host names from /etc/hosts will make them fall back to platform DNS, which will use the rules in /etc/hosts.

; network.trr.builtin-excluded-domains :

(default: `localhost,local`) Comma separated list of domain names to be resolved using the native resolver instead of TRR. The host of the captive portal detection is also added to the exclusion list internally, in order to be able to detect local captive portals. Users should change this pref as it may get overwritten by changes to the default values.

; network.trr.enable_when_vpn_detected :

(default: false) When false if a '''Windows VPN''' is detected on the system then TRR will be disabled. If true, VPN status will be ignored when deciding if to enable TRR.

; network.trr.enable_when_proxy_detected :

(default: false) When false if a '''Windows System Proxy''' is detected on the system then TRR will be disabled. If true, proxy status will be ignored when deciding if to enable TRR. The proxy is detected by checking the related Windows Registry keys.

; network.trr.enable_when_nrpt_detected :

(default: false) When false on Windows if '''NRPT is detected''' on the system then TRR will be disabled. If true, NRPT status will be ignored when deciding if to enable TRR. NRPT is detected by checking the related Windows Registry keys.

; network.trr.send_user-agent_headers :

(default: false) When false the User-Agent header will not be set on TRR requests.

; network.trr.send_accept-language_headers :

(default: false) When false the Accept-Language header will not be set on TRR requests.

; network.trr.clear-cache-on-pref-change :

(default: true) When true, the DNS+TRR cache will be cleared when a relevant TRR pref changes. (uri, bootstrapAddress, excluded-domains)

== Dynamic Blacklist ==

To keep the failure rate at a minimum, the TRR system manages a dynamic
persistent blacklist for host names that can't be resolved with DOH but works
with the native resolver. Blacklisted entries will not be retried over DOH for one minute.
"localhost" and names in the ".local" TLD will never be
resolved via DOH.

When TRR starts up, it will first verify that it works by first checking a
"confirmation" domain name. This confirmation domain is a pref by default set
to "example.com".

== Notes ==

=== DNS ===

TRR bypasses system DNS so you might not be using any 'enhanced' DNS services provided by your default DNS server which may include Web Content Filtering or basic Malware Protection, phishing protection.

=== ESNI ===

The way ESNI is currently implemented requires TRR. When TRR is disabled ESNI will not work because the platform DNS APIs don't allow retrieving TXT records.

== See also ==

* Initial ticket: https://bugzilla.mozilla.org/show_bug.cgi?id=1434852
* The DNS-over-HTTPS spec: https://tools.ietf.org/html/rfc8484

* https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

Security/DNS Over HTTPS

2020-07-16T20:35:26Z

Nhnt11: rm TODO from migrations section

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T20:29:09Z

Nhnt11: add trr performance info

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`.

See also:
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T20:16:44Z

Nhnt11: fix flow diagram visibility

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:DoH Controller Flow Diagram.png

2020-07-16T20:14:08Z

Nhnt11: Nhnt11 uploaded a new version of File:DoH Controller Flow Diagram.png

DoH Controller Flow Diagram

Security/DNS Over HTTPS

2020-07-16T20:09:18Z

Nhnt11: add main flow diagram

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Flow Diagram ==

[[File:DoH Controller Flow Diagram.png|800px|frameless|DoH Frontend Flow Diagram]]

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:DoH Controller Flow Diagram.png

2020-07-16T20:07:46Z

Nhnt11:

DoH Controller Flow Diagram

Security/DNS Over HTTPS

2020-07-16T18:49:56Z

Nhnt11: update provider steering flow size

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T18:49:23Z

Nhnt11: update provider steering flow size

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|545px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:DoH provider steering flow.png

2020-07-16T18:48:41Z

Nhnt11: Nhnt11 uploaded a new version of File:DoH provider steering flow.png

DoH provider steering flow

Security/DNS Over HTTPS

2020-07-16T18:46:32Z

Nhnt11: add provider steering flow diagram

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

[[File:DoH provider steering flow.png|800px|frameless|DoH Provider Steering Flow]]

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:DoH provider steering flow.png

2020-07-16T18:46:10Z

Nhnt11:

DoH provider steering flow

Security/DNS Over HTTPS

2020-07-16T18:29:17Z

Nhnt11: dry-run mechanism header level decrease

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

==== Dry-Run Mechanism ====

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T18:28:55Z

Nhnt11: increase trrselect flow size

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

=== Dry-Run Mechanism ===

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T18:28:04Z

Nhnt11: add trrselect flow

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

=== Dry-Run Mechanism ===

* Default provider selection is done in two phases: a dry-run followed by committing the result.
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`.
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`.

[[File:DoH automatic provider selection flow.png|frameless|DoH automatic provider selection flow]]

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:DoH automatic provider selection flow.png

2020-07-16T18:26:02Z

Nhnt11:

DoH automatic provider selection flow

Security/DNS Over HTTPS

2020-07-16T16:17:17Z

Nhnt11: undo align cfr screenshot on the right

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T16:16:41Z

Nhnt11: align cfr screenshot on the right

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|right|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T16:15:47Z

Nhnt11: move cfr screenshot to top of section

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T16:15:21Z

Nhnt11: add links and remove todos, add cfr screenshot

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651

[[File:Cfr.png|frameless|DoH CFR message screenshot]]

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

File:Cfr.png

2020-07-16T16:14:55Z

Nhnt11:

CFR message screenshot

Security/DNS Over HTTPS

2020-07-16T16:06:55Z

Nhnt11: update rollout bug link

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].
* TODO: flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T16:06:21Z

Nhnt11: cleanup

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
# https://bugzilla.mozilla.org/show_bug.cgi?id=1573840

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].
* TODO: flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T16:05:55Z

Nhnt11: link to implementation

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.

See also:
1. https://bugzilla.mozilla.org/show_bug.cgi?id=1573840

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].
* TODO: flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS/Heuristics

2020-07-16T16:05:31Z

Nhnt11: add links for third-party roots section

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

'''High-level overview:''' https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh/DoHHeuristics.jsm 
[https://searchfox.org/mozilla-central/source/browser/components/doh/DoHController.jsm DoHController.jsm] is responsible for running them at startup and upon network changes, and taking action to disable or enable DoH based on the outcome.

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
# [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
# https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
# https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

See also:
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/security/manager/ssl/nsIX509CertDB.idl#329
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/security/manager/ssl/nsIX509Cert.idl#47

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
# https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
# https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS/Heuristics

2020-07-16T16:02:55Z

Nhnt11: clean intro more

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

'''High-level overview:''' https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh/DoHHeuristics.jsm 
[https://searchfox.org/mozilla-central/source/browser/components/doh/DoHController.jsm DoHController.jsm] is responsible for running them at startup and upon network changes, and taking action to disable or enable DoH based on the outcome.

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
# [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
# https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
# https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
# https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
# https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS/Heuristics

2020-07-16T16:02:28Z

Nhnt11: clean up intro

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

'''High-level overview:''' https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh/DoHHeuristics.jsm
[https://searchfox.org/mozilla-central/source/browser/components/doh/DoHController.jsm DoHController.jsm] is responsible for running them at startup and upon network changes, and taking action to disable or enable DoH based on the outcome.

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
# [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
# https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
# https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
# https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
# https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS/Heuristics

2020-07-16T16:01:08Z

Nhnt11: add code links

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. This page details each heuristic we use.

Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

A high-level overview is also available here: https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

Heuristics are implemented in [https://searchfox.org/mozilla-central/source/browser/components/doh/DoHHeuristics.jsm DoHHeuristics.jsm]
[https://searchfox.org/mozilla-central/source/browser/components/doh/DoHController.jsm DoHController.jsm] is responsible for running them at startup and upon network changes, and taking action to disable or enable DoH based on the outcome.

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
# [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
# https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
# https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
# https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
# https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS

2020-07-16T15:51:48Z

Nhnt11: update heuristics link

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* TODO: links to tickets, bugs, dashboards etc.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* Main article: [[Security/DNS Over HTTPS/Heuristics]].
* TODO: flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-16T15:50:57Z

Nhnt11: link individual heuristics doc

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* TODO: links to tickets, bugs, dashboards etc.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* The individual heuristics are documented [[Security/DNS Over HTTPS/Heuristics|here]].
* TODO: flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS/Heuristics

2020-07-16T15:49:11Z

Nhnt11: use lists in markup

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. This page details each heuristic we use.

Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

A high-level overview is also available here: https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
# [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
# https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
# https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
# https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
# https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS/Heuristics

2020-07-16T15:48:24Z

Nhnt11: add doc for individual heuristics

Firefox runs several heuristics on each network to determine whether it's OK to enable DoH on that network. This page details each heuristic we use.

Generally, the heuristics attempt to disable DoH in order to support parental controls and enterprise configurations.

A high-level overview is also available here: https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

== Global Canary ==

See https://support.mozilla.org/en-US/kb/canary-domain-use-application-dnsnet

== Parental Controls Service ==

[https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/nsIParentalControlsService.idl nsIParentalControlsService] provides an interface to check whether parental controls are enabled on the user account on the OS. If so, we disable DoH.

See also:
1. [https://searchfox.org/mozilla-central/source/toolkit/components/parentalcontrols/ Parental Controls Service component]
2. https://developer.apple.com/documentation/devicemanagement/parentalcontrolscontentfilter
3. https://docs.microsoft.com/en-us/windows/win32/parcon/using-parental-controls-settings-apis

== Forced SafeSearch (DNS-based Parental Controls) ==

As a way to detect DNS-based content filtering, we perform DNS lookups of filtered and unfiltered domains of popular content platforms. If any of the IPs returned for the filtered domains of a given platform are identical to any of the IPs returned for the unfiltered domains, we disable DoH. Currently, Google and YouTube are supported.

== Third-party Root Certificates ==

We look at all certs in the cert database and check if any of them are not "built-in". If such certs are present, we disable DoH.

== Enterprise Policies ==

If enterprise policies are active, we disable DoH unless it is explicitly enabled by the DNSOverHTTPS policy.

See also:
1. https://support.mozilla.org/en-US/products/firefox-enterprise/policies-customization-enterprise/policies-overview-enterprise

== Enterprise Roots ==

If enterprise root support has been enabled by setting the pref `security.enterprise_roots.enabled` to true, we disable DoH.

See also:
1. https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox

== ZScaler Canary Domain ==

Currently, ZScaler has not yet adopted the global canary, and is supported by a separate canary lookup heuristic that operates on `sitereview.zscaler.com`.

Security/DNS Over HTTPS

2020-07-15T23:54:30Z

Nhnt11: add prefs section

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* TODO: links to tickets, bugs, dashboards etc.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* TODO: more details, individual docs for each heuristic, flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

== Prefs ==

* TODO: list all involved prefs and semantics.

Security/DNS Over HTTPS

2020-07-15T23:52:53Z

Nhnt11: clean up intro

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* TODO: links to tickets, bugs, dashboards etc.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* TODO: more details, individual docs for each heuristic, flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

Security/DNS Over HTTPS

2020-07-15T23:52:03Z

Nhnt11: add todos

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend and its sub-features are gated behind prefs that are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* TODO: links to tickets, bugs, dashboards etc.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass, and disabled otherwise.
* TODO: more details, individual docs for each heuristic, flow diagram

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* TODO: sub-page for documenting the mechanism, flow diagram, links to code/docs

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.
* TODO: links to CFR code/docs, screenshot

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.
* TODO: links to Events.yaml, data review bugs, etc.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.
* TODO: sub-page with details on each migration, versioning, links to code.

Security/DNS Over HTTPS

2020-07-15T23:47:07Z

Nhnt11: improve reading flow

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* DoH is enabled on the network if all heuristics pass.

== Respecting User-choice ==

* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
* This holds for prefs that were set prior to enrollment in the rollout.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Default Provider Selection ==

* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.

== Provider Steering ==

* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work.
* Currently, Comcast is the only supported provider.
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

Security/DNS Over HTTPS

2020-07-15T22:21:02Z

Nhnt11: change "popup" to "doorhanger"

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.

== User-choice ==

* User-choice is respected throughout the frontend code.
* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* If all of the heuristics pass, DoH is enabled by setting the pref `doh-rollout.mode=2`.
* If any heuristic fails, DoH is disabled by setting the pref `doh-rollout.mode=0`.

== Default Provider Selection ==

* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)

== Provider Steering ==

* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* Currently, Comcast is the only supported provider.

== Opt-out Doorhanger ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This doorhanger offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The doorhanger is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The doorhanger is implemented as a CFR message, gated behind the relevant prefs.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

Security/DNS Over HTTPS

2020-07-15T22:18:38Z

Nhnt11: split enterprise policy point into two for easy reading

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.

== User-choice ==

* User-choice is respected throughout the frontend code.
* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client.
* This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* If all of the heuristics pass, DoH is enabled by setting the pref `doh-rollout.mode=2`.
* If any heuristic fails, DoH is disabled by setting the pref `doh-rollout.mode=0`.

== Default Provider Selection ==

* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)

== Provider Steering ==

* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* Currently, Comcast is the only supported provider.

== Opt-out Popup ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This popup offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The popup is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The popup is implemented as a CFR message, gated behind the relevant prefs.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

Security/DNS Over HTTPS

2020-07-15T22:14:38Z

Nhnt11: Add basic doc for DoH frontend.

This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.

== Rollout ==

* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* Every mechanism described below depends on this pref being set to true.
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.

== User-choice ==

* User-choice is respected throughout the frontend code.
* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.

== Enterprise Policy ==

* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client. This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.

== Heuristics ==

* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* If all of the heuristics pass, DoH is enabled by setting the pref `doh-rollout.mode=2`.
* If any heuristic fails, DoH is disabled by setting the pref `doh-rollout.mode=0`.

== Default Provider Selection ==

* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)

== Provider Steering ==

* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* Currently, Comcast is the only supported provider.

== Opt-out Popup ==

* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This popup offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The popup is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The popup is implemented as a CFR message, gated behind the relevant prefs.

== Telemetry ==

* Interaction and functional data is collected in the form of two telemetry Events.
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc.
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status.

== Migrations ==

* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* Two of the migrations work on the format of stored state (local storage and prefs)
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one.

Berlin Office

2019-02-05T17:49:35Z

Nhnt11: Removed my email from the bridge photo description

[[File:Oberbaumbrucke.jpg|thumbnail|upright=1.8|right|link=|alt=Oberbaumbrücke|The Oberbaum Bridge as seen from the office]]

= Welcome To Berlin! =

Welcome to the Berlin office! We're glad to have you here!

''Come and join us for some German beer, some Currywurst, and our fun new space...''

=== Need Help with a Mozilla product? ===
<div style="background: yellow;">
For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
Please understand that Mozilla, as a non-profit, cannot provide phone support.
</div>

= Office Logistics =
To access the building use the driveway to the courtyard of Schlesische Strasse 27 and go straight until the end of the area. Then enter Haus 3 entrance C on the lefthand side. You can use either stairs or the elevator to go to the 4th Floor.

==Accessibility==
The building entrance door opens automatically. However, the next door needs to be opened manually. Once you pass them, there are two elevators on the righthand side. Press the button and choose 4th floor (it is where our welcome/reception area is located).
There is a grey door on the right when you exit the elevator on the 4th floor; they remain open. The glass door at the end of the short corridor can be opened with a badge.
There are two floors in the office connected by an internal stairwell. If you want to use the kitchen or event space on the 3rd floor, please take the same elevator you used to get to the 4th / reception floor.
There are 2 accessible toilets, one on each floor.
-3rd floor- On the lefthand side as you enter the event & community space.
-4th floor- On the lefthand side as you enter the reception area.

== Rooms ==
* Entrance area with comfy lounge space
* A common space that can be extended to fit 80 people
* Conferencing rooms equipped for video conferencing
* A community space with an adjacent maker space
* Kitchen with a great view, serving refrigerated drinks, espresso machine, dishwasher, snack bar

= Getting Here =

=== Traveling to Berlin ===
Berlin has two functional airports: Tegel (TXL) and Schönefeld (SXF):

* Tegel is closer to the city center and has service from transatlantic flights (Brussels Airlines, United, Air Canada Rouge) as well as many normal-cost air carriers. Some flights departing from terminal A allow you to get very quickly from the gate to the waiting lounge because each jetbridge has its own gate, security, and lounge. All other terminals in Tegel take a little longer.
* Schönefeld is a little further from the city's center, but also has a very easy connection to the office. Schönefeld is primarily served by low-cost air carriers (Ryanair, Easyjet).

Berlin is also well connected by train. The closest major station for long distance and international trains is the Ostbahnhof. If the train does not stop at Ostbahnhof, then the Hauptbahnhof is the next best choice.

=== Public transportation ===

[[File:Berlin public transport logos.png|thumbnail|upright=1.6|right|link=|alt=Berlin public transport logos|Indicating the next local train ("S-Bahn"), subway ("U-Bahn"), or bus station.]]The subway ("U-Bahn") station closest to the office is Schlesisches Tor, served by '''subway line U1''' (which actually drives above the earth in this section of the line). Another great choice is S-Bahn station '''Warschauer Straße''', from which it is a 10 to 15-minute walk to the office, or '''Treptower Park''', from which you can take a 10-minute walk or bus 165/265 to '''Taborstraße''' right in front of the office. You can find information on the metro service and maps here: http://www.bvg.de/en/Travel-information

* The transit authority in Berlin is [http://www.vbb.de/en/index.html VBB]. Most inner city services are operated by [http://www.bvg.de/en/ BVG] and [http://www.s-bahn-berlin.de/en S-Bahn-Berlin].
* There are three fare zones in Berlin: A, B, and C. A is the inner city, bounded by the Ringbahn (S41/S42). B is between the Ringbahn and the Brandenburg border. C is Brandenburg.
* Tickets are sold as AB, BC or ABC. An AB or BC can be extended to the third zone with the purchase of an "Anschlussfahrausweis". This also applies to single rides in concert with a flat rate (daily/weekly/monthly) ticket.
* You will almost exclusively use AB tickets. The main exception is a trip to Schönefeld Airport (SXF), which requires zone C
* A ticket from BVG can be used on an S-Bahn-Berlin and vice versa
* A ticket from BVG/S-Bahn-Berlin can be used on regional trains within the ticketed zone. These are trains which have a number like "RE1" or "RB1". They are primarily operated by DB Regio (mainly red), ODEG (grey with yellow lettering) and NEB (blue and white).
* A ticket from BVG/S-Bahn-Berlin '''cannot''' be used on long-distance trains, even within the ticketed zone. Google maps sometimes suggest these routes in their transit directions. These are trains with routes like "IC 500", "EC 40" or "ICE 100". In Berlin, these are often grey with a thin horizontal red stripe (DB), light blue (PKP), dark blue (ČD) or light blue with a white stripe (MÁV)
* '''A single ride ticket is valid for two hours, but only for one direction.'''
* Berlin time-based transit tickets are valid until 3:00 AM the following day
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=399 Subway and S-Bahn train map (region ABC) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=400 Subway and S-Bahn train map (city/region AB) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=401 Tram map (PDF)]
* [http://fahrinfo.bvg.de/Fahrinfo/bin/query.bin/en/dn?ujm=1&MapLayer=NETWORK Interactive map]
* Day tickets are cheaper when taking three rides or more. Also: buying tickets in sets of 4 gives you a decent deal.
* Day tickets for groups up to five people are dirt-cheap.
* Multi-day tickets (regular ones or the "City/Welcome" variety which allow rebates in certain museums and restaurants) are not really a good deal.
* Every ticket machine also sells special tickets, but they're hidden in sub-menus. Keep digging! Most support changing to English on the main screen.
* Remember to always validate your ticket before boarding a subway, S-Bahn or regional train. Ticket validation machines are located near the ticket machine itself and on the platforms.
* Most ticket machines accept coins. Ticket machines might additionally accept a combination of credit card, banknotes <= 10€, any banknote and EC card (German debit cards).
* If the ticket machine doesn't like your coin, rub the edge against the machine and try again

==== Smartphone Apps ====
Google maps give pretty good transit directions in Berlin and are available for Ios and Android. Transit app, Here maps, and Citymapper also work well

The single best public transportation app for Android is [https://play.google.com/store/apps/details?id=de.schildbach.oeffi&hl=en Öffi]. It covers all of Germany and is available for free through Google Play.
* Open "Öffi Directions", choose ''My current location'' as starting point and ''Schlesisches Tor'' (U-Bahn stop close to the office) or ''Taborstraße'' (bus stop directly in front of the office) as your destination, and you should be good to go.

There's also the BVG Fahrinfo app, which is BVG's official transit app. This app gives really good transit directions as well as schedules. You can also buy tickets directly from the app.

==== From Tegel Airport TXL ====
* The recommended route from TXL to the office is via the S-Bahn ring. From the airport, take bus TXL to S Beusselstraße (2 stops). From there, take S41 (via Gesundbrunnen, Ostkreuz) to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight (it's a beautiful walk!). You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Schönefeld Airport SXF ====
* '''NOTE''': you will require a ticket in fare zone ABC
* The recommended route from SXF is via S-Bahn route S9. From the airport, take the S9 to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight. You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Berlin Hauptbahnhof, Ostbahnhof or Alexanderplatz train station ====
* The recommended route is the S5, S7 or S75. All of these stations are on all of these routes. From the station, take the route to Warschauer Strasse station. From Warschauer Strasse station, either walk or take the U1 one stop to Schlesisches Tor U-Bahn.

My Taxi

If you know you need to take a lot of taxis while you are in town, we suggest downloading the [http://www.mytaxi.com/en/passengers/mytaxi-in-your-city/berlin.html MyTaxi] app. You can filter taxis by who takes card, how many people you need to pick up etc.

* Most taxi rides within central Berlin are around 10 EUR, hardly more than 15 EUR.

= Visiting Berlin =

=== Hotels ===

;Michelberger Hotel
http://michelbergerhotel.com/
15min walk from the office. Great location, great hotel. Free yoga class on Thursdays, make their own coconut water. Delicious food (local and made from scrap) and drinks. Rooms range from "Cozy" (very tiny but beautiful and has everything you need) to a larger scale. More hipster vibe. Very different from your usual hotel. It's an experience in itself.

;'''Hotel Johann'''
https://www.hotel-johann-berlin.de/ in Johanniterstrasse (U1 Prinzenstr). This is definitely outside of walking distance, but if you take the U1 towards Schlesisches Tor, you are close.

;'''Hotel Vier Jahreszeiten'''
http://vj-hotels.com/ in Skalitzer Str (U1 Görlitzer Bhf). Similar as Hotel Johann, just 2 stops closer

=== Tipping & Money ===

* Local Currency: Euro
* It is customary in Germany to tip a little by rounding up and around 10% at restaurants for good service. Tipping in bars is not something many Europeans do.
* Not many places accept Credit/Debit Card. Many smaller restaurants and shops do not accept credit cards like in the US and other larger European cities. Please be prepared to pay in cash. It's a good practice in Berlin to ask in advance of making a restaurant reservation if they accept credit cards.

=== Things to do in Berlin ===

'''Museums'''

* [http://www.computerspielemuseum.de/1210_Home.htm Computerspielemuseum] – computer games museum (see [https://en.wikipedia.org/wiki/Computerspielemuseum_Berlin Wikipedia]) in Friedrichshain
* [https://www.ddr-museum.de/en DDR-Museum] – an interactive museum about the German Democratic Republic (GDR) in Mitte
*Museum Insel [https://www.museumsinsel-berlin.de/en/buildings/overview-of-the-buildings/] - 'Museum Island' is a unique complex of 5 significant national museums on the Spree Island. It is on the UNESCO World Heritage List.

'''Sight Seeing'''

* [http://en.wikipedia.org/wiki/Fernsehturm_Berlin Fernsehturm am Alexanderplatz] – best view of the city, but long waiting lines
* [https://www.google.com/maps/place/Oranienstraße Oranienstr. in Kreuzberg] – lots of cafes, bars, and restaurants
* Take one ride around the [http://en.wikipedia.org/wiki/Berlin_Ringbahn S-Bahn-Ring]. Train lines 41 or 42. A public transport ticket (region AB) is only 2.70 EUR. The full circle takes about an hour and will show you many facets of the city and you'll see people from all walks of life.
* [http://berliner-teufelsberg.com/web/ Teufelsberg] – the old NSA listening post
* [http://berliner-unterwelten.de/home.1.1.html Berliner Unterwelten] – awesome guided tours through old bunkers and other abandoned, mostly underground places.

'''Websites for short stays!'''

* [http://fotostrasse.1982.us/what-to-do-in-berlin-mainstream-tour-guide/ 24 Hours Guide]
* [http://www.12hrs.net/guides/12-hrs-in-berlin-with-herbert-hofmann/ 12 Hours Guide]

=== Restaurants ===

Freischwimmer[https://www.freischwimmer-berlin.com/] 
Vor dem Schlesischen Tor 2, 10997 Berlin 
Waterside dining space with wooden decking over the water, comfy rooms, serving an eclectic menu.

Burgermeister 
Oberbaumstraße 8, 10997 Berlin 
Delicious and fast burgers right at the U1 Schlesisches Tor.

Curry 36[http://www.curry36.de/] 
Mehringdamm 36, 10961 Berlin Kreuzberg 
Typically Berlin fast food place serving pork sausage with curry ketchup.

Schwarzwaldstuben [http://www.schwarzwaldstuben-berlin.com/] 
Tucholskystraße 48, 10117 Berlin-Mitte 
Simple and tasty South German cuisine. Located in Mitte, close to Rosenthaler Platz and Hackescher Markt.

Zur Gerichtslaube [http://www.gerichtslaube.de/?lang=en] 
Poststraße 28 · 10178 Berlin Mitte / Nikolaiviertel 
If you would like to see traditional German restaurant and try creamy potato soup, 'Berliner style' grilled sausage or oven-fresh apple-strudel, this place is for you!

<div class="h-card">
Sadhu https://foursquare.com/v/sadhu/4afef6f7f964a520323222e3 
Falckensteinstr. 41,
10997
Berlin Wrangelkiez
Excellent Indian Food! Can accommodate medium to large parties with a reservation.
</div>

=== Bars ===
Hopfenreich[hopfenreich.de 
Sorauer Str. 31, 10997 Berlin
If you’re looking for a Bar with Craft Beers from Berlin, Germany and all over the world you should check this one out.

John Muir[http://johnmuirberlin.com/] 
Skalitzer Str. 51, 10997 Berlin
Good Cocktails and live music in the heart of Kreuzberg.

[http://weinerei.com/forum/ Forum Wine Bar] 
Fehrbelliner Straße 57, 10119 Berlin, Germany 
The Forum wine bar is super cool. You pay 2EUR when you enter and you drink as much wine as you want and eat from their small salad bar. In the end, you pay what you feel it was worth. Done!

[http://www.eschschloraque.de/ Eschschloraque] 
Rosenthaler Straße 39, 10178 Berlin 
Where all the hackers hang out. Smoker's bar. Pro-tipp: order a "Tschunk" (Caipirinha with Club-Mate). It's close to S-Bahn stop Hackescher Markt in walking distance from Alexanderplatz, and easy to miss with the entrance hidden deep inside the backyard.

[http://www.brauhaus-lemke.com/index.php/home Brauhaus Lemke] 
Dircksenstraße 143, 10178 Berlin 
Very, very German and not nearly as bad as it sounds. They serve decent foods and very tasty beer from their own brewery. Pro-tipp: order a "Bierprobe", which is a small sample of all their beers. Located right next to S-Bahn stop Hackescher Markt and in walking distance from Alexanderplatz.

[http://vagabundbrauerei.com/ Vagabund Brauerei] 
Antwerpenerstr. 3, 13353 Berlin 
Bar with built-in micro brewery located in district Wedding. Watch your beer in the making.

=== Hacker / Maker Spaces ===

[[Berlin Makerspace|Mozilla Makerspace]] 
[[Berlin Office|Mozilla Office Berlin]] 
Mozilla's Berlin office is home to Mozilla's first dedicated maker space. Swing by if you want to learn, share or just make something.

[http://x-hain.de XHain] 
Grünberger Str. 14, 10243 Berlin 
One of the youngest maker spaces of Berlin located near S-Bahn stop Warschauer Straße. It's just a 15-minute walk from the office. The space is very active and we hear that people there are unusually friendly and welcoming.

[http://c-base.org/ c-base] 
Rungestraße 20, 10179 Berlin 
The largest hackerspace of the city located directly on the river Spree near Subway/S-Bahn station Jannowitzbrücke. It's not easy to find because it's located in the second backyard from the street. Open every day, it has regular and irregular events on most of the evenings and parties on the weekends. The included bar also sells the legendary "Tschunk".

[http://www.raumfahrtagentur.org/ Raumfahrtagentur] 
Gerichtstr. 15, 13347 Berlin 
Need to quickly machine your metal parts, 3D-print a case for your electronics project, or sew your pants? Or reverse-engineer your DNA in a biolab, smell the vegetables or just hang out in the hot tub of a massively green backyard garden? The "Space Agency" is one of the most well-equipped fablabs you'll find in this country, and always worth a little visit.

= Berlin Office Location =

'''Address:''' 
Mozilla Berlin 
Gebäude 3, 4. Obergeschoss 
Schlesische Straße 27 
10997 Berlin 
Germany

'''Additional Information'''

*Finding the office ([https://www.openstreetmap.org/node/4996803917 location on OpenStreetMap]): Use driveway Schlesische Str. 27 ([https://wiki.mozilla.org/images/thumb/b/b4/Moz_berlin_entrance.jpg/800px-Moz_berlin_entrance.jpg see photo]). Walk along the cobblestone path all the way to the end. We are in the white building, and the entrance is on the left side right before the path ends ([https://wiki.mozilla.org/images/thumb/a/ae/Moz_berlin_entrance1.jpg/450px-Moz_berlin_entrance1.jpg see photo]). Enter through the door marked "Treppenhaus C" ([https://wiki.mozilla.org/images/thumb/e/e5/Moz_berlin_door.jpg/450px-Moz_berlin_door.jpg see photo]), and go up to the 4th floor. The door to the office is marked by a Mozilla Berlin sticker ([https://wiki.mozilla.org/images/thumb/2/20/Moz_berlin_sticker.jpg/450px-Moz_berlin_sticker.jpg see photo]).
*Bikes: Our office is also bike friendly! To access the bike shed, enter through the ''''third'''' floor, if you don't want to use one of the many racks outside of our building. We also have a bike for guests!

* '''This is not a support hotline. For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
* '''Main Office''': +49 30 56795983
* '''Reception Desk''': +49 30 56795986
* '''Fax''': +49 30 56795987

= Emergency Information =

* Emergency Services: 110 (police), 112 (ambulance, fire), mobile networks also support 911

Berlin Office

2019-02-05T14:59:16Z

Nhnt11: Updated Oberbaumbrucke description text

[[File:Oberbaumbrucke.jpg|thumbnail|upright=1.8|right|link=|alt=Oberbaumbrücke|The Oberbaum Bridge as seen from the office, CC-ZERO nhnt11(at)gmail(dot)com]]

= Welcome To Berlin! =

Welcome to the Berlin office! We're glad to have you here!

''Come and join us for some German beer, some Currywurst, and our fun new space...''

=== Need Help with a Mozilla product? ===
<div style="background: yellow;">
For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
Please understand that Mozilla, as a non-profit, cannot provide phone support.
</div>

= Office Logistics =
To access the building use the driveway to the courtyard of Schlesische Strasse 27 and go straight until the end of the area. Then enter Haus 3 entrance C on the lefthand side. You can use either stairs or the elevator to go to the 4th Floor.

==Accessibility==
The building entrance door opens automatically. However, the next door needs to be opened manually. Once you pass them, there are two elevators on the righthand side. Press the button and choose 4th floor (it is where our welcome/reception area is located).
There is a grey door on the right when you exit the elevator on the 4th floor; they remain open. The glass door at the end of the short corridor can be opened with a badge.
There are two floors in the office connected by an internal stairwell. If you want to use the kitchen or event space on the 3rd floor, please take the same elevator you used to get to the 4th / reception floor.
There are 2 accessible toilets, one on each floor.
-3rd floor- On the lefthand side as you enter the event & community space.
-4th floor- On the lefthand side as you enter the reception area.

== Rooms ==
* Entrance area with comfy lounge space
* A common space that can be extended to fit 80 people
* Conferencing rooms equipped for video conferencing
* A community space with an adjacent maker space
* Kitchen with a great view, serving refrigerated drinks, espresso machine, dishwasher, snack bar

= Getting Here =

=== Traveling to Berlin ===
Berlin has two functional airports: Tegel (TXL) and Schönefeld (SXF):

* Tegel is closer to the city center and has service from transatlantic flights (Brussels Airlines, United, Air Canada Rouge) as well as many normal-cost air carriers. Some flights departing from terminal A allow you to get very quickly from the gate to the waiting lounge because each jetbridge has its own gate, security, and lounge. All other terminals in Tegel take a little longer.
* Schönefeld is a little further from the city's center, but also has a very easy connection to the office. Schönefeld is primarily served by low-cost air carriers (Ryanair, Easyjet).

Berlin is also well connected by train. The closest major station for long distance and international trains is the Ostbahnhof. If the train does not stop at Ostbahnhof, then the Hauptbahnhof is the next best choice.

=== Public transportation ===

[[File:Berlin public transport logos.png|thumbnail|upright=1.6|right|link=|alt=Berlin public transport logos|Indicating the next local train ("S-Bahn"), subway ("U-Bahn"), or bus station.]]The subway ("U-Bahn") station closest to the office is Schlesisches Tor, served by '''subway line U1''' (which actually drives above the earth in this section of the line). Another great choice is S-Bahn station '''Warschauer Straße''', from which it is a 10 to 15-minute walk to the office, or '''Treptower Park''', from which you can take a 10-minute walk or bus 165/265 to '''Taborstraße''' right in front of the office. You can find information on the metro service and maps here: http://www.bvg.de/en/Travel-information

* The transit authority in Berlin is [http://www.vbb.de/en/index.html VBB]. Most inner city services are operated by [http://www.bvg.de/en/ BVG] and [http://www.s-bahn-berlin.de/en S-Bahn-Berlin].
* There are three fare zones in Berlin: A, B, and C. A is the inner city, bounded by the Ringbahn (S41/S42). B is between the Ringbahn and the Brandenburg border. C is Brandenburg.
* Tickets are sold as AB, BC or ABC. An AB or BC can be extended to the third zone with the purchase of an "Anschlussfahrausweis". This also applies to single rides in concert with a flat rate (daily/weekly/monthly) ticket.
* You will almost exclusively use AB tickets. The main exception is a trip to Schönefeld Airport (SXF), which requires zone C
* A ticket from BVG can be used on an S-Bahn-Berlin and vice versa
* A ticket from BVG/S-Bahn-Berlin can be used on regional trains within the ticketed zone. These are trains which have a number like "RE1" or "RB1". They are primarily operated by DB Regio (mainly red), ODEG (grey with yellow lettering) and NEB (blue and white).
* A ticket from BVG/S-Bahn-Berlin '''cannot''' be used on long-distance trains, even within the ticketed zone. Google maps sometimes suggest these routes in their transit directions. These are trains with routes like "IC 500", "EC 40" or "ICE 100". In Berlin, these are often grey with a thin horizontal red stripe (DB), light blue (PKP), dark blue (ČD) or light blue with a white stripe (MÁV)
* '''A single ride ticket is valid for two hours, but only for one direction.'''
* Berlin time-based transit tickets are valid until 3:00 AM the following day
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=399 Subway and S-Bahn train map (region ABC) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=400 Subway and S-Bahn train map (city/region AB) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=401 Tram map (PDF)]
* [http://fahrinfo.bvg.de/Fahrinfo/bin/query.bin/en/dn?ujm=1&MapLayer=NETWORK Interactive map]
* Day tickets are cheaper when taking three rides or more. Also: buying tickets in sets of 4 gives you a decent deal.
* Day tickets for groups up to five people are dirt-cheap.
* Multi-day tickets (regular ones or the "City/Welcome" variety which allow rebates in certain museums and restaurants) are not really a good deal.
* Every ticket machine also sells special tickets, but they're hidden in sub-menus. Keep digging! Most support changing to English on the main screen.
* Remember to always validate your ticket before boarding a subway, S-Bahn or regional train. Ticket validation machines are located near the ticket machine itself and on the platforms.
* Most ticket machines accept coins. Ticket machines might additionally accept a combination of credit card, banknotes <= 10€, any banknote and EC card (German debit cards).
* If the ticket machine doesn't like your coin, rub the edge against the machine and try again

==== Smartphone Apps ====
Google maps give pretty good transit directions in Berlin and are available for Ios and Android. Transit app, Here maps, and Citymapper also work well

The single best public transportation app for Android is [https://play.google.com/store/apps/details?id=de.schildbach.oeffi&hl=en Öffi]. It covers all of Germany and is available for free through Google Play.
* Open "Öffi Directions", choose ''My current location'' as starting point and ''Schlesisches Tor'' (U-Bahn stop close to the office) or ''Taborstraße'' (bus stop directly in front of the office) as your destination, and you should be good to go.

There's also the BVG Fahrinfo app, which is BVG's official transit app. This app gives really good transit directions as well as schedules. You can also buy tickets directly from the app.

==== From Tegel Airport TXL ====
* The recommended route from TXL to the office is via the S-Bahn ring. From the airport, take bus TXL to S Beusselstraße (2 stops). From there, take S41 (via Gesundbrunnen, Ostkreuz) to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight (it's a beautiful walk!). You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Schönefeld Airport SXF ====
* '''NOTE''': you will require a ticket in fare zone ABC
* The recommended route from SXF is via S-Bahn route S9. From the airport, take the S9 to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight. You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Berlin Hauptbahnhof, Ostbahnhof or Alexanderplatz train station ====
* The recommended route is the S5, S7 or S75. All of these stations are on all of these routes. From the station, take the route to Warschauer Strasse station. From Warschauer Strasse station, either walk or take the U1 one stop to Schlesisches Tor U-Bahn.

My Taxi

If you know you need to take a lot of taxis while you are in town, we suggest downloading the [http://www.mytaxi.com/en/passengers/mytaxi-in-your-city/berlin.html MyTaxi] app. You can filter taxis by who takes card, how many people you need to pick up etc.

* Most taxi rides within central Berlin are around 10 EUR, hardly more than 15 EUR.

= Visiting Berlin =

=== Hotels ===

;Michelberger Hotel
http://michelbergerhotel.com/
15min walk from the office. Great location, great hotel. Free yoga class on Thursdays, make their own coconut water. Delicious food (local and made from scrap) and drinks. Rooms range from "Cozy" (very tiny but beautiful and has everything you need) to a larger scale. More hipster vibe. Very different from your usual hotel. It's an experience in itself.

;'''Hotel Johann'''
https://www.hotel-johann-berlin.de/ in Johanniterstrasse (U1 Prinzenstr). This is definitely outside of walking distance, but if you take the U1 towards Schlesisches Tor, you are close.

;'''Hotel Vier Jahreszeiten'''
http://vj-hotels.com/ in Skalitzer Str (U1 Görlitzer Bhf). Similar as Hotel Johann, just 2 stops closer

=== Tipping & Money ===

* Local Currency: Euro
* It is customary in Germany to tip a little by rounding up and around 10% at restaurants for good service. Tipping in bars is not something many Europeans do.
* Not many places accept Credit/Debit Card. Many smaller restaurants and shops do not accept credit cards like in the US and other larger European cities. Please be prepared to pay in cash. It's a good practice in Berlin to ask in advance of making a restaurant reservation if they accept credit cards.

=== Things to do in Berlin ===

'''Museums'''

* [http://www.computerspielemuseum.de/1210_Home.htm Computerspielemuseum] – computer games museum (see [https://en.wikipedia.org/wiki/Computerspielemuseum_Berlin Wikipedia]) in Friedrichshain
* [https://www.ddr-museum.de/en DDR-Museum] – an interactive museum about the German Democratic Republic (GDR) in Mitte
*Museum Insel [https://www.museumsinsel-berlin.de/en/buildings/overview-of-the-buildings/] - 'Museum Island' is a unique complex of 5 significant national museums on the Spree Island. It is on the UNESCO World Heritage List.

'''Sight Seeing'''

* [http://en.wikipedia.org/wiki/Fernsehturm_Berlin Fernsehturm am Alexanderplatz] – best view of the city, but long waiting lines
* [https://www.google.com/maps/place/Oranienstraße Oranienstr. in Kreuzberg] – lots of cafes, bars, and restaurants
* Take one ride around the [http://en.wikipedia.org/wiki/Berlin_Ringbahn S-Bahn-Ring]. Train lines 41 or 42. A public transport ticket (region AB) is only 2.70 EUR. The full circle takes about an hour and will show you many facets of the city and you'll see people from all walks of life.
* [http://berliner-teufelsberg.com/web/ Teufelsberg] – the old NSA listening post
* [http://berliner-unterwelten.de/home.1.1.html Berliner Unterwelten] – awesome guided tours through old bunkers and other abandoned, mostly underground places.

'''Websites for short stays!'''

* [http://fotostrasse.1982.us/what-to-do-in-berlin-mainstream-tour-guide/ 24 Hours Guide]
* [http://www.12hrs.net/guides/12-hrs-in-berlin-with-herbert-hofmann/ 12 Hours Guide]

=== Restaurants ===

Freischwimmer[https://www.freischwimmer-berlin.com/] 
Vor dem Schlesischen Tor 2, 10997 Berlin 
Waterside dining space with wooden decking over the water, comfy rooms, serving an eclectic menu.

Burgermeister 
Oberbaumstraße 8, 10997 Berlin 
Delicious and fast burgers right at the U1 Schlesisches Tor.

Curry 36[http://www.curry36.de/] 
Mehringdamm 36, 10961 Berlin Kreuzberg 
Typically Berlin fast food place serving pork sausage with curry ketchup.

Schwarzwaldstuben [http://www.schwarzwaldstuben-berlin.com/] 
Tucholskystraße 48, 10117 Berlin-Mitte 
Simple and tasty South German cuisine. Located in Mitte, close to Rosenthaler Platz and Hackescher Markt.

Zur Gerichtslaube [http://www.gerichtslaube.de/?lang=en] 
Poststraße 28 · 10178 Berlin Mitte / Nikolaiviertel 
If you would like to see traditional German restaurant and try creamy potato soup, 'Berliner style' grilled sausage or oven-fresh apple-strudel, this place is for you!

<div class="h-card">
Sadhu https://foursquare.com/v/sadhu/4afef6f7f964a520323222e3 
Falckensteinstr. 41,
10997
Berlin Wrangelkiez
Excellent Indian Food! Can accommodate medium to large parties with a reservation.
</div>

=== Bars ===
Hopfenreich[hopfenreich.de 
Sorauer Str. 31, 10997 Berlin
If you’re looking for a Bar with Craft Beers from Berlin, Germany and all over the world you should check this one out.

John Muir[http://johnmuirberlin.com/] 
Skalitzer Str. 51, 10997 Berlin
Good Cocktails and live music in the heart of Kreuzberg.

[http://weinerei.com/forum/ Forum Wine Bar] 
Fehrbelliner Straße 57, 10119 Berlin, Germany 
The Forum wine bar is super cool. You pay 2EUR when you enter and you drink as much wine as you want and eat from their small salad bar. In the end, you pay what you feel it was worth. Done!

[http://www.eschschloraque.de/ Eschschloraque] 
Rosenthaler Straße 39, 10178 Berlin 
Where all the hackers hang out. Smoker's bar. Pro-tipp: order a "Tschunk" (Caipirinha with Club-Mate). It's close to S-Bahn stop Hackescher Markt in walking distance from Alexanderplatz, and easy to miss with the entrance hidden deep inside the backyard.

[http://www.brauhaus-lemke.com/index.php/home Brauhaus Lemke] 
Dircksenstraße 143, 10178 Berlin 
Very, very German and not nearly as bad as it sounds. They serve decent foods and very tasty beer from their own brewery. Pro-tipp: order a "Bierprobe", which is a small sample of all their beers. Located right next to S-Bahn stop Hackescher Markt and in walking distance from Alexanderplatz.

[http://vagabundbrauerei.com/ Vagabund Brauerei] 
Antwerpenerstr. 3, 13353 Berlin 
Bar with built-in micro brewery located in district Wedding. Watch your beer in the making.

=== Hacker / Maker Spaces ===

[[Berlin Makerspace|Mozilla Makerspace]] 
[[Berlin Office|Mozilla Office Berlin]] 
Mozilla's Berlin office is home to Mozilla's first dedicated maker space. Swing by if you want to learn, share or just make something.

[http://x-hain.de XHain] 
Grünberger Str. 14, 10243 Berlin 
One of the youngest maker spaces of Berlin located near S-Bahn stop Warschauer Straße. It's just a 15-minute walk from the office. The space is very active and we hear that people there are unusually friendly and welcoming.

[http://c-base.org/ c-base] 
Rungestraße 20, 10179 Berlin 
The largest hackerspace of the city located directly on the river Spree near Subway/S-Bahn station Jannowitzbrücke. It's not easy to find because it's located in the second backyard from the street. Open every day, it has regular and irregular events on most of the evenings and parties on the weekends. The included bar also sells the legendary "Tschunk".

[http://www.raumfahrtagentur.org/ Raumfahrtagentur] 
Gerichtstr. 15, 13347 Berlin 
Need to quickly machine your metal parts, 3D-print a case for your electronics project, or sew your pants? Or reverse-engineer your DNA in a biolab, smell the vegetables or just hang out in the hot tub of a massively green backyard garden? The "Space Agency" is one of the most well-equipped fablabs you'll find in this country, and always worth a little visit.

= Berlin Office Location =

'''Address:''' 
Mozilla Berlin 
Gebäude 3, 4. Obergeschoss 
Schlesische Straße 27 
10997 Berlin 
Germany

'''Additional Information'''

*Finding the office ([https://www.openstreetmap.org/node/4996803917 location on OpenStreetMap]): Use driveway Schlesische Str. 27 ([https://wiki.mozilla.org/images/thumb/b/b4/Moz_berlin_entrance.jpg/800px-Moz_berlin_entrance.jpg see photo]). Walk along the cobblestone path all the way to the end. We are in the white building, and the entrance is on the left side right before the path ends ([https://wiki.mozilla.org/images/thumb/a/ae/Moz_berlin_entrance1.jpg/450px-Moz_berlin_entrance1.jpg see photo]). Enter through the door marked "Treppenhaus C" ([https://wiki.mozilla.org/images/thumb/e/e5/Moz_berlin_door.jpg/450px-Moz_berlin_door.jpg see photo]), and go up to the 4th floor. The door to the office is marked by a Mozilla Berlin sticker ([https://wiki.mozilla.org/images/thumb/2/20/Moz_berlin_sticker.jpg/450px-Moz_berlin_sticker.jpg see photo]).
*Bikes: Our office is also bike friendly! To access the bike shed, enter through the ''''third'''' floor, if you don't want to use one of the many racks outside of our building. We also have a bike for guests!

* '''This is not a support hotline. For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
* '''Main Office''': +49 30 56795983
* '''Reception Desk''': +49 30 56795986
* '''Fax''': +49 30 56795987

= Emergency Information =

* Emergency Services: 110 (police), 112 (ambulance, fire), mobile networks also support 911

Berlin Office

2019-02-05T14:58:34Z

Nhnt11: Replaced TV Tower image with my photo of Oberbaumbrucke

[[File:Oberbaumbrucke.jpg|thumbnail|upright=1.8|right|link=|alt=Oberbaumbrücke|The Oberbaum Bridge, CC-ZERO nhnt11(at)gmail(dot)com]]

= Welcome To Berlin! =

Welcome to the Berlin office! We're glad to have you here!

''Come and join us for some German beer, some Currywurst, and our fun new space...''

=== Need Help with a Mozilla product? ===
<div style="background: yellow;">
For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
Please understand that Mozilla, as a non-profit, cannot provide phone support.
</div>

= Office Logistics =
To access the building use the driveway to the courtyard of Schlesische Strasse 27 and go straight until the end of the area. Then enter Haus 3 entrance C on the lefthand side. You can use either stairs or the elevator to go to the 4th Floor.

==Accessibility==
The building entrance door opens automatically. However, the next door needs to be opened manually. Once you pass them, there are two elevators on the righthand side. Press the button and choose 4th floor (it is where our welcome/reception area is located).
There is a grey door on the right when you exit the elevator on the 4th floor; they remain open. The glass door at the end of the short corridor can be opened with a badge.
There are two floors in the office connected by an internal stairwell. If you want to use the kitchen or event space on the 3rd floor, please take the same elevator you used to get to the 4th / reception floor.
There are 2 accessible toilets, one on each floor.
-3rd floor- On the lefthand side as you enter the event & community space.
-4th floor- On the lefthand side as you enter the reception area.

== Rooms ==
* Entrance area with comfy lounge space
* A common space that can be extended to fit 80 people
* Conferencing rooms equipped for video conferencing
* A community space with an adjacent maker space
* Kitchen with a great view, serving refrigerated drinks, espresso machine, dishwasher, snack bar

= Getting Here =

=== Traveling to Berlin ===
Berlin has two functional airports: Tegel (TXL) and Schönefeld (SXF):

* Tegel is closer to the city center and has service from transatlantic flights (Brussels Airlines, United, Air Canada Rouge) as well as many normal-cost air carriers. Some flights departing from terminal A allow you to get very quickly from the gate to the waiting lounge because each jetbridge has its own gate, security, and lounge. All other terminals in Tegel take a little longer.
* Schönefeld is a little further from the city's center, but also has a very easy connection to the office. Schönefeld is primarily served by low-cost air carriers (Ryanair, Easyjet).

Berlin is also well connected by train. The closest major station for long distance and international trains is the Ostbahnhof. If the train does not stop at Ostbahnhof, then the Hauptbahnhof is the next best choice.

=== Public transportation ===

[[File:Berlin public transport logos.png|thumbnail|upright=1.6|right|link=|alt=Berlin public transport logos|Indicating the next local train ("S-Bahn"), subway ("U-Bahn"), or bus station.]]The subway ("U-Bahn") station closest to the office is Schlesisches Tor, served by '''subway line U1''' (which actually drives above the earth in this section of the line). Another great choice is S-Bahn station '''Warschauer Straße''', from which it is a 10 to 15-minute walk to the office, or '''Treptower Park''', from which you can take a 10-minute walk or bus 165/265 to '''Taborstraße''' right in front of the office. You can find information on the metro service and maps here: http://www.bvg.de/en/Travel-information

* The transit authority in Berlin is [http://www.vbb.de/en/index.html VBB]. Most inner city services are operated by [http://www.bvg.de/en/ BVG] and [http://www.s-bahn-berlin.de/en S-Bahn-Berlin].
* There are three fare zones in Berlin: A, B, and C. A is the inner city, bounded by the Ringbahn (S41/S42). B is between the Ringbahn and the Brandenburg border. C is Brandenburg.
* Tickets are sold as AB, BC or ABC. An AB or BC can be extended to the third zone with the purchase of an "Anschlussfahrausweis". This also applies to single rides in concert with a flat rate (daily/weekly/monthly) ticket.
* You will almost exclusively use AB tickets. The main exception is a trip to Schönefeld Airport (SXF), which requires zone C
* A ticket from BVG can be used on an S-Bahn-Berlin and vice versa
* A ticket from BVG/S-Bahn-Berlin can be used on regional trains within the ticketed zone. These are trains which have a number like "RE1" or "RB1". They are primarily operated by DB Regio (mainly red), ODEG (grey with yellow lettering) and NEB (blue and white).
* A ticket from BVG/S-Bahn-Berlin '''cannot''' be used on long-distance trains, even within the ticketed zone. Google maps sometimes suggest these routes in their transit directions. These are trains with routes like "IC 500", "EC 40" or "ICE 100". In Berlin, these are often grey with a thin horizontal red stripe (DB), light blue (PKP), dark blue (ČD) or light blue with a white stripe (MÁV)
* '''A single ride ticket is valid for two hours, but only for one direction.'''
* Berlin time-based transit tickets are valid until 3:00 AM the following day
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=399 Subway and S-Bahn train map (region ABC) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=400 Subway and S-Bahn train map (city/region AB) (PDF)]
* [http://www.bvg.de/en/index.php?section=downloads&cmd=58&download=401 Tram map (PDF)]
* [http://fahrinfo.bvg.de/Fahrinfo/bin/query.bin/en/dn?ujm=1&MapLayer=NETWORK Interactive map]
* Day tickets are cheaper when taking three rides or more. Also: buying tickets in sets of 4 gives you a decent deal.
* Day tickets for groups up to five people are dirt-cheap.
* Multi-day tickets (regular ones or the "City/Welcome" variety which allow rebates in certain museums and restaurants) are not really a good deal.
* Every ticket machine also sells special tickets, but they're hidden in sub-menus. Keep digging! Most support changing to English on the main screen.
* Remember to always validate your ticket before boarding a subway, S-Bahn or regional train. Ticket validation machines are located near the ticket machine itself and on the platforms.
* Most ticket machines accept coins. Ticket machines might additionally accept a combination of credit card, banknotes <= 10€, any banknote and EC card (German debit cards).
* If the ticket machine doesn't like your coin, rub the edge against the machine and try again

==== Smartphone Apps ====
Google maps give pretty good transit directions in Berlin and are available for Ios and Android. Transit app, Here maps, and Citymapper also work well

The single best public transportation app for Android is [https://play.google.com/store/apps/details?id=de.schildbach.oeffi&hl=en Öffi]. It covers all of Germany and is available for free through Google Play.
* Open "Öffi Directions", choose ''My current location'' as starting point and ''Schlesisches Tor'' (U-Bahn stop close to the office) or ''Taborstraße'' (bus stop directly in front of the office) as your destination, and you should be good to go.

There's also the BVG Fahrinfo app, which is BVG's official transit app. This app gives really good transit directions as well as schedules. You can also buy tickets directly from the app.

==== From Tegel Airport TXL ====
* The recommended route from TXL to the office is via the S-Bahn ring. From the airport, take bus TXL to S Beusselstraße (2 stops). From there, take S41 (via Gesundbrunnen, Ostkreuz) to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight (it's a beautiful walk!). You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Schönefeld Airport SXF ====
* '''NOTE''': you will require a ticket in fare zone ABC
* The recommended route from SXF is via S-Bahn route S9. From the airport, take the S9 to Treptower Park. From there the office is only 10 min walk away: go right on Puschkinallee and keep straight. You can also take bus 165 (direction U Märkisches Museum) or 265 (direction U Stadtmitte ) to Taborstraße. This will leave you right in front of our office building.

==== From Berlin Hauptbahnhof, Ostbahnhof or Alexanderplatz train station ====
* The recommended route is the S5, S7 or S75. All of these stations are on all of these routes. From the station, take the route to Warschauer Strasse station. From Warschauer Strasse station, either walk or take the U1 one stop to Schlesisches Tor U-Bahn.

My Taxi

If you know you need to take a lot of taxis while you are in town, we suggest downloading the [http://www.mytaxi.com/en/passengers/mytaxi-in-your-city/berlin.html MyTaxi] app. You can filter taxis by who takes card, how many people you need to pick up etc.

* Most taxi rides within central Berlin are around 10 EUR, hardly more than 15 EUR.

= Visiting Berlin =

=== Hotels ===

;Michelberger Hotel
http://michelbergerhotel.com/
15min walk from the office. Great location, great hotel. Free yoga class on Thursdays, make their own coconut water. Delicious food (local and made from scrap) and drinks. Rooms range from "Cozy" (very tiny but beautiful and has everything you need) to a larger scale. More hipster vibe. Very different from your usual hotel. It's an experience in itself.

;'''Hotel Johann'''
https://www.hotel-johann-berlin.de/ in Johanniterstrasse (U1 Prinzenstr). This is definitely outside of walking distance, but if you take the U1 towards Schlesisches Tor, you are close.

;'''Hotel Vier Jahreszeiten'''
http://vj-hotels.com/ in Skalitzer Str (U1 Görlitzer Bhf). Similar as Hotel Johann, just 2 stops closer

=== Tipping & Money ===

* Local Currency: Euro
* It is customary in Germany to tip a little by rounding up and around 10% at restaurants for good service. Tipping in bars is not something many Europeans do.
* Not many places accept Credit/Debit Card. Many smaller restaurants and shops do not accept credit cards like in the US and other larger European cities. Please be prepared to pay in cash. It's a good practice in Berlin to ask in advance of making a restaurant reservation if they accept credit cards.

=== Things to do in Berlin ===

'''Museums'''

* [http://www.computerspielemuseum.de/1210_Home.htm Computerspielemuseum] – computer games museum (see [https://en.wikipedia.org/wiki/Computerspielemuseum_Berlin Wikipedia]) in Friedrichshain
* [https://www.ddr-museum.de/en DDR-Museum] – an interactive museum about the German Democratic Republic (GDR) in Mitte
*Museum Insel [https://www.museumsinsel-berlin.de/en/buildings/overview-of-the-buildings/] - 'Museum Island' is a unique complex of 5 significant national museums on the Spree Island. It is on the UNESCO World Heritage List.

'''Sight Seeing'''

* [http://en.wikipedia.org/wiki/Fernsehturm_Berlin Fernsehturm am Alexanderplatz] – best view of the city, but long waiting lines
* [https://www.google.com/maps/place/Oranienstraße Oranienstr. in Kreuzberg] – lots of cafes, bars, and restaurants
* Take one ride around the [http://en.wikipedia.org/wiki/Berlin_Ringbahn S-Bahn-Ring]. Train lines 41 or 42. A public transport ticket (region AB) is only 2.70 EUR. The full circle takes about an hour and will show you many facets of the city and you'll see people from all walks of life.
* [http://berliner-teufelsberg.com/web/ Teufelsberg] – the old NSA listening post
* [http://berliner-unterwelten.de/home.1.1.html Berliner Unterwelten] – awesome guided tours through old bunkers and other abandoned, mostly underground places.

'''Websites for short stays!'''

* [http://fotostrasse.1982.us/what-to-do-in-berlin-mainstream-tour-guide/ 24 Hours Guide]
* [http://www.12hrs.net/guides/12-hrs-in-berlin-with-herbert-hofmann/ 12 Hours Guide]

=== Restaurants ===

Freischwimmer[https://www.freischwimmer-berlin.com/] 
Vor dem Schlesischen Tor 2, 10997 Berlin 
Waterside dining space with wooden decking over the water, comfy rooms, serving an eclectic menu.

Burgermeister 
Oberbaumstraße 8, 10997 Berlin 
Delicious and fast burgers right at the U1 Schlesisches Tor.

Curry 36[http://www.curry36.de/] 
Mehringdamm 36, 10961 Berlin Kreuzberg 
Typically Berlin fast food place serving pork sausage with curry ketchup.

Schwarzwaldstuben [http://www.schwarzwaldstuben-berlin.com/] 
Tucholskystraße 48, 10117 Berlin-Mitte 
Simple and tasty South German cuisine. Located in Mitte, close to Rosenthaler Platz and Hackescher Markt.

Zur Gerichtslaube [http://www.gerichtslaube.de/?lang=en] 
Poststraße 28 · 10178 Berlin Mitte / Nikolaiviertel 
If you would like to see traditional German restaurant and try creamy potato soup, 'Berliner style' grilled sausage or oven-fresh apple-strudel, this place is for you!

<div class="h-card">
Sadhu https://foursquare.com/v/sadhu/4afef6f7f964a520323222e3 
Falckensteinstr. 41,
10997
Berlin Wrangelkiez
Excellent Indian Food! Can accommodate medium to large parties with a reservation.
</div>

=== Bars ===
Hopfenreich[hopfenreich.de 
Sorauer Str. 31, 10997 Berlin
If you’re looking for a Bar with Craft Beers from Berlin, Germany and all over the world you should check this one out.

John Muir[http://johnmuirberlin.com/] 
Skalitzer Str. 51, 10997 Berlin
Good Cocktails and live music in the heart of Kreuzberg.

[http://weinerei.com/forum/ Forum Wine Bar] 
Fehrbelliner Straße 57, 10119 Berlin, Germany 
The Forum wine bar is super cool. You pay 2EUR when you enter and you drink as much wine as you want and eat from their small salad bar. In the end, you pay what you feel it was worth. Done!

[http://www.eschschloraque.de/ Eschschloraque] 
Rosenthaler Straße 39, 10178 Berlin 
Where all the hackers hang out. Smoker's bar. Pro-tipp: order a "Tschunk" (Caipirinha with Club-Mate). It's close to S-Bahn stop Hackescher Markt in walking distance from Alexanderplatz, and easy to miss with the entrance hidden deep inside the backyard.

[http://www.brauhaus-lemke.com/index.php/home Brauhaus Lemke] 
Dircksenstraße 143, 10178 Berlin 
Very, very German and not nearly as bad as it sounds. They serve decent foods and very tasty beer from their own brewery. Pro-tipp: order a "Bierprobe", which is a small sample of all their beers. Located right next to S-Bahn stop Hackescher Markt and in walking distance from Alexanderplatz.

[http://vagabundbrauerei.com/ Vagabund Brauerei] 
Antwerpenerstr. 3, 13353 Berlin 
Bar with built-in micro brewery located in district Wedding. Watch your beer in the making.

=== Hacker / Maker Spaces ===

[[Berlin Makerspace|Mozilla Makerspace]] 
[[Berlin Office|Mozilla Office Berlin]] 
Mozilla's Berlin office is home to Mozilla's first dedicated maker space. Swing by if you want to learn, share or just make something.

[http://x-hain.de XHain] 
Grünberger Str. 14, 10243 Berlin 
One of the youngest maker spaces of Berlin located near S-Bahn stop Warschauer Straße. It's just a 15-minute walk from the office. The space is very active and we hear that people there are unusually friendly and welcoming.

[http://c-base.org/ c-base] 
Rungestraße 20, 10179 Berlin 
The largest hackerspace of the city located directly on the river Spree near Subway/S-Bahn station Jannowitzbrücke. It's not easy to find because it's located in the second backyard from the street. Open every day, it has regular and irregular events on most of the evenings and parties on the weekends. The included bar also sells the legendary "Tschunk".

[http://www.raumfahrtagentur.org/ Raumfahrtagentur] 
Gerichtstr. 15, 13347 Berlin 
Need to quickly machine your metal parts, 3D-print a case for your electronics project, or sew your pants? Or reverse-engineer your DNA in a biolab, smell the vegetables or just hang out in the hot tub of a massively green backyard garden? The "Space Agency" is one of the most well-equipped fablabs you'll find in this country, and always worth a little visit.

= Berlin Office Location =

'''Address:''' 
Mozilla Berlin 
Gebäude 3, 4. Obergeschoss 
Schlesische Straße 27 
10997 Berlin 
Germany

'''Additional Information'''

*Finding the office ([https://www.openstreetmap.org/node/4996803917 location on OpenStreetMap]): Use driveway Schlesische Str. 27 ([https://wiki.mozilla.org/images/thumb/b/b4/Moz_berlin_entrance.jpg/800px-Moz_berlin_entrance.jpg see photo]). Walk along the cobblestone path all the way to the end. We are in the white building, and the entrance is on the left side right before the path ends ([https://wiki.mozilla.org/images/thumb/a/ae/Moz_berlin_entrance1.jpg/450px-Moz_berlin_entrance1.jpg see photo]). Enter through the door marked "Treppenhaus C" ([https://wiki.mozilla.org/images/thumb/e/e5/Moz_berlin_door.jpg/450px-Moz_berlin_door.jpg see photo]), and go up to the 4th floor. The door to the office is marked by a Mozilla Berlin sticker ([https://wiki.mozilla.org/images/thumb/2/20/Moz_berlin_sticker.jpg/450px-Moz_berlin_sticker.jpg see photo]).
*Bikes: Our office is also bike friendly! To access the bike shed, enter through the ''''third'''' floor, if you don't want to use one of the many racks outside of our building. We also have a bike for guests!

* '''This is not a support hotline. For fast and easy support go to [http://support.mozilla.org/ Mozilla Support]'''
* '''Main Office''': +49 30 56795983
* '''Reception Desk''': +49 30 56795986
* '''Fax''': +49 30 56795987

= Emergency Information =

* Emergency Services: 110 (police), 112 (ambulance, fire), mobile networks also support 911