InfoScope 2.3 Server and Client package ======================================= NetGeo Inc. 1/7/2003 0. Introduction Thank you for using InfoScope. InfoScope is a powerful IP-to-geolocation mapping tool for variety of applications. This README contains the following information regarding InfoScope product. - Downloading the InfoScope - Minimum hardware/software requirement - Installing the InfoScope - Launching the InfoScope - Applying InfoScope client APIs - Customizing configuration files - Updating quarterly datafile 1. Downloading the InfoScope For windows 95/98/2000/XP, you will need to get infoscope_setup_2_3.exe. For Unix platform, you will need to get infoscope_2_3.tar.gz. They are found from the following URL: http://www.netgeo.com/download/ 2. Minimum hardware/software requirement Minimum hardware/software requirement is the following: - 256MB of RAM - Pentium 600MHz or equivalent speed CPU - 500MB of available harddrive space - Windows 2000/Me/XP or Linux - Java Runtime Environment (JRE) version 1.3.x Recommended hardware/software configuration is the following: - 512MB of RAM or more - Pentium 1GHz or equivalent speed CPU - 1GB of available harddrive space - Windows 2000 or Linux - Java Runtime Environment (JRE) version 1.4.1 3. Installing the InfoScope Installing infoscope_setup_2_3.exe is straight forward. Once the file is downloaded, you can double click on the file and follow the instructions to install InfoScope server and client in Java. As for infoscope_2_3.tar.gz, you can unzip and untar in the directory that you intend to install InfoScope. Once installed, both version will install themselves in the following directory structure: - infoscope_root +--- bin : contains scripts to run class files | +--- conf : contains configuration files | +--- data : contains the IP-to-geolocation datafile | +--- docs : various documentations | +--- lib : third party jar files and InfoScope jars | +--- logs : access/error logs go here 4. Launching the InfoScope In order to launch the InfoScope server, you need to do make sure the followings: - JAVA_HOME environment variable - NG_SERVER_HOME environment variable - NG_HOME environment variable - Remote client's IP included in ngserver.auth Let's look at each and how they can be configured in the subsequent subsections. 4.1. JAVA_HOME environment variable JAVA_HOME environment variable is needed to locate the JRE to run InfoScope. InfoScope server is written entirely in Java 1.3.x. For this reason, you need JRE 1.3.x or later version to properly run the server. For instructions on obtaining the JRE 1.3.x or later versions, please consult javasofr's page at http://java.sun.com/. Once you have proper JRE installed on your machine, JAVA_HOME environment variable should point to JRE's root directory. For instance, if you have installed JRE under 'c:\j2sdk1.4.1' directory, then JAVA_HOME should have 'c:\j2sdk1.4.1'. For windows, you could do this in a couple of different ways: One is to use 'set' command and set the variable in the console window, and the other is to set it system-wide environment variable from the system property. In order to use 'set' command, you first open up the console window, and type the following: set JAVA_HOME=c:\j2sdk1.4.1 (that is if you have installed JRE under c:\j2sdk1.4.1 directory.) This environment variable would disappear once you close this console window. In order to use system-wide environment variable, go to start | settings | control panel | System icon | Advanced tab. Clicking on the 'Environment Variables...' button will pop up a window listing all the environment variables defined currently. Click on the 'New' button from the 'System variables' section. Type 'JAVA_HOME' for the variable name, and 'c:\j2sdk1.4.1' for the variable value (that is if you have installed JRE under c:\j2sdk1.4.1 directory). Click on 'OK' to save the change and 'OK's to close the parent pop-up windows. This environment variable would appear on everytime you log on to the machine. For Unix, you set the environment variable by typing the following: [for sh or ksh] JAVA_HOME=/usr/local/java; export JAVA_HOME [for csh] setenv JAVA_HOME /usr/local/java (that is if you have installed JRE under /usr/local/java directory.) In order to automatically execute the environment variable setting, you can include the above lines in your .login script to have it configured when you log in. 4.2. NG_SERVER_HOME environment variable NG_SERVER_HOME should point to the directory where InfoScope server is installed. For instance, if you have installed InfoScope at /usr/local/infoscope directory, then this needs to point to that directory. However, if you are launching the server from the '$NG_SERVER_HOME/bin' directory with the ngserver script, then you do not need to worry about this environment variable, as the script relatively finds the executables. Otherwise, you need to set it in similar ways shown in subsection 3.1. 4.3. NG_HOME environment variable NG_HOME should point to the directory where InfoScope client is installed. Starting from version 2.3, this should be the same as the NG_SERVER_HOME, that is, client is installed in the same directory where server is installed. For instance, if you have installed InfoScope at /usr/local/infoscope directory, then this needs to point to that directory. If you are launching the server from the '$NG_HOME/bin' directory with the ngplugin_java script, then you do not need to worry about this environment variable, as the script relatively finds the executables. Otherwise, you need to set it in similar ways shown in subsection 3.1. 4.4. Remote client's IP included in ngserver.auth '$NG_SERVER_HOME/conf/ngserver.auth' file contains the allowed client IPs to access the server. If your client IP address is not included in the list, simply append the IP address here, and restart the server to have it affected. 4.5. Launching the server If you have gone through the above 4 steps, then you are ready to launch the InfoScope server. Go to '$NG_SERVER_HOME/bin' directory and type the following to start up the server: [for Windows] ngserver.bat start [for Unix] ngserver.sh start To stop the server once it's running, you could either ctrl-c from the console window you've started the server, or type the following from the different console window: [for Windows] ngserver.bat stop [for Unix] ngserver.sh stop Alternatively, if you are on Windows, and installed InfoScope using infoscope_setup_2_3.exe, then you could start the server by start | programs | infoscope | start server, and stop the server by start | programs | infoscope | stop server. 4.6. Launching the demo client Once the server is running, now you are ready to start the client. Change the current directory to '$NG_HOME/bin' and type the following: [for Windows] ngplugin_java.bat i [for Unix] ngplugin_java.sh i This starts up the interactive command line session with the server. You can type IP address in dot notation, such as xxx.xxx.xxx.xxx, and get the geolocation information back from the server. 5. Applying InfoScope client APIs InfoScope client API is available for you to integrate IP-to-geolocation solution to your environment. The example source code, and javadoc of API are included in the '$NG_HOME/docs/api_doc.zip' or '$NG_HOME/docs/api_doc.tar.gz'. 6. Customizing configuration files There are several files found under '$NG_SERVER_HOME/conf' directory. While some files are configurable, some are not. Non-configurable system files are the following two: ngplugin.key : Java plugin key file needed by the client to connect to the server .regkey : Auto-generated registration key file needed by the server to start The above two files should not be edited. If they are modified in any way, either server or client may not function properly. In order to obtain the ngplugin.key or .regkey file, visit http://www.netgeo.com/download/. The rest of configuration files are editable. They are ngserver.cfg : Configures server related variables. ngserver.auth : Lists client machines' IP addresses that are accepted by the server. ngwatchdog.cfg : Configures watchdog related variables (Watchdog is the running process that pings server, and restarts the server when server is not responding). ngplugin.cfg : Configures client related variables. Let's look at each file in subsequent subsections. (Note that once variables are updated, for them to take effect, the server needs to be restarted.) 6.1. ngserver.cfg 'ngserver.cfg' configures server related variables. Port : Port number server listens for the client requests. AdminPort : Port number server listens for administrative requests, such as server stop request and watchdog services. 'AdminPort' needs to be different from 'Port'. MaxThreadConnection : Maximum number of concurrent client connections allowed plus 1. For example, if you want to allow maximum of 5 concurrent client connections from the server, you set this variable to 6. Recommended value is less than 10. AuthorizedClientFile : Filename of the authorized client IP file. This file should contain newline delimited IP addresses from which clients could access the server. If non-listed IPs trying to access the server, server rejects the connection attempt. DBFile : Datafile name to use. Datafile must be located in '$NG_SERVER_HOME/data' directory. ErrorLogFile : Error log filename to use. Error log file will be created in '$NG_SERVER_HOME/logs' directory. If such file already exists, error logs are appended to the end of the file. AccessLogFile : Access log filename to use. Access log file will be created in '$NG_SERVER_HOME/logs' directory. If such file already exists, access logs are appended to the end of the file. Note that this needs to be different from 'ErrorLogFile' for an obvious reason. ErrorLogFlag : Whether to generate error log or not. 'true' will generate the error logs, 'false' will not. AccessLogFlag : Whether to generate access log or not. 'true' will generate the access logs, 'false' will not. 6.2. ngserver.auth 'ngserver.auth' lists IP addresses that clients could access the server from. If a client trying to connect to the server from non-listed IP address, the connection is rejected. If you have a client located remotely and trying to access the server, make sure the client's IP address is included in this file. 6.3. ngwatchdog.cfg 'ngwatchdog.cfg' configures the watchdog related variables. Watchdog is a process that pings the server periodically, and upon detecting the server is not reachable, it attempts to restart the server, and send an email notification to appropriate parties. Watchdog can be started by using the following command: [for Windows] $NG_SERVER_HOME/bin/ngserver.bat watch or [for Unix] $NG_SERVER_HOME/bin/ngserver.sh watch Watchdog starts by reading the configurations from the '$NG_SERVER_HOME/conf/ngwatchdog.cfg'. Port : Port where server is listening in for client requests. This should be identical to the 'Port' value in 'ngserver.cfg' file. Delay : Initial delay time period in minutes before start periodically pinging the server. Period : Time delay in minutes between two successive pings. For instance, if 'Period' is 1, then it pings the server every minute. os.name : The OS type of the server. For all Unix type OS, specify 'Solaris'. ServerExec : Script that starts the server, namely 'ngserver'. This script must be found in '$NG_SERVER_HOME/bin' directory. Do not modify this value. From : "From" e-mail address field for server restart notification is taken from this variable. MailServer : Mailserver to use when sending server restart notification e-mail. To : "To" e-mail address field for server restart notification is taken from this variable. In order to specify multiple recipients, delimit the recipient e-mail addresses with ';', semicolon without any space. 6.4. ngplugin.cfg 'ngplugin.cfg' configures client related variables. PrimaryServer : Primary server's IP address. Client uses this IP address to make the initial connection to a server. PrimaryServerPort : Primary server's Port number. This port number should correspond to the 'Port' value in 'ngserver.cfg' on the primary server. SecondaryServer : Secondary server's IP address. Client uses this IP address to make the secondary connection to a server when the primary server is unreachable for any reason. SecondaryServerPort : Secondary server's Port number. This port number should correspond to the 'Port' value in 'ngserver.cfg' on secondary server. 7. Updating quarterly datafile As you may already know, IP-to-geolocation data change everyday. In order to keep up with the on-going changes, we provide quarterly datafile updates. This datafile updates are only available to registered users. If you are using a copy of InfoScope, please register it with us so that we could provide you the up-to-date datafile for more accurate result. You can register at http://www.netgeo.com/download/. 8. Feedback Your feedback is always valuable to us in improving our product. Please, send your feedkback, comments and bug reports to support@netgeo.com. Thank you for using InfoScope!