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 is the test

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.