NST v2.x Guidelines: Difference between revisions

From MediaWiki
Jump to navigationJump to search
(RPM Build Tips - moved to RPM Quick Guide page)
 
(68 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= [[File:Warning.png]] Caution =
This page is a historical document of the decision making process when we made the major transition in the NST build framework from the '''1.8.1''' release to the '''2.11.0''' release. Do not treat this information as current.
= Overview =
= Overview =


Line 9: Line 13:
* Using '''livecd-creator''' will keep us Fedora compatible.
* Using '''livecd-creator''' will keep us Fedora compatible.


* Hard drive installation will be through standard Fedora tool.
* Hard drive installation will be through the standard Fedora tool.


* Migration to the next release of Fedora should be much less painful.
* Migration to the next release of Fedora should be much less painful.


* Much less effort required on our parts for installing the numerous Fedora packages we depend on.
* Much less effort required on our part for installing the numerous Fedora packages we depend on.


* Potential for creating our own '''yum''' repository (allowing one to update their NST system using a standard ''yum update'' invocation).
* Ability for creating our own '''yum''' repository (allowing one to update their NST system using a standard ''yum update'' invocation).


== Bad Things ==
== Bad Things ==
Line 26: Line 30:


The building of the NST ISO image will then involve the following steps:
The building of the NST ISO image will then involve the following steps:
* Verifying that selinux is in '''Permissive''' mode. After days of hair pulling, Ron finally discovered that the installation from a live boot to hard disk would fail if the ISO was originally created on a system with selinux in '''Disabled''' mode.


* The building of a local '''yum''' repository for packages which we want to continue building ourselves (or are not found in the Fedora repositories). This will be located under the top level  [http://nst.cvs.sourceforge.net/viewvc/nst/yum/ yum] directory.
* The building of a local '''yum''' repository for packages which we want to continue building ourselves (or are not found in the Fedora repositories). This will be located under the top level  [http://nst.cvs.sourceforge.net/viewvc/nst/yum/ yum] directory.
Line 42: Line 48:


* Change to the ''yum'' directory.
* Change to the ''yum'' directory.
* Run the '''./configure''' script.


* Run: '''make help | less''' to review what you can build.
* Run: '''make help | less''' to review what you can build.
* Run: '''yum install $(make build-requires)''' to make sure your development system has the necessary packages for building the yum repository.


* Run '''make all''' to build the repository (the files will appear under the ''repo'' sub directory).
* Run '''make all''' to build the repository (the files will appear under the ''repo'' sub directory).
Line 53: Line 55:
The command sequence looks something like the following:
The command sequence looks something like the following:


   nstcvs co -d nst .
   export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst
  svn co ${SVNROOT}/trunk nst
   cd nst
   cd nst
  ./configure
  cd yum
   ./configure
   ./configure
   make all
   make all
Line 69: Line 70:
   make all
   make all


IMPORTANT: The make dependencies will only rebuild if the associated pkginfo.xml file is modified. This means if you modify source code for the NST WUI, a ''make all'' under the ''yum'' area will NOT detect the change and may not rebuild the package. To force the building of a package, include ''NAME-remove'' on the command line. For example, to force the building of the ''nstwui'' and ''nst-icons'' packages, use the following:
IMPORTANT: The make dependencies rules won't necessarily detect changes to all of the source files related to a package. This means if you modify source code for a package, a ''make all'' under the ''yum'' area may NOT detect the change and may not rebuild the package. To force the building of a package, include ''NAME-remove'' on the command line. For example, to force the building of the ''nstwui'' and ''nst-icons'' packages, use the following:


   make nstwui-remove nst-icons-remove all
   make nstwui-remove nst-icons-remove all
Line 104: Line 105:
== Normal Build ==
== Normal Build ==


You need to be in the ''livecd'' sub-directory in order to build the ISO image.
You should be in the top level directory in order to build the ISO image.
 
cd livecd
 
Make sure you build your ''yum'' repository first (if you haven't done so yet):
 
make -C ../yum all


To build the ISO image:
To build the ISO image:
Line 119: Line 114:
For more possibilities use the ''help'' target:
For more possibilities use the ''help'' target:


make help | less
There are ISO specific targets under the ''livecd'' directory:
cd livecd
  make help | less
  make help | less


Line 151: Line 151:
If you have booted the NST system from a "live" DVD image, you can use the ''Live USB Creator'' interface from the ''fluxbox'' menu system to install the "live" version of NST directly onto a USB memory stick. To do so:
If you have booted the NST system from a "live" DVD image, you can use the ''Live USB Creator'' interface from the ''fluxbox'' menu system to install the "live" version of NST directly onto a USB memory stick. To do so:


* Bring up the ''fluxbox'' desktop (either on native X over via VNC).
* Bring up the ''Fluxbox'' desktop (either on native X over via VNC).


* Right click on the desktop to pull up the menu.
* Right click on the desktop to pull up the menu.


* Select ''System Utilities|Create Live USB Disk''.
* Select ''System Utilities|Create Live USB Disk''.
On a ''GNOME'' desktop, you can find the ''Fedora LiveUSB Creator'' tool on the ''Applications|System Tools'' menu.


==== Disk Preparation ====
==== Disk Preparation ====
Line 165: Line 167:
* If you have a large USB memory stick (8GB for example), you may be better off using FAT 32.
* If you have a large USB memory stick (8GB for example), you may be better off using FAT 32.


* You can format a filesystem as FAT 32 via:
* You can format a partition with a FAT 32 file system via (change ''/dev/sdu1'' as appropriate):


  mkdosfs -F 32 -n usbdrive /dev/sdb1
  mkdosfs -F 32 -n usbdrive /dev/sdu1


* If you use ''gparted'' to setup your partitions, make sure that the boot flag is set on the partition you install to (otherwise ''Live USB Creator'' will complain about the partition).
* If you use ''gparted'' to setup your partitions, make sure that the boot flag is set on the partition you install to (otherwise ''Live USB Creator'' will complain about the partition).
Line 195: Line 197:
* Press the ''Create Live USB'' button to begin the installation.
* Press the ''Create Live USB'' button to begin the installation.


=== Live USB Boot ===
Unfortunately, this ''/dev/sr0'' trick does not always seem to work. If it doesn't work from the GUI tool, try reading the man page for the '''liveusb-creator''' command line tool. You might be able to get it to work from the command line by including the ''--noverify'' option.
 
==== Menu Boot Choices ====
 
You can not use the ''Local'' boot method when booting from a ''live'' USB device. Feel free to delete this choice from your ''syslinux.cfg'' file.
 
==== Detecting Persistent Overlay ====
 
During a ''live'' boot, a overlay image is used. This overlay may be created in RAM, or it may be ''persistent'' in which case changes will be preserved across boots.
 
The current method for testing for the presence of a ''persistent'' overlay is to look for the presence of the string: "'''overlay='''" on the command line (''/proc/cmdline'').
 
==== Reset Persistent Overlay ====
 
A persistent overlay will eventually become full. When this happens, the root file system becomes a read-only file system and things go downhill rapidly. The solution to this problem is:
 
* Reboot the system.
 
* Select a boot option (like: ''Console'') from the boot choices menu.
 
* Edit the boot option and append the kernel parameter ''reset_overlay'' to the end of the line.
 
* Boot the system.
 
This should reset your persistent overlay to its original state allowing you to start over.


= USB Installation =
= USB Installation =
Line 231: Line 209:
Each method has its advantages and disadvantages.
Each method has its advantages and disadvantages.


=== Dual Boot NST Hard Disk Install/NST Live from USB ===
= Yum Tips =
 
It is possible to dual boot off of a USB memory stick. This allows one to put both the NST Live version and the NST hard disk installation on the same memory stick. This will require a memory stick of '''8GB''' or more.
 
The following steps are required:
 
* Setup up a '''2GB''' partition as primary partition 1 on the system according to the requirements of the ''liveusb-creator'' utility.
 
* Install the NST Live version onto the '''2GB''' partition using the "''System Utilities|Create NST Live USB Disk''" command from the ''fluxbox'' menu.
 
* Verify that the NST Live version installed boots.
 
* After booting NST Live, perform a full hard disk installation to the remaining portion of the memory stick use the "''System Utilities|Install NST Live To Disk''" command from the ''fluxbox'' menu.
 
* Reboot the system, it should boot up using the hard disk installation on your USB memory stick (you should see the ''grub'' boot loader).
 
* After logging in, add the following to your: ''/boot/grub.conf'' file:
 
title NST Live (for install)
      root (hd0,0)
      chainloader +1
 
* From this point on, when you boot off of your USB memory stick, you should see the ''grub'' boot loader come up and you should have the option to select "''NST Live (for install)''" from the ''grub'' boot screen.
 
 
NOTE: This may work for other USB devices (like a USB hard disk), but has not been tested.
 
= RPM Build Tips =
 
== RPM Reference Documentation ==
 
* [http://www.rpm.org/max-rpm-snapshot/ Maximum RPM] - Taking the RPM Package Manager to the Limit
* [http://docs.fedoraproject.org/drafts/rpm-guide-en/ Fedora RPM Guide] - Fedora RPM Reference Guide
 
== Tips on RPM "%macros" ==
 
To find the secret "%macros", try commands like:
 
rpmbuild --showrc | grep _ln
rpmbuild --showrc | grep share
 
To find RPM query format macros:
 
rpm --querytags | less
 
== HowTo: Show Spec File Scripts Within An RPM Package ==
 
Example: Show all scripts within the RPM package: '''"php-pear-Mail"'''
 
rpm -q php-pear-Mail --scripts | less
 
Example: To show post (%post) install scripts for RPM package: "'''nstwui'''"
 
rpm -q nstwui --queryformat "%{POSTIN}" | less
 
== The Available RPM "Groups" ==
 
The ''Group:'' line in a spec file should be set to one of the group names allowed by Fedora. Refer to the file: "/usr/share/doc/rpm-4.6.0/GROUPS" on your development system to see what group names are available.
 
== Downloading/Installing Source For A Fedora Package ==


You can use the ''yumdownloader'' and ''rpm'' commands to download (and install) the source code for most packages which can be ''yum'' installed. For example, the following demonstrates how to get the source code for the ''vnc-server'' package:
== Yum Reference Documentation ==


yumdownloader --source vnc-server
* [http://blog.kagesenshi.org/2008/04/12-yum-tips-and-tricks.html 12 YUM Tips and Tricks] - Yum Info
rpm -ivh vnc-4.1.3-1.fc10.src.rpm
ls ~/rpmbuild/SPECS ~/rpmbuild/SOURCES

Latest revision as of 12:18, 5 May 2013

Caution

This page is a historical document of the decision making process when we made the major transition in the NST build framework from the 1.8.1 release to the 2.11.0 release. Do not treat this information as current.

Overview

While looking at the effort involved in moving NST to Fedora 10, we decided that we wanted to spend less time and effort on package maintenance and focus more on WUI development. To accomplish this, we will migrate away from our custom ISO script building techniques (that we started back in 2003) and move to the livecd-creator mechanism that has become a part of the standard Fedora distribution.

Good Things

  • Users will have access to yum package manager and the ability to enhance (or trash) their NST systems to their hearts content.
  • Using livecd-creator will keep us Fedora compatible.
  • Hard drive installation will be through the standard Fedora tool.
  • Migration to the next release of Fedora should be much less painful.
  • Much less effort required on our part for installing the numerous Fedora packages we depend on.
  • Ability for creating our own yum repository (allowing one to update their NST system using a standard yum update invocation).

Bad Things

  • ISO will not fit on CD (will require DVD).
  • Build times may be slower and it may be difficult to test individual package installations without doing a full build.

General Build Guidelines

The building of the NST ISO image will then involve the following steps:

  • Verifying that selinux is in Permissive mode. After days of hair pulling, Ron finally discovered that the installation from a live boot to hard disk would fail if the ISO was originally created on a system with selinux in Disabled mode.
  • The building of a local yum repository for packages which we want to continue building ourselves (or are not found in the Fedora repositories). This will be located under the top level yum directory.
  • The building of the ISO using the standard livecd-creator package. This will involve many custom scripts for "tweaking" the default ISO image created. This will be located under the top level livecd directory.

Local Yum Repository

Initial Build

To build the NST Yum repository on a development machine (from scratch):

  • Checkout the NST source tree.
  • Run the top level ./configure script.
  • Change to the yum directory.
  • Run: make help | less to review what you can build.
  • Run make all to build the repository (the files will appear under the repo sub directory).

The command sequence looks something like the following: 

 export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst
 svn co ${SVNROOT}/trunk nst
 cd nst
 ./configure
 make all

NOTE: If the configure stage determines that your system is missing some packages, it should report what packages you need to install.

Subsequent Builds

After the initial build, you can use the following to update: 

 ./configure
 make all

IMPORTANT: The make dependencies rules won't necessarily detect changes to all of the source files related to a package. This means if you modify source code for a package, a make all under the yum area may NOT detect the change and may not rebuild the package. To force the building of a package, include NAME-remove on the command line. For example, to force the building of the nstwui and nst-icons packages, use the following: 

 make nstwui-remove nst-icons-remove all

Rebuilding Repository

If you want to rebuild your entire repository, remove the repo sub directory and then build: 

 rm -fr repo
 make all

Rebuilding Everything

If you want to re-download all of the source and rebuild your entire repository: 

 make nuke
 make all

Single Build

Once the yum area is configured, you can force the building of a single package. For example, if you want to force the build of the nst-config package, run: 

make nst-config-remove nst-config

Test Build

If you have a running instance of a NST system, you can force the building of a package and install it on the remote NST system. For example, to force the building of the nst-config and do a test installation on the NST at 192.168.100.10, run: 


make HOST=192.168.100.10 nst-config-remove nst-config-probe-install

ISO

Normal Build

You should be in the top level directory in order to build the ISO image.

To build the ISO image: 

./configure
make iso

For more possibilities use the help target: 

make help | less

There are ISO specific targets under the livecd directory: 

cd livecd
make help | less

Clean Build

For a clean build: 

make clean
./configure
make iso

Live USB Build

You can use the "liveusb USBDEV=USB_DEV" target to install the NST ISO image onto a USB flash drive (these drives are also known as: memory sticks and thumb drives). This will take a considerable amount of space on your thumb drive (you should have at least 1.5 GB of free space).

Before attempting this, you should review the How to create and use Live USB page at the Fedora Wiki. This page offers some useful troubleshooting tips as well.

The following demonstrates the make invocation to install the NST onto a USB flash drive. In this example invocation, I plugged in my flash drive and determined (through fdisk -l) that my flash drive partition was /dev/sdb1. Do not assume that your system will have the same device mapping if you specify a disk partition other than your USB flash drive, YOU WILL LIKELY DESTROY THE DATA ON THAT PARTITION! 

make liveusb USBDEV=/dev/sdb1

NOTE: This command can only be used after the NST ISO image has already been created.

NOTE: The flash drive should not be mounted (or at least it does not need to be mounted) when invoking this make target.

You may specify a persistent overlay value using: OVERLAY=SIZE_IN_MB. This persistent overlay is used between reboots to persist changes you may make to your system. If omitted, this value defaults to 512. You can specify a value up to 2048. The following example demonstrates a invocation setting up a 1024 MB overlay: 

make liveusb USBDEV=/dev/sdb1 OVERLAY=1024

liveusb-creator Notes

If you have booted the NST system from a "live" DVD image, you can use the Live USB Creator interface from the fluxbox menu system to install the "live" version of NST directly onto a USB memory stick. To do so:

  • Bring up the Fluxbox desktop (either on native X over via VNC).
  • Right click on the desktop to pull up the menu.
  • Select System Utilities|Create Live USB Disk.

On a GNOME desktop, you can find the Fedora LiveUSB Creator tool on the Applications|System Tools menu.

Disk Preparation

The "How to create and use Live USB" page has a lot of useful information on preparing and testing USB memory sticks. Here are a couple of items we've noticed:

  • If you use a FAT 16 filesystem, the maximum overlay image size will be limited to 2048MB
  • If you have a large USB memory stick (8GB for example), you may be better off using FAT 32.
  • You can format a partition with a FAT 32 file system via (change /dev/sdu1 as appropriate):
mkdosfs -F 32 -n usbdrive /dev/sdu1
  • If you use gparted to setup your partitions, make sure that the boot flag is set on the partition you install to (otherwise Live USB Creator will complain about the partition).
  • We have seen Live USB Creator fail to update the MBR on the USB device. Refer to: "How to create and use Live USB" for trouble shooting this situation.

ISO Selection

It is not obvious how to use the graphical interface of Live USB Creator to install from the booted ISO image. To tell Live USB Creator to use the ISO image which is currently booted, you need to:

  • Press the Browse button inside the Use existing Live CD group.
  • Ignore the normal browse controls! Instead, type in the device assigned to your CD/DVD drive (it should be something similar to: /dev/sr0).
  • Press the Enter key after typing the device name.
  • A message should appear in the log window. Something along the lines of:
sr0 selected
  • The Create Live USB button should activate (if a target device is selected).
  • Verify (or change) the Target Device
  • Specify the amount of Persistent Storage you'd like to allocate.
  • Press the Create Live USB button to begin the installation.

Unfortunately, this /dev/sr0 trick does not always seem to work. If it doesn't work from the GUI tool, try reading the man page for the liveusb-creator command line tool. You might be able to get it to work from the command line by including the --noverify option.

USB Installation

The NST distribution can be installed onto and run directly from a memory stick. There are two ways in which one can perform the installation.

  • As a NST Live installation.
  • As a full NST hard disk installation.

Each method has its advantages and disadvantages.

Yum Tips

Yum Reference Documentation

Retrieved from "https://wiki.networksecuritytoolkit.org/nstwiki/index.php?title=NST_v2.x_Guidelines&oldid=6908"