
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 $
