logo_kerberos.gif

Difference between revisions of "Kerberos for Windows Release Engineering"

From K5Wiki
Jump to: navigation, search
(Move some issues into the (new) "we think they're fixed" category)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Release Engineering notes for the Kerberos for Windows 4.0.0 release
+
[[Category: Kerberos for Windows]]
  +
Release Engineering notes for the Kerberos for Windows 4.2.0 release
   
 
Software to test against new builds:
 
Software to test against new builds:
Line 7: Line 7:
 
* SPNEGO (in multiple browsers?)
 
* SPNEGO (in multiple browsers?)
 
* Adobe Keyserver a.k.a the Sassafras key client
 
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
 
  +
* SMTP/IMAP via Thunderbird (must disable SSPI though?)
 
* LDAP in some form?
 
* LDAP in some form?
* XMPP in some form (pidgin?)?
+
* XMPP via, e.g., Pidgin
   
 
Upgrades scenarios to test:
 
Upgrades scenarios to test:
Line 19: Line 19:
 
* 64-bit to 32-bit, from 4.0
 
* 64-bit to 32-bit, from 4.0
 
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.
 
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.
  +
The NSIS upgrade path is a separate codepath and should be tested separately.
   
 
Current known issues:
 
Current known issues:
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
+
* The version number implanted in various dlls no longer reflects the underlying krb5 version (instead using the KfW version); this may not actually be a bug.
* windows/README is outdated
+
* (Version) upgrades that go from 64-bit to 32-bit leave 64-bit binaries around but otherwise succeed.
* Thunderbird cannot do GSSAPI auth
 
   
Issues that we believe to be resolved:
 
  +
See [[Kerberos_for_Windows_(KfW)_Build_Environment]] for notes on setting up the build environment.
* The uninstaller prompts to kill running processes but does not do succeed in doing so. There may be cases in which it just kills processes without prompting, which may still be a bug.
 
  +
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
 
  +
Each KfW u.v release line takes place on a krb5-x.y branch. For instance, KfW 4.2 takes place on the krb5-1.17 branch. A KfW release tag is kfw-u.v[.w]-{final|betaN}[-mit]. (The WiX installer configuration does not currently have support for alpha versions.)
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used
 
  +
* Uninitialized (NULL) TLS pointers that were most prominent on multi-processor machines, causing internal ccache errors that were reported as "unknown error" due to another minor bug.
 
  +
If the calendar year has changed since the last branch maintenance, pull up the commit updating the project-wide copyright years from the master branch before preparing KfW releases. Make sure src/windows/version.rc is updated in this commit.
  +
  +
There are two versions of each release, one for MIT-internal use and one for external use. The MIT-internal version install a short krb5.ini file to set the default realm and a few domain_realm mappings.
  +
  +
Each release has three associated branch commits and two associated tags. The commits can be produced on Linux, pushed to a private github fork, and checked out on the Windows VM while testing the build process, then pushed to the authoritative repository when basic testing is complete.
  +
  +
* Updates for kfw-u.v[.w]-final-mit (or kfw-u.v[.w]-betaN-mit)
  +
** In src/patchlevel.h, define KRB5_RELTAIL and KRB5_RELTAG to the tag name (e.g. kfw-u.v-final-mit). They should have the same value.
  +
** In src/windows/installer/wix/site-local.wxi, define Beta to the beta number of the release if it is a beta, or comment out the define tag if it is not. Define VersionMajor, VersionMinor, and VersionPatch to match the intended u.v[.w] version. If this is the first KfW commit on the krb5-x.y branch, uncomment the definition of Release.
  +
** In src/windows/kerberos.ver, define KRB5_RELTAIL to "betaN" if this is a beta release. Change it to "/* #undef KRB5_RELTAIL */" if this is a final release. Set KRB5_MAJOR_RELEASE, KRB5_MINOR_RELEASE, and KRB5_PATCHLEVEL to match the intended u.v version. If this is the first KfW commit on the branch, remove the line defining KRB5_RELTAG.
  +
** In src/windows/winlevel.h, increment KRB5_BUILDLEVEL. If this is the first KfW commit on the branch, leave it at 0.
  +
** Tag this commit with the release tag name with the suffix "-mit".
  +
** Create a source zip achive with "git archive --prefix=<tagname> --format=zip -o /path/to/<tagname>-src.zip <tagname>". Sign it with gpg -ab filename.zip to produce the detached .asc signature.
  +
** Build this release with "set NODEBUG=1" and "set MIT_INTERNAL=1".
  +
** Sign the kfw32.msi and kfw64.msi files (see below) and copy them out to be installed with the appropriate names in /mit/kerberos/dist/kfw/u.v.
  +
  +
* Updates for kfw-u.v[.w]-final (or kfw-u.v[.w]-betaN)
  +
** In src/patchlevel.h, remove the "-mit" from KRB5_RELTAIL and KRB5_RELTAG. They should still have the same value as each other.
  +
** In src/windows/winlevel.h, increment KRB5_BUILDLEVEL.
  +
** Tag this commit with the release tag name without the "-mit" suffix.
  +
** Build this release with "set NODEBUG=1" but not MIT_INTERNAL. Sign and copy out the kfw32.msi and kfw64.msi files again.
  +
  +
* Back to krb5-x.y-postrelease
  +
** In src/patchlevel.h, define KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y".
  +
  +
The code signing command is:
  +
  +
signtool sign /v /d "MIT Kerberos for Windows installer" /a /fd sha256 /tr http://timestamp.comodoca.com /td sha256 foo.msi
  +
  +
MSI signatures can be verified with "signtool verify /v /pa foo.msi".
  +
  +
The web page presence for KfW releases is:
  +
  +
* /mit/kerberos/kfw-u.v/kfw-u.v.html
  +
* /mit/kerberos/kfw-u.v/kfw-u.v/kfw-u.v-help
  +
* /mit/kerberos/index.html (just the current release link; we haven't written news items since kfw-3.2)
  +
* /mit/kerberos/dist/historic.html (for old releases)
  +
* /mit/kerberos/dist/index.html
  +
* /mit/kerberos/dist/testing.html (for testing releases)
  +
* /mit/kerberos/dist/kfw/u.v (MSI files, source zip files, signatures)
  +
  +
We used to produce debug symbols during the build, by setting DEBUG_SYMBOL=1 during the build (but not while building the installer) and copying aside the *.pdb files from %KRB_INSTALL_DIR%\bin. We did not do this for KfW 4.2.
  +
  +
Use the arCHMage package to extract HTML from the CHM file for the web. The tool outputs some bogus absolute URLs for links and inline images, so use
  +
  +
perl -pi -e 's,((?:href|src)=")/,\1../,g' */*
  +
  +
to postprocess.

Latest revision as of 13:13, 7 April 2019

Release Engineering notes for the Kerberos for Windows 4.2.0 release

Software to test against new builds:

  • SapGUI
  • OpenAFS
  • SecureCRT (and SecureFX?)
  • SPNEGO (in multiple browsers?)
  • Adobe Keyserver a.k.a the Sassafras key client
  • SMTP/IMAP via Thunderbird (must disable SSPI though?)
  • LDAP in some form?
  • XMPP via, e.g., Pidgin

Upgrades scenarios to test:

  • 32-bit to 32-bit, from 3.2
  • 64-bit to 64-bit, from 3.2
  • 32-bit to 64-bit, from 3.2
  • 32-bit and 64-bit to 64-bit, from 3.2
  • 32-bit to 64-bit, from 4.0
  • 64-bit to 32-bit, from 4.0

When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version. The NSIS upgrade path is a separate codepath and should be tested separately.

Current known issues:

  • The version number implanted in various dlls no longer reflects the underlying krb5 version (instead using the KfW version); this may not actually be a bug.
  • (Version) upgrades that go from 64-bit to 32-bit leave 64-bit binaries around but otherwise succeed.

See Kerberos_for_Windows_(KfW)_Build_Environment for notes on setting up the build environment.

Each KfW u.v release line takes place on a krb5-x.y branch. For instance, KfW 4.2 takes place on the krb5-1.17 branch. A KfW release tag is kfw-u.v[.w]-{final|betaN}[-mit]. (The WiX installer configuration does not currently have support for alpha versions.)

If the calendar year has changed since the last branch maintenance, pull up the commit updating the project-wide copyright years from the master branch before preparing KfW releases. Make sure src/windows/version.rc is updated in this commit.

There are two versions of each release, one for MIT-internal use and one for external use. The MIT-internal version install a short krb5.ini file to set the default realm and a few domain_realm mappings.

Each release has three associated branch commits and two associated tags. The commits can be produced on Linux, pushed to a private github fork, and checked out on the Windows VM while testing the build process, then pushed to the authoritative repository when basic testing is complete.

  • Updates for kfw-u.v[.w]-final-mit (or kfw-u.v[.w]-betaN-mit)
    • In src/patchlevel.h, define KRB5_RELTAIL and KRB5_RELTAG to the tag name (e.g. kfw-u.v-final-mit). They should have the same value.
    • In src/windows/installer/wix/site-local.wxi, define Beta to the beta number of the release if it is a beta, or comment out the define tag if it is not. Define VersionMajor, VersionMinor, and VersionPatch to match the intended u.v[.w] version. If this is the first KfW commit on the krb5-x.y branch, uncomment the definition of Release.
    • In src/windows/kerberos.ver, define KRB5_RELTAIL to "betaN" if this is a beta release. Change it to "/* #undef KRB5_RELTAIL */" if this is a final release. Set KRB5_MAJOR_RELEASE, KRB5_MINOR_RELEASE, and KRB5_PATCHLEVEL to match the intended u.v version. If this is the first KfW commit on the branch, remove the line defining KRB5_RELTAG.
    • In src/windows/winlevel.h, increment KRB5_BUILDLEVEL. If this is the first KfW commit on the branch, leave it at 0.
    • Tag this commit with the release tag name with the suffix "-mit".
    • Create a source zip achive with "git archive --prefix=<tagname> --format=zip -o /path/to/<tagname>-src.zip <tagname>". Sign it with gpg -ab filename.zip to produce the detached .asc signature.
    • Build this release with "set NODEBUG=1" and "set MIT_INTERNAL=1".
    • Sign the kfw32.msi and kfw64.msi files (see below) and copy them out to be installed with the appropriate names in /mit/kerberos/dist/kfw/u.v.
  • Updates for kfw-u.v[.w]-final (or kfw-u.v[.w]-betaN)
    • In src/patchlevel.h, remove the "-mit" from KRB5_RELTAIL and KRB5_RELTAG. They should still have the same value as each other.
    • In src/windows/winlevel.h, increment KRB5_BUILDLEVEL.
    • Tag this commit with the release tag name without the "-mit" suffix.
    • Build this release with "set NODEBUG=1" but not MIT_INTERNAL. Sign and copy out the kfw32.msi and kfw64.msi files again.
  • Back to krb5-x.y-postrelease
    • In src/patchlevel.h, define KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y".

The code signing command is:

 signtool sign /v /d "MIT Kerberos for Windows installer" /a /fd sha256 /tr http://timestamp.comodoca.com /td sha256 foo.msi

MSI signatures can be verified with "signtool verify /v /pa foo.msi".

The web page presence for KfW releases is:

  • /mit/kerberos/kfw-u.v/kfw-u.v.html
  • /mit/kerberos/kfw-u.v/kfw-u.v/kfw-u.v-help
  • /mit/kerberos/index.html (just the current release link; we haven't written news items since kfw-3.2)
  • /mit/kerberos/dist/historic.html (for old releases)
  • /mit/kerberos/dist/index.html
  • /mit/kerberos/dist/testing.html (for testing releases)
  • /mit/kerberos/dist/kfw/u.v (MSI files, source zip files, signatures)

We used to produce debug symbols during the build, by setting DEBUG_SYMBOL=1 during the build (but not while building the installer) and copying aside the *.pdb files from %KRB_INSTALL_DIR%\bin. We did not do this for KfW 4.2.

Use the arCHMage package to extract HTML from the CHM file for the web. The tool outputs some bogus absolute URLs for links and inline images, so use

   perl -pi -e 's,((?:href|src)=")/,\1../,g' */*

to postprocess.