logo_kerberos.gif

Difference between revisions of "Kerberos for Windows Release Engineering"

From K5Wiki
Jump to: navigation, search
 
Line 1: Line 1:
 
[[Category: Kerberos for Windows]]
 
[[Category: Kerberos for Windows]]
Release Engineering notes for the Kerberos for Windows 4.0.0 release
+
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 24: Line 24:
 
Current known issues:
 
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.
 
* 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.
 
* (Version) upgrades that go from 64-bit to 32-bit leave 64-bit binaries around but otherwise succeed.
   
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
 
* 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.
 
* Thunderbird cannot do GSSAPI auth unless you disable SSPI
 
* Our DllMain attach/detach handler spews to the terminal when running command-line utilities. Possibly other debug print statements, too.
 
   
Versioning stuff:
 
  +
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.)
   
* src/patchlevel.h
 
  +
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.
* src/windows/installer/wix/site-local.wxi
 
* src/windows/version.rc (copyright year)
 
* src/windows/winlevel.h
 
* src/windows/kerberos.ver
 
   
Procedure for building release binaries (MIT and non-MIT, i386 and amd64):
 
  +
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.
   
On the VM host:
 
  +
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.
 
  +
rm -rf /path/to/share/kfw-4.1-beta2 && git archive --prefix=kfw-4.1-beta2/ [committish] | (cd /path/to/share/; tar x)
 
  +
* Updates for kfw-u.v[.w]-final-mit (or kfw-u.v[.w]-betaN-mit)
rm -rf /path/to/share/kfw-4.1-beta2-mit && git archive --prefix=kfw-4.1-beta2-mit/ [committish] | (cd /path/to/share/; tar x)
 
  +
** 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.
git archive --prefix=kfw-4.1-beta2/ --format=zip -o ../kfw-4.1-beta2-src.zip refs/tags/kfw-4.1-beta2
 
  +
** 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.
mkdir C:\destdir
 
  +
** Tag this commit with the release tag name with the suffix "-mit".
mkdir C:\debug-symbols
 
  +
** 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.
mkdir C:\debug-symbols\kfw-NNN-i386-mit
 
  +
** Build this release with "set NODEBUG=1" and "set MIT_INTERNAL=1".
mkdir C:\debug-symbols\kfw-NNN-amd64-mit
 
  +
** 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.
mkdir C:\debug-symbols\kfw-NNN-i386
 
  +
mkdir C:\debug-symbols\kfw-NNN-amd64
 
  +
* Updates for kfw-u.v[.w]-final (or kfw-u.v[.w]-betaN)
setenv /x86 /release
 
  +
** In src/patchlevel.h, remove the "-mit" from KRB5_RELTAIL and KRB5_RELTAG. They should still have the same value as each other.
set CPU=i386
 
  +
** In src/windows/winlevel.h, increment KRB5_BUILDLEVEL.
set KRB_INSTALL_DIR=C:\destdir
 
  +
** Tag this commit with the release tag name without the "-mit" suffix.
set NODEBUG=1
 
  +
** Build this release with "set NODEBUG=1" but not MIT_INTERNAL. Sign and copy out the kfw32.msi and kfw64.msi files again.
set DEBUG_SYMBOL=1
 
  +
set MIT_INTERNAL=1
 
  +
* Back to krb5-x.y-postrelease
# do the MIT i386 build
 
  +
** In src/patchlevel.h, define KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y".
cd C:\kfw-NNN-mit\src
 
  +
nmake -f Makefile.in prep-windows
 
  +
The code signing command is:
nmake
 
  +
nmake install
 
  +
signtool sign /v /d "MIT Kerberos for Windows installer" /a /fd sha256 /tr http://timestamp.comodoca.com /td sha256 foo.msi
set DEBUG_SYMBOL= # unset it
 
  +
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-i386-mit
 
  +
MSI signatures can be verified with "signtool verify /v /pa foo.msi".
cd windows\installer\wix
 
  +
nmake
 
  +
The web page presence for KfW releases is:
rename kfw.msi kfw-NNN-i386-mit.msi
 
  +
# time for the MIT amd64 build
 
  +
* /mit/kerberos/kfw-u.v/kfw-u.v.html
cd ..\..\..
 
  +
* /mit/kerberos/kfw-u.v/kfw-u.v/kfw-u.v-help
setenv /x64 /release
 
  +
* /mit/kerberos/index.html (just the current release link; we haven't written news items since kfw-3.2)
set CPU=AMD64
 
  +
* /mit/kerberos/dist/historic.html (for old releases)
set DEBUG_SYMBOL=1
 
  +
* /mit/kerberos/dist/index.html
nmake clean
 
  +
* /mit/kerberos/dist/testing.html (for testing releases)
nmake
 
  +
* /mit/kerberos/dist/kfw/u.v (MSI files, source zip files, signatures)
nmake install
 
  +
set DEBUG_SYMBOL= # unset it
 
  +
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.
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-amd64-mit
 
cd windows\installer\wix
 
nmake clean
 
nmake
 
rename kfw.msi kfw-NNN-amd64-mit.msi
 
rm -r C:\destdir\bin
 
rm -r C:\destdir\lib
 
rm -r C:\destdir\include
 
# fresh env for the non-MIT i386 build
 
setenv /x86 /release
 
set CPU=i386
 
set DEBUG_SYMBOL=1
 
set MIT_INTERNAL= # unset it
 
cd C:\kfw-NNN\src
 
nmake -f Makefile.in prep-windows
 
nmake
 
nmake install
 
set DEBUG_SYMBOL= # unset it
 
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-i386
 
cd windows\installer\wix
 
nmake
 
rename kfw.msi kfw-NNN-i386.msi
 
cd ..\..\..
 
# the non-MIT amd64 build
 
setenv /x64 /release
 
set CPU=AMD64
 
set DEBUG_SYMBOL=1
 
nmake clean
 
nmake
 
nmake install
 
set DEBUG_SYMBOL= # unset it
 
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-amd64
 
cd windows\installer\wix
 
nmake clean
 
nmake
 
rename kfw.msi kfw-NNN-amd64.msi
 
[copy C:\kfw-NNN{,-mit}\src\windows\installer\wix\*.msi to the shared drive]
 
[recursively copy C:\debug-symbols\kfw-NNN* to the shared drive]
 
 
On the VM host, extract the build output for signing.
 
   
 
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
 
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

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.