nstvmware

Name

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

Synopsis

nstvmware [ -m ENTRY | --mode ENTRY ] [ --passwd TEXT ] [ --gdm [true]|false ] [ --width INTEGER ] [ --height INTEGER ] [ --diagonal NUMBER ] [ --disallowtcp [true]|false ] [ -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 virtual machine. 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 fully install a NST distribution into a VMware virtual disk.

  • 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 a graphical desktop. Once rebooted, gdm will start and a user will be able to login directly to a graphical desktop. TCP/IP connections will be allowed to the X Window Server.

[root@probe ~]# nstvmware -v --mode install --gdm --disallowtcp false

+ NOTE    + System appears to be running within a VMware virtual machine.
+ NOTE    + Generating: The kickstart template file for VMware installation via:

... Lots of omitted output ...

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

1. Issue the "poweroff" command and then restart the NST virtual machine.

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 distribution to others. The process to generate the final i686 ZIP file is outlined below (producing the x86_64 version is similar):

  • On the host system, build (or download) the NST ISO image.

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

    [pkb@salsa tmp]$ unzip /tmp/nst-vm-live-28.i686.zip
Archive:  /tmp/28/nst-vm-live-28.i686.zip
  inflating: nst-28-i686/bios.nvram
  inflating: nst-28-i686/nst-s001.vmdk
  inflating: nst-28-i686/nst-s002.vmdk
  inflating: nst-28-i686/nst-s003.vmdk
  inflating: nst-28-i686/nst-s004.vmdk
  inflating: nst-28-i686/nst-s005.vmdk
  inflating: nst-28-i686/nst-s006.vmdk
  inflating: nst-28-i686/nst-s007.vmdk
  inflating: nst-28-i686/nst-s008.vmdk
  inflating: nst-28-i686/nst-s009.vmdk
  inflating: nst-28-i686/nst.vmdk
  inflating: nst-28-i686/nst-vm-linux-28.vmx
  inflating: nst-28-i686/nst-vm-windows-28.vmx
  inflating: nst-28-i686/README.txt

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


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

    Note

    The RPM package nst-vm-live, which you can yum install, contains the file: "nst-vm-live-28.i686.zip".

  • The Anaconda installer has changed drastically over the years. Sometimes it hangs at the end (refusing to exit back to the calling script). So, for best results it is recommended to boot the NST system in desktop mode (with a graphical login), login in and then open up a terminal.

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

    [root@probe ~]# nstvmware -m install -v --gdm --disallowtcp true \
--width 1024 --height 768 --diagonal 13.33 --passwd nst2003


You will see the anaconda graphical installer progress indicators and
it may prompt you to make some choices. Eventually you will get to the
Close button. After pressing the close button the installer may hang
if you ran the installation from the console instead of a graphical
desktop environment.

    Note

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

    This configuration disallows TCP/IP connections to be made to the X Window Server.

  • If you ran the installation from a graphical desktop, you should be able to shutdown your machine at this point as normal (you can use the poweroff command if you want). If you ran the installation from the console, anaconda may not exit cleanly (hang) and you will need to find the "Shut Down Guest" action in your VMware environment to instruct the system to power down safely.

    [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-appliance-28.i686.zip file. This file can be found in the nst-vm-appliance package.

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

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

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


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

    If the system does not automatically boot to a graphical desktop, you will need to edit the /boot/grub/grub.conf file and change the default boot to the graphical desktop entry.

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

    • You may want to adjust the MATE panel settings. In particular, you may want to drag a copy of the Terminal and Firefox launchers from the menu to the MATE panel.

    • For the virtual machine, we've been using the nstpasswd script to reset the initial password to "nst2003" which will enable the sshd and nstwui service when the user boots the system.

    • Remove the file /etc/nst/nstpasswd.conf. This will force a reminder on the initial NST WUI screen telling the user they need to set the password.

    • Start Firefox. When prompted, enter the password and tell Firefox to remember its value. You should see a big red button telling the user that they need to set their password (this is the desired condition).

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

    • Repeatedly start, adjust and quit Firefox until it starts up in a reasonable state (make sure you quit once it looks good).

  • Reboot the virtual machine and select "Maintenance" (single user mode) from the boot menu. From the console, you can then prepare the system for "zipping" and power it off.

    sh-3.00# /usr/bin/nstvmware -m prezip -v

+ NOTE    + System appears to be running within a VMware virtual machine.
+ 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 and directories (*.log, *.vmxf, caches, and *.vmsd) and create the final ZIP file. Pay attention to the files added to the ZIP file in case VMware introduces new temporary files which need to be removed.

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

VM Verify

When you specify --mode verify, this script will check to see whether or not the system is running within a VMware virtual machine. The script will exit with a return code of 0 if it appears that the system is running within a VMware virtual machine. It will exit with a return code of 1 otherwise. No output is produced unless you include 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

Hard Disk Installation

When you specify --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 many of the other recognized command line arguments to customize the installation. For example, if you want the system to come up to a graphical X desktop you may want to include the --gdm 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

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.

Pre-Zip

Prior to creating a ZIP archive of a NST virtual machine, you 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. You typically switch to run level 1, uses the "prezip" feature, and then power 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".

X Configuration

When performing a full install, a appropriate X configuration file will be created. However, there may be times where you want to adjust your display settings WITHOUT performing all of the other tasks associated with a full install. By using the --mode xorg.conf you can tweak the X configuration for the current 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 you 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 virtual machine.
+ 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 systemctl isolate graphical.target 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 effects 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/vmx.html.

  • 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", "install", "xorg.conf", "prezip" or "status". If you specify "verify" (the default), the script simply exits true if it determines that the NST is running in a VMware virtual machine. Specify "install" to run nstliveinst into the virtual machine's hard disk. This uses ALL of virtual disk /dev/sda (destroying any existing data) and requires that the disk be at least 6GB 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 changes). Specify "prezip" if you have booted off of a hard disk install and want to clean of the system before creating a "ZIP" file of the entire virtual machine. Specify "status" to see the current state of both Kernel and User level components running on this virtual machine.

[--passwd TEXT]

By default, this script will use the default password of "nst2003" for the hard disk installation. You may use this command line argument to specify a different system password for the initial install.

[--gdm [true]|false]

This option should be included if a graphical desktop is desired. 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 you to specify the width (in pixels) which you would like to set the 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 you to specify the height (in pixels) which you would like to set the 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. 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.

[--disallowtcp [true]|false]

This option is used to disable the TCP/IP transport associated with the X Window Server default display for the just installed NST distribution. If disabled, the X Window Server will not bind a TCP/IP port (Typically Port: 6000) to its process, thus not allowing a TCP/IP connection to be established. For example, one would not be able to render the display of an X Client Application to this X Window Server. Set this option to: "false" to allow for TCP/IP connections to the X Window Server default display. This option actually inserts the variable "DisallowTCP" in the file: "/etc/gdm/custom.conf" and sets it value accordingly.

[-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/share/nstvmware

Directory containing resource files used by nstvmware.

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 ...).

See Also

nstliveinst(l), Network Security Toolkit