For a customer project, I recently needed to take a closer look at best strategies of deploying Chromium settings to thrillions of client machines in a corporate network.
Unfortunately, the information on how to deploy site-wide Chromium
browser policies are a little scattered over the internet and the
intertwining of Chromium preferences and Chromium policies required
Here, I'd like to provide the result of that research, namely a list of references
that has been studied before setting up Chromium policies for the customer's proof-of-concept.
Difference between Preferences and Policies
Chromium can be controlled via preferences (mainly user preferences) and
administratively rolled-out policy files.
The difference between preferences and policies are explained here:
The site-admin (or distro package maintainer) can pre-configure the
user's Chromium experience via a master preferences file
). This master preferences file is
the template for the user's preferences file and gets copied over into
the Chromium user profile folder on first browser start.
Note: By studying the recent Chromium code it was found out that
is the legacy filename of the initial
preferences file. The new filename is
. We will continue with
here as most Linux distributions still provide the
initial preferences via this file. Whereas the new filename is already
supported by Chromium in openSUSE/SLES, it is not yet support by Chromium
in Debian/Ubuntu. (See Debian bug
Difference of 'managed' and 'recommended' Policies
The difference between 'managed' and 'recommended' Chromium policies is
Quoting from above URL (last visited 2021/08): Policies that should be
editable by the user are called "recommended policies" and offer a better
alternative than the master_preferences file. Their contents can be
changed and are respected as long as the user has not modified the value
of that preference themselves.
So, policies of type 'managed' override user preferences (and also lock
them in the Chromium settings UI). Those 'managed' policies are good for
enforcing browser settings. They can be blended in also for existing
browser user profiles. Policies ('managed' and
'recommended') even get
blended it at browser run-time when modified.
Use case: e.g. for rolling out browser security settings that are
required for enforcing a site-policy-compliant browser user
Policies of type 'recommended' have an impact on setting defaults of the
Chromium browser. They apply to already existing browser profiles, if the
user hasn't tweaked with the to-be-recommended settings, yet. Also, they
get applied at browser run-time.
However, if the user has already fiddled with such a to-be-recommended
setting via the Chromium settings UI, the user choice takes precedence
over the recommended policy.
Use case: Policies of type 'recommended' are good for long-term
adjustments to browser configuration options. Esp. if users don't touch
their browser settings much, 'recommended' policies are a good approach
for fine-tuning site-wide browser settings on user machines.
CAVEAT: While researching on this topic, two problematic observations were
- All setting parameters put into the master preferences file
/etc/chromium/master_preferences) can't be superceded by
'recommended' Chromium policies. Pre-configured preferences are
handled as if the user has already tinkered with those preferences
in Chromium's settings UI. It also was discovered, that distributors
tend to overload
/etc/chromium/master_preferences with their
best practice browser settings. Everything that is not required on
first browser start should be provided as 'recommended' policies,
already in the distribution packages for Chromium .
- There does not seem to be an elegant way to override the package
maintainer's choice of options in
/etc/chromium/master_preferences file via some file drop-in
replacement. (See Debian bug
#992179). So, deploying Chromium
involves post-install config file tinkering by hand, by script or by
config management tools. There is space for improvement here.
Managing Chromium Policy with Files
Chromium supports 'managed' policies and 'recommended' policies. Policies
get deployed as JSON files.
For Linux, this is explained here:
Note, that for Chromium, the policy files have to be placed into
. The example on the above web page shows where to place them
for Google Chrome.
Good 'How to Get Started' Documentation for Chromium Policy Setups
This overview page provides a good get-started-documentation on how to
provision Chromium via policies:
It seems, not every setting can be tweaked via a Chromium policy. Esp.
the first-run preferences are affected by this:
So, for tweaking the first-run settings, one needs to adjust
(which is suboptimal, again see Debian
for a detailed explanation
on why this is suboptimal).
The required adjustments to
can be achieved with the
command line tool, here is one example:
# Tweak chromium's /etc/chromium/master_preferences file.
# First change: drop everything that can be provisioned via Chromium Policies.
# Rest of the changes: Adjust preferences for new users to our needs for all
# parameters that cannot be provisioned via Chromium Policies.
cat /etc/chromium/master_preferences \
jq 'del(.browser.show_home_button, .browser.check_default_browser, .homepage)'
jq '.first_run_tabs=[ "https://first-run.example.com/", "https://your-admin-faq.example.com" ]'
jq '.credentials_enable_service=false .credentials_enable_autosignin=false'
jq '.distribution.import_bookmarks=false .distribution.verbose_logging=false .distribution.skip_first_run_ui=true'
jq '.distribution.create_all_shortcuts=true .distribution.suppress_first_run_default_browser_prompt=true'
cat > /etc/chromium/master_preferences.adapted
if [ -n "/etc/chromium/master_preferences.adapted" ]; then
mv /etc/chromium/master_preferences.adapted /etc/chromium/master_preferences
echo "WARNING (chromium tweaks): The file /etc/chromium/master_preferences.adapted was empty after tweaking."
echo " Leaving /etc/chromium/master_preferences untouched."
The list of available (first-run and other) initial preferences can be found in Chromium's
List of Available Chromium Policies
The list of available Chromium policies used to be maintained in the Chromium wiki:
However, that page these days redirects to the Google Chrome Enterprise
Each policy variable has its own documentation page there. Please note
the "Supported Features" section for each policy item. There, you can
see, if the policy supports being placed into "recommended" and/or
This is an example
file (note that all kinds of filenames are allowed, even files without .json suffix):
And this is an example
And for defining a custom search provider, I use
(here, I recommend not using DuckDuckGo as DefaultSearchProviderName, but some custom name; unfortunately, I did not find a policy parameter that simply selects an already existing search provider name as the default :-( ):
"DefaultSearchProviderName": "DuckDuckGo used by Example.com",
"DefaultSearchProviderSearchURL": "https://duckduckgo.com/?q= searchTerms ",
"DefaultSearchProviderSuggestURL": "https://duckduckgo.com/ac/?q= searchTerms &type=list",
The Essence and Recommendations
On first startup, Chromium copies
. It does this only if the
Chromium user profile has'nt been created, yet.
So, settings put into
by the distro and the site
or device admin are one-time-shot preferences (new user logs into a
device, preferences get applied on first start of Chromium). Chromium
policy files, however, get continuously applied at browser runtime.
Chromium watches its policy files and you can observe Chromium settings
change when policy files get modified.
So, for continuously provisioning site-wide settings that mostly always
trickle into the user's browser configuration, Chromium policies should
definitely be preferred over
and this should be
the approach to take.
When using Chromium policies, one needs to take into account that
seem to have
precedence over 'recommended' policies. So, settings that you want to
deploy as recommended policies must
be removed from
Essentially, these are the recommendations extracted from all the above
research and information for deploying Chromium on enterprise scale:
- Everything that's required at first-run should go into
- Everything that's not required at first-run should be removed from
- Everything that's deployable as a Chromium policy should be deployed as a policy (as
you can influence existing browser sessions with that, also long-term)
- Chromium policy files should be split up into several files.
Chromium parses those files in alpha-numerical order. If policies occur
more than once, the last policy being parsed takes precedence.
If you have any feedback or input on this post, I'd be happy to hear it. Please get in touch via the various channels where I am known as sunweaver (OFTC and libera.chat IRC, [matrix], Mastodon, E-Mail at debian.org, etc.). Looking forward to hearing from you. Thanks!
Mike Gabriel (aka sunweaver)