From 22fbf94fcd6a3be86f197b26ffdcd5891fd91906 Mon Sep 17 00:00:00 2001
From: Asanka Herath <asanka@mit.edu>
Date: Tue, 27 Jul 2004 14:32:38 +0000
Subject: [PATCH] msi-deployment-guide-20040727

a guide to making organization specific modifications to the msi
installer
---
 doc/txt/winnotes/msi-deployment-guide.txt | 367 ++++++++++++++++++++++
 1 file changed, 367 insertions(+)
 create mode 100644 doc/txt/winnotes/msi-deployment-guide.txt

diff --git a/doc/txt/winnotes/msi-deployment-guide.txt b/doc/txt/winnotes/msi-deployment-guide.txt
new file mode 100644
index 000000000..7bdfb3bba
--- /dev/null
+++ b/doc/txt/winnotes/msi-deployment-guide.txt
@@ -0,0 +1,367 @@
+
+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$
-- 
2.39.5