Contents
1. Introduction
- 1.1 Requirements
+ 1.1 Requirements
2. Configuration options
- 2.1 Configurable properties
- 2.2 Existing registry values
+ 2.1 Configurable properties
+ 2.2 Existing registry values
+ 2.3 Replacing Configuration Files
+ 2.4 Adding Domain Specific Registry Keys
3. Additional resources
- 3.1 Example
4. Upgrades
to deploy OpenAFS 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 OpenAFS for Windows is
- already installed will pick up these customizations.
+ 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 OpenAFS for Windows is already
+ installed will pick up these customizations.
1.1 Requirements
releases. Not all releases support all the configuration options
documented here.
- Authoring a Windows Installer transform requires additional
+ 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
+ which are included in the Windows Platform SDK ("Windows Installer"
SDK) can be used for this purpose.
- The schema for the MSI package is based on SCHEMA.MSI distributed
- with the Platform SDK.
+ 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 openafs.msi openafs-modified.msi
+
+ (edit the openafs-modified.msi to include the necessary changes)
+
+ > msitran -g openafs-modified.msi openafs.msi openafs-transform.mst
+
+ (generates openafs-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 openafs.msi openafs-test.msi
+ > msitran -a openafs-transform.mst openafs-test.msi
+
+ and then checking the resulting openafs-test.msi to see if all the
+ changes you have made above to openafs-modified.msi is present in
+ openafs-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 openafs-modified.msi. More
+ details are given below.
----------------------------------------------------------------------
2. Configuration Options
+ The logic necessary to implement many of the settings described in
+ the registry.txt file 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.
- To avoid duplication, only a reference to the relevant registry key
- or value is given here. For more details about the associated
- semantics, please refer to registry.txt distributed with the
- OpenAFS for Windows release.
+ 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.
- These properties are, of course, found in the 'Property' table of
- the MSI package.
+ 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.
- For brevity the following nomenclature will be used to refer to
- registry keys:
+ 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 registry.txt file.
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. To achieve this effect you'll have to
- drop the relevant row.
+ 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 OpenAFS for Windows properties
(Service parameters):
[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
(Network provider):
[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
+ (OpenAFS Client):
+ [HKLM\SOFTWARE\OpenAFS\Client]
+
The configurable properties are as follows:
+ AFSCACHEPATH
+ Registry key : (Service parameters)
+ Registry value : CachePath
+ Valid values : string
+
+ AFSCACHESIZE
+ Registry key : (Service parameters)
+ Registry value : CacheSize
+ Valid values : numeric
+
AFSCELLNAME
Registry key : (Service parameters)
Option for AFSCREDS.EXE. Enables renewing drive map at
startup.
+ (see below)
+
+ CREDSSHOW
+ Valid values : '-s' or ''
- The four properties above determine the behavior of the AFS
+ Option for AFSCREDS.EXE. Enables displaying the credential
+ manager window when AFSCREDS starts up.
+
+ The five properties above determine the behavior of the AFS
credential manager ( AFSCREDS.EXE ). Each property adds a
command line option to the shortcut that will be created in
- the Program Menu (both under 'OpenAFS' and 'Startup' folders).
+ the Program Menu, both under 'OpenAFS' and 'Startup' folders
+ (see CREDSSTARTUP).
The way in which the options are specified was chosen for easy
integration with the Windows Installer user interface.
options to AFSCREDS.EXE, we advise against it because such
transforms may not apply to future releases of OpenAFS.
+ CREDSSTARTUP
+ Valid values : '1' or '0'
+
+ Controls whether AFSCREDS.EXE starts up automatically when a
+ user logs on. When CREDSSTARTUP is '1' a shortcut is added
+ to the 'Startup' folder in the 'Program menu' which starts
+ AFSCREDS.EXE with the options that are determined by the
+ other CREDS* properties.
+
FREELANCEMODE
Registry key : (Service parameters)
Registry value : SMBAuthType
Valid values : '0','1' or '2'
+ STOREANSIFILENAMES
+
+ Registry key : (OpenAFS Client)
+ Registry value : StoreAnsiFilenames
+ Valid values : '0' or '1'
+
USEDNS
Registry key : (Service parameters)
column in the 'Registry' table. If you want to add additional
registry keys please refer to section 3 (Additional Resources).
-----------------------------------------------------------------------
+2.3 Replacing Configuration Files
-3 Additional Resources
+ The OpenAFS configuration files (CellServDB)
+ can be replaced by your own configuration files. These files are
+ contained in separate MSI components so that you can disable them
+ individually.
- If you want to add registry keys or files you need to create new
- components and features for those. Refer to the Windows Platform
- SDK for details.
+ The recommended method for replacing these files is to first
+ disable the components containing the configuration files that you
+ want to replace, and then add new components for the replacement
+ files. This is outlined below (assuming you are using ORCA.EXE to
+ author the transform).
- Add new features under the 'feaClient' or 'feaServer' as
- appropriate 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 OpenAFS 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.
+ Note that transforms are not a good way to add a new file as an
+ embedded stream. The method outlined here places the file in the
+ same directory as the MSI for deployment.
- If you are creating new components, retain the same component GUID
- when creating new transforms against new releases of the OpenAFS
- MSI package.
+ The walkthrough below is to add a custom 'CellServDB' file.
+
+ 1) Disable the component that contains the configuration file that
+ you want to replace.
+
+ 1.1) Locate and select the 'Component' table in the 'Tables'
+ list.
+
+ 1.2) In the Component table, locate the component you need to
+ change ( Ctrl-F invokes the 'Find' dialog). The component
+ names are listed below in section 2.3.1. For this
+ example, the component name is 'elf_CellServDB'.
+
+ 1.3) Go to the 'Condition' column of the component.
+
+ 1.4) Enter a condition that evaluates to
+ false. I.e. 'DONOTINSTALL'. (Note that an undefined
+ property always evaluates to false).
-3.1 Example: Adding domain specific registry keys
+ Note that you can also use this step to disable other
+ configuration files without providing replacements.
+
+ 2) Add a new component containing the new configuration file.
+
+ 2.1) Select the 'Component' table in the 'Tables' list.
+
+ 2.2) Select 'Tables'->'Add Row' (Ctrl-R).
+
+ 2.3) Enter the following :
+
+ Component : cmf_my_CellServDB
+ ComponentId : {7019836F-BB2C-4AF6-9463-0D6EC9035CF1}
+ Directory_ : dirClient
+ Attributes : 144
+ Condition :
+ KeyPath : fil_my_CellServDB
+
+ Note that the ComponentId is an uppercase GUID. You can
+ generate one using GUIDGEN.EXE or UUIDGEN.EXE, both of
+ which are included in the Platform SDK.
+
+ The Attributes value of 144 is a sum of
+ msidbComponentAttributesPermanent (16) and
+ msidbComponentAttributesNeverOverwrite (128). This
+ ensures that local modifications are not overwritten or
+ lost during an installation or uninstallation. These are
+ the same settings used on the default configuration files.
+
+ 'fil_my_CellServDB' is a key into the 'File' table which we
+ will fill later.
+
+ 3) Add a new feature to hold the new component.
+
+ 3.1) Select the 'Feature' table.
+
+ 3.2) Add a new row (Ctrl-R or 'Tables'->'Add Row') with the
+ following values:
+
+ Feature : fea_my_CellServDB
+ Feature_Parent: feaClient
+ Title :
+ Description :
+ Display : 0
+ Level : 30
+ Directory_ :
+ Attributes : 8
+
+ It is important to create the new feature under the
+ 'feaClient' feature, which will ensure that the
+ configuration file will be installed when the client
+ binaries are installed.
+
+ Setting 'Display' to 0 will hide this feature from the
+ feature selection dialog during an interactive
+ installation. A value of 30 for 'Level' allows this
+ feature to be installed by default (on a 'Typical'
+ installation).
+
+ The 'Attributes' value is
+ msidbFeatureAttributesDisallowAdvertise (8), which is set
+ on all features in the OpenAFS MSI. The OpenAFS MSI is not
+ designed for an advertised installation.
+
+ 4) Join the component and the feature.
+
+ 4.1) Select the 'FeatureComponents' table.
+
+ 4.2) Add a new row with the following values:
+
+ Feature : fea_my_CellServDB
+ Component : cmf_my_CellServDB
+
+ 5) Add an entry to the 'File' table.
+
+ 5.1) Select the 'File' table.
+
+ 5.2) Add a new row with the following values:
+
+ File : fil_my_CellServDB
+ Component_ : cmf_my_CellServDB
+ FileName : CellServDB
+ FileSize : (enter file size here)
+ ...
+ Attributes : 8192
+ Sequence : 1000
+ (leave other fields blank)
+
+ The 'Attributes' value is msidbFileAttributesNonCompressed
+ (8192). This is because we will be placing this file in
+ the same directory as the MSI instead of embedding the
+ file in it. Transforms do not support updating compressed
+ sources or adding new cabinet streams.
+
+ Finally, the 'Sequence' value of 1000 will be used later
+ to distinguish the file as being in a separate source
+ location than the other files in the MSI.
+
+ 6) Set a media source for the file.
+
+ 6.1) Select the 'Media' table.
+
+ 6.2) Add a row with the following values :
+
+ DiskId : 2
+ LastSequence : 1000
+ ...
+ (leave other fields blank)
+
+ The sequence number of 1000 designates this as the media
+ source for the newly added file.
+
+2.3.1 Components for Configuration Files
+
+ CellServDB : 'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})
+
+2.4 Adding Domain Specific Registry Keys
Following is an example for adding domain specific registry keys.
Refer to section 2.1 in REGISTRY.TXT for more information.
integrated logon) and 'LOCALHOST' (disable integrated logon and
fail logins silently).
+----------------------------------------------------------------------
+
+3 Additional Resources
+
+ If you want to add registry keys or files you need to create new
+ components and features for those. Refer to the Windows Platform
+ SDK for details.
+
+ 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
+
+ A sample walkthrough of adding a new configuration file is in
+ section 2.3.
+
+ Add new features under the 'feaClient' or 'feaServer' as
+ appropriate 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 OpenAFS 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 OpenAFS
+ MSI package.
+
After making the adjustments to the MSI database using ORCA.EXE
you can generate a transform with MSITRAN.EXE as follows :
git://git.openafs.org / openafs.git / blobdiff