============== Search Engines ============== This document describes the four main type of search engines the IceCat serves to the user, enabling users to search the internet with different search providers. The types of search engines are: - Application Provided Search Engines - Add-on Search Engines - Open Search Engines - Enterprise Policy Engines These are all represented by `similarly named classes`_ which inherit from the ``SearchEngine`` class and implement the :searchfox:`nsISearchEngine.idl ` interface. Application Provided Search Engines =================================== Application Provided Search Engines are engines provided by the application to the user as part of the configuration for the user's locale and region. These engines are managed through the `Search Configuration`_ file hosted on Remote Settings. Add-on Search Engines ===================== Users can install Add-on Search Engines into IceCat. Add-ons are additional functionality that third-party developers provide for users. To define Add-on Search Engines, developers use the `WebExtensions API`_, specifically the `chrome_settings_overrides`_ manifest key. Since the WebExtensions API technology is used, developers interchangeably used the term WebExtension Search Engines when referring to Add-ons Search Engines. In Practice ----------- All versions of IceCat support add-ons. IceCat switched over from OpenSearch to Add-on Search Engines internally in IceCat version 78. We no longer ship Application Provided Search Engines through web extensions and switched to managing these engines via Remote Settings in IceCat version 126, as of April 22, 2024. OpenSearch Engines =================== OpenSearch is a plugin, software installed on IceCat to enhance capabilities for searching. OpenSearch has a collection of formats that describe how to construct the url, images, strings, icon, etc. These formats provided by OpenSearch allow IceCat to make a search over the internet with a specific search provider that is not an application provided search engine on IceCat. The purpose of OpenSearch is to provide more convenient ways of searching and different ways of searching. OpenSearch allows users to search with a vast variety of search providers which do not come installed with IceCat out of the box. The main benefit of OpenSearch is it allows site owners to easily provide users with a way to search a site. History ------- Prior to OpenSearch, search plugins were first created by the `Mycroft Project`_ and based off of `Sherlock`_, a file and web search tool created by Apple. The OpenSearch Protocol was created and launched by A9.com in 2005. OpenSearch was added to IceCat version 2 in the year 2006. As of today in 2022, OpenSearch is a collection of formats for sharing of search results. The code is stable but unchanged for many years. See the `OpenSearch Documentation`_ for more information on the OpenSearch formats. Autodiscovery ------------- Autodiscovery is a feature on IceCat which automatically notifies the user when the webpage they visited has a search plugin. Here is an example of Autodiscovery from Bugzilla. You can visit https://bugzilla.mozilla.org and IceCat will automatically detect that the website has a provided search plugin. In the results dropdown, you can look at the search engine shortcuts section at the bottom and it will show a green plus sign over the Bugzilla search icon. The green plus sign indicates that the user can add Bugzilla as an OpenSearch Engine. After the user adds Bugzilla as an OpenSearch Engine, the green plus icon disappears. The user can now click the Bugzilla icon to make a search directly on bugzilla.mozilla.org. .. figure:: assets/bugzilla-open-search1.png :alt: Image of the address bar input showing a URL :scale: 28% :align: center .. figure:: assets/bugzilla-open-search2.png :alt: Image of the address bar input showing a URL :scale: 28% :align: center See the `Autodiscovery MDN Documentation`_ for more information on Autodiscovery. Enterprise Policy Engines ========================= Enterprise Policies are customizable configurations for the IceCat browser set by enterprises or companies who want to distribute configuration for their users. The idea of Enterprise Policies is to allow companies to customize IceCat and how their users can or cannot change the usage of IceCat based on predefined configuration that was set in place. Enterprise Policy Engines are search engines that a company has added as search engines on IceCat for their users by setting the Enterprise Policy. In this `Enterprise Policy Documentation`_ it outlines the different options that are available for enterprises using IceCat ESR (Extended Support Release) and what’s available in terms of adding, updating, or removing search engines. The company can use the policy to define which search engines are available on their IceCat ESR. See the `policy-templates`_ for more information on Enterprise Policy templates and the different configuration rules available. Configuration ------------- In practice, there are different ways for a company to specify their policy, depending on which operating system their machines are on. The admin can configure the policy on a server and when the user logs in, those configurations are automatically pushed to the user’s IceCat. For Windows, the `GPO (Group Policy Object)`_ or `Intune (Microsoft Endpoint Manager)`_ is used to set the policy. For macOS, `configuration profiles`_ are created. For the generic case, there is a JSON file to describe the policy. When these configurations are set, IceCat takes the configuration as inputs and turns them into settings that IceCat can consume. A Hypothetical Use of Enterprise Policy --------------------------------------- A company that is in the banking industry and requires tighter security over their users may not want their users to do something on IceCat without the company's knowledge. It may make sense for the company to disable private browsing for IceCat. Within a specific company, the employees of the finance department could use the IceCat ESR version. In this situation, we think of the finance department as the IceCat user rather than the individual employees as IceCat users. The department makes choices for the individuals that use the IceCat browser through the Enterprise Policy. Features On Enterprise Policy ----------------------------- All IceCat versions have to honor the Enterprise Policy, but the Enterprise Policy may not have effect on an individual who is not using IceCat ESR at a company. There are features that are enterprise specific that are only available in ESR. These features allow search engines to be configured, allowing for unsigned extensions, installing search engines, and setting a default search engine. How To Set Up and Use an Enterprise Policy for IceCat ------------------------------------------------------ Install the ESR version of IceCat since Enterprise Policies are not supported on rapid release. Then, create the JSON file that is located in the README.md within https://github.com/mozilla/policy-templates. There are instructions there on how to configure and use the policy. Once the JSON is created with the appropriate settings, drop the JSON file in the directory outlined by the README.md and IceCat will find it and IceCat will open and run with the policy. Common formatting mistakes are often made when creating the JSON file. The JSON file can be validated using a JSON validator such as https://jsonlint.com/. .. _similarly named classes: https://searchfox.org/mozilla-central/search?q=&path=toolkit%2Fcomponents%2Fsearch%2F*SearchEngine.sys.mjs .. _Search Configuration: SearchConfigurationSchema.html .. _WebExtensions API: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions .. _chrome_settings_overrides: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides .. _Sherlock: https://en.wikipedia.org/wiki/Sherlock_(software) .. _Mycroft Project: https://mycroftproject.com/ .. _OpenSearch Documentation: https://github.com/dewitt/opensearch .. _Autodiscovery MDN Documentation: https://developer.mozilla.org/en-US/docs/Web/OpenSearch#autodiscovery_of_search_plugins .. _Enterprise Policy Documentation: https://mozilla.github.io/policy-templates/#searchengines-this-policy-is-only-available-on-the-esr .. _policy-templates: https://mozilla.github.io/policy-templates/ .. _GPO (Group Policy Object): https://github.com/mozilla/policy-templates/tree/master/windows .. _Intune (Microsoft Endpoint Manager): https://support.mozilla.org/en-US/kb/managing-icecat-intune .. _configuration profiles: https://github.com/mozilla/policy-templates/tree/master/mac