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
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
|
Kerberos for Windows
MSI Deployment Guide
----------------------------------------------------------------------
Contents
1. Introduction
1.1 Requirements
1.2 Authoring a Transform
2. Configuration Options
2.1 Configurable Properties
2.1.1 Setting Properties
2.1.2 Leash GUI Properties
2.1.3 Leash DLL Properties
2.1.4 Kerberos IV Properties
2.1.5 Kerberos V Properties
2.2 Existing Registry Entries
3. Additional Resources
4. Upgrades
5. FAQ
----------------------------------------------------------------------
1. Introduction
Beginning with Kerberos for Windows version 2.6.5 a MSI installer
option is available for those who wish to use Windows Installer
for installing Kerberos and for organizations that wish to deploy
Kerberos through Group Policy.
This document provides a guide for authoring transforms used to
customize the MSI package for a particular organization. Although
many settings can be deployed via transforms, in an Active
Directory environment it is advisable to deploy registry settings
and configuration files through group policy and/or startup
scripts so that machines where Kerberos for Windows is already
installed will pick up these customizations.
1.1 Requirements
The information in this document applies to MSI packages
distributed with Kerberos for Windows releases from 2.6.5 and
onwards or MSI packages built from corresponding source
releases. Not all releases support all the configuration options
documented here.
Authoring a Windows Installer transform requires additional
software for editing the MSI database tables and generating the
transform from the modified MSI package. ORCA.EXE and MSITRAN.EXE
which are included in the Windows Platform SDK (Windows Installer
SDK) can be used for this purpose.
For reference, the schema for the MSI package is based on
SCHEMA.MSI distributed with the Platform SDK.
For general information about Windows Installer, refer to :
http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp
For general information about authoring MSI transforms, refer to :
http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp
The remainder of this document assumes some familiarity with
authoring transforms. While the MSDN documentation for Windows
Installer is a bit dense, it is recommended that you read through
the guide on MSI transforms found at the second link above. Also
MSDN includes a step-by-step example for creating a transform at:
http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp
1.2 Authoring a Transform
Transforms describe a set of modifications to be performed on an
existing MSI for the purpose of customizing it. This is
ordinarily done by making a copy of the MSI to be customized,
modifying the copy and then using the old and the new MSI to
generate a transform.
E.g:
> copy kfw.msi kfw-modified.msi
(edit the kfw-modified.msi to include the necessary changes)
> msitran -g kfw-modified.msi kfw.msi kfw-transform.mst
(generates kfw-transform.mst, which is the transform)
Transforms have an extension of .mst. 'msitran' is a tool
distributed as part of the Windows Installer SDK (which in turn is
a part of the Windows Platform SDK).
You can test a transform by :
> copy kfw.msi kfw-test.msi
> msitran -a kfw-transform.mst kfw-test.msi
and then checking the resulting kfw-test.msi to see if all the
changes you have made above to kfw-modified.msi is present in
kfw-test.msi. 'msitran' will complain if some modification in the
transform can not be successfully applied.
As mentioned above, you can use a tool like ORCA.EXE to edit the
MSI databases directly when editing kfw-modified.msi. More
details are given below.
----------------------------------------------------------------------
2. Configuration Options
The logic necessary to implement all of the setttings described in
the release notes are present in the MSI. Most of these can be
controlled by setting the corresponding properties to the desired
value. Some settings may require modifying existing registry
entries (though not recommended) or adding new resources (like
files or registry keys). Instructions for performing these tasks
are below.
2.1 Configurable Properties
Most configurable properties correspond to registry keys or
values. Please refer to the release notes for more information
about how these registry settings are used.
Due to the logic invoked based on the existence of these registry
keys or values, they are only set if the associated property is
defined to have a non null value. If the associated property is
not defined in the MSI, the registry key or value will not be
touched. By default, the MSI does not contain these properties
and hence will not set the registry keys. You will need to add
properties as needed to the MSI.
When one of the configurable properties is set, the installer will
use the property value to set the corresponding setting in the
HKEY_LOCAL_MACHINE registry hive. HKEY_CURRENT_USER hive is not
touched by the installer.
For each property, the associated registry setting is referenced
by the same text used in the release notes ('Registry and
Environment Settings' section).
Strings are quoted using single quotes (e.g. 'a string'). An empty
string is denoted as ''. Note that you can't author null values
into the 'Property' table.
Numeric values should be authored as decimal strings.
2.1.1 Setting Properties
In order to set a property,
a. Open the MSI in ORCA.EXE
b. Select the 'Property' table from the list of tables on the left.
c. Find the property in the list of properties on the right,
double click the value and type the new value.
d. If the property does not exist in the property list, right
click the list and select 'Add Row', type the property name
and the desired value.
2.1.2 Leash GUI properties
LEASHAFSSTATUS
Setting: afs token retrieval
Values : '0' or '1'
LEASHCREATEMISSINGCONFIG
Setting: automatic generation of missing configuration files
Values : '0' or '1'
LEASHAUTORENEWTICKETS
Setting: automatic ticket renewal
Values : '0' or '1'
LEASHLOCKFILELOCATIONS
Setting: lock configuration files location
Values : '0' or '1'
LEASHMSLSAIMPORT
Setting: automatic importation of MSLSA credentials
Values : '0', '1' or '2'
2.1.3 Leash32 DLL properties
LEASHLIFETIME
Setting: default lifetime (minutes)
Values : numeric
LEASHRENEWTILL
Setting: default renew till time (minutes)
Values : numeric
LEASHRENEWABLE
Setting: default renewable tickets setting
Values : '0' or '1'
LEASHFORWARDABLE
Setting: default forwardable tickets setting
Values : '0' or '1'
LEASHNOADDRESSES
Setting: default addressless tickets setting
Values : '0' or '1'
LEASHPROXIABLE
Setting: default proxiable tickets setting
Values : '0' or '1'
LEASHPUBLICIP
Setting: default public ipv4 address
Values : numeric
LEASHUSEKRB4
Setting: request kerberos iv tickets
Values : '0' or '1'
LEASHHIDEKINITOPTIONS
Setting: hide advanced kinit options in dialog
Values : '0' or '1'
LEASHLIFEMIN
Setting: minimum kinit dialog lifetime
Values : numeric
LEASHLIFEMAX
Setting: maximum kinit dialog lifetime
Values : numeric
LEASHRENEWMIN
Setting: minimum kinit dialog renew till time
Values : numeric
LEASHRENEWMAX
Setting: maximum kinit dialog renew till time
Values : numeric
LEASHUPPERCASEREALM
Setting: upper case realm
Values : '0' or '1'
LEASHTIMEHOST
Setting: timesync host
Values : string
LEASHPRESERVEKINITOPTIONS
Setting: Preserve ticket initialization dialog options
Values : numeric
2.1.4 Kerberos 4 properties
KRB4KRBREALMS (realms full pathname)
KRB4KRBCONF (config full pathname)
KRB4KRBCONFIDIR (dir for both files)
Setting: location of krbrealm & krbconf
Values : string
(note that the three registry settings are conditioned
independently. I.e. If you only set KRB4KRBCONF, only the
krb.conf setting will be written.)
KRB4TICKETFILE
Setting: ticket file
Values : string
2.1.5 Kerberos 5 properties
KRB5CONFIG
Setting: location of krb5.ini
Values : string
KRB5CCNAME
Setting: Default credentials cache name
Values : string
KRB5PRESERVEIDENTITY
Setting: MSLSA: credential cache client principal identity generation
Values : '0' or '1'
2.2 Existing Registry Entries
You can change existing registry values subject to the
restrictions mentioned in the Windows Platform SDK. Pay special
attention to component keypaths and try to only change the 'Value'
column in the 'Registry' table. If you want to add additional
registry keys please refer to section 3 (Additional Resources).
----------------------------------------------------------------------
3 Additional Resources
If you want to add registry keys or files you need to create new
components and features for those.
Add new features under the 'feaKfwClient' feature and set the
'Level' column for those features to equal the 'Level' for their
parent features for consistency. Note that none of the features
in the Kerberos for Windows MSI package are designed to be
installed to run from 'source' or 'advertised'. It is recommended
that you set 'msidbFeatureAttributesFavorLocal' (0),
'msidbFeatureAttributesFollowParent' (2) and
'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
features.
If you are creating new components, retain the same component GUID
when creating new transforms against new releases of the Kerberos
MSI package.
It is beyond the scope of this document to provide a comprehensive
overview of how to add new resources through a transform. Please
refer to the Windows Installer documentation for details. The
relevant section is at :
http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp
----------------------------------------------------------------------
4. Upgrades
The MSI package is designed to uninstall previous versions of
Kerberos for Windows during installation. Note that it doesn't
directly upgrade an existing installation. This is intentional
and ensures that development releases which do not have strictly
increasing version numbers are properly upgraded.
Versions of Kerberos that are upgraded by the MSI package are :
1) Kerberos for Windows MSI package
Upgrade code {61211594-AAA1-4A98-A299-757326763CC7}
Upto current release
2) MIT Project Pismere Kerberos for Windows MSI package and MIT
SWRT Kerberos for Windows MSI
Upgrade code {83977767-388D-4DF8-BB08-3BF2401635BD}
All versions
3) Kerberos for Windows NSIS package
All versions
Note that versions of the Kerberos for Windows NSIS package had
a bug where it couldn't be uninstalled properly in unattended
mode. Therefore the MSI package will not try to uninstall an
Kerberos for Windows NSIS package if running unattended. This
means that group policy based deployments will fail on machines
that have the Kerberos for Windows NSIS package installed.
If you have used a different MSI package to install Kerberos for
Windows and wish to upgrade it you can author rows into the
'Upgrade' table to have the Kerberos for Windows MSI replace these
installations for you.
----------------------------------------------------------------------
5. FAQ
(Q/A's will be added here as needed)
----------------------------------------------------------------------
$Id$
|