cifs-pattern-match-20040921
[openafs.git] / doc / txt / winnotes / msi-deployment-guide.txt
1
2 OpenAFS for Windows
3                          MSI Deployment Guide
4 ----------------------------------------------------------------------
5
6      Contents
7
8      1.  Introduction
9      1.1 Requirements
10
11      2.  Configuration options
12      2.1 Configurable properties
13      2.2 Existing registry values
14
15      3.  Additional resources
16      3.1 Example
17
18      4.  Upgrades
19
20      5.  FAQ
21
22
23 ----------------------------------------------------------------------
24
25 1.  Introduction
26
27     Beginning with OpenAFS for Windows version 1.3.65 a MSI installer
28     option is available for those who wish to use Windows
29     Installer for installing OpenAFS and for organizations that wish
30     to deploy OpenAFS through Group Policy.
31
32     This document provides a guide for authoring transforms used to
33     customize the MSI package for a particular organization.
34     Although many settings can be deployed via transforms, in an
35     Active Directory environment it is advisable to deploy registry
36     settings and configuration files through group policy and/or
37     startup scripts so that machines where OpenAFS for Windows is
38     already installed will pick up these customizations.
39
40 1.1 Requirements
41
42     The information in this document applies to MSI packages
43     distributed with OpenAFS for Windows releases from 1.3.65 and
44     onwards or MSI packages built from corresponding source
45     releases. Not all releases support all the configuration options
46     documented here.
47
48     Authoring a Windows Installer transform requires additional
49     software for editing the MSI database tables and generating the
50     transform from the modified MSI package.  ORCA.EXE and MSITRAN.EXE
51     which are included in the Windows Platform SDK (Windows Installer
52     SDK) can be used for this purpose.
53
54     The schema for the MSI package is based on SCHEMA.MSI distributed
55     with the Platform SDK.
56
57 ----------------------------------------------------------------------
58
59 2.  Configuration Options
60
61 2.1 Configurable Properties
62
63     Most configurable properties correspond to registry keys or values.
64     To avoid duplication, only a reference to the relevant registry key
65     or value is given here.  For more details about the associated
66     semantics, please refer to registry.txt distributed with the
67     OpenAFS for Windows release.
68
69     These properties are, of course, found in the 'Property' table of
70     the MSI package.
71
72     For brevity the following nomenclature will be used to refer to
73     registry keys:
74
75     Strings are quoted using single quotes (e.g. 'a string'). An empty
76     string is denoted as ''.  Note that you can't author null values
77     into the 'Property' table.  To achieve this effect you'll have to
78     drop the relevant row.
79
80     (Service parameters):
81     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
82
83     (Network provider):
84     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
85
86     The configurable properties are as follows:
87
88     AFSCACHEPATH
89         Registry key    : (Service parameters)
90         Registry value  : CachePath
91         Valid values    : string
92
93     AFSCACHESIZE
94         Registry key    : (Service parameters)
95         Registry value  : CacheSize
96         Valid values    : numeric
97
98     AFSCELLNAME
99
100         Registry key    : (Service parameters)
101         Registry value  : Cell
102         Valid values    : string
103
104     CREDSAUTOINIT
105         Valid values    : '-a' or ''
106         
107         Option for AFSCREDS.EXE.  Enables automatic initialization.
108         (see below)
109
110     CREDSIPCHDET
111         Valid values    : '-n' or ''
112
113         Option for AFSCREDS.EXE.  Enables IP address change detection.
114         (see below)
115
116     CREDSQUIET
117         Valid values    : '-q' or ''
118
119         Option for AFSCREDS.EXE.  Enables quiet mode.
120         (see below)
121
122     CREDSRENEWDRMAP
123         Valid values    : '-m' or ''
124
125         Option for AFSCREDS.EXE.  Enables renewing drive map at
126         startup.
127         (see below)
128
129     CREDSSHOW
130         Valid values    : '-s' or ''
131
132         Option for AFSCREDS.EXE.  Enables displaying the credential
133         manager window when AFSCREDS starts up.
134
135         The five properties above determine the behavior of the AFS
136         credential manager ( AFSCREDS.EXE ).  Each property adds a
137         command line option to the shortcut that will be created in
138         the Program Menu, both under 'OpenAFS' and 'Startup' folders
139         (see CREDSSTARTUP).
140
141         The way in which the options are specified was chosen for easy
142         integration with the Windows Installer user interface.
143         Although you can come up with creative ways to provide other
144         options to AFSCREDS.EXE, we advise against it because such
145         transforms may not apply to future releases of OpenAFS.
146
147     CREDSSTARTUP
148         Valid values    : '1' or '0'
149
150         Controls whether AFSCREDS.EXE starts up automatically when a
151         user logs on.  When CREDSSTARTUP is '1' a shortcut is added
152         to the 'Startup' folder in the 'Program menu' which starts
153         AFSCREDS.EXE with the options that are determined by the
154         other CREDS* properties.
155
156     FREELANCEMODE
157
158         Registry key    : (Service parameters)
159         Registry value  : FreelanceClient
160         Valid values    : '1' or '0'
161
162     HIDEDOTFILES
163
164         Registry key    : (Service parameters)
165         Registry value  : HideDotFiles
166         Valid values    : '1' or '0'
167
168     LOGONOPTIONS
169
170         Registry key    : (Network provider)
171         Registry value  : LogonOptions
172         Valid values    : '0','1' or '3'
173
174         See section 2.1 of registry.txt (Domain specific configuration
175         keys for Network Provider) and section [filler] of this
176         document (filler) for more details.
177
178     MOUNTROOT
179
180         Registry key    : (Service parameters)
181         Registry value  : Mountroot
182         Valid values    : string
183
184     NETBIOSNAME
185
186         Registry key    : (Service parameters)
187         Registry value  : NetbiosName
188         Valid values    : string (at most 15 characters)
189
190     NOFINDLANABYNAME
191
192         Registry key    : (Service parameters)
193         Registry value  : NoFindLanaByName
194         Valid values    : '1' or '0'
195
196     RXMAXMTU
197
198         Registry key    : (Service parameters)
199         Registry value  : RxMaxMTU
200         Valid values    : numeric
201
202     SECURITYLEVEL
203
204         Registry key    : (Service parameters)
205         Registry value  : SecurityLevel
206         Valid values    : '1' or '0'
207
208     SMBAUTHTYPE
209
210         Registry key    : (Service parameters)
211         Registry value  : SMBAuthType
212         Valid values    : '0','1' or '2'
213
214     USEDNS
215
216         Registry key    : (Service parameters)
217         Registry value  : UseDNS
218         Valid values    : '1' or '0'
219
220
221 2.2 Existing Registry Entries
222
223     You can change existing registry values subject to the
224     restrictions mentioned in the Windows Platform SDK.  Pay special
225     attention to component keypaths and try to only change the 'Value'
226     column in the 'Registry' table.  If you want to add additional
227     registry keys please refer to section 3 (Additional Resources).
228
229 ----------------------------------------------------------------------
230
231 3   Additional Resources
232
233     If you want to add registry keys or files you need to create new
234     components and features for those.  Refer to the Windows Platform
235     SDK for details.
236
237     Add new features under the 'feaClient' or 'feaServer' as
238     appropriate and set the 'Level' column for those features to equal
239     the 'Level' for their parent features for consistency.  Note that
240     none of the features in the OpenAFS for Windows MSI package are
241     designed to be installed to run from 'source' or 'advertised'.  It
242     is recommended that you set 'msidbFeatureAttributesFavorLocal' (0),
243     'msidbFeatureAttributesFollowParent' (2) and
244     'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
245     features.
246
247     If you are creating new components, retain the same component GUID
248     when creating new transforms against new releases of the OpenAFS
249     MSI package.
250
251 3.1 Example: Adding domain specific registry keys
252
253     Following is an example for adding domain specific registry keys.
254     Refer to section 2.1 in REGISTRY.TXT for more information.
255
256     Columns that are unspecified should be left empty.
257
258     We create a new feature and component to hold the new registry keys.
259
260     'Feature' table:
261
262     (new row)
263         Feature         : 'feaDomainKeys'
264         Feature Parent  : 'feaClient'
265         Display         : 0
266         Level           : 30
267         Attributes      : 10
268
269     'Component' table:
270
271         (new row)
272     Component   : 'rcm_DomainKeys'
273         ComponentId     : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
274         Directory       : 'TARGETDIR'
275         Attributes      : 4
276         KeyPath         : 'reg_domkey0'
277
278     'FeatureComponents' table:
279
280     (new row)
281         Feature         : 'feaDomainKeys'
282         Component       : 'rcm_DomainKeys'
283
284     'Registry' table:
285
286         (new row)
287         Registry        : 'reg_domkey0'
288         Root            : 2
289         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
290         Component       : 'rcm_DomainKeys'
291
292         (new row)
293         Registry        : 'reg_domkey1'
294         Root            : 2
295         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
296         Name            : '*'
297         Component       : 'rcm_DomainKeys'
298
299         (new row)
300         Registry        : 'reg_domkey2'
301         Root            : 2
302         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
303         Name            : '*'
304         Component       : 'rcm_DomainKeys'
305
306         (new row)
307         Registry        : 'reg_domkey3'
308         Root            : 2
309         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
310         Name            : 'LogonOptions'
311         Value           : 1
312         Component       : 'rcm_DomainKeys'
313
314         (new row)
315         Registry        : 'reg_domkey4'
316         Root            : 2
317         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
318         Name            : '*'
319         Component       : 'rcm_DomainKeys'
320
321         (new row)
322         Registry        : 'reg_domkey5'
323         Root            : 2
324         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
325         Name            : 'LogonOptions'
326         Value           : 0
327         Component       : 'rcm_DomainKeys'
328
329         (new row)
330         Registry        : 'reg_domkey6'
331         Root            : 2
332         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
333         Name            : 'FailLoginsSilently'
334         Value           : 1
335         Component       : 'rcm_DomainKeys'
336
337     The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable
338     integrated logon) and 'LOCALHOST' (disable integrated logon and
339     fail logins silently).
340
341     After making the adjustments to the MSI database using ORCA.EXE
342     you can generate a transform with MSITRAN.EXE as follows :
343
344     (Modified MSI package is 'openafs-en_US_new.msi' and the original
345     MSI package is 'openafs-en_US.msi'.  Generates transform
346     'openafs-transform.mst')
347
348     > msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst glpruw
349
350     See the Platform SDK documentation for information on command line
351     options for MSITRAN.EXE.
352
353 ----------------------------------------------------------------------
354
355 4.  Upgrades
356
357     The MSI package is designed to uninstall previous versions of
358     OpenAFS for Windows during installation.  Note that it doesn't
359     directly upgrade an existing installation.  This is intentional
360     and ensures that development releases which do not have strictly
361     increasing version numbers are properly upgraded.
362
363     Versions of OpenAFS that are upgraded by the MSI package are :
364
365     1) OpenAFS MSI package
366        Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
367        Upto current release
368
369     2) MIT's Transarc AFS MSI package
370        Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
371        Upto version 3.6.2
372
373     3) OpenAFS NSIS package
374        All versions
375
376        Note that versions of the OpenAFS NSIS package prior to 1.3.65
377        had a bug where it couldn't be uninstalled properly in
378        unattended mode.  Therefore the MSI package will not try to
379        uninstall an OpenAFS NSIS package if running unattended.  This
380        means that group policy based deployments will fail on machines
381        that have the OpenAFS NSIS package installed.
382
383     If you have used a different MSI package to install OpenAFS and
384     wish to upgrade it you can author rows into the 'Upgrade' table as
385     described in the Platform SDK.
386
387 ----------------------------------------------------------------------
388
389 5.  FAQ
390
391     (Q/A's will be added here as needed)
392
393 ----------------------------------------------------------------------
394 $Id$