windows-notes-20050317
[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      2.3   Replacing Configuration Files
15      2.4   Adding Domain Specific Registry Keys
16
17      3.  Additional resources
18
19      4.  Upgrades
20
21      5.  FAQ
22
23
24 ----------------------------------------------------------------------
25
26 1.  Introduction
27
28     Beginning with OpenAFS for Windows version 1.3.65 a MSI installer
29     option is available for those who wish to use Windows
30     Installer for installing OpenAFS and for organizations that wish
31     to deploy OpenAFS through Group Policy.
32
33     This document provides a guide for authoring transforms used to
34     customize the MSI package for a particular organization.  Although 
35     many settings can be deployed via transforms, in an Active 
36     Directory environment it is advisable to deploy registry settings
37     and configuration files through group policy and/or startup 
38     scripts so that machines where OpenAFS for Windows is already
39     installed will pick up these customizations.
40
41 1.1 Requirements
42
43     The information in this document applies to MSI packages
44     distributed with OpenAFS for Windows releases from 1.3.65 and
45     onwards or MSI packages built from corresponding source
46     releases. Not all releases support all the configuration options
47     documented here.
48
49     Authoring a "Windows Installer" transform requires additional
50     software for editing the MSI database tables and generating the
51     transform from the modified MSI package.  ORCA.EXE and MSITRAN.EXE
52     which are included in the Windows Platform SDK ("Windows Installer"
53     SDK) can be used for this purpose.
54
55     For reference, the schema for the MSI package is based on
56     SCHEMA.MSI distributed with the Platform SDK.
57
58     For general information about "Windows Installer", refer to :
59
60     http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp
61
62     For general information about authoring MSI transforms, refer to :
63
64     http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp
65
66     The remainder of this document assumes some familiarity with
67     authoring transforms.  While the MSDN documentation for Windows
68     Installer is a bit dense, it is recommended that you read through
69     the guide on MSI transforms found at the second link above.  Also
70     MSDN includes a step-by-step example for creating a transform at:
71
72     http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp
73
74 1.2  Authoring a Transform
75
76     Transforms describe a set of modifications to be performed on an
77     existing MSI for the purpose of customizing it.  This is
78     ordinarily done by making a copy of the MSI to be customized,
79     modifying the copy and then using the old and the new MSI to
80     generate a transform.
81
82     E.g:
83        > copy openafs.msi openafs-modified.msi
84        
85        (edit the openafs-modified.msi to include the necessary changes)
86
87        > msitran -g openafs-modified.msi openafs.msi openafs-transform.mst
88
89        (generates openafs-transform.mst, which is the transform)
90
91     Transforms have an extension of .mst.  'msitran' is a tool
92     distributed as part of the "Windows Installer" SDK (which in turn is
93     a part of the Windows Platform SDK).
94
95     You can test a transform by :
96
97        > copy openafs.msi openafs-test.msi
98        > msitran -a openafs-transform.mst openafs-test.msi
99
100     and then checking the resulting openafs-test.msi to see if all the
101     changes you have made above to openafs-modified.msi is present in
102     openafs-test.msi.  'msitran' will complain if some modification in the
103     transform can not be successfully applied.
104
105     As mentioned above, you can use a tool like ORCA.EXE to edit the
106     MSI databases directly when editing openafs-modified.msi.  More
107     details are given below.
108
109 ----------------------------------------------------------------------
110
111 2.  Configuration Options
112
113     The logic necessary to implement many of the settings described in
114     the registry.txt file are present in the MSI.  Most of these can be
115     controlled by setting the corresponding properties to the desired
116     value.  Some settings may require modifying existing registry
117     entries (though not recommended) or adding new resources (like
118     files or registry keys).  Instructions for performing these tasks
119     are below.
120
121 2.1 Configurable Properties
122
123     Most configurable properties correspond to registry keys or
124     values.  Please refer to the release notes for more information
125     about how these registry settings are used.
126
127     Due to the logic invoked based on the existence of these registry
128     keys or values, they are only set if the associated property is
129     defined to have a non null value.  If the associated property is
130     not defined in the MSI, the registry key or value will not be
131     touched.  By default, the MSI does not contain these properties
132     and hence will not set the registry keys.  You will need to add
133     properties as needed to the MSI.
134
135     When one of the configurable properties is set, the installer will
136     use the property value to set the corresponding setting in the
137     HKEY_LOCAL_MACHINE registry hive.  HKEY_CURRENT_USER hive is not
138     touched by the installer.
139
140     For each property, the associated registry setting is referenced
141     by the same text used in the registry.txt file.
142
143     Strings are quoted using single quotes (e.g. 'a string'). An empty
144     string is denoted as ''.  Note that you can't author null values
145     into the 'Property' table.
146
147     Numeric values should be authored as decimal strings.
148
149 2.1.1  Setting Properties
150
151     In order to set a property,
152
153     a.  Open the MSI in ORCA.EXE
154
155     b.  Select the 'Property' table from the list of tables on the left.
156
157     c.  Find the property in the list of properties on the right,
158         double click the value and type the new value.
159
160     d.  If the property does not exist in the property list, right
161         click the list and select 'Add Row', type the property name
162         and the desired value.
163
164
165 2.1.2   OpenAFS for Windows properties
166
167     (Service parameters):
168     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
169
170     (Network provider):
171     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
172
173     (OpenAFS Client):
174     [HKLM\SOFTWARE\OpenAFS\Client]
175
176     The configurable properties are as follows:
177
178     AFSCACHEPATH
179         Registry key    : (Service parameters)
180         Registry value  : CachePath
181         Valid values    : string
182
183     AFSCACHESIZE
184         Registry key    : (Service parameters)
185         Registry value  : CacheSize
186         Valid values    : numeric
187
188     AFSCELLNAME
189
190         Registry key    : (Service parameters)
191         Registry value  : Cell
192         Valid values    : string
193
194     CREDSAUTOINIT
195         Valid values    : '-a' or ''
196         
197         Option for AFSCREDS.EXE.  Enables automatic initialization.
198         (see below)
199
200     CREDSIPCHDET
201         Valid values    : '-n' or ''
202
203         Option for AFSCREDS.EXE.  Enables IP address change detection.
204         (see below)
205
206     CREDSQUIET
207         Valid values    : '-q' or ''
208
209         Option for AFSCREDS.EXE.  Enables quiet mode.
210         (see below)
211
212     CREDSRENEWDRMAP
213         Valid values    : '-m' or ''
214
215         Option for AFSCREDS.EXE.  Enables renewing drive map at
216         startup.
217         (see below)
218
219     CREDSSHOW
220         Valid values    : '-s' or ''
221
222         Option for AFSCREDS.EXE.  Enables displaying the credential
223         manager window when AFSCREDS starts up.
224
225         The five properties above determine the behavior of the AFS
226         credential manager ( AFSCREDS.EXE ).  Each property adds a
227         command line option to the shortcut that will be created in
228         the Program Menu, both under 'OpenAFS' and 'Startup' folders
229         (see CREDSSTARTUP).
230
231         The way in which the options are specified was chosen for easy
232         integration with the Windows Installer user interface.
233         Although you can come up with creative ways to provide other
234         options to AFSCREDS.EXE, we advise against it because such
235         transforms may not apply to future releases of OpenAFS.
236
237     CREDSSTARTUP
238         Valid values    : '1' or '0'
239
240         Controls whether AFSCREDS.EXE starts up automatically when a
241         user logs on.  When CREDSSTARTUP is '1' a shortcut is added
242         to the 'Startup' folder in the 'Program menu' which starts
243         AFSCREDS.EXE with the options that are determined by the
244         other CREDS* properties.
245
246     FREELANCEMODE
247
248         Registry key    : (Service parameters)
249         Registry value  : FreelanceClient
250         Valid values    : '1' or '0'
251
252     HIDEDOTFILES
253
254         Registry key    : (Service parameters)
255         Registry value  : HideDotFiles
256         Valid values    : '1' or '0'
257
258     LOGONOPTIONS
259
260         Registry key    : (Network provider)
261         Registry value  : LogonOptions
262         Valid values    : '0','1' or '3'
263
264         See section 2.1 of registry.txt (Domain specific configuration
265         keys for Network Provider) and section [filler] of this
266         document (filler) for more details.
267
268     MOUNTROOT
269
270         Registry key    : (Service parameters)
271         Registry value  : Mountroot
272         Valid values    : string
273
274     NETBIOSNAME
275
276         Registry key    : (Service parameters)
277         Registry value  : NetbiosName
278         Valid values    : string (at most 15 characters)
279
280     NOFINDLANABYNAME
281
282         Registry key    : (Service parameters)
283         Registry value  : NoFindLanaByName
284         Valid values    : '1' or '0'
285
286     RXMAXMTU
287
288         Registry key    : (Service parameters)
289         Registry value  : RxMaxMTU
290         Valid values    : numeric
291
292     SECURITYLEVEL
293
294         Registry key    : (Service parameters)
295         Registry value  : SecurityLevel
296         Valid values    : '1' or '0'
297
298     SMBAUTHTYPE
299
300         Registry key    : (Service parameters)
301         Registry value  : SMBAuthType
302         Valid values    : '0','1' or '2'
303
304     STOREANSIFILENAMES
305
306         Registry key    : (OpenAFS Client)
307         Registry value  : StoreAnsiFilenames
308         Valid values    : '0' or '1'
309
310     USEDNS
311
312         Registry key    : (Service parameters)
313         Registry value  : UseDNS
314         Valid values    : '1' or '0'
315
316
317 2.2 Existing Registry Entries
318
319     You can change existing registry values subject to the
320     restrictions mentioned in the Windows Platform SDK.  Pay special
321     attention to component keypaths and try to only change the 'Value'
322     column in the 'Registry' table.  If you want to add additional
323     registry keys please refer to section 3 (Additional Resources).
324
325 2.3 Replacing Configuration Files
326
327     The OpenAFS configuration files (CellServDB)
328     can be replaced by your own configuration files.  These files are
329     contained in separate MSI components so that you can disable them
330     individually.
331
332     The recommended method for replacing these files is to first
333     disable the components containing the configuration files that you
334     want to replace, and then add new components for the replacement
335     files.  This is outlined below (assuming you are using ORCA.EXE to
336     author the transform).
337
338     Note that transforms are not a good way to add a new file as an
339     embedded stream.  The method outlined here places the file in the
340     same directory as the MSI for deployment.
341
342     The walkthrough below is to add a custom 'CellServDB' file.
343
344     1) Disable the component that contains the configuration file that
345        you want to replace.
346
347        1.1) Locate and select the 'Component' table in the 'Tables'
348             list.
349
350        1.2) In the Component table, locate the component you need to
351             change ( Ctrl-F invokes the 'Find' dialog).  The component
352             names are listed below in section 2.3.1.  For this
353             example, the component name is 'elf_CellServDB'.
354
355        1.3) Go to the 'Condition' column of the component.
356
357        1.4) Enter a condition that evaluates to
358             false. I.e. 'DONOTINSTALL'. (Note that an undefined
359             property always evaluates to false).
360
361        Note that you can also use this step to disable other
362        configuration files without providing replacements.
363
364     2) Add a new component containing the new configuration file.
365
366        2.1) Select the 'Component' table in the 'Tables' list.
367
368        2.2) Select 'Tables'->'Add Row' (Ctrl-R).
369
370        2.3) Enter the following :
371
372             Component     : cmf_my_CellServDB
373             ComponentId   : {7019836F-BB2C-4AF6-9463-0D6EC9035CF1}
374             Directory_    : dirClient
375             Attributes    : 144
376             Condition     :
377             KeyPath       : fil_my_CellServDB
378
379             Note that the ComponentId is an uppercase GUID.  You can
380             generate one using GUIDGEN.EXE or UUIDGEN.EXE, both of
381             which are included in the Platform SDK.
382
383             The Attributes value of 144 is a sum of
384             msidbComponentAttributesPermanent (16) and
385             msidbComponentAttributesNeverOverwrite (128).  This
386             ensures that local modifications are not overwritten or
387             lost during an installation or uninstallation.  These are
388             the same settings used on the default configuration files.
389
390             'fil_my_CellServDB' is a key into the 'File' table which we
391             will fill later.
392
393     3) Add a new feature to hold the new component.
394
395        3.1) Select the 'Feature' table.
396
397        3.2) Add a new row (Ctrl-R or 'Tables'->'Add Row') with the
398             following values:
399
400             Feature       : fea_my_CellServDB
401             Feature_Parent: feaClient
402             Title         :
403             Description   :
404             Display       : 0
405             Level         : 30
406             Directory_    :
407             Attributes    : 8
408
409             It is important to create the new feature under the
410             'feaClient' feature, which will ensure that the
411             configuration file will be installed when the client
412             binaries are installed.
413
414             Setting 'Display' to 0 will hide this feature from the
415             feature selection dialog during an interactive
416             installation.  A value of 30 for 'Level' allows this
417             feature to be installed by default (on a 'Typical'
418             installation).
419
420             The 'Attributes' value is
421             msidbFeatureAttributesDisallowAdvertise (8), which is set
422             on all features in the OpenAFS MSI.  The OpenAFS MSI is not
423             designed for an advertised installation.
424
425     4) Join the component and the feature.
426
427        4.1) Select the 'FeatureComponents' table.
428
429        4.2) Add a new row with the following values:
430
431             Feature    : fea_my_CellServDB
432             Component  : cmf_my_CellServDB
433
434     5) Add an entry to the 'File' table.
435
436        5.1) Select the 'File' table.
437
438        5.2) Add a new row with the following values:
439
440             File        : fil_my_CellServDB
441             Component_  : cmf_my_CellServDB
442             FileName    : CellServDB
443             FileSize    : (enter file size here)
444             ...
445             Attributes  : 8192
446             Sequence    : 1000
447             (leave other fields blank)
448
449             The 'Attributes' value is msidbFileAttributesNonCompressed
450             (8192).  This is because we will be placing this file in
451             the same directory as the MSI instead of embedding the
452             file in it.  Transforms do not support updating compressed
453             sources or adding new cabinet streams.
454
455             Finally, the 'Sequence' value of 1000 will be used later
456             to distinguish the file as being in a separate source
457             location than the other files in the MSI.
458
459     6) Set a media source for the file.
460
461        6.1) Select the 'Media' table.
462
463        6.2) Add a row with the following values :
464
465             DiskId       : 2
466             LastSequence : 1000
467             ...
468             (leave other fields blank)
469
470             The sequence number of 1000 designates this as the media
471             source for the newly added file.
472
473 2.3.1 Components for Configuration Files
474
475       CellServDB : 'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})
476
477 2.4 Adding Domain Specific Registry Keys
478
479     Following is an example for adding domain specific registry keys.
480     Refer to section 2.1 in REGISTRY.TXT for more information.
481
482     Columns that are unspecified should be left empty.
483
484     We create a new feature and component to hold the new registry keys.
485
486     'Feature' table:
487
488     (new row)
489         Feature         : 'feaDomainKeys'
490         Feature Parent  : 'feaClient'
491         Display         : 0
492         Level           : 30
493         Attributes      : 10
494
495     'Component' table:
496
497         (new row)
498     Component   : 'rcm_DomainKeys'
499         ComponentId     : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
500         Directory       : 'TARGETDIR'
501         Attributes      : 4
502         KeyPath         : 'reg_domkey0'
503
504     'FeatureComponents' table:
505
506     (new row)
507         Feature         : 'feaDomainKeys'
508         Component       : 'rcm_DomainKeys'
509
510     'Registry' table:
511
512         (new row)
513         Registry        : 'reg_domkey0'
514         Root            : 2
515         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
516         Component       : 'rcm_DomainKeys'
517
518         (new row)
519         Registry        : 'reg_domkey1'
520         Root            : 2
521         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
522         Name            : '*'
523         Component       : 'rcm_DomainKeys'
524
525         (new row)
526         Registry        : 'reg_domkey2'
527         Root            : 2
528         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
529         Name            : '*'
530         Component       : 'rcm_DomainKeys'
531
532         (new row)
533         Registry        : 'reg_domkey3'
534         Root            : 2
535         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
536         Name            : 'LogonOptions'
537         Value           : 1
538         Component       : 'rcm_DomainKeys'
539
540         (new row)
541         Registry        : 'reg_domkey4'
542         Root            : 2
543         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
544         Name            : '*'
545         Component       : 'rcm_DomainKeys'
546
547         (new row)
548         Registry        : 'reg_domkey5'
549         Root            : 2
550         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
551         Name            : 'LogonOptions'
552         Value           : 0
553         Component       : 'rcm_DomainKeys'
554
555         (new row)
556         Registry        : 'reg_domkey6'
557         Root            : 2
558         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
559         Name            : 'FailLoginsSilently'
560         Value           : 1
561         Component       : 'rcm_DomainKeys'
562
563     The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable
564     integrated logon) and 'LOCALHOST' (disable integrated logon and
565     fail logins silently).
566
567 ----------------------------------------------------------------------
568
569 3   Additional Resources
570
571     If you want to add registry keys or files you need to create new
572     components and features for those.  Refer to the Windows Platform
573     SDK for details.
574
575     It is beyond the scope of this document to provide a comprehensive
576     overview of how to add new resources through a transform.  Please
577     refer to the "Windows Installer" documentation for details.  The
578     relevant section is at :
579
580     http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp
581
582     A sample walkthrough of adding a new configuration file is in
583     section 2.3.
584
585     Add new features under the 'feaClient' or 'feaServer' as
586     appropriate and set the 'Level' column for those features to equal
587     the 'Level' for their parent features for consistency.  Note that
588     none of the features in the OpenAFS for Windows MSI package are
589     designed to be installed to run from 'source' or 'advertised'.  It
590     is recommended that you set 'msidbFeatureAttributesFavorLocal' (0),
591     'msidbFeatureAttributesFollowParent' (2) and
592     'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
593     features.
594
595     If you are creating new components, retain the same component GUID
596     when creating new transforms against new releases of the OpenAFS
597     MSI package.
598
599     After making the adjustments to the MSI database using ORCA.EXE
600     you can generate a transform with MSITRAN.EXE as follows :
601
602     (Modified MSI package is 'openafs-en_US_new.msi' and the original
603     MSI package is 'openafs-en_US.msi'.  Generates transform
604     'openafs-transform.mst')
605
606     > msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst glpruw
607
608     See the Platform SDK documentation for information on command line
609     options for MSITRAN.EXE.
610
611 ----------------------------------------------------------------------
612
613 4.  Upgrades
614
615     The MSI package is designed to uninstall previous versions of
616     OpenAFS for Windows during installation.  Note that it doesn't
617     directly upgrade an existing installation.  This is intentional
618     and ensures that development releases which do not have strictly
619     increasing version numbers are properly upgraded.
620
621     Versions of OpenAFS that are upgraded by the MSI package are :
622
623     1) OpenAFS MSI package
624        Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
625        Upto current release
626
627     2) MIT's Transarc AFS MSI package
628        Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
629        Upto version 3.6.2
630
631     3) OpenAFS NSIS package
632        All versions
633
634        Note that versions of the OpenAFS NSIS package prior to 1.3.65
635        had a bug where it couldn't be uninstalled properly in
636        unattended mode.  Therefore the MSI package will not try to
637        uninstall an OpenAFS NSIS package if running unattended.  This
638        means that group policy based deployments will fail on machines
639        that have the OpenAFS NSIS package installed.
640
641     If you have used a different MSI package to install OpenAFS and
642     wish to upgrade it you can author rows into the 'Upgrade' table as
643     described in the Platform SDK.
644
645 ----------------------------------------------------------------------
646
647 5.  FAQ
648
649     (Q/A's will be added here as needed)
650
651 ----------------------------------------------------------------------
652 $Id$