--- /dev/null
+
+OpenAFS for Windows
+ MSI Deployment Guide
+----------------------------------------------------------------------
+
+ Contents
+
+ 1. Introduction
+ 1.1 Requirements
+
+ 2. Configuration options
+ 2.1 Configurable properties
+ 2.2 Existing registry values
+
+ 3. Additional resources
+ 3.1 Example
+
+ 4. Upgrades
+
+ 5. FAQ
+
+
+----------------------------------------------------------------------
+
+1. Introduction
+
+ Beginning with OpenAFS for Windows version 1.3.65 a MSI installer
+ option is available for those who wish to use Windows
+ Installer for installing OpenAFS and for organizations that wish
+ 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.
+
+1.1 Requirements
+
+ The information in this document applies to MSI packages
+ distributed with OpenAFS for Windows releases from 1.3.65 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.
+
+ The schema for the MSI package is based on SCHEMA.MSI distributed
+ with the Platform SDK.
+
+----------------------------------------------------------------------
+
+2. Configuration Options
+
+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.
+
+ These properties are, of course, found in the 'Property' table of
+ the MSI package.
+
+ For brevity the following nomenclature will be used to refer to
+ registry keys:
+
+ 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.
+
+ (Service parameters):
+ [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
+
+ (Network provider):
+ [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
+
+ The configurable properties are as follows:
+
+ AFSCELLNAME
+
+ Registry key : (Service parameters)
+ Registry value : Cell
+ Valid values : string
+
+ CREDSAUTOINIT
+ Valid values : '-a' or ''
+
+ Option for AFSCREDS.EXE. Enables automatic initialization.
+ (see below)
+
+ CREDSIPCHDET
+ Valid values : '-n' or ''
+
+ Option for AFSCREDS.EXE. Enables IP address change detection.
+ (see below)
+
+ CREDSQUIET
+ Valid values : '-q' or ''
+
+ Option for AFSCREDS.EXE. Enables quiet mode.
+ (see below)
+
+ CREDSRENEWDRMAP
+ Valid values : '-m' or ''
+
+ Option for AFSCREDS.EXE. Enables renewing drive map at
+ startup.
+
+ The four 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 way in which the options are specified was chosen for easy
+ integration with the Windows Installer user interface.
+ Although you can come up with creative ways to provide other
+ options to AFSCREDS.EXE, we advise against it because such
+ transforms may not apply to future releases of OpenAFS.
+
+ FREELANCEMODE
+
+ Registry key : (Service parameters)
+ Registry value : FreelanceClient
+ Valid values : '1' or '0'
+
+ HIDEDOTFILES
+
+ Registry key : (Service parameters)
+ Registry value : HideDotFiles
+ Valid values : '1' or '0'
+
+ LOGONOPTIONS
+
+ Registry key : (Network provider)
+ Registry value : LogonOptions
+ Valid values : '0','1' or '3'
+
+ See section 2.1 of registry.txt (Domain specific configuration
+ keys for Network Provider) and section [filler] of this
+ document (filler) for more details.
+
+ MOUNTROOT
+
+ Registry key : (Service parameters)
+ Registry value : Mountroot
+ Valid values : string
+
+ NETBIOSNAME
+
+ Registry key : (Service parameters)
+ Registry value : NetbiosName
+ Valid values : string (at most 15 characters)
+
+ NOFINDLANABYNAME
+
+ Registry key : (Service parameters)
+ Registry value : NoFindLanaByName
+ Valid values : '1' or '0'
+
+ RXMAXMTU
+
+ Registry key : (Service parameters)
+ Registry value : RxMaxMTU
+ Valid values : numeric
+
+ SECURITYLEVEL
+
+ Registry key : (Service parameters)
+ Registry value : SecurityLevel
+ Valid values : '1' or '0'
+
+ SMBAUTHTYPE
+
+ Registry key : (Service parameters)
+ Registry value : SMBAuthType
+ Valid values : '0','1' or '2'
+
+ USEDNS
+
+ Registry key : (Service parameters)
+ Registry value : UseDNS
+ Valid values : '1' or '0'
+
+
+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. Refer to the Windows Platform
+ SDK for details.
+
+ 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.
+
+3.1 Example: 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.
+
+ Columns that are unspecified should be left empty.
+
+ We create a new feature and component to hold the new registry keys.
+
+ 'Feature' table:
+
+ (new row)
+ Feature : 'feaDomainKeys'
+ Feature Parent : 'feaClient'
+ Display : 0
+ Level : 30
+ Attributes : 10
+
+ 'Component' table:
+
+ (new row)
+ Component : 'rcm_DomainKeys'
+ ComponentId : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
+ Directory : 'TARGETDIR'
+ Attributes : 4
+ KeyPath : 'reg_domkey0'
+
+ 'FeatureComponents' table:
+
+ (new row)
+ Feature : 'feaDomainKeys'
+ Component : 'rcm_DomainKeys'
+
+ 'Registry' table:
+
+ (new row)
+ Registry : 'reg_domkey0'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey1'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
+ Name : '*'
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey2'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
+ Name : '*'
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey3'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
+ Name : 'LogonOptions'
+ Value : 1
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey4'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+ Name : '*'
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey5'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+ Name : 'LogonOptions'
+ Value : 0
+ Component : 'rcm_DomainKeys'
+
+ (new row)
+ Registry : 'reg_domkey6'
+ Root : 2
+ Key : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
+ Name : 'FailLoginsSilently'
+ Value : 1
+ Component : 'rcm_DomainKeys'
+
+ The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable
+ integrated logon) and 'LOCALHOST' (disable integrated logon and
+ fail logins silently).
+
+ After making the adjustments to the MSI database using ORCA.EXE
+ you can generate a transform with MSITRAN.EXE as follows :
+
+ (Modified MSI package is 'openafs-en_US_new.msi' and the original
+ MSI package is 'openafs-en_US.msi'. Generates transform
+ 'openafs-transform.mst')
+
+ > msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst glpruw
+
+ See the Platform SDK documentation for information on command line
+ options for MSITRAN.EXE.
+
+----------------------------------------------------------------------
+
+4. Upgrades
+
+ The MSI package is designed to uninstall previous versions of
+ OpenAFS 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 OpenAFS that are upgraded by the MSI package are :
+
+ 1) OpenAFS MSI package
+ Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
+ Upto current release
+
+ 2) MIT's Transarc AFS MSI package
+ Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
+ Upto version 3.6.2
+
+ 3) OpenAFS NSIS package
+ All versions
+
+ Note that versions of the OpenAFS NSIS package prior to 1.3.65
+ had a bug where it couldn't be uninstalled properly in
+ unattended mode. Therefore the MSI package will not try to
+ uninstall an OpenAFS NSIS package if running unattended. This
+ means that group policy based deployments will fail on machines
+ that have the OpenAFS NSIS package installed.
+
+ If you have used a different MSI package to install OpenAFS and
+ wish to upgrade it you can author rows into the 'Upgrade' table as
+ described in the Platform SDK.
+
+----------------------------------------------------------------------
+
+5. FAQ
+
+ (Q/A's will be added here as needed)
+
+----------------------------------------------------------------------
+$Id$
git://git.openafs.org / openafs.git / commitdiff