4 ----------------------------------------------------------------------
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 2.5 Adding Site Specific Freelance Registry Keys
18 3. Additional resources
25 ----------------------------------------------------------------------
29 Beginning with OpenAFS for Windows version 1.3.65 a MSI installer
30 option is available for those who wish to use Windows
31 Installer for installing OpenAFS and for organizations that wish
32 to deploy OpenAFS through Group Policy.
34 This document provides a guide for authoring transforms used to
35 customize the MSI package for a particular organization. Although
36 many settings can be deployed via transforms, in an Active
37 Directory environment it is advisable to deploy registry settings
38 and configuration files through group policy and/or startup
39 scripts so that machines where OpenAFS for Windows is already
40 installed will pick up these customizations.
44 The information in this document applies to MSI packages
45 distributed with OpenAFS for Windows releases from 1.3.65 and
46 onwards or MSI packages built from corresponding source
47 releases. Not all releases support all the configuration options
50 Authoring a "Windows Installer" transform requires additional
51 software for editing the MSI database tables and generating the
52 transform from the modified MSI package. ORCA.EXE and MSITRAN.EXE
53 which are included in the Windows Platform SDK ("Windows Installer"
54 SDK) can be used for this purpose.
56 For reference, the schema for the MSI package is based on
57 SCHEMA.MSI distributed with the Platform SDK.
59 For general information about "Windows Installer", refer to :
61 http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp
63 For general information about authoring MSI transforms, refer to :
65 http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp
67 The remainder of this document assumes some familiarity with
68 authoring transforms. While the MSDN documentation for Windows
69 Installer is a bit dense, it is recommended that you read through
70 the guide on MSI transforms found at the second link above. Also
71 MSDN includes a step-by-step example for creating a transform at:
73 http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp
75 1.2 Authoring a Transform
77 Transforms describe a set of modifications to be performed on an
78 existing MSI for the purpose of customizing it. This is
79 ordinarily done by making a copy of the MSI to be customized,
80 modifying the copy and then using the old and the new MSI to
84 > copy openafs.msi openafs-modified.msi
86 (edit the openafs-modified.msi to include the necessary changes)
88 > msitran -g openafs-modified.msi openafs.msi openafs-transform.mst
90 (generates openafs-transform.mst, which is the transform)
92 Transforms have an extension of .mst. 'msitran' is a tool
93 distributed as part of the "Windows Installer" SDK (which in turn is
94 a part of the Windows Platform SDK).
96 You can test a transform by :
98 > copy openafs.msi openafs-test.msi
99 > msitran -a openafs-transform.mst openafs-test.msi
101 and then checking the resulting openafs-test.msi to see if all the
102 changes you have made above to openafs-modified.msi is present in
103 openafs-test.msi. 'msitran' will complain if some modification in the
104 transform can not be successfully applied.
106 As mentioned above, you can use a tool like ORCA.EXE to edit the
107 MSI databases directly when editing openafs-modified.msi. More
108 details are given below.
110 ----------------------------------------------------------------------
112 2. Configuration Options
114 The logic necessary to implement many of the settings described in
115 the registry.txt file are present in the MSI. Most of these can be
116 controlled by setting the corresponding properties to the desired
117 value. Some settings may require modifying existing registry
118 entries (though not recommended) or adding new resources (like
119 files or registry keys). Instructions for performing these tasks
122 2.1 Configurable Properties
124 Most configurable properties correspond to registry keys or
125 values. Please refer to the release notes for more information
126 about how these registry settings are used.
128 Due to the logic invoked based on the existence of these registry
129 keys or values, they are only set if the associated property is
130 defined to have a non null value. If the associated property is
131 not defined in the MSI, the registry key or value will not be
132 touched. By default, the MSI does not contain these properties
133 and hence will not set the registry keys. You will need to add
134 properties as needed to the MSI.
136 When one of the configurable properties is set, the installer will
137 use the property value to set the corresponding setting in the
138 HKEY_LOCAL_MACHINE registry hive. HKEY_CURRENT_USER hive is not
139 touched by the installer.
141 For each property, the associated registry setting is referenced
142 by the same text used in the registry.txt file.
144 Strings are quoted using single quotes (e.g. 'a string'). An empty
145 string is denoted as ''. Note that you can't author null values
146 into the 'Property' table.
148 Numeric values should be authored as decimal strings.
150 2.1.1 Setting Properties
152 In order to set a property,
154 a. Open the MSI in ORCA.EXE
156 b. Select the 'Property' table from the list of tables on the left.
158 c. Find the property in the list of properties on the right,
159 double click the value and type the new value.
161 d. If the property does not exist in the property list, right
162 click the list and select 'Add Row', type the property name
163 and the desired value.
166 2.1.2 OpenAFS for Windows properties
168 (Service parameters):
169 [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
172 [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
175 [HKLM\SOFTWARE\OpenAFS\Client]
177 The configurable properties are as follows:
180 Registry key : (Service parameters)
181 Registry value : CachePath
182 Valid values : string
185 Registry key : (Service parameters)
186 Registry value : CacheSize
187 Valid values : numeric
191 Registry key : (Service parameters)
192 Registry value : Cell
193 Valid values : string
196 Valid values : '-a' or ''
198 Option for AFSCREDS.EXE. Enables automatic initialization.
202 Valid values : '-n' or ''
204 Option for AFSCREDS.EXE. Enables IP address change detection.
208 Valid values : '-q' or ''
210 Option for AFSCREDS.EXE. Enables quiet mode.
214 Valid values : '-m' or ''
216 Option for AFSCREDS.EXE. Enables renewing drive map at
221 Valid values : '-s' or ''
223 Option for AFSCREDS.EXE. Enables displaying the credential
224 manager window when AFSCREDS starts up.
226 The five properties above determine the behavior of the AFS
227 credential manager ( AFSCREDS.EXE ). Each property adds a
228 command line option to the shortcut that will be created in
229 the Program Menu, both under 'OpenAFS' and 'Startup' folders
232 The way in which the options are specified was chosen for easy
233 integration with the Windows Installer user interface.
234 Although you can come up with creative ways to provide other
235 options to AFSCREDS.EXE, we advise against it because such
236 transforms may not apply to future releases of OpenAFS.
239 Valid values : '1' or '0'
241 Controls whether AFSCREDS.EXE starts up automatically when a
242 user logs on. When CREDSSTARTUP is '1' a shortcut is added
243 to the 'Startup' folder in the 'Program menu' which starts
244 AFSCREDS.EXE with the options that are determined by the
245 other CREDS* properties.
249 Registry key : (Service parameters)
250 Registry value : FreelanceClient
251 Valid values : '1' or '0'
255 Registry key : (Service parameters)
256 Registry value : HideDotFiles
257 Valid values : '1' or '0'
261 Registry key : (Network provider)
262 Registry value : LogonOptions
263 Valid values : '0','1' or '3'
265 See section 2.1 of registry.txt (Domain specific configuration
266 keys for Network Provider) and section [filler] of this
267 document (filler) for more details.
271 Registry key : (Service parameters)
272 Registry value : Mountroot
273 Valid values : string
277 Registry key : (Service parameters)
278 Registry value : NetbiosName
279 Valid values : string (at most 15 characters)
283 Registry key : (Service parameters)
284 Registry value : NoFindLanaByName
285 Valid values : '1' or '0'
289 Registry key : (Service parameters)
290 Registry value : RxMaxMTU
291 Valid values : numeric
295 Registry key : (Service parameters)
296 Registry value : SecurityLevel
297 Valid values : '1' or '0'
301 Registry key : (Service parameters)
302 Registry value : SMBAuthType
303 Valid values : '0','1' or '2'
307 Registry key : (OpenAFS Client)
308 Registry value : StoreAnsiFilenames
309 Valid values : '0' or '1'
313 Registry key : (Service parameters)
314 Registry value : UseDNS
315 Valid values : '1' or '0'
318 2.2 Existing Registry Entries
320 You can change existing registry values subject to the
321 restrictions mentioned in the Windows Platform SDK. Pay special
322 attention to component keypaths and try to only change the 'Value'
323 column in the 'Registry' table. If you want to add additional
324 registry keys please refer to section 3 (Additional Resources).
326 2.3 Replacing Configuration Files
328 The OpenAFS configuration files (CellServDB)
329 can be replaced by your own configuration files. These files are
330 contained in separate MSI components so that you can disable them
333 The recommended method for replacing these files is to first
334 disable the components containing the configuration files that you
335 want to replace, and then add new components for the replacement
336 files. This is outlined below (assuming you are using ORCA.EXE to
337 author the transform).
339 Note that transforms are not a good way to add a new file as an
340 embedded stream. The method outlined here places the file in the
341 same directory as the MSI for deployment.
343 The walkthrough below is to add a custom 'CellServDB' file.
345 1) Disable the component that contains the configuration file that
348 1.1) Locate and select the 'Component' table in the 'Tables'
351 1.2) In the Component table, locate the component you need to
352 change ( Ctrl-F invokes the 'Find' dialog). The component
353 names are listed below in section 2.3.1. For this
354 example, the component name is 'elf_CellServDB'.
356 1.3) Go to the 'Condition' column of the component.
358 1.4) Enter a condition that evaluates to
359 false. I.e. 'DONOTINSTALL'. (Note that an undefined
360 property always evaluates to false).
362 Note that you can also use this step to disable other
363 configuration files without providing replacements.
365 2) Add a new component containing the new configuration file.
367 2.1) Select the 'Component' table in the 'Tables' list.
369 2.2) Select 'Tables'->'Add Row' (Ctrl-R).
371 2.3) Enter the following :
373 Component : cmf_my_CellServDB
374 ComponentId : {7019836F-BB2C-4AF6-9463-0D6EC9035CF1}
375 Directory_ : dirClient
378 KeyPath : fil_my_CellServDB
380 Note that the ComponentId is an uppercase GUID. You can
381 generate one using GUIDGEN.EXE or UUIDGEN.EXE, both of
382 which are included in the Platform SDK.
384 The Attributes value of 144 is a sum of
385 msidbComponentAttributesPermanent (16) and
386 msidbComponentAttributesNeverOverwrite (128). This
387 ensures that local modifications are not overwritten or
388 lost during an installation or uninstallation. These are
389 the same settings used on the default configuration files.
391 'fil_my_CellServDB' is a key into the 'File' table which we
394 3) Add a new feature to hold the new component.
396 3.1) Select the 'Feature' table.
398 3.2) Add a new row (Ctrl-R or 'Tables'->'Add Row') with the
401 Feature : fea_my_CellServDB
402 Feature_Parent: feaClient
410 It is important to create the new feature under the
411 'feaClient' feature, which will ensure that the
412 configuration file will be installed when the client
413 binaries are installed.
415 Setting 'Display' to 0 will hide this feature from the
416 feature selection dialog during an interactive
417 installation. A value of 30 for 'Level' allows this
418 feature to be installed by default (on a 'Typical'
421 The 'Attributes' value is
422 msidbFeatureAttributesDisallowAdvertise (8), which is set
423 on all features in the OpenAFS MSI. The OpenAFS MSI is not
424 designed for an advertised installation.
426 4) Join the component and the feature.
428 4.1) Select the 'FeatureComponents' table.
430 4.2) Add a new row with the following values:
432 Feature : fea_my_CellServDB
433 Component : cmf_my_CellServDB
435 5) Add an entry to the 'File' table.
437 5.1) Select the 'File' table.
439 5.2) Add a new row with the following values:
441 File : fil_my_CellServDB
442 Component_ : cmf_my_CellServDB
443 FileName : CellServDB
444 FileSize : (enter file size here)
448 (leave other fields blank)
450 The 'Attributes' value is msidbFileAttributesNonCompressed
451 (8192). This is because we will be placing this file in
452 the same directory as the MSI instead of embedding the
453 file in it. Transforms do not support updating compressed
454 sources or adding new cabinet streams.
456 Finally, the 'Sequence' value of 1000 will be used later
457 to distinguish the file as being in a separate source
458 location than the other files in the MSI.
460 6) Set a media source for the file.
462 6.1) Select the 'Media' table.
464 6.2) Add a row with the following values :
469 (leave other fields blank)
471 The sequence number of 1000 designates this as the media
472 source for the newly added file.
474 2.3.1 Components for Configuration Files
476 CellServDB : 'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})
478 2.4 Adding Domain Specific Registry Keys
480 Following is an example for adding domain specific registry keys.
481 Refer to section 2.1 in REGISTRY.TXT for more information.
483 Columns that are unspecified should be left empty.
485 We create a new feature and component to hold the new registry keys.
490 Feature : 'feaDomainKeys'
491 Feature Parent : 'feaClient'
499 Component : 'rcm_DomainKeys'
500 ComponentId : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
501 Directory : 'TARGETDIR'
503 KeyPath : 'reg_domkey0'
505 'FeatureComponents' table:
508 Feature : 'feaDomainKeys'
509 Component : 'rcm_DomainKeys'
514 Registry : 'reg_domkey0'
516 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
517 Component : 'rcm_DomainKeys'
520 Registry : 'reg_domkey1'
522 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
524 Component : 'rcm_DomainKeys'
527 Registry : 'reg_domkey2'
529 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
531 Component : 'rcm_DomainKeys'
534 Registry : 'reg_domkey3'
536 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
537 Name : 'LogonOptions'
539 Component : 'rcm_DomainKeys'
542 Registry : 'reg_domkey4'
544 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
546 Component : 'rcm_DomainKeys'
549 Registry : 'reg_domkey5'
551 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
552 Name : 'LogonOptions'
554 Component : 'rcm_DomainKeys'
557 Registry : 'reg_domkey6'
559 Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
560 Name : 'FailLoginsSilently'
562 Component : 'rcm_DomainKeys'
564 The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable
565 integrated logon) and 'LOCALHOST' (disable integrated logon and
566 fail logins silently).
568 2.5 Adding Site Specific Freelance Registry Keys
570 Following is an example for adding site specific Freelance registry keys
571 to pre-populate the Mountpoints and Symlinks in the fake root.afs volume.
573 Columns that are unspecified should be left empty.
575 We create a new feature and component to hold the new registry keys.
580 Feature : 'feaFreelanceKeys'
581 Feature Parent : 'feaClient'
589 Component : 'rcm_FreelanceKeys'
590 ComponentId : '{4E3B3CBF4-9AE7-40C3-7B09-C48CF842C583}'
591 Directory : 'TARGETDIR'
593 KeyPath : 'reg_freekey0'
595 'FeatureComponents' table:
598 Feature : 'feaFreelanceKeys'
599 Component : 'rcm_FreelanceKeys'
604 Registry : 'reg_freekey0'
606 Key : 'SOFTWARE\OpenAFS\Client\Freelance'
607 Component : 'rcm_FreelanceKeys'
610 Registry : 'reg_freekey1'
612 Key : 'SOFTWARE\OpenAFS\Client\Freelance'
614 Value : 'athena.mit.edu#athena.mit.edu:root.cell.'
615 Component : 'rcm_FreelanceKeys'
618 Registry : 'reg_freekey2'
620 Key : 'SOFTWARE\OpenAFS\Client\Freelance'
622 Value : '.athena.mit.edu%athena.mit.edu:root.cell.'
623 Component : 'rcm_FreelanceKeys'
626 Registry : 'reg_freekey3'
628 Key : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
629 Component : 'rcm_FreelanceKeys'
632 Registry : 'reg_freekey4'
634 Key : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
636 Value : 'athena:athena.mit.edu.'
637 Component : 'rcm_FreelanceKeys'
640 Registry : 'reg_freekey5'
642 Key : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
644 Value : '.athena:.athena.mit.edu.'
645 Component : 'rcm_FreelanceKeys'
647 The example adds a read-only mountpoint to the athena.mit.edu
648 cell's root.afs volume as well as a read-write mountpoint. Aliases
649 are also provided using symlinks.
651 ----------------------------------------------------------------------
653 3 Additional Resources
655 If you want to add registry keys or files you need to create new
656 components and features for those. Refer to the Windows Platform
659 It is beyond the scope of this document to provide a comprehensive
660 overview of how to add new resources through a transform. Please
661 refer to the "Windows Installer" documentation for details. The
662 relevant section is at :
664 http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp
666 A sample walkthrough of adding a new configuration file is in
669 Add new features under the 'feaClient' or 'feaServer' as
670 appropriate and set the 'Level' column for those features to equal
671 the 'Level' for their parent features for consistency. Note that
672 none of the features in the OpenAFS for Windows MSI package are
673 designed to be installed to run from 'source' or 'advertised'. It
674 is recommended that you set 'msidbFeatureAttributesFavorLocal' (0),
675 'msidbFeatureAttributesFollowParent' (2) and
676 'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
679 If you are creating new components, retain the same component GUID
680 when creating new transforms against new releases of the OpenAFS
683 After making the adjustments to the MSI database using ORCA.EXE
684 you can generate a transform with MSITRAN.EXE as follows :
686 (Modified MSI package is 'openafs-en_US_new.msi' and the original
687 MSI package is 'openafs-en_US.msi'. Generates transform
688 'openafs-transform.mst')
690 > msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst glpruw
692 See the Platform SDK documentation for information on command line
693 options for MSITRAN.EXE.
695 ----------------------------------------------------------------------
699 The MSI package is designed to uninstall previous versions of
700 OpenAFS for Windows during installation. Note that it doesn't
701 directly upgrade an existing installation. This is intentional
702 and ensures that development releases which do not have strictly
703 increasing version numbers are properly upgraded.
705 Versions of OpenAFS that are upgraded by the MSI package are :
707 1) OpenAFS MSI package
708 Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
711 2) MIT's Transarc AFS MSI package
712 Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
715 3) OpenAFS NSIS package
718 Note that versions of the OpenAFS NSIS package prior to 1.3.65
719 had a bug where it couldn't be uninstalled properly in
720 unattended mode. Therefore the MSI package will not try to
721 uninstall an OpenAFS NSIS package if running unattended. This
722 means that group policy based deployments will fail on machines
723 that have the OpenAFS NSIS package installed.
725 If you have used a different MSI package to install OpenAFS and
726 wish to upgrade it you can author rows into the 'Upgrade' table as
727 described in the Platform SDK.
729 When performing an upgrade with msiexec.exe execute the MSI with
730 the repair options "vomus".
732 ----------------------------------------------------------------------
736 (Q/A's will be added here as needed)
738 ----------------------------------------------------------------------