From 19ba2ebe8755077f26d69d90e7d878287254c7de Mon Sep 17 00:00:00 2001 From: Jeffrey Altman Date: Mon, 13 Sep 2004 01:50:24 +0000 Subject: [PATCH] Add msi-deployment-guide.txt ticket: 2707 git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@16744 dc483132-0cff-0310-8789-dd5450dbe970 --- src/windows/installer/wix/ChangeLog | 5 + .../installer/wix/msi-deployment-guide.txt | 366 ++++++++++++++++++ 2 files changed, 371 insertions(+) create mode 100644 src/windows/installer/wix/msi-deployment-guide.txt diff --git a/src/windows/installer/wix/ChangeLog b/src/windows/installer/wix/ChangeLog index f8aa27c9a..bc0f95231 100644 --- a/src/windows/installer/wix/ChangeLog +++ b/src/windows/installer/wix/ChangeLog @@ -1,3 +1,8 @@ +2004-09-12 Asanka Herath + + Updates to Wix installer to satisfy the needs of MIT SWRT + Add msi-deployment-guide.txt + 2004-08-20 Asanka Herath New WiX 2.0 MSI for KFW \ No newline at end of file diff --git a/src/windows/installer/wix/msi-deployment-guide.txt b/src/windows/installer/wix/msi-deployment-guide.txt new file mode 100644 index 000000000..4a280cc30 --- /dev/null +++ b/src/windows/installer/wix/msi-deployment-guide.txt @@ -0,0 +1,366 @@ + +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$ + -- 2.26.2