nstnewscript

Name

nstnewscript — Stubs in the start of a new script into a NST development system.

Synopsis

nstnewscript -n TEXT | --name TEXT [ -a TEXT | --author TEXT ] [ -r FILENAME | --root FILENAME ] [ -c FILENAME | --config FILENAME ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The nstnewscript is used by NST developers when they want to create a new script for the NST distribution. Scripts created in this manner will help produce consistency.

Each time you run this script, it creates the following (but only if they don't exist):

src/scripts/NAME

A dedicated directory for source files to associate with the new script.

src/scripts/NAME/makefile

A simple makefile used to build the new script (and its documentation) from the source files.

src/scripts/NAME/NAME.nstscript

A XML file which defines the legal command line arguments which the script accepts. You will want to edit this file in emacs to add and modify the command line argument options.

src/scripts/NAME/NAME.sh

The body of the new script. This is where you place the "meat" of script.

src/scripts/NAME/NAME.docbook

A template DocBook file used to document your script. You will want to update this file after you finish your script.

src/scripts/NAME/.cvsignore

This file tells CVS what files are generated during the build process. It will prevent the question marks from appearing when you commit or update your CVS area. This file is only created if the parent directory of the new script has a CVS directory.

test/NAME

A dedicated directory for source files associated with performing system tests against your new script (after it is installed on a remote NST system).

test/NAME/test.bash

A simple test.bash script to be used as a starting point for testing the script. The commands contained will be run on a remote NST system during a top level "test".

yum/pkgs/NAME

A dedicated directory for the source files used to package your script into a RPM.

Note

If the name of your script does not include the string "nst", then the package name chosen for your script will be prefixed with the string "nst-". For example, if you create a new script named "hostinfo", the package name will be "nst-hostinfo".

yum/pkgs/NAME/build.bash

A template build.bash script which will be run when your script needs to be packaged. If you follow conventions, you should NEVER need to modify this script.

yum/pkgs/NAME/makefile

A template makefile which will be invoked when your script needs to be packaged. If you follow the standard conventions, you should NEVER need to modify this file.

yum/pkgs/NAME/pkginfo.xml

A template pkginfo.xml which you will want to modify. This file indicates what other packages your script needs to run, whether it should be installed onto a NST system, etc.

yum/pkgs/NAME/template.spec

A template.spec file which you will want to modify (in particular the "group" and "description" areas).

Note

The above directory and files will need to be added and committed to your source control management system in order to make your script a permanent addition to the NST source tree (the .cvsignore is only present and required when using CVS).

There are several conventions in using nstnewscript to create new scripts:

  • Only rudimentary checks are made on command line options. You may need to add additional checks. For example, if your script requires a "--infile FILE" command line argument, the automatic "rudimentary" checks will verify that the argument was present, but won't check that the file exists and is readable (you will have to add these checks to your script if necessary).

  • If your script has a required command line option, you should set its default value to REQUIRED in the NAME.nstscript file.

  • By default, it is assumed that each script will need to be installed on the NST system and not the development system. If you need to change this, update the "disable" and "devel" attribute settings at the top of the "yum/pkgs/NAME/pkginfo.xml" file.

  • There are many functions which are useful in creating scripts. These common functions are found in the src/include/functions directory. To add these functions to your script, you update the INCLUDES setting in your makefile. For example, the following would add the functions found in version.bash and long_help.bash:

    INCLUDES=version.bash long_help.bash

    Note

    There are dependencies - so including one file may require another. If you use INCLUDES=$(STANDARD_SCRIPT_INCLUDES), it will put in the standard functions used by most NST scripts and reduce the chance of you omitting a dependency.

  • If your script requires additional files, you will need to update the makefile to make sure that these files are listed and installed by the "install-list" and "install" targets.

Example

The following command sequence illustrates how one "stubs in" a new script:


[root@nstdev nst]# nstnewscript -n nstbogus -a pkb
Created: nstbogus

You should now be able to:

1. Verify initial template is valid via:

   HOST=IP_OF_NST
   cd /root/nst/yum
   ./configure
   make HOST=${HOST} nstbogus-probe-install
   make -C /root/nst HOST=${HOST} test TEST=nstbogus

2. Edit script sources under: /root/nst/src/scripts/nstbogus

3. Edit script packaging under: /root/nst/yum/pkgs/nstbogus

4. Edit script test under: /root/nst/test/nstbogus

[root@nstdev nst]#

If you have a NST system running, you can immediately try building and installing your new script onto the NST system. The example below builds the new "nstbogus" script, packages it into a RPM and installs it onto the NST system having a IP address of "192.168.1.141":


[root@nstdev nst]# cd yum
[root@nstdev yum]# ./configure

Configuration complete, try:

  make help

[root@nstdev yum]# make HOST=192.168.1.141 nstbogus-probe-install
make[1]: Entering directory `/root/nst/yum/pkgs/nstbogus'
/root/nst/yum/pkgs/nstbogus/build.bash \
	   "/root/nst" "nstbogus" \
	   "2.10.0" "1.nst" "noarch" \
	  "http://downloads.sourceforge.net/nst/nst-2.10.0.tar.gz" \
	  "/root/nst/yum/tmp/nstbogus" "/root/nst/yum/repo";

-------------------------------------------------------------------------------
Building script into: /root/nst/yum/tmp/nstbogus/nstbogus-2.10.0/src
-------------------------------------------------------------------------------

... Omitted output as the script is built and packaged ...

-------------------------------------------------------------------------------
SUCCESS: Successfully installed nstbogus-2.10.0-1.nst.noarch.rpm
-------------------------------------------------------------------------------
make[1]: Leaving directory `/root/nst/yum/pkgs/nstbogus'
scp repo/noarch/nstbogus-2.10.0-1.nst.noarch.rpm root@192.168.1.141:/tmp/ && \
    ssh root@192.168.1.141 'if rpm -q nstbogus &>/dev/null; then rpm -Uvh ...
nstbogus-2.10.0-1.nst.noarch.rpm                       100%   15KB  14.7KB/s   00:00    
Preparing...                ##################################################
nstbogus                    ##################################################
[root@nstdev yum]#

After installing the script onto a NST system running, you can then run some system tests against the script. A initial system test file was created for our example in "test/nstbogus/test.bash". The commands shown below demonstrate how we can run the system test for our newly built and installed "nstbogus" script.


[root@nstdev yum]# cd ..
[root@nstdev nst]# make HOST=192.168.1.141 test TEST=nstbogus

Running test: "nstbogus" on: "192.168.1.141"

      Script: "/root/nst/tmp/test/nstbogus/runtest"
	 Log: "/root/nst/tmp/test/nstbogus/runtest.log"

  Locating: "nstbogus" ....................................... [  OK  ]
  Locating: "man" ............................................ [  OK  ]
  Verify "man nstbogus" returns 0 ............................ [  OK  ]
  Running: /usr/bin/nstbogus --version ....................... [  OK  ]
  Verify existance of: /root/runtest/nstbogus/nstbogus-version [  OK  ]
    Searching for: "nstbogus.*2.10.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/nstbogus --help .......................... [  OK  ]
  Verify existance of: /root/runtest/nstbogus/nstbogus-help.tx [  OK  ]
    Searching for: "Shows detailed information on using nstbo" [  OK  ]
    Searching for: "Description:" ............................ [  OK  ]
    Searching for: "Usage:" .................................. [  OK  ]
    Searching for: "Where:" .................................. [  OK  ]
  Performing a RPM verfication on: nstbogus .................. [  OK  ]
  Running nstbogus without any arguments ..................... [  OK  ]
  Verify existance of: /root/runtest/nstbogus/nstbogus.log ... [  OK  ]
    Searching for: "nstbogus" ................................ [  OK  ]
    Searching for: "Hello" ................................... [  OK  ]
  Verify existance of: /root/runtest/nstbogus/nstbogus.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)

[root@nstdev nst]#

At this point, we know that we can build, install and test our new script. We can now modify the template files which were stubbed in to make our script perform its intended task.

Options

The following command line options are available:

-n TEXT | --name TEXT

This option specifies the name of the new script to create. This option is required. If omitted, an error will be shown along with the short usage information.

[-a TEXT] | [--author TEXT]

By default, we assume that the USER environment variable is set to the ID of the NST author creating the script. You can use this option to force the author ID to a specific value (if you are logged in as someone else).

[-r FILENAME] | [--root FILENAME]

In order to create the necessary files, we need to know where the top most directory of the NST source code is located on the system. If you omit this argument, we will attempt to find it by first checking the current directory and then recursively checking the parent directories. You only need to specify this command line argument if you run the script from a directory outside of the NST source code.

[-c FILENAME] | [--config FILENAME]

By default, the nstnewscript will attempt to load configuration information from both /etc/nst/nstnewscript.conf and ${HOME}/.nstnewscript.conf (where the values in the latter file take precedence). If the files are not found, then all required parameters must be specified on the command line. You can specify --config FILE to load a configuration file other than ${HOME}/.nstnewscript.conf. You may specify --config no to disable the loading of any configuration. You may specify --config load if you want the script to exit in error if ${HOME}/.nstnewscript.conf is not found. You may specify --config save to save the options specified as ${HOME}/.nstnewscript.conf. You may specify --config show to see what the current command line arguments (or default values) would look like if saved in a configuration file.

[-h [true]|false] | [--help [true]|false]

When this option is specified, nstnewscript will display a short one line description of nstnewscript, followed by a short description of each of the supported command line options. After displaying this information nstnewscript will terminate.

[-H [true]|false] | [--help-long [true]|false]

This option will attempt to pull up additional nstnewscript documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

[-v [true]|false] | [--verbose [true]|false]

When you set this option to true, nstnewscript will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

[--version [true]|false]

If this option is specified, the version number of the script is displayed.

Files

/usr/share/nstnewscript

Directory containing the template files used when stubbing in a new script.

src/include/functions

Directory on a NST development system which contains small blocks of bash code. These useful functions can easily be added to your new script by updating the INCLUDES variable in your makefile.

$HOME/.nst.nstnewscript.conf

User configuration file where you can adjust the default values for the nstnewscript script. Use nstnewscript --config save to create a initial version which you can then edit with any text editor. The values found in this file take precedence over any values found in /etc/nst.nstnewscript.conf.

/etc/nst.nstnewscript.conf

System configuration file where you can adjust the default values for all users of the nstnewscript script. Use nstnewscript --config show >| /etc/nstnewscript to create a initial version which you can then edit with any text editor.

Authors

Paul Blankenbaker created initial version.

See Also

Network Security Toolkit