1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
|
---
breadcrumbs:
- - /administrators
- Documentation for Administrators
page_name: configuring-other-preferences
title: Configuring Other Preferences
---
Not all user preferences are managed through policy, typically because they do
not need to be managed centrally.
**Preferences vs. Policies**
Preferences and policies are two different methods for controlling the browser's
behavior. They have different purposes, however:
Preferences:
* Keep state of a user's personal browsing experience.
* Are usually unique to each user.
* Are writable by the user, as they live in the user's directory in a
text file.
* Are often under-the-hood, technical settings that don't necessarily
make sense to pre-set per user or lock in with policy.
* Use the master_preferences file as a template if no Preferences
already exist. **Preferences are copied from master_preferences
==only once==; changes to the master_preferences file made after
that are not respected!**
Policies:
* Are rules that the user's browsing experience must abide by.
* Do not keep state of the user's experience.
* Are usually applied to groups of users; they are not necessarily
unique to each user.
* Are not (typically) writable by the user.
* Are clearly enumerated and are intended for the admin to use & set.
* Are set only by the admin in special locations (registry, MCX,
/etc/...).
* 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.
There are several notable preferences that are also policies, "homepage" being
the most common.
Policies take precedence to preferences and preferences take precedence to
recommended policies. If "homepage" is specified in both the policies, and in
the "master_preferences" file, policies will always override.
**Should I use a Preference, or a Policy?**
Prefer policies to configure Chrome on managed computers. Use recommended
policies for settings that users should be able to change, and use mandatory
policies for settings that users should not be able to change. A
master_preferences file may be used to make default settings for new users,
though doing so has some drawbacks:
* The contents of a master_preferences file are copied once per
profile at profile creation. As a result, it is not possible to
automatically propagate modifications to a master_preferences file
to users.
* The preferences that may be set via master_preferences are not
guaranteed to work in the future. It is possible that preferences
may change or be removed such that values in master_preferences
files would be ignored.
### The Gritty Details
Preferences are kept in a file named "Preferences", which every Chromium /
Google Chrome user will have in their own user directory. This Preferences file
is a text file that contains JSON markup. Going through and editing every user's
Preferences file to deploy a behavior change is really cumbersome and some
preferences are protected by cryptographic hashes and can not be manually
edited, so there are easier ways to manage this:
* When users start Chromium / Google Chrome for the first time, they
don't yet have any Preferences file.
* A file named "master_preferences" located next to chrome.exe or
chromium executable, is used as a template for what becomes users'
Preferences file. On a system with Chrome installed from an MSI,
this will be C:\\Program Files
(x86)\\Google\\Chrome\\Application\\master_preferences
* On **Mac OS X**, for **Google Chrome**, this file is either of
~/Library/Application Support/Google/Chrome/Google Chrome Master
Preferences or /Library/Google/Google Chrome Master Preferences
* On **Mac OS X**, for **Chromium**, this file is either of
~/Library/Application Support/Chromium/Chromium Master
Preferences or /Library/Application Support/Chromium/Chromium
Master Preferences
* You only need to create and populate the master_preferences file
when you deploy Google Chrome, and all users on that machine will
get those settings when they first start Chromium / Google Chrome.
The master_preferences file, like each user's Preferences file, is simply a text
file that contains JSON markup, and will look something like this:
```none
{
"homepage" : "http://www.chromium.org/",
"homepage_is_newtabpage" : false,
"distribution" : {
...more stuff here ...
}
}
```
Some of the preferences should be obvious, but some are not entirely clear --
they are described at the end of this document.
Moreover, you'll notice that some of these preferences are managed by policy.
Note that **no matter what is in the master_preferences or Preferences files,
policy always takes precedence.** Setting the home page in both the Preferences
file and policy means that the home page in policy will be the one that Chromium
/ Google Chrome uses, and the user will not be able to edit it.
**Preferences List**
So, what preferences should you actually use? There are actually lots and lots
of preferences, most of which you won't really care about.
Here is a sample master_preferences list that may be of interest (this is a
fully-functional master_preferences file):
{
"homepage": "http://www.google.com",
"homepage_is_newtabpage": false,
"browser": {
"show_home_button": true
},
"session": {
"restore_on_startup": 4,
"startup_urls": \[
"http://www.google.com/ig"
\]
},
"bookmark_bar": {
"show_on_all_tabs": true
},
"sync_promo": {
"show_on_first_run_allowed": false
},
"distribution": {
"import_bookmarks_from_file": "bookmarks.html",
"import_bookmarks": true,
"import_history": true,
"import_home_page": true,
"import_search_engine": true,
"ping_delay": 60,
"do_not_create_desktop_shortcut": true,
"do_not_create_quick_launch_shortcut": true,
"do_not_create_taskbar_shortcut": true,
"do_not_launch_chrome": true,
"do_not_register_for_update_launch": true,
"make_chrome_default": true,
"make_chrome_default_for_user": true,
"system_level": true,
"verbose_logging": true,
"browser": {
"confirm_to_quit": true,
}
},
"first_run_tabs": \[
"http://www.example.com",
"http://welcome_page",
"http://new_tab_page"
\]
}
Most of these settings should be self-explanatory. The most interesting settings
are:
* import_bookmarks_from_file: silently imports bookmarks from the
given HTML file.
* import_\*: each of these import parameters will trigger automatic
imports of settings on first run.
* ping_delay: RLZ ping delay in seconds.
* do_not_create_any_shortcuts: suppress creation of all shortcuts
(including the Start Menu shortcut)
* do_not_create_taskbar_shortcut: only supported on Windows 8 and
below -- TaskBar shortcuts are never created on Windows 10
* do_not_launch_chrome: doesn't launch chrome after the first install.
* do_not_register_for_update_launch: does not register with Google
Update to have Chrome launched after install.
* make_chrome_default: makes chrome the default browser.
* make_chrome_default_for_user: makes chrome the default browser for
the current user.
* system_level: install chrome to system-wide location.
* verbose_logging: emit extra details to the installer's log file to
diagnose install or update failures.
* first_run_tabs: these are the tabs & URLs shown on the first launch
(and only on first launch) of the browser.
* sync_promo.show_on_first_run_allowed: prevents the sign-in page from
appearing on first run.
* browser/confirm_to_quit: Supported only on MacOS can be used to
prevent the confirmation prompt on quitting the browser. Note that
it needs to be in the "distribution" section of the file.
### Pre-installed Bookmarks
To add pre-installed bookmarks, you have to create a file that contains all of
your bookmarks, then give the right signals for a Chrome install to import them
when a user runs Chrome for the first time.
1. First, set up bookmarks in Chrome as you'd like them to appear to
the end-user
2. Go to the Wrench Menu -> Bookmark Manager -> Organize
Bookmarks -> Export Bookmarks
3. The file that is saved/exported contains all of the bookmark data
that will be imported.
To instruct an end-user's Chrome to import these bookmarks, include these
elements in your master_preferences:
{ "distribution": { "import_bookmarks": false, "import_bookmarks_from_file":
"c:\\\\path\\\\to\\\\your\\\\bookmarks.html" }, "bookmark_bar": {
"show_on_all_tabs": true } }
The relevant entries are:
* "import_bookmarks_from_file": needs to have the path to bookmark
file. **The backslashes in the path must be escaped by a backslash;
use double-backslashes. Also be sure that this file exists at the
point that the user first runs Chrome.**
* "import_bookmarks" should probably be false, so your imported
bookmarks don't get overwritten.
* "show_on_all_tabs": can either be true or false, whether we've
promised the partner to show the bookmarks bar on by default or not.
|
