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

Revision as of 14:50, 24 July 2009

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

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

Scripting Support

As mentioned above, the Cygwin distribution is used to provide source control access clients. The distribution also provides several tools required by the KfW build script. These include sed, awk, cat, rm, and find. The script itself is written in Perl designed to be executed by ActiveState Perl.

Compilers and Libraries

The KfW build script requires the Microsoft Visual Studio build tools to assemble the KfW binaries. The Microsoft Platform SDK is required to provide the necessary libraries for the KfW build.

Documentation

External documentation is automatically generated by Doxygen as part of the build script.

Installation Packagers

The build script uses both the Windows Installer XML (WiX) toolset, as well as the 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.

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 configuration is properly setup, 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).