OpenAFS for Windows
                         MSI Deployment Guide
----------------------------------------------------------------------

     Contents

     1.  Introduction
     1.1   Requirements

     2.	 Configuration options
     2.1   Configurable properties
     2.2   Existing registry values
     2.3   Replacing Configuration Files
     2.4   Adding Domain Specific Registry Keys
     2.5   Adding Site Specific Freelance Registry Keys

     3.	 Additional resources

     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.

    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.msi openafs-modified.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.  Please refer to the release notes for more information
    about how these registry settings are used.

    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.

    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.

    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)
	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'

    STOREANSIFILENAMES

	Registry key	: (OpenAFS Client)
	Registry value	: StoreAnsiFilenames
	Valid values	: '0' or '1'

    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).

2.3 Replacing Configuration Files

    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.

    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).

    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.

    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).

       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.

    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).

2.5 Adding Site Specific Freelance Registry Keys

    Following is an example for adding site specific Freelance registry keys
    to pre-populate the Mountpoints and Symlinks in the fake root.afs volume.

    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		: 'feaFreelanceKeys'
	Feature Parent	: 'feaClient'
	Display		: 0
	Level		: 30
	Attributes	: 10

    'Component' table:

	(new row)
    Component	: 'rcm_FreelanceKeys'
	ComponentId	: '{4E3B3CBF4-9AE7-40C3-7B09-C48CF842C583}'
	Directory	: 'TARGETDIR'
	Attributes	: 4
	KeyPath		: 'reg_freekey0'

    'FeatureComponents' table:

    (new row)
	Feature		: 'feaFreelanceKeys'
	Component	: 'rcm_FreelanceKeys'

    'Registry' table:

	(new row)
	Registry	: 'reg_freekey0'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance'
	Component	: 'rcm_FreelanceKeys'

	(new row)
	Registry	: 'reg_freekey1'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance'
	Name		: '0'
        Value           : 'athena.mit.edu#athena.mit.edu:root.cell.'
	Component	: 'rcm_FreelanceKeys'

	(new row)
	Registry	: 'reg_freekey2'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance'
	Name		: '1'
        Value           : '.athena.mit.edu%athena.mit.edu:root.cell.'
	Component	: 'rcm_FreelanceKeys'

	(new row)
	Registry	: 'reg_freekey3'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
	Component	: 'rcm_FreelanceKeys'

	(new row)
	Registry	: 'reg_freekey4'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
	Name		: '0'
        Value           : 'athena:athena.mit.edu.'
	Component	: 'rcm_FreelanceKeys'

	(new row)
	Registry	: 'reg_freekey5'
	Root		: 2
	Key		: 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'
	Name		: '1'
        Value           : '.athena:.athena.mit.edu.'
	Component	: 'rcm_FreelanceKeys'

    The example adds a read-only mountpoint to the athena.mit.edu
    cell's root.afs volume as well as a read-write mountpoint.  Aliases
    are also provided using symlinks.

----------------------------------------------------------------------

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 :

    (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

    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.

    When performing an upgrade with msiexec.exe execute the MSI with
    the repair options "vomus".

----------------------------------------------------------------------

5.  FAQ

    (Q/A's will be added here as needed)

----------------------------------------------------------------------
$Id: msi-deployment-guide.txt,v 1.7 2005/06/17 16:07:59 jaltman Exp $