Creating A New NST Script

We have developed a set of tools which let us create custom scripts for the NST distribution that are fairly consistent in usage. This page offers some notes for NST developers which would like to create new scripts for the NST distribution.

Creating The Initial Framework For Your New Script

After you check out NST source code from Subversion, you will need to run a top level ./configure. Once the top level configuration completes successfully (it takes a VERY long time the first time you set up a development system), you will be able to run the nstnewscript command. This command will generate the following boiler-plate files for you:

• The files to build the script, document and define the command line options, and a docbook template man page for the script.
• A basic test script which can be enhanced to test that your script behaves as expected.
• The necessary files to generate a new package to contain your script.

For example, to create a new script named: getipv6, you would run the following from the top level of the NST source tree:

[root@nstdev32 trunk]# nstnewscript --name getipv6 --author pkb
Created: getipv6

You should now be able to:

1. Verify initial template is valid via:

   HOST=IP_OF_NST
   cd /opt/trunk/yum
   ./configure
   make HOST=${HOST} nst-getipv6-probe-install
   make -C /opt/trunk HOST=${HOST} test TEST=getipv6

2. Edit script sources under: /opt/trunk/src/scripts/getipv6

3. Edit script packaging under: /opt/trunk/yum/pkgs/nst-getipv6

4. Edit script test under: /opt/trunk/test/getipv6

[root@nstdev32 trunk]# 

From the output above you will notice that the nstnewscript stubbed in enough files that your new script can be built, installed and tested on another NST system. Before doing so, it is recommended that you add the new files and directories created to the Subversion repository.

Adding The New Files To Subversion

Immediately after running the nstnewscript it is recommended that you add the new files and directories to the NST Subversion repository. The following shows the commands to identify the new directories created and to add the new directories and files to Subversion for our new getipv6 script:

[root@nstdev32 trunk]# svn status
?       test/getipv6
?       src/scripts/getipv6
?       yum/pkgs/nst-getipv6
[root@nstdev32 trunk]# svn add test/getipv6 src/scripts/getipv6 yum/pkgs/nst-getipv6
... output from svn invocation omitted ...
[root@nstdev32 trunk]# 

Building And Testing Your New Script

Now that we've added the files associated with the new getipv6 script, let's build the initial skeleton, package it up as a RPM and test it on a NST system (the following assumes you have another system booted using the NST Live ISO image and that it has a IP address of 192.168.1.136 and you have your ssh-agent and keys setup so that you can log into the NST system from your development system without being prompted for a password):

[root@nstdev32 trunk]# HOST=192.168.1.136
[root@nstdev32 trunk]# cd yum
[root@nstdev32 yum]# ./configure
Configuration complete, try:

  make help

[root@nstdev32 yum]# make HOST=${HOST} nst-getipv6-probe-install

... A lot of output as the new script is built, packaged and installed ...
 
[root@nstdev32 yum]# make -C .. HOST=${HOST} test TEST=getipv6
make: Entering directory `/opt/trunk'

Running test: "getipv6" on: "192.168.1.136"

      Script: "/opt/trunk/tmp/test/getipv6/runtest" 
         Log: "/opt/trunk/tmp/test/getipv6/runtest.log"

  Locating: "getipv6" ........................................ [  OK  ]
  Locating: "man" ............................................ [  OK  ]
  Verify "man getipv6" returns 0 ............................. [  OK  ]
  Running: /usr/bin/getipv6 --version ........................ [  OK  ]
  Verify existance of: /root/runtest/getipv6/getipv6-version.t [  OK  ]
    Searching for: "getipv6.*2.13.0" ......................... [  OK  ]
    Searching for: "Copyright.*networksecuritytoolkit.org" ... [  OK  ]
    Searching for: "This is free software; see the source for  [  OK  ]
    Searching for: "warranty; not even for MERCHANTABILITY or  [  OK  ]
  Running: /usr/bin/getipv6 --help ........................... [  OK  ]
  Verify existance of: /root/runtest/getipv6/getipv6-help.txt  [  OK  ]
    Searching for: "Shows detailed information on using getipv [  OK  ]
    Searching for: "Description:" ............................ [  OK  ]
    Searching for: "Usage:" .................................. [  OK  ]
    Searching for: "Where:" .................................. [  OK  ]
  Performing a RPM verfication on: nst-getipv6 ............... [  OK  ]
  Running getipv6 without any arguments ...................... [  OK  ]
  Verify existance of: /root/runtest/getipv6/getipv6.log ..... [  OK  ]
    Searching for: "getipv6" ................................. [  OK  ]
    Searching for: "Hello" ................................... [  OK  ]
  Verify existance of: /root/runtest/getipv6/getipv6.log ..... [  OK  ]
    Verify absence of: "ERROR" ............................... [  OK  ]
    Verify absence of: "Failed" .............................. [  OK  ]
  Success! All 23 tests passed ............................... [  OK  ]


SUCCESS!    All 24 of 24 tests passed (0 test(s) failed)

make: Leaving directory `/opt/trunk'
[root@nstdev32 yum]# 

Now that we see that the skeleton files can be built, packaged, installed and tested on a NST system it's time to edit the source files such that our new script can do something other than say "Hello".

Files You Should Edit

Now that the new script has been stubbed in and you know how to test your scripts behavior, it's time to edit the source files. Here are the files that are initially created and their intended purpose:

test/getipv6/test.bash

This script is used to test your new script. You should edit this file to perform automated tests and validation steps whenever possible. It is assumed that the test will be run on fresh NST live boot and while your test does not need to restore the system to the initial state in which it found it, it should not modify the system in such a manner as to cause a different test case to fail. There are many helper test functions. See the heavily commented include/test/test_functions.bash file.

src/scripts/getipv6/getipv6.sh

This is where you put the meat of your script. It will be adjusted to source in some common bash function files from the /usr/share/nst-bash/ directory based on the INCLUDES setting in the makefile.

src/scripts/getipv6/getipv6.nstscript

This is where you define the command line arguments which your script will honor. This definition file is used when producing your final script AND the documentation for your script.

src/scripts/getipv6/getipv6.docbook

This is where you put the man page documentation for your script.

src/scripts/getipv6/makefile

You may not need to edit this file at all. However, if you need to include more than the standard set of /usr/share/nst-bash/ files, you will want to update the INCLUDES line. Also, if your new script requires some additional resource files, you will need to update the install and install-list targets. The makefile is commented and should help you through the process.

yum/pkgs/nst-getipv6/pkginfo.xml

This file will need to be updated (at a minimum you will need to change the <summary>...</summary> line. The values in this file are used internally to generate makefile dependencies and set values in the generated RPM spec file.

yum/pkgs/nst-getipv6/template.spec

This file will need to be updated (at a minimum you will want to edit the %description area). This is the template file that is used to generate the final spec file during the packaging stage of your script.

Editing svn:ignore

Unfortunately, there will be temporary files generated under the src/getipv6 directory when you build the new nst-getipv6 package. You will need to run the following commands to tell Subversion to ignore these temporary files:

[root@nstdev32 trunk]# cd src/scripts/getipv6
[root@nstdev32 getipv6]# svn propedit svn:ignore .
... A editor will appear enter the following lines ...
getipv6
*_config.*
*.gz
*.man.html
... Then save your edits ...
[root@nstdev32 getipv6]#

Updating Links/Menu Entries

Unfortunately, the nstnewscript does not automatically add links or menu entries for your new script into the files used to generate the NST WUI and NST web site HTML. You will need to edit the following files:

src/scripts/nstmenu/share/applications/nstwui.documents.apps.xml

A file which contains many menu item definitions for the NST WUI (including NST scripts).

src/scripts/nstmenu/share/applications/website.apps.xml

A file which contains many menu item definitions for the NST web site (including NST scripts).

src/scripts/nstmenu/share/groups/website.nstscripts.group.xml

The menu panel for the NST web site which lists the NST scripts.

src/scripts/nstmenu/share/groups/documents.nstscripts.group.xml

The menu panel for the NST WUI which lists the NST scripts.

wui/index.cgi

The main index page of the NST WUI which has a list of NST script links.

yum/pkgs/nstmenu/pkginfo.xml

You will need to bump the release number for this package as the menus will have changed.

yum/pkgs/nstmenu/template.spec

You will need to add a change log entry.

yum/pkgs/nstwui/pkginfo.xml

You will need to bump the release number for this package as the links on the index page will have changed.

yum/pkgs/nstwui/template.spec

You will need to add a change log entry.

Update A NST Distro Package

In order for the new script to appear in the ISO distribution, you will need to add it to one of the following files:

yum/pkgs/nst-required/pkginfo.xml

Add your script's package name to this file if the script must remain on a NST system in order for the NST system to function properly.

yum/pkgs/nst-live/pkginfo.xml

Add your script's package name to this file if it is a optional script which the end user can remove from their NST system and still expect the NST system to function properly.

Updating the NST Web Site

Once you have finalized your script, you will want to publish it on the Internet at the NST web site. To accomplish this, change to the top level directory of your NST source tree and run the following commands:

[root@nstdev32 trunk]# yum update

... Output from the yum update - should install the latest nstmenu package if necessary ...

[root@nstdev32 trunk]# ./configure --on-line-docs

... A lot of output as your development area is re-configured to generate web site documentation ...

[root@nstdev32 trunk]# cd docs
[root@nstdev32 docs]# make scripts.html scripts.upload

... A lot of output as HTML pages for the NST scripts are generated and uploaded to the web site ...

[root@nstdev32 docs]# cd ..
[root@nstdev32 trunk]# make html-build-upload

... A lot of output as it configures the system for uploading HTML to the web site,
    builds and uploads the HTML and then configures the system back for development ...

[root@nstdev32 trunk]#