Firefox Ansible Role¶

An Ansible role to install, configure, and manage Firefox on Debian-based systems using policy-based configuration.

Features¶

Installation and uninstallation of Firefox ESR
Policy-based configuration using policies.json
Extension management (force install, block, allow)
Comprehensive Firefox policy settings
Support for multiple extensions configuration
Fine-grained control over Firefox features and permissions

Supported OS¶

This role is regularly tested with * Debian 12 * Debian 13 * Ubuntu 2204 * Ubuntu 2404 * Fedora 43 * Fedora 44 * Kali Linux

Installation¶

First add the following line to your requirements.yml file:

roles:
  - name: firefox
    src: https://gitlab.com/niclas-zone/tools/ansible/roles/firefox.git
    version: 1.0.0
    scm: git

After that, we can install the role by executing the following command:

ansible-galaxy install -r requirements.yml --force

Role Variables¶

Top-level¶

Variable	Default Value	Type	Description
`firefox_allowed_domains_for_apps`	`[]`	list	Allowed domains for apps (joined as comma-separated string)
`firefox_app_auto_update`	`true`	boolean	Enable/disable application auto-updates
`firefox_app_update_pin`	`""`	string	Pin updates to a specific version
`firefox_app_update_url`	`""`	string	Custom update URL

Authentication¶

Variable	Default Value	Type	Description
`firefox_authentication_spnego`	`[]`	list	SPNEGO allowlist entries
`firefox_authentication_delegated`	`[]`	list	Delegated authentication hosts
`firefox_authentication_ntlm`	`[]`	list	NTLM allowlist entries
`firefox_authentication_allow_non_fqdn_spnego`	`false`	boolean	Allow non-FQDN for SPNEGO
`firefox_authentication_allow_non_fqdn_ntlm`	`false`	boolean	Allow non-FQDN for NTLM
`firefox_authentication_allow_proxies_spnego`	`false`	boolean	Allow proxies for SPNEGO
`firefox_authentication_allow_proxies_ntlm`	`false`	boolean	Allow proxies for NTLM
`firefox_authentication_locked`	`false`	boolean	Lock authentication policy
`firefox_authentication_private_browsing`	`false`	boolean	Authentication in private browsing

Auto-launch / Background¶

Variable	Default Value	Type	Description
`firefox_auto_launch_protocols`	`[]`	list	Origins allowed to auto-launch protocols
`firefox_background_app_update`	`false`	boolean	Background app update setting

About / Blocking flags¶

Variable	Default Value	Type	Description
`firefox_block_about_addons`	`false`	boolean	Block about:addons page
`firefox_block_about_config`	`false`	boolean	Block about:config page
`firefox_block_about_profiles`	`false`	boolean	Block about:profiles page
`firefox_block_about_support`	`false`	boolean	Block about:support page

Bookmarks & Managed Bookmarks¶

Variable	Default Value	Type	Description
`firefox_bookmarks`	`[]`	list	Managed bookmarks entries
`firefox_managed_bookmarks`	`[]`	list	Managed bookmarks structure

Captive Portal¶

Variable	Default Value	Type	Description
`firefox_captive_portal`	`false`	boolean	Enable captive portal handling

Certificates¶

Variable	Default Value	Type	Description
`firefox_certificates_install`	`[]`	list	CA certificates to install via policy

Containers¶

Variable	Default Value	Type	Description
`firefox_containers_default`	`[]`	list	Default container configuration

Cookies¶

Variable	Default Value	Type	Description
`firefox_cookies_allow`	`[]`	list	Domains to allow cookies
`firefox_cookies_allow_session`	`[]`	list	Domains allowed session cookies
`firefox_cookies_block`	`[]`	list	Domains to block cookies
`firefox_cookies_locked`	`false`	boolean	Lock cookie settings
`firefox_cookies_behavior`	`"reject-tracker"`	string	Cookie behavior setting
`firefox_cookies_behavior_private_browsing`	`"reject-tracker"`	string	Cookie behavior in private browsing

Downloads¶

Variable	Default Value	Type	Description
`firefox_default_download_directory`	`""`	string	Default download directory
`firefox_download_directory`	`""`	string	Download directory policy
`firefox_prompt_for_download_location`	`false`	boolean	Prompt for download location
`firefox_start_downloads_in_temp_directory`	`false`	boolean	Start downloads in temp directory

Disable / Feature flags¶

Variable	Default Value	Type	Description
`firefox_disable_builtin_pdf_viewer`	`false`	boolean	Disable built-in PDF viewer
`firefox_disable_developer_tools`	`false`	boolean	Disable developer tools
`firefox_disable_encrypted_client_hello`	`false`	boolean	Disable ECH support
`firefox_disable_feedback_commands`	`false`	boolean	Disable feedback commands
`firefox_disable_firefox_accounts`	`false`	boolean	Disable Firefox Accounts
`firefox_disable_firefox_screenshots`	`false`	boolean	Disable screenshots feature
`firefox_disable_firefox_studies`	`true`	boolean	Disable studies (experiments)
`firefox_disable_forget_button`	`false`	boolean	Disable forget button
`firefox_disable_form_history`	`false`	boolean	Disable form history
`firefox_disable_master_password_creation`	`false`	boolean	Disable master password creation
`firefox_disable_password_reveal`	`false`	boolean	Disable password reveal
`firefox_disable_private_browsing`	`false`	boolean	Disable private browsing
`firefox_disable_profile_import`	`false`	boolean	Disable profile import
`firefox_disable_profile_refresh`	`false`	boolean	Disable profile refresh
`firefox_disable_safe_mode`	`false`	boolean	Disable safe mode
`firefox_disable_security_bypass_invalid_certificate`	`false`	boolean	Disable invalid certificate bypass
`firefox_disable_security_bypass_safe_browsing`	`false`	boolean	Disable safe browsing bypass
`firefox_disable_set_desktop_background`	`false`	boolean	Disable setting desktop background
`firefox_disable_system_addon_update`	`false`	boolean	Disable system add-on updates
`firefox_disable_telemetry`	`true`	boolean	Disable telemetry

Display¶

Variable	Default Value	Type	Description
`firefox_display_bookmarks_toolbar`	`"never"`	string	Bookmarks toolbar display setting
`firefox_display_menu_bar`	`"default-off"`	string	Menu bar display setting
`firefox_show_home_button`	`true`	boolean	Show home button

DNS over HTTPS (DNSOverHTTPS)¶

Variable	Default Value	Type	Description
`firefox_dns_over_https_enabled`	`false`	boolean	Enable DNS over HTTPS
`firefox_dns_over_https_provider_url`	`""`	string	Provider URL for DNS over HTTPS
`firefox_dns_over_https_locked`	`false`	boolean	Lock DNS over HTTPS setting
`firefox_dns_over_https_excluded_domains`	`[]`	list	Domains excluded from DoH

Default browser / Homepage / Startpage¶

Variable	Default Value	Type	Description
`firefox_dont_check_default_browser`	`false`	boolean	Disable default browser check
`firefox_homepage_url`	`""`	string	Homepage URL
`firefox_homepage_locked`	`false`	boolean	Lock homepage setting
`firefox_homepage_additional`	`[]`	list	Additional homepage URLs
`firefox_homepage_start_page`	`"homepage"`	string	Start page mode

Tracking & Privacy¶

Variable	Default Value	Type	Description
`firefox_enable_tracking_protection_value`	`true`	boolean	Enable tracking protection
`firefox_enable_tracking_protection_locked`	`false`	boolean	Lock tracking protection
`firefox_enable_tracking_protection_cryptomining`	`true`	boolean	Cryptomining protection
`firefox_enable_tracking_protection_fingerprinting`	`true`	boolean	Fingerprinting protection
`firefox_enable_tracking_protection_email_tracking`	`true`	boolean	Email tracking protection
`firefox_enable_tracking_protection_suspected_fingerprinting`	`false`	boolean	Suspected fingerprinting protection
`firefox_enable_tracking_protection_category`	`"strict"`	string	Tracking protection category
`firefox_enable_tracking_protection_exceptions`	`[]`	list	Exceptions for tracking protection
`firefox_encrypted_media_extensions_enabled`	`true`	boolean	Enable EME
`firefox_encrypted_media_extensions_locked`	`false`	boolean	Lock EME setting

Extensions¶

Variable	Default Value	Type	Description
`firefox_extensions_install`	`[]`	list	List of extensions to install
`firefox_extensions_uninstall`	`[]`	list	List of extensions to uninstall
`firefox_extensions_locked`	`[]`	list	List of extension IDs to lock
`firefox_extension_settings`	`[{'id':'uBlock0@raymondhill.net','installation_mode':'force_installed','install_url':'https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi'}]`	list(mapping)	Per-extension mappings (must include `id`)
`firefox_extension_update`	`true`	boolean	Enable/disable extension updates

Firefox Home & Suggest / Generative AI¶

Variable	Default Value	Type	Description
`firefox_firefox_home_search`	`true`	boolean	Show search on Firefox Home
`firefox_firefox_home_top_sites`	`true`	boolean	Show top sites on Firefox Home
`firefox_firefox_home_sponsored_top_sites`	`false`	boolean	Show sponsored top sites
`firefox_firefox_home_highlights`	`true`	boolean	Show highlights
`firefox_firefox_home_pocket`	`false`	boolean	Show Pocket on home
`firefox_firefox_home_sponsored_pocket`	`false`	boolean	Show sponsored Pocket items
`firefox_firefox_home_snippets`	`false`	boolean	Show snippets
`firefox_firefox_home_locked`	`false`	boolean	Lock Firefox Home settings
`firefox_firefox_suggest_web_suggestions`	`false`	boolean	Web suggestions in suggestions UI
`firefox_firefox_suggest_sponsored_suggestions`	`false`	boolean	Sponsored suggestions
`firefox_firefox_suggest_improve_suggest`	`false`	boolean	Improve suggestions flag
`firefox_firefox_suggest_locked`	`false`	boolean	Lock suggestions settings
`firefox_generative_ai_chatbot`	`false`	boolean	Generative AI chatbot setting
`firefox_generative_ai_link_previews`	`false`	boolean	Generative AI link previews
`firefox_generative_ai_tab_groups`	`false`	boolean	Generative AI tab groups
`firefox_generative_ai_locked`	`false`	boolean	Lock Generative AI settings

Intranet / Handlers¶

Variable	Default Value	Type	Description
`firefox_go_to_intranet_site_for_single_word_entry`	`false`	boolean	Treat single-word address bar entries as intranet sites
`firefox_handlers_mime_types`	`[]`	list	MIME type handlers
`firefox_handlers_schemes`	`[]`	list	Scheme handlers
`firefox_handlers_extensions`	`[]`	list	File extension handlers

Hardware & Performance¶

Variable	Default Value	Type	Description
`firefox_hardware_acceleration`	`true`	boolean	Enable hardware acceleration
`firefox_network_prediction`	`false`	boolean	Network prediction setting
`firefox_visual_search_enabled`	`false`	boolean	Visual search feature

HTTP / HTTPS / Local links¶

Variable	Default Value	Type	Description
`firefox_http_allowlist`	`[]`	list	HTTP allowlist entries
`firefox_https_only_mode`	`"enabled"`	string	HTTPS-only mode setting
`firefox_local_file_links`	`[]`	list	Local file link handlers

Install Add-ons Permission¶

Variable	Default Value	Type	Description
`firefox_install_addons_permission_allow`	`[]`	list	Domains allowed to install add-ons
`firefox_install_addons_permission_default`	`false`	boolean	Default install add-ons permission

Variable	Default Value	Type	Description
`firefox_legacy_same_site_cookie_behavior_enabled`	`false`	boolean	Enable legacy SameSite cookie behavior
`firefox_legacy_same_site_cookie_behavior_enabled_for_domain_list`	`[]`	list	Domains for legacy SameSite behavior

Managed bookmarks / Locales¶

Variable	Default Value	Type	Description
`firefox_managed_bookmarks`	`[]`	list	Managed bookmarks
`firefox_requested_locales`	`[]`	list	Requested locales list

Tab & UI behavior¶

Variable	Default Value	Type	Description
`firefox_new_tab_page`	`true`	boolean	New tab page enabled
`firefox_no_default_bookmarks`	`false`	boolean	Prevent default bookmarks

Logins & Passwords¶

Variable	Default Value	Type	Description
`firefox_offer_to_save_logins`	`true`	boolean	Offer to save logins
`firefox_offer_to_save_logins_default`	`true`	boolean	Default for offer to save logins
`firefox_password_manager_enabled`	`true`	boolean	Enable password manager
`firefox_password_manager_exceptions`	`[]`	list	Exceptions for password manager
`firefox_primary_password`	`false`	boolean	Primary password (master password)

PDF & Printing¶

Variable	Default Value	Type	Description
`firefox_pdfjs_enabled`	`true`	boolean	Enable PDF.js
`firefox_pdfjs_enable_permissions`	`false`	boolean	Enable PDF.js permissions
`firefox_printing_enabled`	`true`	boolean	Enable printing
`firefox_use_system_print_dialog`	`false`	boolean	Use system print dialog

Permissions (Camera, Microphone, Location, Notifications, Autoplay, VR, ScreenShare)¶

Variable	Default Value	Type	Description
`firefox_permissions_camera_allow`	`[]`	list	Camera allowlist
`firefox_permissions_camera_block`	`[]`	list	Camera blocklist
`firefox_permissions_camera_block_new_requests`	`false`	boolean	Block new camera permission requests
`firefox_permissions_camera_locked`	`false`	boolean	Lock camera permissions
`firefox_permissions_microphone_allow`	`[]`	list	Microphone allowlist
`firefox_permissions_microphone_block`	`[]`	list	Microphone blocklist
`firefox_permissions_microphone_block_new_requests`	`false`	boolean	Block new microphone permission requests
`firefox_permissions_microphone_locked`	`false`	boolean	Lock microphone permissions
`firefox_permissions_location_allow`	`[]`	list	Location allowlist
`firefox_permissions_location_block`	`[]`	list	Location blocklist
`firefox_permissions_location_block_new_requests`	`false`	boolean	Block new location permission requests
`firefox_permissions_location_locked`	`false`	boolean	Lock location permissions
`firefox_permissions_notifications_allow`	`[]`	list	Notifications allowlist
`firefox_permissions_notifications_block`	`[]`	list	Notifications blocklist
`firefox_permissions_notifications_block_new_requests`	`false`	boolean	Block new notifications permission requests
`firefox_permissions_notifications_locked`	`false`	boolean	Lock notifications permissions
`firefox_permissions_autoplay_allow`	`[]`	list	Autoplay allowlist
`firefox_permissions_autoplay_block`	`[]`	list	Autoplay blocklist
`firefox_permissions_autoplay_default`	`"block-audio-video"`	string	Default autoplay behavior
`firefox_permissions_autoplay_locked`	`false`	boolean	Lock autoplay permissions
`firefox_permissions_virtual_reality_allow`	`[]`	list	VR allowlist
`firefox_permissions_virtual_reality_block`	`[]`	list	VR blocklist
`firefox_permissions_virtual_reality_block_new_requests`	`false`	boolean	Block new VR permission requests
`firefox_permissions_virtual_reality_locked`	`false`	boolean	Lock VR permissions
`firefox_permissions_screen_share_allow`	`[]`	list	ScreenShare allowlist
`firefox_permissions_screen_share_block`	`[]`	list	ScreenShare blocklist
`firefox_permissions_screen_share_block_new_requests`	`false`	boolean	Block new ScreenShare permission requests
`firefox_permissions_screen_share_locked`	`false`	boolean	Lock ScreenShare permissions

Variable	Default Value	Type	Description
`firefox_picture_in_picture_enabled`	`true`	boolean	Enable picture-in-picture
`firefox_picture_in_picture_locked`	`false`	boolean	Lock picture-in-picture setting
`firefox_popup_blocking_allow`	`[]`	list	Popup allowlist
`firefox_popup_blocking_default`	`true`	boolean	Default popup blocking behavior
`firefox_popup_blocking_locked`	`false`	boolean	Lock popup blocking setting

Misc features¶

Variable	Default Value	Type	Description
`firefox_post_quantum_key_agreement_enabled`	`true`	boolean	Post-quantum key agreement setting
`firefox_preferences`	`{}`	mapping	Arbitrary preferences passed to the policy
`firefox_private_browsing_mode_availability`	`0`	number	string
`firefox_prompt_for_download_location`	`false`	boolean	Prompt for download location
`firefox_proxy_mode`	`"none"`	string	Proxy mode
`firefox_proxy_locked`	`false`	boolean	Lock proxy settings
`firefox_proxy_http_proxy`	`""`	string	HTTP proxy host:port
`firefox_proxy_use_http_proxy_for_all_protocols`	`false`	boolean	Use HTTP proxy for all protocols
`firefox_proxy_ssl_proxy`	`""`	string	SSL proxy host:port
`firefox_proxy_ftp_proxy`	`""`	string	FTP proxy host:port
`firefox_proxy_socks_proxy`	`""`	string	SOCKS proxy host:port
`firefox_proxy_socks_version`	`5`	number	SOCKS version
`firefox_proxy_passthrough`	`"<local>"`	string	Proxy passthrough domains
`firefox_proxy_auto_config_url`	`""`	string	Proxy auto-config URL
`firefox_proxy_auto_login`	`false`	boolean	Auto-login to proxy
`firefox_proxy_use_proxy_for_dns`	`false`	boolean	Use proxy for DNS
`firefox_security_devices`	`{}`	list	Security devices to register
`firefox_search_engines_add`	`[]`	list	Search engines to add
`firefox_search_engines_default`	`"DuckDuckGo"`	string	Default search engine
`firefox_search_engines_prevent_installs`	`false`	boolean	Prevent search engine installs
`firefox_search_engines_remove`	`["Google","Bing"]`	list	Search engines to remove
`firefox_search_suggest_enabled`	`true`	boolean	Enable search suggestions
`firefox_skip_terms_of_use`	`true`	boolean	Skip terms of use
`firefox_ssl_version_max`	`""`	string	Maximum SSL/TLS version
`firefox_ssl_version_min`	`""`	string	Minimum SSL/TLS version
`firefox_support_menu_title`	`""`	string	Support menu title
`firefox_support_menu_url`	`""`	string	Support menu URL
`firefox_support_menu_access_key`	`""`	string	Support menu access key
`firefox_start_downloads_in_temp_directory`	`false`	boolean	Start downloads in temp directory
`firefox_translate_enabled`	`true`	boolean	Enable built-in translate

Sanitize on shutdown¶

Variable	Default Value	Type	Description
`firefox_sanitize_on_shutdown_cache`	`false`	boolean	Clear cache on shutdown
`firefox_sanitize_on_shutdown_cookies`	`false`	boolean	Clear cookies on shutdown
`firefox_sanitize_on_shutdown_history`	`false`	boolean	Clear history on shutdown
`firefox_sanitize_on_shutdown_sessions`	`false`	boolean	Clear sessions on shutdown
`firefox_sanitize_on_shutdown_site_settings`	`false`	boolean	Clear site settings on shutdown
`firefox_sanitize_on_shutdown_locked`	`false`	boolean	Lock sanitize on shutdown setting

User messaging & Labs¶

Variable	Default Value	Type	Description
`firefox_user_messaging_extension_recommendations`	`true`	boolean	Extension recommendations
`firefox_user_messaging_feature_recommendations`	`true`	boolean	Feature recommendations
`firefox_user_messaging_urlbar_interventions`	`true`	boolean	Urlbar interventions
`firefox_user_messaging_skip_onboarding`	`false`	boolean	Skip onboarding
`firefox_user_messaging_more_from_mozilla`	`true`	boolean	More from Mozilla card
`firefox_user_messaging_firefox_labs`	`true`	boolean	Firefox Labs setting
`firefox_user_messaging_locked`	`false`	boolean	Lock user messaging settings

Website filter¶

Variable	Default Value	Type	Description
`firefox_website_filter_block`	`[]`	list	Blocked websites
`firefox_website_filter_exceptions`	`[]`	list	Website filter exceptions

Example Playbooks¶

Basic Installation¶

---
- hosts: servers
  become: true
  roles:
    - role: firefox

Install with uBlock Origin and Custom Settings¶

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_state: present
        firefox_disable_telemetry: true
        firefox_disable_firefox_studies: true
        firefox_extension_settings:
          - id: "uBlock0@raymondhill.net"
            installation_mode: "force_installed"
            install_url: "https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi"
        firefox_homepage_url: "https://www.example.com"
        firefox_permissions_autoplay_allow:
          - "https://example.org"

Install with Multiple Extensions¶

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_extension_settings:
          - id: "uBlock0@raymondhill.net"
            installation_mode: "force_installed"
            install_url: "https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi"
          - id: "addon@mozilla.org"
            installation_mode: "force_installed"
            install_url: "https://addons.mozilla.org/firefox/downloads/latest/addon/latest.xpi"

Strict Privacy Configuration¶

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_disable_telemetry: true
        firefox_disable_firefox_studies: true
        firefox_disable_firefox_accounts: true
        firefox_enable_tracking_protection_value: true
        firefox_enable_tracking_protection_category: "strict"
        firefox_https_only_mode: "force_enabled"
        firefox_disable_password_reveal: true
        firefox_primary_password: true

Custom Search Engine Configuration¶

Set DuckDuckGo as the default search engine and remove Google and Bing (this is the default configuration):

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_search_engines_default: "DuckDuckGo"
        firefox_search_engines_remove:
          - "Google"
          - "Bing"

You can also add custom search engines:

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_search_engines_default: "DuckDuckGo"
        firefox_search_engines_remove:
          - "Google"
          - "Bing"
        firefox_search_engines_add:
          - Name: "Example Search"
            URLTemplate: "https://www.example.org/search?q={searchTerms}"
            Method: "GET"
            IconURL: "https://www.example.org/favicon.ico"
            Alias: "example"
            Description: "Example search engine"

Uninstall Firefox¶

---
- hosts: servers
  become: true
  roles:
    - role: firefox
      vars:
        firefox_state: absent