2.2. Installation and Configuration using package in tar format

2.2.1. Installation

Distributed tar package includes Java jar files, prototype configuration files, some auxiliary scrips and documentation.

when you install using tar archive, the easiest way to is to place everything in the same directory: unpacked distribuition archive, configuration files, Python scripts, logs and reports. NetSpyGlass forms certain directory hierarchy to keep files organized, for example logs are in the directory logs, the database if in directory db, reports are in the directory reports and so on.

  • Create role user account “nw2”, put its home directory on the file system where you have enough room. This can be this user’s home directory, e.g.:

    /home/nw2/
    

    You can start with your own user account instead of nw2 if you plan to just evaluate the product and experiment with it.

  • Download and unpack package nw2-NN.tar in this directory (where NN is the latest version available). You should get the main binary netspyglass-1.0.jar, a few startup and auxiliary scripts in subdirectory bin, prototype configuration file nw2.conf.minimal, prototype launch configuration file launch.conf.prototype and directory docs/ with documentation files

  • we recommend you begin with the minimal configuration file which you can make by copying nw2.conf.minimal under the name nw2.conf. Default (full) configuration file doc/default_config/netspyglass.conf has some advanced configuration options you may need in the future.

  • Make sure the directory and all files in it belong to the role account nw2.

After you unpack the package, make a copy of the file nw2.conf.minimal under the name nw2.conf and edit it. See section Configuration for more details. Also make a copy of the file launch.conf.prototype under the name launch.conf and edit it to make sure HOME directory, path to the config file and directories where the server should keep its logs are set up correctly. Startup scripts use config file launch.conf to start the server and monitor.

File launch.conf defines shell variables for all important server parameters and forms server command line. This file is equivalent of /etc/default/netspyglass configuration file that is used with rpm or deb based installation and has the same parameters. See Startup configuration file /etc/edfault/netspyglass

2.2.2. Running the Server

We provide shell script bin/netspyglass that can be used to start and stop NetSpyGlass process.

2.2.2.1. Starting and stopping NetSpyGlass

Once files launch.conf and nw2.conf are ready, you can start the server using script netspyglass.sh in subdirectory bin.

Script netspyglass.sh accepts the following commands supplied to it as a single command line parameter:

  • start start both components and exit
  • stop stop both components
  • status check if NetSpyGlass is running and print report

To start NetSpyGlass this way, use command:

./netspyglass.sh start

To stop it, use:

./netspyglass.sh stop

Script netspyglass.sh expects to find the main configuration file nw2.conf in the current directory.

If for some reason you can’t use netspyglass.sh stop to stop it, you can kill the process running Java class Nw2Ui with lower process id (out of two with the same name and command line).

If you only plan to start and stop the system manually, this is all you need to do. You can skip following sections.

2.2.2.2. Upgrade

To upgrade to the new version, do the following:

  • stop the system using command:

    ./netspyglass.sh stop
    
  • back up current version (the whole directory)

  • unpack new version in the same directory, on top of the old one, then start it again:

    ./netspyglass.sh start
    

2.2.2.3. Starting the server for the first time

Once you start the server, watch log files logs/info.log and logs/error.log for errors. Standard output and standard error streams of the server are written to files logs/stdout and logs/stderr. Typical errors at this stage are:

  • config file syntax errors
  • port conflicts (port used by the embedded web server is specified by the config parameter ui.url)

Once the serer is up and running and you dont get any errors, connect to it with your browser using url configured in the config file parameter ui.url.