nstvmware

Name

nstvmware — Configures/installs NST in a VMware virtual machine.

Synopsis

nstvmware [ -m ENTRY | --mode ENTRY ] [ -a ENTRY | --appliance ENTRY ] [ --xdm [true]|false ] [ --width INTEGER ] [ --height INTEGER ] [ --diagonal NUMBER ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The nstvmware script is intended to be used after booting the Network Security Toolkit (NST) within a VMware session. The nstvmware script has several modes of operation.

  • It provides a mode to determine whether the NST is running within a VMware virtual machine.

  • It provides a mechanism to setup a NST system (and optionally bring up X) after a live CD boot.

  • It provides a mechanism to fully install a NST distribution into a VMware virtual disk. In addition to the installation, it allows one to customize the boot up state to a set of common "appliance modes".

  • It provides a mechanism to adjust the X settings (including the ability to correctly set the DPI).

Here is a example of using the install mode to fully install the NST into a VMware virtual disk such that it will boot up to run level 5. Once rebooted, xdm will start and a user will be able to login directly to a graphical desktop.

[root@probe ~]# nstvmware -v --mode install --xdm
+ SUCCESS + Found 'Card:VMWare' video device
+ NOTE    + Virtual disk does not require any modules
+ SUCCESS + Kudzu reported VMware virtual disk as: /dev/hda
+ SUCCESS + Found /dev/hda
+ SUCCESS + Partition /dev/hda1 already exists - no need to create

================================================
 NST Hard Disk Installation Initial Check Phase
================================================

... Lots of omitted output ...

Installation has completed succesfully. You will need to perform the
following steps:

1. Issue the "poweroff" command and then restart the VMware Player.

2. When the VMware virtual machine starts, press the "F2" key and make
   sure that the BIOS is configured to check for the hard disk PRIOR
   to checking for the ISO image. OR, you may press the "Esc" key and
   choose the "Hard Disk" boot from the VMware menu.

Have a good day.

[root@probe ~]#

Creating The NST Virtual Machine

This script is designed to automate the process of preparing the "Network Security Toolkit (NST) Virtual Machine" for public distribution at the "VMware Virtual Appliances" site. The process to generate the final ZIP file is as follows:

  • On the host system, build (or download) the NST ISO image (you must use a 1.4.1 or later release of the NST).

  • On the host system, boot the NST ISO image within a VMware virtual machine using the nst-vm-livecd-1.8.1.zip configuration.

    [pkb@salsa tmp]$ unzip /tmp/nst-vm-livecd-1.8.1.zip
Archive:  /lan/pub/download/nst/1.8.1/nst-vm-livecd-1.8.1.zip
  inflating: nst-1.8.1/bios.nvram
  inflating: nst-1.8.1/nst-s001.vmdk
  inflating: nst-1.8.1/nst-s002.vmdk
  inflating: nst-1.8.1/nst-s003.vmdk
  inflating: nst-1.8.1/nst-s004.vmdk
  inflating: nst-1.8.1/nst-s005.vmdk
  inflating: nst-1.8.1/nst.vmdk
  inflating: nst-1.8.1/nst-vm-linux-1.8.1smp.vmx
  inflating: nst-1.8.1/nst-vm-linux-1.8.1.vmx
  inflating: nst-1.8.1/nst-vm-windows-1.8.1smp.vmx
  inflating: nst-1.8.1/nst-vm-windows-1.8.1.vmx
  inflating: nst-1.8.1/README.txt

[pkb@salsa tmp]$ cp /tmp/nst-1.8.1.iso nst-1.8.1
[pkb@salsa tmp]$ vmplayer nst-1.8.1/nst-vm-linux-1.8.1.vmx


... NST Virtual Machine should boot up in a new window ...

    Note

    The nst-vm-livecd-1.8.1.zip can be created on a NST development system via: "make -C src/vmware/nst".

  • From within the virtual machine, use the nstvmware script to install the NST to the virtual hard disk.

    [root@probe ~]# nstvmware -m install -a toolkit -v --width 1024 --height 768 --diagonal 13.33

+ NOTE    + System appears to be running within a VMware session.
+ NOTE    + Invoking /root/bin/auto_modprobe_disk to load any necessary drivers

... Lots of omitted output ...

+ SUCCESS + Installed:
+ SUCCESS + Should now be configured to come up as a toolkit appliance

Installation has completed succesfully. You will need to perform the
following steps:

1. Issue the "poweroff" command and then restart the VMware Player.

2. When the VMware virtual machine starts, press the "F2" key and make
   sure that the BIOS is configured to check for the hard disk PRIOR
   to checking for the ISO image. OR, you may press the "Esc" key and
   choose the "Hard Disk" boot from the VMware menu.

Have a good day.

[root@probe ~]#

    Note

    The choice of "13.33" inches was chosen as a default screen size as it yields a DPI of "96" - which matches the DPI setting of many Windows systems.

  • From within the virtual machine, shutdown the virtual machine using the "poweroff" command.

    [root@probe ~]# poweroff

Broadcast message from root (tty1) (Fri May 26 13:14:43 2006):

The system is going down for system halt NOW!

... Lots of omitted output ...

  • On the host system, unzip the template nst-vm-1.8.1.zip file.

    [pkb@salsa tmp]$ unzip /tmp/nst-vm-1.8.1.zip
Archive:  nst-vm-1.8.1.zip
  inflating: nst-vm-1.8.1/bios.nvram
  inflating: nst-vm-1.8.1/nst-vm-linux-1.8.1.vmx
  inflating: nst-vm-1.8.1/nst-vm-windows-1.8.1.vmx
  inflating: nst-vm-1.8.1/README.txt
[pkb@salsa tmp]$

    Note

    The nst-vm-1.8.1.zip can be created on a NST development system via: "make -C src/vmware/appliance".

  • On the host system, copy (or move) the virtual disk images to the nst-vm-1.8.1 directory created by the previous step and boot the virtual machine.

    [pkb@salsa tmp]$ cp nst-1.8.1/*.vmdk nst-vm-1.8.1
[pkb@salsa tmp]$ vmplayer nst-vm-1.8.1/nst-vm-linux-1.8.1.vmx


... NST Virtual Machine should boot up in a new window ...

  • Once the virtual machine comes up, go ahead and login (the password will have reset to the default value of: "nst2003"). This should bring up the X desktop where you will be able to "initialize" some application values (primarily firefox).

    • When firefox comes up, it will be prompting you for a password. Enter the password and tell firefox to remember its value.

    • Make sure you submit at least one form to verify (or clear) the firefox warning about submitting data over an unencrypted connection (this is OK since we are connecting to http://127.0.0.1/ within the virtual machine).

    • Quit firefox to make sure its settings are saved to disk.

  • From within the virtual machine, open a "aterm" window, and switch to run level 1. This will kill your X session and leave you at a console prompt. From the console, you can then prepare the system for "zipping" and power it off.

    [root@probe ~]# init 1


... The X session will terminate and you will
    return to a console in single user mode ...

Telling INIT to go to single user mode.
INIT: Going single user
INIT: Sending processes the TERM signal
INIT: Sending processes the KILL signal
sh-3.00# /usr/local/bin/nstvmware -m prezip -v

+ NOTE    + System appears to be running within a VMware session.
+ NOTE    + Clearing: /var/log/boot.log...

... Lots of omitted output ...

+ NOTE    + Zero filling unused disk space for better compression...
/bin/cat: write error: No space left on device
+ NOTE    + Exiting from "prezip" mode
+ SUCCESS + All "prezip" operations complete - you may now poweroff.

sh-3.00# poweroff

  • At this point, you should be back at the host system. You should remove the unneeded files (*.log and *.vmsd) and create the final ZIP file.

    [pkb@salsa tmp]# rm -f nst-vm-1.8.1/*.vmsd nst-vm-1.8.1/*.log
[pkb@salsa tmp]# zip -r $HOME/nst-vm-1.8.1.zip nst-vm-1.8.1
  adding: nst-vm-1.8.1/ (stored 0%)
  adding: nst-vm-1.8.1/nst-s003.vmdk (deflated 68%)
  adding: nst-vm-1.8.1/bios.nvram (deflated 89%)
  adding: nst-vm-1.8.1/nst-s002.vmdk (deflated 67%)
  adding: nst-vm-1.8.1/nst-vm-linux-1.8.1.vmx (deflated 66%)
  adding: nst-vm-1.8.1/nst-s001.vmdk (deflated 92%)
  adding: nst-vm-1.8.1/README.txt (deflated 46%)
  adding: nst-vm-1.8.1/nst-vm-windows-1.8.1.vmx (deflated 66%)
  adding: nst-vm-1.8.1/nst.vmdk (deflated 48%)
  adding: nst-vm-1.8.1/nst-s005.vmdk (deflated 100%)
  adding: nst-vm-1.8.1/nst-s004.vmdk (deflated 89%)
[pkb@salsa tmp]$ ls -l $HOME/nst-vm-1.8.1.zip
-rw-r--r--  1 pkb pkb 328131057 May 26 15:26 /home/pkb/nst-vm-1.8.1.zip
[pkb@salsa tmp]$

Mode "verify"

When one specifies --mode verify, this script will check to see whether or not the system is running within a VMware session. The script will exit with a return code of 0 if it appears that the system is running within a VMware session. It will exit with a return code of 1 otherwise. No output is produced unless one includes the -v (verbose) option.

This mode of operation is really intended to support other scripts as shown in the following example:

if nstvmware --mode verify; then
  run_under_vmware;
else
  run_outside_vmware;
fi

Mode "setup"

The --mode setup option is used when one is running the NST within a VMware session. The primary goal is to setup the NST system to a state which should work well under a VMware session. The following things are done:

  • The VMware virtual disk will be partitioned and formatted for use by the NST probe. This step is only done if required.

  • The virtual disk will be mounted to the /var/nst directory. This step is only done if required.

  • Configuration files will be installed (or replaced) for things like X to put the NST system into a state known to work within a VMware virtual machine.

  • Optional "appliance" customizations will be applied to change the default mode of operation of the NST to act like a simple appliance. For example, we we might want to setup the NST to be a ntop appliance that the user simply starts the virtual machine and sees ntop information immediately.

  • To bring up a X (graphical) desktop if the --xdm option is specified.

The following demonstrates the typical usage (notice how the --xdm option was included to bring up the X desktop login):

[root@probe ~]# nstvmware -v --mode setup --xdm

+ SUCCESS + Found 'Card:VMWare' video device
+ NOTE    + Virtual disk does not require any modules
+ SUCCESS + Kudzu reported VMware virtual disk as: /dev/hda
+ SUCCESS + Found /dev/hda
+ SUCCESS + Partition /dev/hda1 already exists - no need to create

================================================
 NST Hard Disk Installation Initial Check Phase
================================================

... Lots of omitted output ...

Installation has completed succesfully. You will need to perform the
following steps:

1. Issue the "reboot" command to start up the new installation.

2. When the VMware virtual machine starts, press the "F2" key and make
   sure that the BIOS is configured to check for the hard disk PRIOR
   to checking for the ISO image. OR, you may press the "Esc" key and
   choose the "Hard Disk" boot from the VMware menu.

Have a good day.

[root@probe ~]#

Here are some things to consider:

  • When run from the command line, one will typically include the -v option to increase the amount of output produced.

  • You can improve your X experience by including the --width PIXELS, --height PIXELS, and --diagonal INCHES values on the command line.

  • If you don't want the script to use the entire virtual disk for the NST installation, then you should create and size the partition prior to running this script. You will need to create a /dev/sda1 partition (if your virtual disk uses SCSI emulation) or a /dev/hda1 partition (if your virtual disk uses IDE emulation).

  • We recommend that 1.5GB or more of space be available in the virtual disk. This will provide a decent amount of room for logging.

Mode "install"

When one specifies --mode install, this script will attempt to perform a hard disk installation of the NST into the VMware virtual disk.

After the hard disk installation completes, you will need to shutdown or reboot your virtual machine (use the shutdown or reboot command).

You may use any of the options mentioned in the --mode setup section above when you perform the install. For example, if you want the system to come up to a graphical X desktop you may want to include the --xdm and other X related options. You can enable verbose output by including the -v option.

There are advantages and disadvantages to installing the NST into a virtual disk instead of booting from the NST ISO image. The nice feature about booting from a virtual disk install is that your configuration and state are preserved. However, even though you need to configure the system each time you boot it, the nice thing about booting from a ISO image is that you always come up in a known state. We recommend that you try both methods and see which you prefer.

Note

If you try to use the "-m install" mode after running "-m setup", the install will fail as it will find that the virtual hard disk is mounted. You should make sure that the virtual hard disk is not mounted prior to using the "-m install" mode.

Note

You may need to adjust the virtual BIOS so that it tries to boot from the hard disk BEFORE the CDROM after installation.

Note

Once you have successfully booted from the virtual installation, you may delete the ISO image file as it will no longer be required.

Mode "prezip"

Prior to creating a ZIP archive of a NST virtual machine, one should take care that the following operations are done:

  • Any files containing sensitive information or location specific configuration should be removed.

  • Files containing historical information should be removed.

  • Unnecessary log files are removed or reset to 0 length.

  • Any files or directories containing cached information are removed.

  • Unused virtual disk space is zero filled (to minimize the size of the ZIP archive).

The "prezip" mode is designed to help automate the above steps. One typically switches to run level 1, uses the "prezip" feature, and then powers off the virtual machine.

An example of using the "prezip" mode can be found near the end of the section titled: "Creating The NST Virtual Machine".

Appliances (Modes: "alist", "ainfo", "setup" and "install")

The --appliance NAME option can be combined with either --mode setup or --mode install. This will cause the NST probe to be configured to act like a dedicated "appliance".

For example, if one specified: --mode install --appliance ntop, the script would perform a hard disk installation and then setup the system such that each time it was booted, it would automatically start up with ntop running in the background and firefox running in the foreground showing the current ntop status WITHOUT the user doing a single thing.

You may specify --mode alist to see a list of appliance types that are available. For more information about a particular appliance, you can use --mode ainfo -a toolkit (you may use ntop or any other appliance reported by the --mode alist output instead of toolkit). For example:

[root@probe ~]# nstvmware -m alist


ntop:
  Configures NST probe as a dedicated ntop appliance

toolkit:
  Configures NST probe as a dedicated toolkit appliance

Found 2 total appliance modes
[root@probe ~]# nstvmware -m ainfo -a toolkit

toolkit appliance

  When you setup a NST probe as a toolkit appliance, you should see
  the following behavior:

  - The system comes up in run level 5 (graphical login)

  - After logging in, firefox is immediately launched and brings up
    the NST WUI (we'll throw in gkrellm as well for some status).


[root@probe ~]# nstvmware -m ainfo -a ntop

ntop appliance

  When you setup a NST probe as a ntop appliance, you should see
  the following behavior:

  - The system starts up ntop in the background

  - The system starts up a X desktop and brings up firefox such that
    the user immediately sees ntop information.


[root@probe ~]#

Note

When using the "Appliance" feature, each "Appliance" implementation is free to use/ignore the other command line options. For example, if you specify the "-a toolkit" appliance, it will force you to a graphical desktop regardless of whether the "--xdm" is specified on the command line.

Mode "xorg.conf" (X Configuration)

Both the --mode setup and --mode install will install a appropriate X configuration file. However, there may be times where you want to adjust your display settings WITHOUT performing all of the other tasks associated with a setup or install. By using the --mode xorg.conf one can tweak the X configuration for the currently running system.

This mode only "tweaks" the X configuration file. It does not start or restart your X server.

Only the --width PIXELS, --height PIXELS and --diagonal INCHES settings are used when this mode is specified.

The following example shows how one could use this feature to set the graphical size of their X desktop to match a 19 inch LCD monitor running at a resolution of 1280x1024 pixels:

[root@probe ~]# nstvmware -v --mode xorg.conf --width 1280 --height 1024 --diagonal 19
+ NOTE    + System appears to be running within a VMware session.
+ SUCCESS + Updated fluxbox menu for VMware. File updated:
  //etc/skel/.fluxbox/menu
+ SUCCESS + Updated fluxbox menu for VMware. File updated:
  //root/.fluxbox/menu
+ NOTE    + Setting xorg.conf DisplaySize to: 376mm by 301mm
+ SUCCESS + Set X display mode to: 1280x1024
+ SUCCESS + A new xorg.conf was installed - (re)start the X server

[root@probe ~]#

If you run the above command before starting your X server, you can use the init 5 command to bring up X in the new mode specified. If your X server has already been started, you will need to "Log Out" and then log back in to see the affects of the changes made.

General VMware Notes

Some bits of information we've found useful in our experience of using the free VMware Player and VMware Server in combination with the NST distribution:

  • A good VMX reference explaining the different properties in a VMware configuration file can be found at http://sanbarrow.com/vmw.html.

  • Sound works after running auto_modprobe_audio to install the proper sound module.

  • You can get access to the mingetty pseudo terminals by pressing Alt+F1, Alt+F2, etc.

Options

The following command line options are available:

[-m ENTRY] | [--mode ENTRY]

This option controls what nstvmware will do. The following modes are available: "verify", "setup", "install", "xorg.conf", "alist" or "ainfo". If you specify "verify" (the default), the script simply exits true if it determines that the NST is running in a VMware virtual machine. If you specify "setup", it will configure the NST for a typical live CD boot inside of a VMware virtual machine. Specify "install" to run nsthdinstall into the virtual machine's hard disk (uses all of your virtual disk which should be at least 1.5GB in size). Specify "xorg.conf" if you want to install/adjust the current X configuration settings (you will need to start or restart your X server in order to see the affects). Specify "prezip" if you have booted off of a hard disk install and want to clean of the system before creating a "ZIP" archive. Specify "alist" to see a list of special "appliances" which can be setup and or installed. Specify "-m ainfo -a NAME" to see information about the "appliance" named NAME.

[-a ENTRY] | [--appliance ENTRY]

This option controls how the system will be configured after setup or a installation completes (when you specify "--mode setup" or "--mode install"). This option defaults to "nst" indicating that no special appliance mode will be configured (the system will behave like a normal NST). A list of available appliance modes can be found by specifying "--mode alist". Details on a particular appliance can be fournd by specifying "--mode ainfo --appliance NAME" (where "NAME" is the name of the appliance - like "ntop"). Currently the NST ships with "toolkit" and "ntop" appliances.

[--xdm [true]|false]

This option should be included if a graphical desktop is desired. When combined with the "--mode setup", the NST will be switch to run level 5 (a graphical desktop) after setup completes. When combined with "--mode install", the NST will come up in run level 5 (a graphical desktop) the next time the virtual machine is restarted.

[--width INTEGER]

This option allows one to specify the width (in pixels) which they would like to set their graphical desktop to. If omitted, it will default to 1024. Width and height values will only be accepted if they are listed as a ModeLine in /etc/X11/xorg.conf. The minimum value permitted is 640. The maximum value permitted is 2000.

[--height INTEGER]

This option allows one to specify the height (in pixels) which they would like to set their graphical desktop to. If omitted, it will default to 768. Width and height values will only be accepted if they are listed as a ModeLine in /etc/X11/xorg.conf. The minimum value permitted is 480. The maximum value permitted is 2000.

[--diagonal NUMBER]

This parameter can be used to specify the size of your display area (the diagnonal measurement in inches). If this option is specified, we will compute the dimensions of your monitor's width and height in millimeters (we'll use the aspect ratio from the width/height pixel values). And put these measurements into your xorg.conf file such that your DPI will be correct. If you omit this value, we won't put any measurements at all into your xorg.conf. NOTE: If you lie and indicate that your monitor is smaller than it really is, then fonts will look larger than normal in applications that honor the DPI settings. The minimum value permitted is 1.0.

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

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

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

This option will attempt to pull up additional nstvmware 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, nstvmware 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/local/share/nstvmware

Directory containing resource files used by nstvmware.

/usr/local/share/nstvmware/appliances

Directory containing appliance scripts that come with a stock NST distribution.

/etc/nstvmware/appliances

Directory where user contributed appliance scripts can be stored.

Environment

TEXTBROWSER

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).

Authors

Paul Blankenbaker created initial version.

See Also

nsthdinstall(l), Network Security Toolkit