Blame src/windows/installer/wix/msi-deployment-guide.txt

Packit fd8b60
Packit fd8b60
Kerberos for Windows
Packit fd8b60
Packit fd8b60
                         MSI Deployment Guide
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
     Contents
Packit fd8b60
Packit fd8b60
     1.    Introduction
Packit fd8b60
     1.1     Requirements
Packit fd8b60
     1.2     Authoring a Transform
Packit fd8b60
     2.	   Configuration Options
Packit fd8b60
     2.1     Configurable Properties
Packit fd8b60
     2.1.1     Setting Properties
Packit fd8b60
     2.1.2     Leash GUI Properties
Packit fd8b60
     2.1.3     Leash DLL Properties
Packit fd8b60
     2.1.4     Kerberos IV Properties
Packit fd8b60
     2.1.5     Kerberos V Properties
Packit fd8b60
     2.2     Existing Registry Entries
Packit fd8b60
     2.3     Replacing Configuration Files
Packit fd8b60
     3.    Network Identity Manager Settings
Packit fd8b60
     3.1     Common Settings for NetIDMgr
Packit fd8b60
     3.1.1     General Settings
Packit fd8b60
     3.1.2     Common Plug-in Settings
Packit fd8b60
     3.1.3     Settings for the Kerberos 5 Credentials Provider Plug-in
Packit fd8b60
     3.1.4     Settings for the kerberos 4 Credentials Provider Plug-in
Packit fd8b60
     4.	   Additional Resources
Packit fd8b60
     5.	   Upgrades
Packit fd8b60
     6.	   FAQ
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
1.  Introduction
Packit fd8b60
Packit fd8b60
    Beginning with "Kerberos for Windows" version 2.6.5, a MSI installer
Packit fd8b60
    option is available for those who wish to use "Windows Installer"
Packit fd8b60
    for installing Kerberos and for organizations that wish to deploy
Packit fd8b60
    Kerberos through Group Policy.
Packit fd8b60
Packit fd8b60
    This document provides a guide for authoring transforms used to
Packit fd8b60
    customize the MSI package for a particular organization.  Although
Packit fd8b60
    many settings can be deployed via transforms, in an Active
Packit fd8b60
    Directory environment it is advisable to deploy registry settings
Packit fd8b60
    and configuration files through group policy and/or startup
Packit fd8b60
    scripts so that machines where "Kerberos for Windows" is already
Packit fd8b60
    installed will pick up these customizations.
Packit fd8b60
Packit fd8b60
1.1 Requirements
Packit fd8b60
Packit fd8b60
    The information in this document applies to MSI packages
Packit fd8b60
    distributed with "Kerberos for Windows" releases from 2.6.5 and
Packit fd8b60
    onwards or MSI packages built from corresponding source
Packit fd8b60
    releases.  Not all releases support all the configuration options
Packit fd8b60
    documented here.
Packit fd8b60
Packit fd8b60
    Authoring a "Windows Installer" transform requires additional
Packit fd8b60
    software for editing the MSI database tables and generating the
Packit fd8b60
    transform from the modified MSI package.  ORCA.EXE and MSITRAN.EXE
Packit fd8b60
    which are included in the Windows Platform SDK ("Windows Installer"
Packit fd8b60
    SDK) can be used for this purpose.
Packit fd8b60
Packit fd8b60
    For reference, the schema for the MSI package is based on
Packit fd8b60
    SCHEMA.MSI distributed with the Platform SDK.
Packit fd8b60
Packit fd8b60
    For general information about "Windows Installer", refer to :
Packit fd8b60
Packit fd8b60
    http://msdn.microsoft.com/library/en-us/msi/setup/windows_installer_start_page.asp
Packit fd8b60
Packit fd8b60
    For general information about authoring MSI transforms, refer to :
Packit fd8b60
Packit fd8b60
    http://msdn.microsoft.com/library/en-us/msi/setup/transforms.asp
Packit fd8b60
Packit fd8b60
    The remainder of this document assumes some familiarity with
Packit fd8b60
    authoring transforms.  While the MSDN documentation for Windows
Packit fd8b60
    Installer is a bit dense, it is recommended that you read through
Packit fd8b60
    the guide on MSI transforms found at the second link above.  Also
Packit fd8b60
    MSDN includes a step-by-step example for creating a transform at:
Packit fd8b60
Packit fd8b60
    http://msdn.microsoft.com/library/en-us/msi/setup/a_customization_transform_example.asp
Packit fd8b60
Packit fd8b60
1.2  Authoring a Transform
Packit fd8b60
Packit fd8b60
    Transforms describe a set of modifications to be performed on an
Packit fd8b60
    existing MSI for the purpose of customizing it.  This is
Packit fd8b60
    ordinarily done by making a copy of the MSI to be customized,
Packit fd8b60
    modifying the copy and then using the old and the new MSI to
Packit fd8b60
    generate a transform.
Packit fd8b60
Packit fd8b60
    E.g:
Packit fd8b60
       > copy kfw.msi kfw-modified.msi
Packit fd8b60
       
Packit fd8b60
       (edit the kfw-modified.msi to include the necessary changes)
Packit fd8b60
Packit fd8b60
       > msitran -g kfw.msi kfw-modified.msi kfw-transform.mst
Packit fd8b60
Packit fd8b60
       (generates kfw-transform.mst, which is the transform)
Packit fd8b60
Packit fd8b60
    Transforms have an extension of .mst.  'msitran' is a tool
Packit fd8b60
    distributed as part of the "Windows Installer" SDK (which in turn is
Packit fd8b60
    a part of the Windows Platform SDK).
Packit fd8b60
Packit fd8b60
    You can test a transform by :
Packit fd8b60
Packit fd8b60
       > copy kfw.msi kfw-test.msi
Packit fd8b60
       > msitran -a kfw-transform.mst kfw-test.msi
Packit fd8b60
Packit fd8b60
    and then checking the resulting kfw-test.msi to see if all the
Packit fd8b60
    changes you have made above to kfw-modified.msi is present in
Packit fd8b60
    kfw-test.msi.  'msitran' will complain if some modification in the
Packit fd8b60
    transform can not be successfully applied.
Packit fd8b60
Packit fd8b60
    As mentioned above, you can use a tool like ORCA.EXE to edit the
Packit fd8b60
    MSI databases directly when editing kfw-modified.msi.  More
Packit fd8b60
    details are given below.
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
2.  Configuration Options
Packit fd8b60
Packit fd8b60
    The logic necessary to implement all of the settings described in
Packit fd8b60
    the release notes are present in the MSI.  Most of these can be
Packit fd8b60
    controlled by setting the corresponding properties to the desired
Packit fd8b60
    value.  Some settings may require modifying existing registry
Packit fd8b60
    entries (though not recommended) or adding new resources (like
Packit fd8b60
    files or registry keys).  Instructions for performing these tasks
Packit fd8b60
    are below.
Packit fd8b60
Packit fd8b60
2.1 Configurable Properties
Packit fd8b60
Packit fd8b60
    Most configurable properties correspond to registry keys or
Packit fd8b60
    values.  Please refer to the release notes for more information
Packit fd8b60
    about how these registry settings are used.
Packit fd8b60
Packit fd8b60
    Due to the logic invoked based on the existence of these registry
Packit fd8b60
    keys or values, they are only set if the associated property is
Packit fd8b60
    defined to have a non null value.  If the associated property is
Packit fd8b60
    not defined in the MSI, the registry key or value will not be
Packit fd8b60
    touched.  By default, the MSI does not contain these properties
Packit fd8b60
    and hence will not set the registry keys.  You will need to add
Packit fd8b60
    properties as needed to the MSI.
Packit fd8b60
Packit fd8b60
    When one of the configurable properties is set, the installer will
Packit fd8b60
    use the property value to set the corresponding setting in the
Packit fd8b60
    HKEY_LOCAL_MACHINE registry hive.  HKEY_CURRENT_USER hive is not
Packit fd8b60
    touched by the installer.
Packit fd8b60
Packit fd8b60
    For each property, the associated registry setting is referenced
Packit fd8b60
    by the same text used in the release notes ('Registry and
Packit fd8b60
    Environment Settings' section).
Packit fd8b60
Packit fd8b60
    Strings are quoted using single quotes (e.g. 'a string'). An empty
Packit fd8b60
    string is denoted as ''.  Note that you can't author null values
Packit fd8b60
    into the 'Property' table.
Packit fd8b60
Packit fd8b60
    Numeric values should be authored as decimal strings.
Packit fd8b60
Packit fd8b60
2.1.1  Setting Properties
Packit fd8b60
Packit fd8b60
    In order to set a property,
Packit fd8b60
Packit fd8b60
    a.  Open the MSI in ORCA.EXE
Packit fd8b60
Packit fd8b60
    b.  Select the 'Property' table from the list of tables on the left.
Packit fd8b60
Packit fd8b60
    c.  Find the property in the list of properties on the right,
Packit fd8b60
        double click the value and type the new value.
Packit fd8b60
Packit fd8b60
    d.  If the property does not exist in the property list, right
Packit fd8b60
        click the list and select 'Add Row', type the property name
Packit fd8b60
        and the desired value.
Packit fd8b60
Packit fd8b60
2.1.2    Leash GUI properties
Packit fd8b60
Packit fd8b60
    LEASHCREATEMISSINGCONFIG
Packit fd8b60
	Setting: automatic generation of missing configuration files
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHAUTORENEWTICKETS
Packit fd8b60
	Setting: automatic ticket renewal
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHMSLSAIMPORT
Packit fd8b60
	Setting: automatic importation of MSLSA credentials
Packit fd8b60
	Values : '0', '1' or '2'
Packit fd8b60
Packit fd8b60
2.1.3    Leash32 DLL properties
Packit fd8b60
Packit fd8b60
    LEASHLIFETIME
Packit fd8b60
	Setting: default lifetime (minutes)
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHRENEWTILL
Packit fd8b60
	Setting: default renew till time (minutes)
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHRENEWABLE
Packit fd8b60
	Setting: default renewable tickets setting
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHFORWARDABLE
Packit fd8b60
	Setting: default forwardable tickets setting
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHNOADDRESSES
Packit fd8b60
	Setting: default addressless tickets setting
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHPROXIABLE
Packit fd8b60
	Setting: default proxiable tickets setting
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHPUBLICIP
Packit fd8b60
	Setting: default public ipv4 address
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHHIDEKINITOPTIONS
Packit fd8b60
	Setting: hide advanced kinit options in dialog
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHLIFEMIN
Packit fd8b60
	Setting: minimum kinit dialog lifetime
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHLIFEMAX
Packit fd8b60
	Setting: maximum kinit dialog lifetime
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHRENEWMIN
Packit fd8b60
	Setting: minimum kinit dialog renew till time
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHRENEWMAX
Packit fd8b60
	Setting: maximum kinit dialog renew till time
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
    LEASHUPPERCASEREALM
Packit fd8b60
	Setting: upper case realm
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
    LEASHTIMEHOST
Packit fd8b60
	Setting: timesync host
Packit fd8b60
	Values : string
Packit fd8b60
Packit fd8b60
    LEASHPRESERVEKINITOPTIONS
Packit fd8b60
	Setting: Preserve ticket initialization dialog options
Packit fd8b60
	Values : numeric
Packit fd8b60
Packit fd8b60
2.1.4  Kerberos 5 properties
Packit fd8b60
Packit fd8b60
    KRB5CONFIG
Packit fd8b60
	Setting: location of krb5.ini
Packit fd8b60
	Values : string
Packit fd8b60
Packit fd8b60
    KRB5CCNAME
Packit fd8b60
	Setting: Default credentials cache name
Packit fd8b60
	Values : string
Packit fd8b60
Packit fd8b60
    KRB5PRESERVEIDENTITY
Packit fd8b60
	Setting: MSLSA: credential cache client principal identity generation
Packit fd8b60
	Values : '0' or '1'
Packit fd8b60
Packit fd8b60
2.2 Existing Registry Entries
Packit fd8b60
Packit fd8b60
    You can change existing registry values subject to the
Packit fd8b60
    restrictions mentioned in the Windows Platform SDK.  Pay special
Packit fd8b60
    attention to component keypaths and try to only change the 'Value'
Packit fd8b60
    column in the 'Registry' table.  If you want to add additional
Packit fd8b60
    registry keys please refer to section 3 (Additional Resources).
Packit fd8b60
Packit fd8b60
2.3 Replacing Configuration Files
Packit fd8b60
Packit fd8b60
    The Kerberos configuration files (krb5.ini, krb.con, krbrealm.con)
Packit fd8b60
    can be replaced by your own configuration files.  These files are
Packit fd8b60
    contained in separate MSI components so that you can disable them
Packit fd8b60
    individually.
Packit fd8b60
Packit fd8b60
    The recommended method for replacing these files is to first
Packit fd8b60
    disable the components containing the configuration files that you
Packit fd8b60
    want to replace, and then add new components for the replacement
Packit fd8b60
    files.  This is outlined below (assuming you are using ORCA.EXE to
Packit fd8b60
    author the transform).
Packit fd8b60
Packit fd8b60
    Note that transforms are not a good way to add a new file as an
Packit fd8b60
    embedded stream.  The method outlined here places the file in the
Packit fd8b60
    same directory as the MSI for deployment.
Packit fd8b60
Packit fd8b60
    The walkthrough below is to add a custom 'krb5.ini' file.
Packit fd8b60
Packit fd8b60
    1) Disable the component that contains the configuration file that
Packit fd8b60
       you want to replace.
Packit fd8b60
Packit fd8b60
       1.1) Locate and select the 'Component' table in the 'Tables'
Packit fd8b60
            list.
Packit fd8b60
Packit fd8b60
       1.2) In the Component table, locate the component you need to
Packit fd8b60
            change ( Ctrl-F invokes the 'Find' dialog).  The component
Packit fd8b60
            names are listed below in section 2.3.1.  For this
Packit fd8b60
            example, the component name is 'cmf_krb5_ini'.
Packit fd8b60
Packit fd8b60
       1.3) Go to the 'Condition' column of the component.
Packit fd8b60
Packit fd8b60
       1.4) Enter a condition that evaluates to
Packit fd8b60
            false. I.e. 'DONOTINSTALL'. (Note that an undefined
Packit fd8b60
            property always evaluates to false).
Packit fd8b60
Packit fd8b60
       Note that you can also use this step to disable other
Packit fd8b60
       configuration files without providing replacements.
Packit fd8b60
Packit fd8b60
    2) Add a new component containing the new configuration file.
Packit fd8b60
Packit fd8b60
       2.1) Select the 'Component' table in the 'Tables' list.
Packit fd8b60
Packit fd8b60
       2.2) Select 'Tables'->'Add Row' (Ctrl-R).
Packit fd8b60
Packit fd8b60
       2.3) Enter the following :
Packit fd8b60
Packit fd8b60
            Component     : cmf_my_krb5_ini
Packit fd8b60
	    ComponentId   : {835BAAC6-5E54-BFFE-DBCB2F240711}
Packit fd8b60
	    Directory_	  : WindowsFolder
Packit fd8b60
	    Attributes	  : 144
Packit fd8b60
	    Condition	  :
Packit fd8b60
	    KeyPath	  : fil_my_krb5_ini
Packit fd8b60
Packit fd8b60
	    Note that the ComponentId is an uppercase GUID.  You can
Packit fd8b60
	    generate one using GUIDGEN.EXE or UUIDGEN.EXE, both of
Packit fd8b60
	    which are included in the Platform SDK.
Packit fd8b60
Packit fd8b60
	    The Attributes value of 144 is a sum of
Packit fd8b60
	    msidbComponentAttributesPermanent (16) and
Packit fd8b60
	    msidbComponentAttributesNeverOverwrite (128).  This
Packit fd8b60
	    ensures that local modifications are not overwritten or
Packit fd8b60
	    lost during an installation or uninstallation.  These are
Packit fd8b60
	    the same settings used on the default configuration files.
Packit fd8b60
Packit fd8b60
	    'fil_my_krb5_ini' is a key into the 'File' table which we
Packit fd8b60
	    will fill later.
Packit fd8b60
Packit fd8b60
    3) Add a new feature to hold the new component.
Packit fd8b60
Packit fd8b60
       3.1) Select the 'Feature' table.
Packit fd8b60
Packit fd8b60
       3.2) Add a new row (Ctrl-R or 'Tables'->'Add Row') with the
Packit fd8b60
            following values:
Packit fd8b60
Packit fd8b60
	    Feature       : fea_my_krb5_ini
Packit fd8b60
	    Feature_Parent: feaKfwClient
Packit fd8b60
	    Title	  :
Packit fd8b60
	    Description	  :
Packit fd8b60
	    Display	  : 0
Packit fd8b60
	    Level	  : 30
Packit fd8b60
	    Directory_	  :
Packit fd8b60
	    Attributes	  : 8
Packit fd8b60
Packit fd8b60
	    It is important to create the new feature under the
Packit fd8b60
	    'feaKfwClient' feature, which will ensure that the
Packit fd8b60
	    configuration file will be installed when the client
Packit fd8b60
	    binaries are installed.
Packit fd8b60
Packit fd8b60
	    Setting 'Display' to 0 will hide this feature from the
Packit fd8b60
	    feature selection dialog during an interactive
Packit fd8b60
	    installation.  A value of 30 for 'Level' allows this
Packit fd8b60
	    feature to be installed by default (on a 'Typical'
Packit fd8b60
	    installation).
Packit fd8b60
Packit fd8b60
	    The 'Attributes' value is
Packit fd8b60
	    msidbFeatureAttributesDisallowAdvertise (8), which is set
Packit fd8b60
	    on all features in the KfW MSI.  The KfW MSI is not
Packit fd8b60
	    designed for an advertised installation.
Packit fd8b60
Packit fd8b60
    4) Join the component and the feature.
Packit fd8b60
Packit fd8b60
       4.1) Select the 'FeatureComponents' table.
Packit fd8b60
Packit fd8b60
       4.2) Add a new row with the following values:
Packit fd8b60
Packit fd8b60
	    Feature    : fea_my_krb5_ini
Packit fd8b60
	    Component  : cmf_my_krb5_ini
Packit fd8b60
Packit fd8b60
    5) Add an entry to the 'File' table.
Packit fd8b60
Packit fd8b60
       5.1) Select the 'File' table.
Packit fd8b60
Packit fd8b60
       5.2) Add a new row with the following values:
Packit fd8b60
Packit fd8b60
	    File        : fil_my_krb5_ini
Packit fd8b60
	    Component_	: cmf_my_krb5_ini
Packit fd8b60
	    FileName	: krb5.ini
Packit fd8b60
	    FileSize	: (enter file size here)
Packit fd8b60
	    ...
Packit fd8b60
	    Attributes	: 8192
Packit fd8b60
	    Sequence	: 1000
Packit fd8b60
	    (leave other fields blank)
Packit fd8b60
Packit fd8b60
	    The 'Attributes' value is msidbFileAttributesNonCompressed
Packit fd8b60
	    (8192).  This is because we will be placing this file in
Packit fd8b60
	    the same directory as the MSI instead of embedding the
Packit fd8b60
	    file in it.  Transforms do not support updating compressed
Packit fd8b60
	    sources or adding new cabinet streams.
Packit fd8b60
Packit fd8b60
	    Finally, the 'Sequence' value of 1000 will be used later
Packit fd8b60
	    to distinguish the file as being in a separate source
Packit fd8b60
	    location than the other files in the MSI.
Packit fd8b60
Packit fd8b60
    6) Set a media source for the file.
Packit fd8b60
Packit fd8b60
       6.1) Select the 'Media' table.
Packit fd8b60
Packit fd8b60
       6.2) Add a row with the following values :
Packit fd8b60
Packit fd8b60
	    DiskId       : 2
Packit fd8b60
	    LastSequence : 1000
Packit fd8b60
	    ...
Packit fd8b60
	    (leave other fields blank)
Packit fd8b60
Packit fd8b60
	    The sequence number of 1000 designates this as the media
Packit fd8b60
	    source for the newly added file.
Packit fd8b60
Packit fd8b60
2.3.1 Components for Configuration Files
Packit fd8b60
Packit fd8b60
      krb5.ini : 'cmf_krb5_ini' (ID {C1AF0670-BBF1-4AA6-B2A6-6C8B1584A1F4})
Packit fd8b60
      krb.con  : 'cmf_krb_con'  (ID {5391A051-CF14-45FF-BF64-CEE78A7A90C2})
Packit fd8b60
      krbrealm.con: 'cmf_krbrealm_con' (ID {D667B54F-1C98-43FB-87C6-0F0517623B90})
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
3.   Network Identity Manager Settings
Packit fd8b60
Packit fd8b60
    Configuration options for Network Identity Manager (NetIDMgr) are
Packit fd8b60
    stored in the Windows registry.  Each option can exist in the user
Packit fd8b60
    registry hive or the machine registry hive or both.  The value
Packit fd8b60
    defined in the user hive always overrides the value defined in the
Packit fd8b60
    machine registry hive.
Packit fd8b60
Packit fd8b60
    All registry keys used by NetIDMgr exist under the key
Packit fd8b60
    'Software\MIT\NetIDMgr' under the user and machine hive.
Packit fd8b60
    Deploying a specific configuration option can be achieved by
Packit fd8b60
    setting the corresponding registry value either by authoring the
Packit fd8b60
    keys into the MSI via a transform or by deploying a registry based
Packit fd8b60
    Group Policy Object.  For deployment purposes, it is advisable to
Packit fd8b60
    deploy values to the machine hive instead of the user hive.
Packit fd8b60
    Deploying per user settings via the MSI is not supported at this
Packit fd8b60
    time.
Packit fd8b60
Packit fd8b60
3.1    Common settings for NetIDMgr
Packit fd8b60
Packit fd8b60
    The following sections describe a partial list of options that can
Packit fd8b60
    be specified for NetIDMgr.  Each set of options is described as a
Packit fd8b60
    set of registry values.  Each section is preceded by the registry
Packit fd8b60
    key under which the values of that section must be specified.
Packit fd8b60
Packit fd8b60
3.1.1    General settings
Packit fd8b60
Packit fd8b60
    Registry key : 'Software\MIT\NetIDMgr\CredWindow'
Packit fd8b60
    --------------
Packit fd8b60
Packit fd8b60
    Value   : AllowAutoRenew
Packit fd8b60
    Type    : DWORD (Boolean)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        Enables automatic credential renewal.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AllowCritical
Packit fd8b60
    Type    : DWORD (Boolean)
Packit fd8b60
    Default : 1	
Packit fd8b60
Packit fd8b60
        Enables critical warning notifications.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AllowWarn	
Packit fd8b60
    Type    : DWORD (Boolean)
Packit fd8b60
    Default : 1	
Packit fd8b60
Packit fd8b60
        Enables warning notifications.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AutoDetectNet
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '1', automatically detects network connectivity changes.
Packit fd8b60
        Network connectivity change notifications are then sent out to
Packit fd8b60
        individual plug-ins which can perform actions such as renewing
Packit fd8b60
        credentials or obtaining new credentials.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AutoImport
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '1', imports credentials from the Windows LSA cache when
Packit fd8b60
        NetIDMgr starts.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AutoInit
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If this value is '1', shows the new credentials dialog if
Packit fd8b60
        there are no credentials when NetIDMgr starts.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AutoStart	
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0	
Packit fd8b60
Packit fd8b60
        Start NetIDMgr when Windows starts
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : AutoRenewThreshold
Packit fd8b60
    Type    : DWORD (seconds)
Packit fd8b60
    Default : 600
Packit fd8b60
Packit fd8b60
        Specifies the time period before credential expiration that will
Packit fd8b60
        trigger a credential renewal.  Requires AllowAutoRenew to be enabled.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : CriticalThreshold	
Packit fd8b60
    Type    : DWORD (seconds)
Packit fd8b60
    Default : 300
Packit fd8b60
Packit fd8b60
        Specifies the time period before credential expiration that will
Packit fd8b60
        trigger the second and final warning balloon.  Requires AllowCritical
Packit fd8b60
        to be enabled.
Packit fd8b60
        
Packit fd8b60
Packit fd8b60
    Value   : DefaultAllowAutoRenew
Packit fd8b60
    Type    : DWORD (Boolean)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
	Specifies the Default AllowAutoRenew value for new identities.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : DefaultSticky
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '0', new identities will not be pinned to the display by default.
Packit fd8b60
        If '1', new identities will be pinned to the display by default.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : DefaultWindowMode
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '0', Advanced mode is used
Packit fd8b60
        If '1', Basic mode is used
Packit fd8b60
Packit fd8b60
    Value   : DestroyCredsOnExit
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', all credentials will be destroyed when NetIDMgr exits.
Packit fd8b60
Packit fd8b60
    Value   : KeepRunning
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '1', when NetIDMgr application is closed, it will continue
Packit fd8b60
        to run in the Windows System Notification Area (System Tray).
Packit fd8b60
        The application can be exited by choosing the 'Exit' menu
Packit fd8b60
        option.  If '0', closing the application will cause it to
Packit fd8b60
        exit completely.
Packit fd8b60
Packit fd8b60
    Value   : LogToFile
Packit fd8b60
    Type    : DWORD  (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', debugging information is logged to %TEMP%\nidmdbg.log
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : NotificationAction
Packit fd8b60
    Type    : DWORD  (50008 or 50025)
Packit fd8b60
    Default : 50025
Packit fd8b60
Packit fd8b60
        If '50025', the default notification icon menu action will be to
Packit fd8b60
        Show the Network Identity Manager application windows.
Packit fd8b60
        If '50008', the default notification icon menu action will be to 
Packit fd8b60
        display the Obtain New Credentials dialog.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : RefreshTimeout	
Packit fd8b60
    Type    : DWORD (seconds)
Packit fd8b60
    Default : 60
Packit fd8b60
Packit fd8b60
        Specifies how often the credential list is refreshed.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : RenewAtHalfLife
Packit fd8b60
    Type    : DWORD (Boolean)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
	Enables the use of a half-life algorithm for credential renewals.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : WarnThreshold
Packit fd8b60
    Type    : DWORD (seconds)
Packit fd8b60
    Default : 900
Packit fd8b60
Packit fd8b60
        Specifies the time period before credential expiration that will
Packit fd8b60
        trigger the first warning balloon.  Requires AllowWarn to be enabled.
Packit fd8b60
Packit fd8b60
Packit fd8b60
3.1.2    Common Plug-in settings
Packit fd8b60
Packit fd8b60
    Registry key : 'Software\MIT\NetIDMgr\PluginManager\Plugins\<plug-in name>'
Packit fd8b60
    --------------
Packit fd8b60
Packit fd8b60
    The '<plug-in name>' is one of the following for the standard plug-ins :
Packit fd8b60
Packit fd8b60
    Krb5Cred : Kerberos 5 credentials provider
Packit fd8b60
    Krb5Ident: Kerberos 5 Identity provider
Packit fd8b60
Packit fd8b60
    Consult the vendors for the plug-in names of other third party
Packit fd8b60
    plug-ins.  Additionally, the plug-ins configuration panel in the
Packit fd8b60
    NetIDMgr application provides a list of currently registered
Packit fd8b60
    plug-ins.
Packit fd8b60
Packit fd8b60
    Value   : Disabled
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', the plug-in will not be loaded.
Packit fd8b60
Packit fd8b60
    Value   : NoUnload
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', the plug-in will not be unloaded from memory when the
Packit fd8b60
        NetIDMgr application exits or if the plug-in is stopped.  The
Packit fd8b60
        plug-in binary will remain loaded until NetIDMgr terminates.
Packit fd8b60
Packit fd8b60
3.1.3    Settings for the Kerberos 5 credentials provider plug-in
Packit fd8b60
Packit fd8b60
    Registry key : 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters'
Packit fd8b60
    --------------
Packit fd8b60
Packit fd8b60
    Value   : AutoRenewTickets
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '1', automatically renews expiring tickets.  The thresholds
Packit fd8b60
        at which renewals happen are controlled in general NetIDMgr
Packit fd8b60
        settings.
Packit fd8b60
Packit fd8b60
    Value   : CreateMissingConfig
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', creates any missing configuration files.
Packit fd8b60
Packit fd8b60
    Value   : MsLsaImport
Packit fd8b60
    Type    : DWORD (0, 1 or 2)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        Controls how credentials are imported from the MSLSA cache.
Packit fd8b60
        This setting can be one of the following.
Packit fd8b60
Packit fd8b60
        0 : Never
Packit fd8b60
        1 : Always
Packit fd8b60
        2 : Only if the principal matches
Packit fd8b60
Packit fd8b60
        Note that this setting only controls how the Kerberos 5
Packit fd8b60
        plug-in handles importing of credentials from the MSLSA cache.
Packit fd8b60
        Whether or not credentials are imported at start-up is
Packit fd8b60
        controlled via general NetIDMgr settings as described in
Packit fd8b60
        section 3.1.1.
Packit fd8b60
Packit fd8b60
    Value   : MsLsaList
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        If '1', includes credentials from the MSLSA cache in the
Packit fd8b60
        credentials listing.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : UseFullRealmList
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        If '1', uses the full realms list as determined by parsing the
Packit fd8b60
        krb5.ini configuration file in the new credentials dialog box.
Packit fd8b60
        If this is '0', only the last recently used list of realms
Packit fd8b60
        will be used.
Packit fd8b60
Packit fd8b60
Packit fd8b60
3.1.3.1    Per-identity settings
Packit fd8b60
Packit fd8b60
    Registry key 1: 'Software\MIT\NetIDMgr\KCDB\Identity\<principal name>\Krb5Cred'
Packit fd8b60
    Registry key 2: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters\Realms\<realm>'
Packit fd8b60
    Registry key 3: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters'
Packit fd8b60
    --------------
Packit fd8b60
Packit fd8b60
    These settings are generally maintained per-identity.  However, if
Packit fd8b60
    a particular setting is not specified for an identity or if the
Packit fd8b60
    identity is new, then the values will be looked up in the
Packit fd8b60
    per-realm configuration key and in the global parameters key in
Packit fd8b60
    turn.  Global defaults should be set in the global parameters key
Packit fd8b60
    (key 3).
Packit fd8b60
Packit fd8b60
    Value   : Addressless
Packit fd8b60
    Type    : DWORD (boolean)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        Determines if addressless tickets will be obtained for new identities.
Packit fd8b60
Packit fd8b60
Packit fd8b60
    Value   : DefaultLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 36000
Packit fd8b60
Packit fd8b60
        Default ticket lifetime, in seconds.
Packit fd8b60
Packit fd8b60
    Value   : DefaultRenewLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 604800
Packit fd8b60
Packit fd8b60
        Default renewable lifetime, in seconds.
Packit fd8b60
Packit fd8b60
    Value   : FileCCList
Packit fd8b60
    Type    : SZ
Packit fd8b60
    Default : <not specified>
Packit fd8b60
Packit fd8b60
        Specifies a comma delimited list of FILE credential caches to monitor
Packit fd8b60
        for credentials.
Packit fd8b60
Packit fd8b60
    Value   : Forwardable
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        Obtain forwardable tickets.
Packit fd8b60
Packit fd8b60
    Value   : MaxLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 86400
Packit fd8b60
Packit fd8b60
        Maximum lifetime, in seconds.  This value is used to set the
Packit fd8b60
        range of the user interface controls that allow setting the
Packit fd8b60
        lifetime of a ticket.
Packit fd8b60
Packit fd8b60
    Value   : MaxRenewLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 2592000
Packit fd8b60
Packit fd8b60
        Maximum renewable lifetime, in seconds.  The value is used to
Packit fd8b60
        set the range of the user interface controls that allow
Packit fd8b60
        setting the renewable lifetime of a ticket.
Packit fd8b60
Packit fd8b60
    Value   : MinLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 60
Packit fd8b60
Packit fd8b60
        Minimum lifetime, in seconds.  This value is used to set the
Packit fd8b60
        range of the user interface controls that allow setting the
Packit fd8b60
        lifetime of a ticket.
Packit fd8b60
Packit fd8b60
    Value   : MinRenewLifetime
Packit fd8b60
    Type    : DWORD
Packit fd8b60
    Default : 60
Packit fd8b60
Packit fd8b60
        Minimum renewable lifetime, in seconds.  This value is used to
Packit fd8b60
        set the range of the user interface controls that allow
Packit fd8b60
        setting the renewable lifetime of a ticket.
Packit fd8b60
Packit fd8b60
    Value   : Proxiable
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 0
Packit fd8b60
Packit fd8b60
        Obtain proxiable tickets.
Packit fd8b60
Packit fd8b60
    Value   : Renewable
Packit fd8b60
    Type    : DWORD (0 or 1)
Packit fd8b60
    Default : 1
Packit fd8b60
Packit fd8b60
        Obtain renewable tickets.
Packit fd8b60
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
4.   Additional Resources
Packit fd8b60
Packit fd8b60
    If you want to add registry keys or files you need to create new
Packit fd8b60
    components and features for those.
Packit fd8b60
Packit fd8b60
    Add new features under the 'feaKfwClient' feature and set the
Packit fd8b60
    'Level' column for those features to equal the 'Level' for their
Packit fd8b60
    parent features for consistency.  Note that none of the features
Packit fd8b60
    in the "Kerberos for Windows" MSI package are designed to be
Packit fd8b60
    installed to run from 'source' or 'advertised'.  It is recommended
Packit fd8b60
    that you set 'msidbFeatureAttributesFavorLocal' (0),
Packit fd8b60
    'msidbFeatureAttributesFollowParent' (2) and
Packit fd8b60
    'msidbFeatureAttributesDisallowAdvertise' (8) attributes for new
Packit fd8b60
    features.
Packit fd8b60
Packit fd8b60
    If you are creating new components, retain the same component GUID
Packit fd8b60
    when creating new transforms against new releases of the Kerberos
Packit fd8b60
    MSI package.
Packit fd8b60
Packit fd8b60
    It is beyond the scope of this document to provide a comprehensive
Packit fd8b60
    overview of how to add new resources through a transform.  Please
Packit fd8b60
    refer to the "Windows Installer" documentation for details.  The
Packit fd8b60
    relevant section is at :
Packit fd8b60
Packit fd8b60
    http://msdn.microsoft.com/library/en-us/msi/setup/using_transforms_to_add_resources.asp
Packit fd8b60
Packit fd8b60
    A sample walkthrough of adding a new configuration file is in
Packit fd8b60
    section 2.3.
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
5.  Upgrades
Packit fd8b60
Packit fd8b60
    The MSI package is designed to uninstall previous versions of
Packit fd8b60
    "Kerberos for Windows" during installation.  Note that it doesn't
Packit fd8b60
    directly upgrade an existing installation.  This is intentional
Packit fd8b60
    and ensures that development releases which do not have strictly
Packit fd8b60
    increasing version numbers are properly upgraded.
Packit fd8b60
Packit fd8b60
    Versions of Kerberos that are upgraded by the MSI package are :
Packit fd8b60
Packit fd8b60
    1) "Kerberos for Windows" 32-bit i386 MSI package
Packit fd8b60
Packit fd8b60
       Upgrade code {61211594-AAA1-4A98-A299-757326763CC7}
Packit fd8b60
       Upto current release
Packit fd8b60
Packit fd8b60
    2) "Kerberos for Windows" 64-bit amd64 MSI package
Packit fd8b60
Packit fd8b60
       Upgrade code {6DA9CD86-6028-4852-8C94-452CAC229244}
Packit fd8b60
       Upto current release
Packit fd8b60
Packit fd8b60
    2) "MIT Project Pismere Kerberos for Windows" MSI package and 
Packit fd8b60
       "MIT SWRT Kerberos for Windows" MSI
Packit fd8b60
Packit fd8b60
       Upgrade code {83977767-388D-4DF8-BB08-3BF2401635BD}
Packit fd8b60
       All versions
Packit fd8b60
Packit fd8b60
    3) "Kerberos for Windows" NSIS package
Packit fd8b60
Packit fd8b60
       All versions
Packit fd8b60
Packit fd8b60
       Note that versions of the "Kerberos for Windows" NSIS package had
Packit fd8b60
       a bug where it couldn't be uninstalled properly in unattended
Packit fd8b60
       mode.  Therefore the MSI package will not try to uninstall an
Packit fd8b60
       "Kerberos for Windows" NSIS package if running unattended.  This
Packit fd8b60
       means that group policy based deployments will fail on machines
Packit fd8b60
       that have the "Kerberos for Windows" NSIS package installed.
Packit fd8b60
Packit fd8b60
       Note that the NSIS package is only available for 32-bit i386.
Packit fd8b60
       You cannot install both the 32-bit NSIS and 64-bit amd64 MSI 
Packit fd8b60
       packages on the same machine.  To install both 32-bit and 64-bit
Packit fd8b60
       KFW, you must use the MSI packages of both.
Packit fd8b60
Packit fd8b60
    If you have used a different MSI package to install Kerberos for
Packit fd8b60
    Windows and wish to upgrade it you can author rows into the
Packit fd8b60
    'Upgrade' table to have the "Kerberos for Windows" MSI replace these
Packit fd8b60
    installations for you.
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
Packit fd8b60
6.  FAQ
Packit fd8b60
Packit fd8b60
    (Q/A's will be added here as needed)
Packit fd8b60
Packit fd8b60
----------------------------------------------------------------------
Packit fd8b60
$Id$
Packit fd8b60