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:
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)
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.
(see below)
CREDSSHOW
Valid values : '-s' or ''
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
(see CREDSSTARTUP).
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.
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 : 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: msi-deployment-guide.txt,v 1.2 2004/08/04 16:36:10 jaltman Exp $