HowTo Build NST 2.13.0

General

This document describes the steps involved in building the NST distribution from the source. This document is written against the state of the NST v2.13.0 source code repository as of 2010-09-13. Things will undoubtedly change in the future - but the basic principles should still hold.

Building a NST system from the source is not a trivial process (expect to invest time and resources). However, building your own NST system from the ground allows you to produce a customized build.

Requirements

In order to build the NST v2.13.0 release, you will need:

• A Fedora 13 based OS installation matching the NST target build. For example, to build a 64 bit version of the NST, you will need to start with a 64 bit Fedora based OS installation.
• Access to the root account on the build system.
• At least 12GB of available free disk space.
• The understanding that the process of building the NST will modify the software and configuration of your build system.
• Broadband Internet access as the initial build process will pull several gigabytes of information down from the Internet.

Recommendations

The general recommendations for a NST build system are as follows:

• Dedicate a machine or virtual machine for the single purpose of building the NST ISO. Since the NST build runs as root and modifies the OS installation, you should NOT use a production machine as your NST build machine.
• We recommend allocating 40GB of storage and 1GB of RAM when creating a NST build machine.
• We have used both VMware and VirtualBox to create NST build machines. Using the virtual machine approach increases the build time, but makes life much more convenient in the long run (you can use one physical machine to setup multiple development machines).

Starting From A Fedora 13 Live Boot

The following outlines the steps for bringing up a NST development system starting from a Fedora 13 Live ISO image.

Install and Update Fedora 13

Download ISO

Download the Fedora 13 ISO image from Fedora's web site (http://fedoraproject.org/). Important: Make sure you download either the 32 bit (i686) or 64 bit (x86_64) version of the Fedora Desktop Live Media (match the version of the NST you plan to build).

Install OS

• Boot the Fedora 13 ISO image.
• If you simply wait, you should eventually see a desktop with a Install To Hard Drive icon.
• Double click on the Install To Hard Drive icon.
• Install the system making sure you have at least 12GB of free space remaining for the NST build (at a minimum allocate at least 20GB of disk for the system).
• After the installation completes, Shutdown the system and remove the DVD (in a virtual environment, you will disconnect the ISO image).
• Boot the system and follow the instructions to complete the installation.

NOTE: You will not be able to log into the GNOME desktop as the root user. If you would like to be able to do this (you will need to be root when building the NST), you will need to edit the files: /etc/pam.d/gdm' and /etc/pam.d/gdm-password.

Find the line:

auth        required    pam_succeed_if.so user != root quiet

Comment out the line by inserting a '#' character:

#auth        required    pam_succeed_if.so user != root quiet

You will need to restart the gdm process (or reboot your system) for the change to take affect.

Check SELINUX Setting

By default, Fedora will enable SELinux in Enforcing mode. Most likely, everything will build when in Enforcing mode. However, we have seen some circumstances (involving multiple disk partitions) when having SELinux set to Enforcing mode causes a failure in the build process.

Using the SELinux Troubleshooter utility can help determine whether a build failure is due to a SELinux issue.

If you want to avoid SELinux issues on your development machine, you can either disable SELinux or change it to Permissive mode. The following shows how the getenforce and setenforce commands can be used to change the selinux mode from Enforcing to Permissive:

[root@cirrus ~]# getenforce
Enforcing
[root@cirrus ~]# setenforce Permissive
[root@cirrus ~]# getenforce
Permissive
[root@cirrus ~]#

However, the above change only lasts until you reboot your machine. To make the change permanent, you need to edit the file: "/etc/sysconfig/selinux".

Update OS

When building the active (trunk) version of the NST (2.13.0 is the active version at the time of this writing), you will want to keep your system up to date with the latest packages. This can be done with the following command:

yum update all

You will need to reboot after this initial update as it is more than likely that your kernel will be updated.

Install Virtual Machine Guest Additions

If your NST is running under a virtual environment such as VMware or VirtualBox, you will want to install the appropriate guest additions for your virtual environment.

VirtualBox

If you are using VirtualBox, follow these steps:

• Install the following packages that are necessary to build the kernel modules:

yum install gcc kernel-devel

• From the Devices menu of VirtualBox, click on the Install Guest Additions options. If things go well, a virtual CD will appear on your GNOME desktop.

• Open a terminal window and login as root.

• Copy the contents of the CD to a temporary directory, run the installation script, and then remove the temporary directory (NOTE: While VBOX* will probably work as shown below, it is recommended to replace it with the actual directory name):

cp -rp /media/VBOX* /tmp/
cd /tmp/VBOX*
./VBoxLinuxAdditions-x86.run # NOTE: Run ./VBoxLinuxAdditions-amd64.run if 64 bit machine
cd
rm -fr /tmp/VBOX*

• Reboot the system

VMware

It is recommended to hold off installing the VMware tools at this point in time (unless you have easy access to them).

Once you complete the building of the NST, you will be able to install the open-vm-tools package from your build to install the guest additions.

Add Base Packages

To check out the NST source code, you will need the subversion package installed on your system:

yum install subversion

Checkout NST Source Code

Add the following line to the end of your ~/.bashrc file:

export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst

Source in your modified ~/.bashrc file, and check out a copy of the source code:

source ~/.bashrc
mkdir -p /opt/nst
cd /opt/nst
svn co $SVNROOT/trunk trunk

At this point, you should have a copy of the current development tree under /opt/nst/trunk (feel free to checkout the source code to the directory of your choosing).

NOTE: As time moves on, the source code under $SVNROOT/trunk will move to newer versions of Fedora releases. When this occurs, the 2.13.0 source tree will migrate to $SVNROOT/maintenance/2.13.0. For example, to check out the current maintenance version of the 2.11.0 source code to the directory: /opt/nst/2.11.0 you would perform the following steps:

source ~/.bashrc
mkdir -p /opt/nst
cd /opt/nst
svn co $SVNROOT/maintenance/2.11.0 2.11.0

Regardless of whether you are working against the trunk or a maintenance release, you should always be able to update your source code using the svn update command. For example:

cd /opt/nst/trunk
svn update

Configure Your System to Build the NST

At this point, you should be ready to begin the configuration of the NST software.

When your run the top level ./configure script, it will:

• Inspect your development system to see if there are any low level packages that are missing that must be installed by hand. If this condition is detected, your inspect your development system and determine if there are any packages missing on the system that need to be installed by hand (the script will fail, but should tell you what you need to install).

• Inspect your development system and automatically install (building if required) the remaining packages that are required in order to build the NST. This will take a long time the first time you configure your system as there are MANY additional packages that will be installed.

• The configure script may update system configuration files (for example, files found under the /etc) directory as well as create build specific configuration files. Since system configuration files may be modified, we always recommend that you dedicate a machine for the purpose of building the NST.

To run the top level ./configure script, change to the directory where you checked out the NST source code. For example:

cd /opt/nst/trunk
./configure

If the above fails, look at the last few lines of the output as it will probably indicate that there are some packages that need to be installed by hand (you should be able to copy/paste from the output).

This will configure the system such that you should be able to build the standard NST distribution (building a customized version of the NST will be discussed later).

You should run the ./configure script everytime you update the source code.

Build ISO

Once the system is configured, building the NST ISO image is not difficult (it just takes a long time).

Assuming that you've checked the source code out under the directory: /opt/nst/trunk, you should be able to build the NST ISO image using the following commands:

cd /opt/nst/trunk
make
ls -l livecd/*.iso

Here are some things to note:

• The build process will build a local copy of the RPMs found in the NST repository (this is done under the yum sub-directory).

• The build process will download a local copy of all of the RPMs making up the NST ISO image (these RPMs live under the livecd/cache sub-directory).

• The final ISO image produced will appear under the livecd directory.

Customizing Your Build

There are many command line options you can specify to the top level ./configure script. To see the various options that can be specified, run:

./configure --help | less

Instead of specifying a long set of parameters each time when invoking the ./configure command, it is recommended that you use standard configuration files to configure your build. The remaining sections will describe the files which can be used to customize your build.

Create the Configuration Directory (/root/.nst)

By default, when your run the ./configure script, it will assume the configuration directory is: /root/.nst. You can create this directory with the following command:

mkdir /root/.nst

/root/.nst/configure.sh

This file will be sourced by the ./configure script and allow you to override variables which change the build. The following shows a sample template of the most common variables you might want to adjust:

# Set the default password
NSTPASSWD="myNewPasswd";

#
# These are only used if your run "make test" or "make probe-check"
# from the top level directory
#

# Set the TEST_EXTENDED variable to "true" to enable test that take a long time to complete
TEST_EXTENDED="false";

# Following are related to tests requiring SMTP server access (tests that generate email)
TEST_SMTP_SERVER="smtp.linux.bogus";
TEST_SMTP_DOMAIN="linux.bogus";
TEST_SENDMAIL_FROM="first.last@linux.bogus";
TEST_SENDMAIL_TO="first.last@destination.bogus";

There used to be a lot more variables that could be "tweaked" in this file, but most of them have become deprecated since version 2.11.0 of the NST. You can review the file include/data/configure.in for a list of some of the other variables that can be overridden.

/root/.nst/custom.ks

This file (if present) is "tacked" onto the kickstart file used to create the NST live ISO image. If you are familiar with kickstart files, you can use this to add other packages to your NST distribution.

For example, lets assume that you wanted the following things to be done in your custom NST build:

• Include both the gcc and kernel-devel packages (as well as all the packages they depend on).
• Transfer the contents of your /root/.ssh configuration from the development system to the ISO image being built.
• Set the default proxy configuration for your local area network.

To accomplish this, you would create the file: /root/.nst/custom.ks with the following contents:

# This %packages block is used to indicate what extra packages we
# would like to include in the Live ISO image. The packages listed
# here along with any required dependencies will be added to the ISO.

%packages

# Pre-install gcc and kernel-devel to simplify installing VirtualBox
# guest additions
gcc
kernel-devel

%end


# This code runs non-chrooted. This allows us to transfer files from
# the host development system into the build image under $INSTALL_ROOT
#
# Useful variables:
#
# LIVE_ROOT - Top level directory of all the file that will appear in the
# ISO image.
#
# INSTALL_ROOT - The directory that is used to make the compressed file system
# image (/) that you see after booting (you'll find: /etc, /var, /usr, ... under here).

%post --nochroot

# Install our ssh keys
if [ -d /root/.ssh ]; then
  [ -d ${INSTALL_ROOT}/root/.ssh ] && /bin/rm -fr ${INSTALL_ROOT}/root/.ssh;
  cp -rp /root/.ssh ${INSTALL_ROOT}/root/.ssh;
fi

%end


# This %post block does not include the --nochroot option. It
# runs in a chroot environment under file system being created
# for the live boot (its as if you are running inside the live boot
# and unable to see the full development filesystem).

%post

# Set default proxy configuration
nstsetproxy --http-host 192.168.1.2 --http-port 3128

%end

This simple /root/.nst/custom.ks file provides the necessary hooks to allow you to extend, customize and tweak your NST ISO build as much as you want.

For more information about kickstart files, see: http://fedoraproject.org/wiki/Anaconda/Kickstart.

NOTE: The /root/.nst/custom.ks feature did not become available until version 2.13.0 of the NST.

Customizing The NST WUI CSS

If you would like to customize the look of the HTML produced by the nstweb and nstwui packages, you can do so by creating the file /root/.nst/site.css. The CSS commands which you specify within this file will override the default CSS provided by the packages.

For example, if you prefer to have less color in your tooltips, create the /root/.nst/site.css file and add the following:

/* Reduce the number of colors used in the tooltips */

div.niceTitle .ttCommand,
div.niceTitle .ttDocument,
div.niceTitle .ttSite,
div.niceTitle .ttNav,
div.niceTitle .ttValue,
div.niceTitle .ttAction,
div.niceTitle .ttAcronym,
div.niceTitle .ttEmphasis,
div.niceTitle .ttEmphasisPFont,
div.niceTitle .ttNote,
div.niceTitle .ttNotePFont {
  color: white;
}

When the nstweb and nstwui packages are built, the contents of /root/.nst/site.css will be appended to /usr/share/nstweb/css/domtt.css and /usr/share/nstwui/domtt.css as these normally the last CSS files are included on most of the HTML pages.