Difference between revisions of "Kerberos for Windows (KfW) 3.2.x Build Environment"

Latest revision as of 15:02, 19 September 2012

Note: this article is archival content, and is believed to describe the procedure needed to generate a build environment for Kerberos for Windows 3.2.x, which is no longer the current version. The build environment for Kerberos for Windows 4.x is different and is described elsewhere.

Kerberos for Windows (KfW) is a specialized distribution of MIT Kerberos targeting the Windows platform. This document describes how to setup your development environment to build KfW.

Overview

The KfW build is automated by a set of Perl scripts and uses a combination of GNU and Microsoft tools to assemble the final build. In the following sections, we’ll outline the required components to run the build system.

Source Control Access

The Kerberos source tree is currently split over two source control systems. Current source is managed using Subversion (SVN), while legacy code is managed using the Concurrent Versioning System (CVS). The Cygwin distribution provides an SVN client that can be used with our Kerberized SVN repository.

Kerberized Access

Both source control systems support Kerberos authentication. In order to execute the KfW build script, you must use the Kerberos authentication mechanism as the script is not designed to prompt for passwords. Unfortunately, neither the CVS nor SVN client natively supports Kerberos authentication.

In order to provide Kerberized access for SVN, you must use a Kerberized SSH client in conjunction with the standard SVN client included with Cygwin. (In this guide, we will use a special build of PuTTY to accomplish this.)

In order to provide Kerberized access for CVS, we will use a custom build of the CVS client that supports Kerberos authentication.

Required Tools

Source Control

• CVS with Kerberos Support
• SVN
• PuTTY

Scripting Support

• Cygwin (v1.5 or later)
  • Provides the sed, awk, cat, rm, and find utilities.
• ActiveState Perl (v5.10.0.1005 or later)

Compilers and Libraries

• Microsoft Visual Studio (v2005 SP1 or later)
• Microsoft Windows SDK (v6.1 or later)

Documentation Generation

• Doxygen
• Microsoft HTML Help Workshop
• Microsoft Windows Help Authoring Kit

Installation Packagers

• Windows Installer XML (WiX) toolset
• Nullsoft Scriptable Install System (NSIS)

Setting up Source Control Access

In order to access the SVN repository, we will need to install and configure Cygwin, the KFW binaries (for Kerberized source control access), PuTTY, and a custom build of the CVS client.

Please note: Prior to testing any of the configurations described below, please be sure that you have been granted permissions to access the SVN and CVS repositories. PuTTY will throw unintelligible errors if permissions have not been set properly.

Installing and Cygwin and SVN

1. Download a copy of the Cygwin installer here. Save it too your local machine (note the location, as this executable is required to make any modifications to you Cygwin distribution).
2. Run setup.exe
3. Click Next through the introduction and download screens, accepting the default values.
4. When prompted, change the root directory of the Cygwin installation to C:\tools\cygwin, and click Next.
5. When choosing a directory to store the installation packages, you may accept the default, though this might place the files in temporary internet files directory. If you want these packages to be available for reinstallation at a later time, choose a more suitable directory (i.e. C:\cyginstall). Click Next.
6. Leave the default connection settings, and click Next
7. Choose a download site from the list, and click Next
8. In the Choose Packages screen, mark the Devel/Subversion package for installation, and click Next. The installer will proceed to download and install the selected packages.
9. Click Finish. The installer will close.
10. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
11. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\tools\cygwin\bin to the variable. Click OK on each window to close it, accepting changes.
12. Open Windows Explorer and navigate to the Cygwin bin directory (C:\tools\cygwin\bin).
13. Delete awk.exe (this is a symbolic link that the Windows shell doesn't handle properly).
14. Copy gawk.exe and rename it to awk.exe.

Installing the KfW Binaries

If you are not currently using a pre-built version of KfW, you'll need to install one now in order to use Kerberized source control access.

1. Download a copy of the MIT Kerberos for Windows MSI installer here. Run the MSI.
2. Accept the default install options.
3. Once setup completes, launch the Network Identity Manager (NIM) from the Kerberos for Windows folder in the Start Menu. By default, it should be configured for the ATHENA.MIT.EDU realm.
4. Create new credentials using you Athena username and password, and minimize NIM (this should hide it in the taskbar).

Installing PuTTY

PuTTY will provide the Kerberized SSH connection to our SVN repository.

1. Download a copy of the PuTTY with GSSAPI Extensions archive here. Note, there are several distributions of PuTTY that support Kerberos. You may choose the one that works best for you.
2. Unzip the archive to C:\tools\putty.
3. Launch C:\tools\putty\putty.exe.
4. Using the tree on the left, navigate to the Connection -> Data screen and enter your Athena username as the Auto-login username.
5. Open the Connection --> SSH --> Auth screen. In Authentication Methods, select Attempt "keyboard-interactive" auth (SSH-2) and Attempt Kerberos 5 GSSAPI/SSPI auth (SSH-2). In Authentication parameters, select Allow Kerberos 5 ticket forwarding in GSSAPI/SSF and enter ATHENA.MIT.EDU as the Server realm.
6. Open the Session screen. Select (highlight) Default Settings from the list and click Save.
7. Close the PuTTY configuration windows.

Configuring SVN & PuTTY

1. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
2. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\tools\putty to the variable. Click OK on each window to close it, accepting changes.
3. Under the System Variables list, add a SVN_SSH variable and give it the value plink.exe.
4. Create a directory to house a temporary SVN snapshot (i.e. C:\kfw\svn).
5. Open the Command Prompt (Start -> Run -> cmd) and type:

   plink svn.mit.edu

   Please note, it's important to run plink once before attempting to use it with SVN, because when connecting to the server for the first time there will be interactive prompts that SVN does not support.

6. You may be prompted to add the server to your trusted list. If so, type y and hit Enter. Once the connection completes, hit Ctrl+C to end plink. It should not prompt you for a password at any time. If so, your Kerberos credentials have not been configured correctly or have expired.
7. Now that we've confirmed plink is working with a Kerberized connection, we need to checkout a snapshot of the SVN repository. In the Command Prompt type:

   svn co svn+ssh://svn.mit.edu/krb5/trunk C:\kfw\svn

If your SVN client is properly configured, you should get a complete snapshot of the Krb5 trunk from the SVN repository, now located in C:\kfw\svn (or another directory of your choosing).

Installing CVS

1. Download a copy of CVS that supports Kerberos authentication. While there doesn't appear to be a readily accessible CVS client distribution that supports Kerberos, you can use the cvs client found here.
2. Move the file to your Cygwin binary directory (i.e. C:\tools\cygwin\bin).

Configuring the Build Tools

Now that we have access to the repositories and have a snapshot of the SVN trunk, we need to install the required Microsoft libraries. We also need to install ActiveState Perl in order to run the build script. Finally, we need to install the remaining build tools required for documentation generation and packaging.

Configuring Microsoft Visual Studio

This guide assumes you have a working version of Microsoft Visual Studio 2005 Standard or later. Be sure to install the 64 bit libraries in addition to the standard 23 bit libraries if you intend to build for both architectures.

Installing the Microsoft Windows SDK

1. Download a copy of the Microsoft Windows SDK (version 6.1 or later) here.
2. Run the installer, accepting all default options (though you may need to select the 64 bit libraries if desired).

Installing ActiveState Perl

1. Download a copy of ActiveState Perl (currently version 5.10.0.1005) here.
2. Run the installer, accepting all default options. This should automatically add the Perl directory to your system path.

Installing Microsoft HTML Help Workshop

1. Download a copy of Microsoft HTML Help Workshop (currently version 1.3) here.
2. Run the installer, accepting all default options. Please note, the installer may complain that you already have a newer version of Help Workshop installed. Ignore this error; the installer will complete successfully..
3. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
4. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\Program Fles\HTML Help Workshop to the variable. Click OK on each window to close it, accepting changes.

Installing the Windows Help Authoring Kit

Depending on your build configuration, you may also need the Windows Help Authoring Kit.

1. Download a copy of the Windows Help Authoring Kit here.
2. Run the installer, accepting all default options.
3. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
4. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\Program Fles\Help Workshop to the variable. Click OK on each window to close it, accepting changes.

Installing Doxygen

1. Download a copy of the Doxygen distribution for Windows (currently version 1.5.9) here.
2. Run the installer, accepting all default options. This should automatically add the Doxygen directory to your system path.

Installing WiX

1. Download a copy of the Windows Install XML (WiX) core toolset (currently version 2.0) here.
2. Unzip the archive to C:\tools\wix.
3. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
4. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\tools\wix to the variable. Click OK on each window to close it, accepting changes.

Installing NSIS

1. Download a copy of the Nullsoft Scriptable Install System (NSIS - currently version 2.45) here.
2. Run installer, accepting all default options.
3. Open the Control Panel -> System applet. Click the Advanced tab and click Environment Variables.
4. Under the System Variables list, double-click Path (possibly listed as PATH), add a semicolon after the last entry and add C:\Program Files\NSIS to the variable. Click OK on each window to close it, accepting changes.

Installing Windows Support Tools

On some machines you may need to install the Windows XP SP2 Support Tools package to get the filever.exe utility (which is currently required by the build script).

1. Download a copy of the Windows XP SP2 Support Tools package here.
2. Run the installer, accepting all default options.