--- /dev/null
+
+Kerberos for Windows
+
+ MSI Deployment Guide
+
+----------------------------------------------------------------------
+
+ Contents
+
+ 1. Introduction
+ 1.1 Requirements
+ 1.2 Authoring a Transform
+ 2. Configuration Options
+ 2.1 Configurable Properties
+ 2.1.1 Setting Properties
+ 2.1.2 Leash GUI Properties
+ 2.1.3 Leash DLL Properties
+ 2.1.4 Kerberos IV Properties
+ 2.1.5 Kerberos V Properties
+ 2.2 Existing Registry Entries
+ 3. Additional Resources
+ 4. Upgrades
+ 5. FAQ
+
+----------------------------------------------------------------------
+
+1. Introduction
+
+ Beginning with Kerberos for Windows version 2.6.5 a MSI installer
+ option is available for those who wish to use Windows Installer
+ for installing Kerberos and for organizations that wish to deploy
+ Kerberos 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 Kerberos for Windows is already
+ installed will pick up these customizations.
+
+1.1 Requirements
+
+ The information in this document applies to MSI packages
+ distributed with Kerberos for Windows releases from 2.6.5 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 kfw.msi kfw-modified.msi
+
+ (edit the kfw-modified.msi to include the necessary changes)
+
+ > msitran -g kfw-modified.msi kfw.msi kfw-transform.mst
+
+ (generates kfw-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 kfw.msi kfw-test.msi
+ > msitran -a kfw-transform.mst kfw-test.msi
+
+ and then checking the resulting kfw-test.msi to see if all the
+ changes you have made above to kfw-modified.msi is present in
+ kfw-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 kfw-modified.msi. More
+ details are given below.
+
+----------------------------------------------------------------------
+
+2. Configuration Options
+
+ The logic necessary to implement all of the setttings described in
+ the release notes 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 release notes ('Registry and
+ Environment Settings' section).
+
+ 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 Leash GUI properties
+
+ LEASHAFSSTATUS
+ Setting: afs token retrieval
+ Values : '0' or '1'
+
+ LEASHCREATEMISSINGCONFIG
+ Setting: automatic generation of missing configuration files
+ Values : '0' or '1'
+
+ LEASHAUTORENEWTICKETS
+ Setting: automatic ticket renewal
+ Values : '0' or '1'
+
+ LEASHLOCKFILELOCATIONS
+ Setting: lock configuration files location
+ Values : '0' or '1'
+
+ LEASHMSLSAIMPORT
+ Setting: automatic importation of MSLSA credentials
+ Values : '0', '1' or '2'
+
+2.1.3 Leash32 DLL properties
+
+ LEASHLIFETIME
+ Setting: default lifetime (minutes)
+ Values : numeric
+
+ LEASHRENEWTILL
+ Setting: default renew till time (minutes)
+ Values : numeric
+
+ LEASHRENEWABLE
+ Setting: default renewable tickets setting
+ Values : '0' or '1'
+
+ LEASHFORWARDABLE
+ Setting: default forwardable tickets setting
+ Values : '0' or '1'
+
+ LEASHNOADDRESSES
+ Setting: default addressless tickets setting
+ Values : '0' or '1'
+
+ LEASHPROXIABLE
+ Setting: default proxiable tickets setting
+ Values : '0' or '1'
+
+ LEASHPUBLICIP
+ Setting: default public ipv4 address
+ Values : numeric
+
+ LEASHUSEKRB4
+ Setting: request kerberos iv tickets
+ Values : '0' or '1'
+
+ LEASHHIDEKINITOPTIONS
+ Setting: hide advanced kinit options in dialog
+ Values : '0' or '1'
+
+ LEASHLIFEMIN
+ Setting: minimum kinit dialog lifetime
+ Values : numeric
+
+ LEASHLIFEMAX
+ Setting: maximum kinit dialog lifetime
+ Values : numeric
+
+ LEASHRENEWMIN
+ Setting: minimum kinit dialog renew till time
+ Values : numeric
+
+ LEASHRENEWMAX
+ Setting: maximum kinit dialog renew till time
+ Values : numeric
+
+ LEASHUPPERCASEREALM
+ Setting: upper case realm
+ Values : '0' or '1'
+
+ LEASHTIMEHOST
+ Setting: timesync host
+ Values : string
+
+ LEASHPRESERVEKINITOPTIONS
+ Setting: Preserve ticket initialization dialog options
+ Values : numeric
+
+2.1.4 Kerberos 4 properties
+
+ KRB4KRBREALMS (realms full pathname)
+ KRB4KRBCONF (config full pathname)
+ KRB4KRBCONFIDIR (dir for both files)
+ Setting: location of krbrealm & krbconf
+ Values : string
+ (note that the three registry settings are conditioned
+ independently. I.e. If you only set KRB4KRBCONF, only the
+ krb.conf setting will be written.)
+
+ KRB4TICKETFILE
+ Setting: ticket file
+ Values : string
+
+2.1.5 Kerberos 5 properties
+
+ KRB5CONFIG
+ Setting: location of krb5.ini
+ Values : string
+
+ KRB5CCNAME
+ Setting: Default credentials cache name
+ Values : string
+
+ KRB5PRESERVEIDENTITY
+ Setting: MSLSA: credential cache client principal identity generation
+ Values : '0' or '1'
+
+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.
+
+ Add new features under the 'feaKfwClient' feature 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 Kerberos 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 Kerberos
+ MSI package.
+
+ 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
+
+----------------------------------------------------------------------
+
+4. Upgrades
+
+ The MSI package is designed to uninstall previous versions of
+ Kerberos 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 Kerberos that are upgraded by the MSI package are :
+
+ 1) Kerberos for Windows MSI package
+
+ Upgrade code {61211594-AAA1-4A98-A299-757326763CC7}
+ Upto current release
+
+ 2) MIT Project Pismere Kerberos for Windows MSI package and MIT
+ SWRT Kerberos for Windows MSI
+
+ Upgrade code {83977767-388D-4DF8-BB08-3BF2401635BD}
+ All versions
+
+ 3) Kerberos for Windows NSIS package
+
+ All versions
+
+ Note that versions of the Kerberos for Windows NSIS package had
+ a bug where it couldn't be uninstalled properly in unattended
+ mode. Therefore the MSI package will not try to uninstall an
+ Kerberos for Windows NSIS package if running unattended. This
+ means that group policy based deployments will fail on machines
+ that have the Kerberos for Windows NSIS package installed.
+
+ If you have used a different MSI package to install Kerberos for
+ Windows and wish to upgrade it you can author rows into the
+ 'Upgrade' table to have the Kerberos for Windows MSI replace these
+ installations for you.
+
+----------------------------------------------------------------------
+
+5. FAQ
+
+ (Q/A's will be added here as needed)
+
+----------------------------------------------------------------------
+$Id$
+
projects / thirdparty / krb5.git / commitdiff
