View source for 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.12.0 source code repository as of 2009-12-09. 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.12.0 release, you will need:

* A Fedora 12 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 10GB 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 build both a 32

= Starting From A Fedora 12 Live Boot =

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

== Install and Update Fedora 12 ==

=== Download ISO ===

Download the Fedora 12 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 12 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.

=== Update OS ===

When building the active (''trunk'') version of the NST (2.12.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 was 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.12.0 source tree will migrate to ''$SVNROOT/maintenance/2.12.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 check 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
 #
 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 our ''/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 $LIVE_ROOT
 #
 # Useful variables:
 #
 # INSTALL_ROOT - Top level directory that build is under (you can reach
 # the isolinux directory from this variable.
 #
 # LIVE_ROOT    - Root (/) view of file system for live build
 
 %post --nochroot
 
 # Install our ssh keys
 if [ -d /root/.ssh ]; then
   [ -d ${LIVE_ROOT}/root/.ssh ] && /bin/rm -fr ${LIVE_ROOT}/root/.ssh;
   cp -rp /root/.ssh ${LIVE_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.12.0 of the NST.