doc/txt/winnotes/msi-deployment-guide.txt

   1
   2 OpenAFS for Windows
   3                          MSI Deployment Guide
   4 ----------------------------------------------------------------------
   5
   6      Contents
   7
   8      1.  Introduction
   9      1.1 Requirements
  10
  11      2.  Configuration options
  12      2.1 Configurable properties
  13      2.2 Existing registry values
  14
  15      3.  Additional resources
  16      3.1 Example
  17
  18      4.  Upgrades
  19
  20      5.  FAQ
  21
  22
  23 ----------------------------------------------------------------------
  24
  25 1.  Introduction
  26
  27     Beginning with OpenAFS for Windows version 1.3.65 a MSI installer
  28     option is available for those who wish to use Windows
  29     Installer for installing OpenAFS and for organizations that wish
  30     to deploy OpenAFS through Group Policy.
  31
  32     This document provides a guide for authoring transforms used to
  33     customize the MSI package for a particular organization.
  34     Although many settings can be deployed via transforms, in an
  35     Active Directory environment it is advisable to deploy registry
  36     settings and configuration files through group policy and/or
  37     startup scripts so that machines where OpenAFS for Windows is
  38     already installed will pick up these customizations.
  39
  40 1.1 Requirements
  41
  42     The information in this document applies to MSI packages
  43     distributed with OpenAFS for Windows releases from 1.3.65 and
  44     onwards or MSI packages built from corresponding source
  45     releases. Not all releases support all the configuration options
  46     documented here.
  47
  48     Authoring a Windows Installer transform requires additional
  49     software for editing the MSI database tables and generating the
  50     transform from the modified MSI package.  ORCA.EXE and MSITRAN.EXE
  51     which are included in the Windows Platform SDK (Windows Installer
  52     SDK) can be used for this purpose.
  53
  54     The schema for the MSI package is based on SCHEMA.MSI distributed
  55     with the Platform SDK.
  56
  57 ----------------------------------------------------------------------
  58
  59 2.  Configuration Options
  60
  61 2.1 Configurable Properties
  62
  63     Most configurable properties correspond to registry keys or values.
  64     To avoid duplication, only a reference to the relevant registry key
  65     or value is given here.  For more details about the associated
  66     semantics, please refer to registry.txt distributed with the
  67     OpenAFS for Windows release.
  68
  69     These properties are, of course, found in the 'Property' table of
  70     the MSI package.
  71
  72     For brevity the following nomenclature will be used to refer to
  73     registry keys:
  74
  75     Strings are quoted using single quotes (e.g. 'a string'). An empty
  76     string is denoted as ''.  Note that you can't author null values
  77     into the 'Property' table.  To achieve this effect you'll have to
  78     drop the relevant row.
  79
  80     (Service parameters):
  81     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]
  82
  83     (Network provider):
  84     [HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]
  85
  86     The configurable properties are as follows:
  87
  88     AFSCACHEPATH
  89         Registry key    : (Service parameters)
  90         Registry value  : CachePath
  91         Valid values    : string
  92
  93     AFSCACHESIZE
  94         Registry key    : (Service parameters)
  95         Registry value  : CacheSize
  96         Valid values    : numeric
  97
  98     AFSCELLNAME
  99
 100         Registry key    : (Service parameters)
 101         Registry value  : Cell
 102         Valid values    : string
 103
 104     CREDSAUTOINIT
 105         Valid values    : '-a' or ''
 106
 107         Option for AFSCREDS.EXE.  Enables automatic initialization.
 108         (see below)
 109
 110     CREDSIPCHDET
 111         Valid values    : '-n' or ''
 112
 113         Option for AFSCREDS.EXE.  Enables IP address change detection.
 114         (see below)
 115
 116     CREDSQUIET
 117         Valid values    : '-q' or ''
 118
 119         Option for AFSCREDS.EXE.  Enables quiet mode.
 120         (see below)
 121
 122     CREDSRENEWDRMAP
 123         Valid values    : '-m' or ''
 124
 125         Option for AFSCREDS.EXE.  Enables renewing drive map at
 126         startup.
 127         (see below)
 128
 129     CREDSSHOW
 130         Valid values    : '-s' or ''
 131
 132         Option for AFSCREDS.EXE.  Enables displaying the credential
 133         manager window when AFSCREDS starts up.
 134
 135         The five properties above determine the behavior of the AFS
 136         credential manager ( AFSCREDS.EXE ).  Each property adds a
 137         command line option to the shortcut that will be created in
 138         the Program Menu, both under 'OpenAFS' and 'Startup' folders
 139         (see CREDSSTARTUP).
 140
 141         The way in which the options are specified was chosen for easy
 142         integration with the Windows Installer user interface.
 143         Although you can come up with creative ways to provide other
 144         options to AFSCREDS.EXE, we advise against it because such
 145         transforms may not apply to future releases of OpenAFS.
 146
 147     CREDSSTARTUP
 148         Valid values    : '1' or '0'
 149
 150         Controls whether AFSCREDS.EXE starts up automatically when a
 151         user logs on.  When CREDSSTARTUP is '1' a shortcut is added
 152         to the 'Startup' folder in the 'Program menu' which starts
 153         AFSCREDS.EXE with the options that are determined by the
 154         other CREDS* properties.
 155
 156     FREELANCEMODE
 157
 158         Registry key    : (Service parameters)
 159         Registry value  : FreelanceClient
 160         Valid values    : '1' or '0'
 161
 162     HIDEDOTFILES
 163
 164         Registry key    : (Service parameters)
 165         Registry value  : HideDotFiles
 166         Valid values    : '1' or '0'
 167
 168     LOGONOPTIONS
 169
 170         Registry key    : (Network provider)
 171         Registry value  : LogonOptions
 172         Valid values    : '0','1' or '3'
 173
 174         See section 2.1 of registry.txt (Domain specific configuration
 175         keys for Network Provider) and section [filler] of this
 176         document (filler) for more details.
 177
 178     MOUNTROOT
 179
 180         Registry key    : (Service parameters)
 181         Registry value  : Mountroot
 182         Valid values    : string
 183
 184     NETBIOSNAME
 185
 186         Registry key    : (Service parameters)
 187         Registry value  : NetbiosName
 188         Valid values    : string (at most 15 characters)
 189
 190     NOFINDLANABYNAME
 191
 192         Registry key    : (Service parameters)
 193         Registry value  : NoFindLanaByName
 194         Valid values    : '1' or '0'
 195
 196     RXMAXMTU
 197
 198         Registry key    : (Service parameters)
 199         Registry value  : RxMaxMTU
 200         Valid values    : numeric
 201
 202     SECURITYLEVEL
 203
 204         Registry key    : (Service parameters)
 205         Registry value  : SecurityLevel
 206         Valid values    : '1' or '0'
 207
 208     SMBAUTHTYPE
 209
 210         Registry key    : (Service parameters)
 211         Registry value  : SMBAuthType
 212         Valid values    : '0','1' or '2'
 213
 214     USEDNS
 215
 216         Registry key    : (Service parameters)
 217         Registry value  : UseDNS
 218         Valid values    : '1' or '0'
 219
 220
 221 2.2 Existing Registry Entries
 222
 223     You can change existing registry values subject to the
 224     restrictions mentioned in the Windows Platform SDK.  Pay special
 225     attention to component keypaths and try to only change the 'Value'
 226     column in the 'Registry' table.  If you want to add additional
 227     registry keys please refer to section 3 (Additional Resources).
 228
 229 ----------------------------------------------------------------------
 230
 231 3   Additional Resources
 232
 233     If you want to add registry keys or files you need to create new
 234     components and features for those.  Refer to the Windows Platform
 235     SDK for details.
 236
 237     Add new features under the 'feaClient' or 'feaServer' as
 238     appropriate and set the 'Level' column for those features to equal
 239     the 'Level' for their parent features for consistency.  Note that
 240     none of the features in the OpenAFS for Windows MSI package are
 241     designed to be installed to run from 'source' or 'advertised'.  It
 242     is recommended that you set 'msidbFeatureAttributesFavorLocal' (0),
 243     'msidbFeatureAttributesFollowParent' (2) and
 244     'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
 245     features.
 246
 247     If you are creating new components, retain the same component GUID
 248     when creating new transforms against new releases of the OpenAFS
 249     MSI package.
 250
 251 3.1 Example: Adding domain specific registry keys
 252
 253     Following is an example for adding domain specific registry keys.
 254     Refer to section 2.1 in REGISTRY.TXT for more information.
 255
 256     Columns that are unspecified should be left empty.
 257
 258     We create a new feature and component to hold the new registry keys.
 259
 260     'Feature' table:
 261
 262     (new row)
 263         Feature         : 'feaDomainKeys'
 264         Feature Parent  : 'feaClient'
 265         Display         : 0
 266         Level           : 30
 267         Attributes      : 10
 268
 269     'Component' table:
 270
 271         (new row)
 272     Component   : 'rcm_DomainKeys'
 273         ComponentId     : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'
 274         Directory       : 'TARGETDIR'
 275         Attributes      : 4
 276         KeyPath         : 'reg_domkey0'
 277
 278     'FeatureComponents' table:
 279
 280     (new row)
 281         Feature         : 'feaDomainKeys'
 282         Component       : 'rcm_DomainKeys'
 283
 284     'Registry' table:
 285
 286         (new row)
 287         Registry        : 'reg_domkey0'
 288         Root            : 2
 289         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
 290         Component       : 'rcm_DomainKeys'
 291
 292         (new row)
 293         Registry        : 'reg_domkey1'
 294         Root            : 2
 295         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'
 296         Name            : '*'
 297         Component       : 'rcm_DomainKeys'
 298
 299         (new row)
 300         Registry        : 'reg_domkey2'
 301         Root            : 2
 302         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
 303         Name            : '*'
 304         Component       : 'rcm_DomainKeys'
 305
 306         (new row)
 307         Registry        : 'reg_domkey3'
 308         Root            : 2
 309         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'
 310         Name            : 'LogonOptions'
 311         Value           : 1
 312         Component       : 'rcm_DomainKeys'
 313
 314         (new row)
 315         Registry        : 'reg_domkey4'
 316         Root            : 2
 317         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
 318         Name            : '*'
 319         Component       : 'rcm_DomainKeys'
 320
 321         (new row)
 322         Registry        : 'reg_domkey5'
 323         Root            : 2
 324         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
 325         Name            : 'LogonOptions'
 326         Value           : 0
 327         Component       : 'rcm_DomainKeys'
 328
 329         (new row)
 330         Registry        : 'reg_domkey6'
 331         Root            : 2
 332         Key             : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'
 333         Name            : 'FailLoginsSilently'
 334         Value           : 1
 335         Component       : 'rcm_DomainKeys'
 336
 337     The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable
 338     integrated logon) and 'LOCALHOST' (disable integrated logon and
 339     fail logins silently).
 340
 341     After making the adjustments to the MSI database using ORCA.EXE
 342     you can generate a transform with MSITRAN.EXE as follows :
 343
 344     (Modified MSI package is 'openafs-en_US_new.msi' and the original
 345     MSI package is 'openafs-en_US.msi'.  Generates transform
 346     'openafs-transform.mst')
 347
 348     > msitran.exe -g openafs-en_US.msi openafs-en_US_new.msi openafs-transform.mst glpruw
 349
 350     See the Platform SDK documentation for information on command line
 351     options for MSITRAN.EXE.
 352
 353 ----------------------------------------------------------------------
 354
 355 4.  Upgrades
 356
 357     The MSI package is designed to uninstall previous versions of
 358     OpenAFS for Windows during installation.  Note that it doesn't
 359     directly upgrade an existing installation.  This is intentional
 360     and ensures that development releases which do not have strictly
 361     increasing version numbers are properly upgraded.
 362
 363     Versions of OpenAFS that are upgraded by the MSI package are :
 364
 365     1) OpenAFS MSI package
 366        Upgrade code {6823EEDD-84FC-4204-ABB3-A80D25779833}
 367        Upto current release
 368
 369     2) MIT's Transarc AFS MSI package
 370        Upgrade code {5332B94F-DE38-4927-9EAB-51F4A64193A7}
 371        Upto version 3.6.2
 372
 373     3) OpenAFS NSIS package
 374        All versions
 375
 376        Note that versions of the OpenAFS NSIS package prior to 1.3.65
 377        had a bug where it couldn't be uninstalled properly in
 378        unattended mode.  Therefore the MSI package will not try to
 379        uninstall an OpenAFS NSIS package if running unattended.  This
 380        means that group policy based deployments will fail on machines
 381        that have the OpenAFS NSIS package installed.
 382
 383     If you have used a different MSI package to install OpenAFS and
 384     wish to upgrade it you can author rows into the 'Upgrade' table as
 385     described in the Platform SDK.
 386
 387 ----------------------------------------------------------------------
 388
 389 5.  FAQ
 390
 391     (Q/A's will be added here as needed)
 392
 393 ----------------------------------------------------------------------
 394 $Id$