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$