WebNMS IoT Platform 6.0 – Installation GuideJava Plug-in Version . Windows 10 59.0.2 65.x 1.7.0...

WebNMS IoT Platform 6.0 – Installation Guide


Table of Contents Introduction ................................................................................................................................................... 1 System Requirements ................................................................................................................................... 3

Hardware Requirements .......................................................................................................................... 3 Software Requirements ............................................................................................................................ 4

Installation and Setup Options ..................................................................................................................... 7 Installing WebNMS IoT ............................................................................................................................. 7 Installing WebNMS IoT as NT Service ................................................................................................... 16 Installing WebNMS IoT as Unix Service ............................................................................................... 22 Configuring Various Databases .............................................................................................................. 24 Configuring Database Parameters ......................................................................................................... 29 Uninstalling WebNMS IoT Server ......................................................................................................... 33 Licensing the Product ............................................................................................................................. 34 Upgrading the License ............................................................................................................................ 39 Uninstalling Service Pack ....................................................................................................................... 43 Installing Service Pack ............................................................................................................................ 46

Cloud Deployment ...................................................................................................................................... 53 Cloud Deployments ................................................................................................................................ 53 Data Center Installation ......................................................................................................................... 53 Deploying IoT in Azure Cloud ................................................................................................................ 54 Deploying IoT in AWS Amazon Cloud ................................................................................................... 62 Introduction ............................................................................................................................................ 62 Architecture ............................................................................................................................................. 62

Startup Options ...........................................................................................................................................67 Starting WebNMS IoT Server ................................................................................................................ 68 Starting WebNMS from Command Line ( bin Directory) ..................................................................... 71 Starting the Web Client ........................................................................................................................... 72 Reinitializing WebNMS .......................................................................................................................... 78 Shutting Down WebNMS Server ........................................................................................................... 80


Introduction The WebNMS IoT Installation Guide explains the system requirements and the procedures involved in installing and getting started with WebNMS IoT Platform in different operating systems such as Windows and Linux. The later sections of the documents provide advanced Cloud Deployment procedures. The various sections of the documents and the contents is provided below:

• System Requirements- Provides the hardware and software requirements to install and work

with WebNMS IoT Platform.

• Installation and Setup Options - Provides product Installation, Licensing, and Service pack installation details in Windows and Linux. Database Setup & Configuring Database Parameter options are stated in this section.

• Cloud Deployment - Provides the Data Center port configuration details. Deployments of IoT in Azure and AWS Cloud are provided as an illustration in this section.

• Startup Options - Provides complete details on starting, reinitializing, and shutting down procedures in the product.

Note: WebNMS IoT Platform Android App is available for download in the play store. The App provides a user interface for monitoring and managing IoT assets remotely.

Product Support

• For sales queries, send mail to [email protected].

• For technical support queries, send mail to [email protected].

• For contact information, refer to Contact page on our Web site www.webnms.com.

Copyright @ 2019 1

https://play.google.com/store/apps/details?id=com.webnms.iot

https://play.google.com/store/apps/details?id=com.webnms.iot

mailto:[email protected]


https://www.webnms.com/iot/contact.html

http://www.webnms.com/


System Requirements

Hardware Requirements

• Hardware Configurations

Introduction WebNMS IoT Platform can be installed on Windows and Linux system. It is necessary to have the basic hardware requirement to install and run the platform without any issues. The performance of WebNMS IoT Platform depends considerably on the CPU and memory of both the client and server systems. Therefore it is vital to check on the hardware configurations before proceeding with the installation. Hardware Configurations The following table describes the suggested minimum configuration of the client and the server.

Operating Platform

Processor Type

Processor Speed Memory

Hard Disc Space Required

(For Installation)

Extra Disc Space Required

(For Execution) Windows Quad-core 2+ GHz 16 GB RAM 500 GB 1 GB

Linux Quad-core 2+ GHz 16 GB RAM 500 GB 1 GB

Note: It is suggested to have two servers (1 Operational + 1 StandBy Server), though it is not mandatory. The Standby server will ensure availability even at times when the operational server stops functioning.

Copyright @ 2019 3


Software Requirements

• Software Requirement

• Linux

• Windows

• Database Drivers

Introduction WebNMS IoT Platform can run on Windows and Linux systems with the necessary hardware configuration. This section of the document states the software supported i.e. the browsers and database drivers etc., on Windows and Linux OS. Software Requirement Below is a list of software versions supported by WebNMS. Though WebNMS supports different software versions, only a particular software version is bundled with the product.

• Windows 7, Windows 2010

• Ubuntu 14.04 LTS or higher, CentOS Linux release 7.2.151, CentOS Linux 7 (Core) For the complete list of software versions bundled with WebNMS, refer to the section Packages Bundled in the User & Admin Guide.

Windows Platform The tables below list the software that is compatible with WebNMS IoT on Windows platform. Back-end Server

Platforms Java Version JRE/JDK

Database Web Server and Servlet Engine MySQL PostgreSQL MSSQL

Windows 10

JRE 1.7.0 JDK 1.7.0 5.5x 10.2 2012 Tomcat 5.5.20

Front-end Server

Platforms JRE Version Web Server and Servlet Engine

Windows 10 1.7.0 Tomcat 5.5.20

Client

Copyright @ 2019 4


Platforms Browser*

JRE Version Firefox ** Chrome ** Java Plug-in

Version Windows 10 59.0.2 65.x 1.7.0 1.7.0

Linux Platform The tables below list the software that is compatible with WebNMS IoT on Linux platform.

Back-end Server

Platforms Java Version JRE/JDK

Database Web Server

and Servlet Engine MySQL PostgreSQL MSSQL

Ubuntu 14.04 LTS or higher

JRE 1.7.0 JDK 1.7.0

5.5x

10.2

2012 Tomcat 5.5.20

CentOS Linux release 7.2.1511

JRE 1.7.0 JDK 1.7.0

5.5x

10.2

2012 Tomcat 5.5.20

CentOS Linux 7 (Core)

JRE 1.7.0 JDK 1.7.0

55x

10.2

2012 Tomcat 5.5.20

Front-end Server

Platforms JRE Version Web Server & Servlet Engine

Ubuntu 14.04 LTS or higher 1.7.0 Tomcat 5.5.20

CentOS Linux release 7.2.1511 1.7.0 Tomcat 5.5.20

CentOS Linux 7 (Core) 1.7.0 Tomcat 5.5.20

Client

Platforms

Browser* JRE

Version Firefox** Chrome** Java

Plug-in Version

Ubuntu 14.04 LTS or higher 59.0.2 65.x 1.7.0 1.7.0

CentOS Linux release 7.2.1511

59.0.2 65.x 1.7.0 1.7.0

CentOS Linux 7 (Core) 59.0.2 65.x 1.7.0 1.7.0

Copyright @ 2019 5


Note: * - HTML UI - Cookies and Java Script should be enabled ** - The browsers supported versions are versions provided in the chart and higher versions.

Database Drivers By default, PostgreSQL 10.2 is bundled with the product. To use any other supported database, certain third party software such as database drivers must be downloaded by the users from the respective sites, and relevant modifications must be done in the database related configuration files.

Database JDBC Driver (WebNMS is JDBC 2.0 compliant)

PostgreSQL PostgreSQL 10.2 (Bundled Version) postgresql_jdbc4.jar

MySQL

MySQL 5.5x mysql-connector-java-5.1.45-bin.jar

MSSQL

SQL SERVER 4 sqljdbc4-2.0.jar

Refer to the Configuring Various Databases section in this document for details on configuring a database. The Java Plug-In can be downloaded from the following link: http://java.sun.com/products/plugin/index.html.

Copyright @ 2019 6

http://java.sun.com/products/plugin/index.html


Installation and Setup Options

Installing WebNMS IoT

• WebNMS IoT Server Installation Steps

• Post Installation Setup

• Configuring Multiple Instances of WebNMS IoT

Introduction The procedure involved in installing the WebNMS IoT product in Windows and Linux system is stated in this document. There are three different ways in which the product can be installed depending on the environment in which the product is to be used. The following table describes the different options and the installation environments.

Mode Description Scenario GUI Mode

Interactive and GUI based

This installation is mostly used in development environment.

Command or Console Mode

Interactive and Non-GUI based

This installation is mostly used while deploying in the production environment.

Silent Mode

Non-interactive and Non-GUI based

This installation is mostly used while deploying in the server machines in the production environment.

Prerequisite

1. Download the installation files (.exe file for Windows and .bin files for Linux) directly from the online Download Page. Or mail to [email protected] the product download. Note: The latest product download is available online in the Download Page and the latest service pack for the product is available in the Service Pack page.

2. Check the executable permission of the .bin/.exe file using the ls -al as given below:

ls -al WebNMS_IoT_Platform_Windows.exe -rwxrwxrwx 1 user group 256009000 Jun 28 15:48 WebNMS_IoT_Platform_Windows.exe r - read permission, w - write permission, x - executable permission.

If the file is not executable, run the following command to provide executable permission for all users:

chmod a+x WebNMS_IoT_Platform_Windows.exe

Copyright @ 2019 7

https://www.webnms.com/iot/download.html



Warning : The example is provided with the windows executable file (.exe). Use the linux binary file name (.bin) for a Linux based installation.

WebNMS IoT Server Installation Steps

GUI Mode of Installation

1. Execute the downloaded file. The InstallShield Wizard with the Welcome message is displayed.

2. Click Next. The License Agreement screen is displayed. Read the Agreement and select "I accept the License Agreement".

3. Click Next. The Localization screen is displayed. Choose the required language - English (default), Japanese, or Chinese.

Copyright @ 2019 8


4. Click Next. The Edition screen is displayed. It provides the choice of Server and Advanced installation options. Select Server to install the Combo package (BE server, FE server).

5. Click Next.

6. If you have chosen Server, skip this step and proceed to the next. If you have chosen Advanced, perform this step and proceed. When Advanced is chosen, the OEM Edition - Advanced screen is displayed with various installation options. Select the required type of installation.

7. Click Next. The directory location screen is displayed. Specify the location where WebNMS IoT server has to be installed. Use the Browse button to specify a different location.

8. Click Next. The details of the installation (pre-installation summary) is displayed. If you need

to change any of it, use the Back button to modify.

Copyright @ 2019 9


9. Click Next. The installation begins. Once the installation is complete, a final screen is

displayed.

10. Click Finish.

Command/Console Mode of Installation

The Command or Console mode is an Interactive and Non-GUI based installation mode. The user can install WebNMS IoT Platform through the command prompt. Follow the steps provided below to install the WebNMS IoT Platform in this command or console mode:

1. Execute the file to install WebNMS with -console parameter as follows :

* For Windows <File Name>.exe –console * For Linux : <File Name>.bin –console

The above command will initiate an interactive installation procedure. The user needs to select the options from the messages displayed on the command prompt.

Silent Mode of Installation

The Silent mode is a Non-interactive and Non-GUI based installation mode. This mode of installation is generally useful for automated setups. The user can specify all the options required in a text file and the installation process continues without manual intervention. The steps to install WebNMS IoT in Silent mode is provided below :

1. For building the installoptions.txt file required for installation, open a new text file and copy the following contents and save the file as installoptions.txt.

#******************************************************

-W locale.lang=English

-W OEMProducts.selectedValue=OEMADV

-W OEMAdvance.selectedValue=OEMADVBE

-W StdCustom.optComponents=Javadocs

-G replaceExistingResponse=”yesToAll”

#******************************************************* The editable options beginning with "-W" can have the following values.

Options Description

locale.lang

Specifies the language in which the Installation will take place.

• English

• Chinese

• Japanese

OEMProducts.selectedValue Specifies the options for installation

• OEMSTD for standard installation

Copyright @ 2019 10


• OEMADV for advanced installation

OEMAdvance.selectedValue

Specifies the category for advanced installation

• OEMADVBE for Back-End Server installation

• OEMADVFE for Standalone Front-End Server installation

• OEMADVClient for Standalone Client installation

StdCustom.optComponents Specifies the option for including Javadocs. The valid values are

• Javadocs - For installing only Javadocs

2. Execute the .exe or .bin files as follows where <InstallLocation> should be replaced by the path where WebNMS has to be installed. For Windows: <File Name>.exe -is:javaconsole -silent -options installoptions.txt -P ProductRoot.installLocation=<InstallLocation> Eg. WebNMS_IoT_Platform_Windows.exe -is:javaconsole -silent -options installoptions.txt -P ProductRoot.installLocation=D:\Product_IoT

For Linux: ./<File Name>.bin -is:javaconsole -silent -options installoptions.txt -P ProductRoot.installLocation=<InstallLocation>

Where,

InstallLocation is any writable location in the system, where the product has to be installed. installoptions.txt is the text file which supplies different arguments to the installer (creating this file is explained above)

Points to remember while installing in Silent Mode.

1. Avoid installing the product using silent mode in a previously installed location.

2. Changing the variable name in the installoptions.txt file (value on LHS of "=") leads to installation failure.

3. The variable OEMAdvance.selectedValue will have no effect if OEMProducts.selectedValue is set to OEMSTD.

Post Installation Setup The following basic configuration needs to be performed before starting the server.

1. Set JAVA_Home classpath in setEnv.bat. Open setEnv.sh file under <WebNMS_IoT_Home> installation directory, and provide JDK home directory path for set JAVA_HOME classpath. Save and close the file. Eg. JAVA_HOME= JAVA_HOME=/home/local/ZOHOCORP/jones-1234/jdk1.7.0_55

2. Set the port values in setEnv.sh file. By default the WEBSERVER and DATA ports are as given below. These values can be modified if required. Also ensure that both the ports have external firewall access. WEBSERVER_PORT=9090 M2MDATA_PORT=9089

Copyright @ 2019 11


3. Set the MEMORY_USAGE_THRESHOLD in NmsProcessBE.conf file. Modify the value

from 0.7 to 0.97.

#com.adventnet.nms.management.WebNMSMgmtBEProcess [MEMORY_USAGE_THRESHOLD 0.1-1.0] [MONITOR_BE_MEMORY_USAGE true/false] [MONITOR_FE_JVM true/false] [RUN_GARBAGE_COLLECTOR true/false] PROCESS com.adventnet.nms.management.WebNMSMgmtBEProcess ARGS MEMORY_USAGE_THRESHOLD 0.97 MONITOR_BE_MEMORY_USAGE true MONITOR_FE_JVM true RUN_GARBAGE_COLLECTOR false

4. Set the cleanup interval CLEAN_DATA_INTERVAL value as per your requirement in the NmsProcessesBE.conf file.

PROCESS com.adventnet.nms.poll.Collector ARGS MAX_OIDS_IN_ONE_POLL 15 AUTHORIZATION true

DATA_COLLECTION_QUERY_INTERVAL 120000 PASS_THRO_ALL_POLLING_OBJECTS true CLEAN_DATA_INTERVAL 90

In the above example, the database will contain the statstable for 90 days.

5. Extra Polled Data configuration can be done in rtuDoc.xml present under <WebNMS IoT Home>/conf. The pdtypes counter and state can be configured for the parameters. This will be configured by default in the rtuDoc.xml file, however it is important to verify that the desired pdtype is set.

Counter - Sample Entry

<Device name="ACEnergyMeter" value="ACEnergyMeter"> <parameter name="Voltage" value="Voltage" units="volts" pdtype="false"/> <parameter name="Current" value="Current" units="amps" pdtype="false"/> <parameter name="Frequency" value="Frequency" units="Hz" pdtype="false"/> <parameter name="ActivePower" value="ActivePower" units="KW" pdtype="false"/> <parameter name="Energy" value="Energy" units="KWH" pdtype="counter"/> <parameter name="ApparentPower" value="ApparentPower" units="KVA" pdtype="false"/> <parameter name="ReactivePower" value="ReactivePower" units="KVAR" pdtype="false"/> <parameter name="PowerFactor" value="PowerFactor" units=" " pdtype="false"/> </Device>

In the above example entry with pdtype="counter" configuration, the difference will be calculated and stored in the field ENERGYMETER_ENERGY_delta in the database. This configuration can be done for any of the above parameters defined for the ACEnergyMeter device.

Copyright @ 2019 12


State - Sample Entry

<Device name="DoorSensor" value="DoorSensor" polledData="true" pdtype="state" stateName="ActPower1"/> <Device name="AC" value="AC" polledData="false" pdtype="state" stateName="ActPowe2"/> Add the below lines: <state> <key name="ActPower1"> <parameter name="0" value="ZERO"/> <parameter name="1" value="ONE"/> </key> <key name="ActPower2"> <parameter name="2" value="TWO"/> <parameter name="3" value="THREE"/> </key> </state> In the above sample entry with the pdtype="state" configuration, the binary i.e. 0 or 1 into string format as ON or OFF. This will be stored in the custom polled data field DOOR_enumerated in the database.

6. Optimize the Web Server thread size in server.xml file under <WebNMS_Home>/apache/tomcat/conf/backup. The maxThreads, minSpareThreads, maxSpareThreads properties need to be modified in this file.

Default Properties Connector port="M2MDATA_PORT" maxThreads="50" minSpareThreads="3" maxSpareThreads="10" Connector port="WEBCONTAINER_PORT" maxThreads="50" minSpareThreads="3" maxSpareThreads="10"

Modified Properties

Connector port="M2MDATA_PORT" maxThreads="500" minSpareThreads="300" maxSpareThreads="400" <Connector port="WEBCONTAINER_PORT" maxThreads="500" minSpareThreads="300" maxSpareThreads="400" The above change done in server.xml file in backup folder needs to be performed in server.xml file in <WebNMS IoT Home>/apache/tomcat/conf folder also. <Connector port="9089" maxThreads="500" minSpareThreads="300" maxSpareThreads="400" enableLookups="true" acceptCount="100" connectionTimeout="-1" disableUploadTimeout="true" URIEncoding="UTF-8" compression="force" compressionMinSize="1024" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml"/>

7. Define the cleanup data period with CLEANUP_DATA_OLDER_THAN in the ReportsManagement.xml file. This will help in showing reports or widgets over a longer period in <WebNMS IoT Home>/conf/ file.

Open the file ReportsManagement.xml, then find the string name "CLEANUP_HOURLY_DATA" then change the value of the property "CLEANUP_DATA_OLDER_THAN" as per your requirement.

Copyright @ 2019 13


Hourly CleanUp Sample Entry

<DATA_CLEANUP className="com.adventnet.nms.server.dataarchiver.DefaultDataCleanupIfcImpl" executeInterval="1" executeIntervalUnit="DAYS" id="CLEANUP_HOURLY_DATA"> <PROPERTY name="TABLE_LIST" value="STATSAGGREGATIONHOURLY"/> <PROPERTY name="TIME_FIELD" value="TTIME"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN" value="2880"/> <PROPERTY name="TYPE" value="PERFORMANCE"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN_UNIT" value="HOURS"/> </DATA_CLEANUP>

Note: Here 2880 is the hours of 120 days. You can change this to any based on your actual requirement.

Daily CleanUp Sample Entry Existing entry: <DATA_CLEANUP className="com.adventnet.nms.server.dataarchiver.DefaultDataCleanupIfcImpl" executeInterval="1" executeIntervalUnit="DAYS" id="CLEANUP_DAILY_DATA"> <PROPERTY name="TABLE_LIST" value="STATSAGGREGATIONDAILY"/> <PROPERTY name="TIME_FIELD" value="TTIME"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN" value="90"/> <PROPERTY name="TYPE" value="PERFORMANCE"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN_UNIT" value="DAYS"/> </DATA_CLEANUP> Modified entry: <DATA_CLEANUP className="com.adventnet.nms.server.dataarchiver.DefaultDataCleanupIfcImpl" executeInterval="1" executeIntervalUnit="DAYS" id="CLEANUP_DAILY_DATA"> <PROPERTY name="TABLE_LIST" value="STATSAGGREGATIONDAILY"/> <PROPERTY name="TIME_FIELD" value="TTIME"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN" value="365"/> <PROPERTY name="TYPE" value="PERFORMANCE"/> <PROPERTY name="CLEANUP_DATA_OLDER_THAN_UNIT" value="DAYS"/> </DATA_CLEANUP>

Note: Here the cleanup interval has been set for 1 year that is 365 days. You can change this to any based on your actual requirement.

8. Start the WebNMS server using <IoT_Home>/bin/startnms.sh file. Execute startnms.sh file from command prompt or double click and execute the file. In the command prompt, you can see that the tables are created and WebNMS Process is started. Once the WebNMS IoT server is started properly, you will see a print “ Please connect your client to the web server on port : 9090”. For more details on starting the server, please refer to the section "Starting WebNMS IoT Server"

9. Now you can connect client to WebNMS server by providing the following URL with the IP Address and Server port in the address bar of Firefox/Chrome browser. Eg. http://<IP Address>:9090/LoginPage.do

Copyright @ 2019 14


For more details on starting the web client, please refer to the section "Starting WebNMS IoT Client".

10. In the login page, enter the user credentials. User Name : root Password : public

Note: For starting the server in Failover setup, refer to the document on Enabling High Availability.

Configuring Multiple Instances of WebNMS IoT To avoid port conflicts when running multiple instances of WebNMS IoT in the same machine, the following port changes must be done in the configuration and script files.

1. Install WebNMS IoT as stated in this Installation section of this document.

2. Perform the Post Installation Steps.

3. Edit <WebNMS IoT Home>/setEnv.bat/sh and provide and unused port value: WEBSERVER_PORT=9090 e.g. 9091 M2MDATA_PORT=9089 e.g. 9088 TOMCAT_SHUTDOWNPORT=8005 e.g. 8006

4. Edit <WebNMS IoT Home>/bin/startnms.bat/sh and provide and unused port value: -Dcom.sun.management.jmxremote.port=16000 e.g. 16001 -Dcom.sun.management.snmp.port=16500 e.g. 16501 com.adventnet.nms.startnms.NmsMainBE NMS_BE_PORT 2000 e.g. 2001

5. Edit <WebNMS IoT Home>/conf/serverparameters.conf and do the following modifications: NMS_BE_PORT 2000 e.g. 2001 RMI_REG_PORT 1099 e.g. 1098

Note: To configure a different database instance, modify the <WebNMS IoT Home>/classes/hbnlib/hibernate.xml file and provide a different dbname. Example : <property name="connection.url">jdbc:postgresql://localhost/WebNmsDB</property>

Copyright @ 2019 15

https://www.webnms.com/iot/help/developer_guide/failover_service/failover_overview.html

https://www.webnms.com/iot/help/developer_guide/failover_service/failover_overview.html


Installing WebNMS IoT as NT Service

WebNMS IoT Platform can be installed as an NT Service. Here the WebNMS IoT Platform product starts when the machine boots up along with other services such as Telnet, FTP etc. This section will guide you in installing and uninstalling WebNMS IoT as an NT Service. This topic explains:

• Installing Web NMS as NT Service

• Uninstalling the Web NMS Service

• Usage of wrapper.exe file for NT Service

• Configurable Parameters in wrapper.conf file

• Configuring HTTP Proxy Host and Port to upload Support Information File to WebNMS Support

• Configuring WebNMS IoT Classes

Warning: If you want to start a fresh installation of WebNMS IoT as a Java service, you must first start the server in the normal mode, supply the required license information and then restart as a Java service. The server will not start as a Java service directly, due the license requirements.

Installing WebNMS IoT as NT Service

• Execute wrapper.exe -i from the command prompt from <WebNMS IoT Home > directory to install Web NMS as NT Service. For information on the parameters in wrapper.exe file, refer to Configurable Parameters in wrapper.conf file.

Example command:

C:\Program Files\WebNMS>wrapper.exe -i conf\wrapper.conf Uninstalling the WebNMS IoT Service

• Execute wrapper.exe -r from the command prompt to uninstall Web NMS Service.

Example command:

C:\Program Files\WebNMS>wrapper.exe -r conf\wrapper.conf

Note:

• When WebNMS service is run, it takes PostgreSQL as its database, as PostgreSQL is the default database bundled with WebNMS. To start WebNMS with a different database, add/edit the wrapper.ntservice.dependency.<x> property of wrapper.conf file

Copyright @ 2019 16


under <WebNMS IoT Home>/conf directory In addition, modify the database_params.conf and DatabaseSchema.conf in the respective database directory under <WebNMS IoT Home >/conf directory and copy the files to <WebNMS IoT Home >/conf. Also modify the hibernate.cfg.xml file available in the <WebNMS IoT Home >/classes/hbnlib directory.

• To make any change to the Java service, you must set the classpath in wrapper.conf file under <WebNMS IoT Home >/conf directory.

Usage of wrapper.exe file for NT Service options in WebNMS Windows version The command: wrapper.exe <command> <configuration file> [configuration properties] [...]

• <command> can be one of:

a. -c run as a Console application

b. -t starT an NT service

c. -p stoP a running NT service

d. -i Install as an NT service

e. -r Remove as an NT service

f. -? print this help message

• <configuration file> is the wrapper.conf to use

• [configuration properties] are configuration name-value pairs which override values in wrapper.conf.

For example: wrapper.debug=true

Configurable Parameters in wrapper.conf file

Command Parameter Description Default Value (If any) wrapper.java.command The Java executable to

be used to run the server.

Configured to the bundled JRE.

wrapper.java.mainclass * The wrapper class to be used to start and stop the WebNMS service.

org.tanukisoftware.wrapper.WrapperSimpleApp

wrapper.java.classpath **** This parameter is used to set the JARs and class directories into classpath.

All WebNMS server side classes (including database JARs, Hibernate JARs, Tomcat JARs, and wrapper JAR) are kept.

Copyright @ 2019 17


The directories and JARs are configured serially numbered starting from 1. The path should configured with respect to <Web NMS Home> directory. Example: wrapper.java.classpath.55=classes/test1.jar //Points <WebNMS IoT Home>/classes/test1.jar wrapper.java.classpath.56=classes/test2.jar //Points <<WebNMS IoT Home>>/classes/test2.jar

wrapper.java.library.path The libraries to be kept in the path when starting the server.

Configured to <WebNMS IoT Home>/lib directory. If needed additional paths can be configured as wrapper.java.library.path.2, 3 etc.

wrapper.java.additional ** The system properties (-D) and non-standard (-X) parameters are configured. (Example: To use SSL, Dual NIC Machine etc.,)

The default system parameters values are configured.

wrapper.java.initmemory Initial Java Heap Size (in Mega Bytes)

The default value is 100.

wrapper.java.maxmemory Maximum Java Heap Size (in Mega Bytes)

The default value is 64.

wrapper.app.parameter The main class to start the server and the required arguments are configured.

Default main class is com.adventnet.launcher.nms.StartNmsJdbc. Can be changed if required.

wrapper.logfile The log file where the output of the wrapper console is to be logged.

Configured to <Web NMS Home>/logs/wrapper.log file. Can be changed if required.

wrapper.logfile.maxsize Maximum size (number of lines) of a single log file.

The default value is 0. Can be changed if required.

wrapper.logfile.maxfiles Maximum number of log files after which the rollover should occur.

The default value is 0. Since the maximum files are 0, only one log file be present. Can be changed if required.

Wrapper Parameters applicable only for Windows wrapper.console.title This parameter is the

title of the console window, if run as a console application.

Configured as WebNMS.

wrapper.ntservice.name Name of the NT/Unix service.

WebNMS6

wrapper.ntservice.displayname Display name of the NT/Unix service.

WebNMS 6

wrapper.ntservice.description Description of the NT/Unix service.

WebNMS6 Service

wrapper.ntservice.starttype The mode in which the service is started. Automatic or Manual.

Configured as AUTOSTART.

wrapper.ntservice.interactive Allow the service to interact with the desktop.

Configured as TRUE.

Copyright @ 2019 18

http://wrapper.tanukisoftware.org/doc/english/launch-win.html%23console


wrapper.ntservice.dependency The Service(s) on which

WebNMS is dependent to get started.

Configure as per requirement. More than one dependency service can be configured. The dependent services can be configured serially numbered starting from 1.

* - Warning: We use the main class as WrapperSimpleApp. The method1 by default. Refer the other two methods (method2 and method3) documented in the Wrapper documentation. Note that when you use method2 or method3, the user name and password should be configured in the wrapper.conf file and when the password for the Admin user is changed, it should be changed in the wrapper.conf file also. Hence we recommend the default method (which uses WrapperSimpleApp) to start and stop the service.

** Configuring Additional WebContainer & IoT Ports

wrapper.java.additional.4=-Dwebcontainer.port=<Port number of webcontainer> (eg. 9090) wrapper.java.additional.5=-Dresource_check=<Resource Check port numbers> (eg. 9090,8009,8005) wrapper.java.additional.6=-Dwebserver.port=<Web server port number> wrapper.java.additional.18=-Dm2mdata.port=<m2m data port> (eg. 9089)

Configuring HTTP Proxy Host and Port to upload Support Information File to WebNMS Support To upload the Support Information File to WebNMS Support, you need to configure the HTTP Proxy Host and Port as given below. Before configuring WebNMS IoT as NT Service/Unix Service

• Edit the wrapper.conf file located in the <WebNMS IoT Home>/conf directory and add the following under the "wrapper.java.additional" parameter entries.

wrapper.java.additional.21=-Dhttp.proxyHost=<Host name of web proxy server> wrapper.java.additional.22=-Dhttp.proxyPort=80 wrapper.java.additional.23=-Dhttp.PROXY_USERNAME=<User name of proxy server> wrapper.java.additional.24=-Dhttp.PROXY_PASSWORD=<Password of proxy server> *The values should match with the entries provided in <WebNMS_IoT_Home>/bin/startnms.bat & <WebNMS_IoT_Home>/setEnv.bat files.

Copyright @ 2019 19

http://wrapper.tanukisoftware.org/doc/english/integrate.html%23method2

http://wrapper.tanukisoftware.org/doc/english/integrate.html%23method3


***** Before configuring Web NMS as NT Service/Unix Service

• Edit the wrapper.conf file located in the <WebNMS IoT Home>/conf directory and add the following under the "wrapper.java.classpath" parameter entries.

Configuring IoT classes

wrapper.java.classpath.58=classes/M2MServerClasses.jar wrapper.java.classpath.59=classes/httpclient-4.2.1.jar wrapper.java.classpath.60=classes/httpcore-4.2.1.jar wrapper.java.classpath.61=classes/httpmime-4.2.1.jar wrapper.java.classpath.62=classes/smslib-3.5.2.jar

*****

Before configuring WebNMS as NT Service/Unix Service

• Edit the wrapper.conf file located in the <WebNMS IoT Home>/conf directory and modify/add (if not present) the following under the "app.parameter" entries.

wrapper.app.parameter.4=<WEBSERVER_PORT> wrapper.app.parameter.5=<Webserver port number> wrapper.java.additional.18=-Dm2mdata.port=<m2m data port> *M2M data port must be added. *The values should match with the entries provided in <WebNMS_IoT_Home>/setEnv.bat file.

Configuring Secured Socket Layer (SSL) To configure the SSL, perform the procedure given below : Before configuring WebNMS IoT as NT Service/Unix Service

• Edit the wrapper.conf file located in the <WebNMS IoT Home>/conf directory and uncomment the following

#wrapper.java.additional.18=-Djavax.net.ssl.trustStore=conf/Truststore.truststore #wrapper.java.additional.19=-Dssl.port=8443

under the "wrapper.java.additional" parameter entries.

####################### FOR SSL ####################### #Change both -Dwebserver.port & -Dwebcontainer.port to 8443 in the above properties & Add below 2 properties #wrapper.java.additional.18=-

Copyright @ 2019 20


Djavax.net.ssl.trustStore=conf/Truststore.truststore #wrapper.java.additional.19=-Dssl.port=8443 ######## For SSL ends #############################

Copyright @ 2019 21


Installing WebNMS IoT as Unix Service

When WebNMS IoT is installed as a service, it starts when the machine boots up along with the other services like Telnet, FTP etc. This topic explains

• Installing WebNMS as UNIX Service in Linux machine

• Uninstalling the WebNMS UNIX Service

• Usage of wrapper.exe file for NT Service

• Configurable Parameters in wrapper.conf file

Warning: If you want to start a fresh installation of WebNMS IoT 6 as a Java service, you must first start the server in the normal mode, supply the required license information and then restart as a Java service. The server will not start as a Java service directly, due the license requirements.

WebNMS IoT can be installed as a Unix Service by performing the following steps by logging in as super user. Linux Machine

• Login to the system as super user. • Execute <Web NMS Home>/bin/admintools/setup-service.sh as:

# sh setup-service.sh install

If you are using the RPM PostgreSQL (that comes by default in Linux OS) skip the below step.

• Change the ownership of PostgreSQL 's data directory as follows: # chown -R pgsql <WebNMS Home>/pgsql/data

• WebNMS IoT will be installed as a UNIX Service. When you reboot/restart the system, at that

time WebNMS service will start and when you shutdown the system, WebNMS service will be shutdown.

Warning: Once you perform the above steps, thereafter WebNMS IoT installation can only be started by super user.

Uninstalling WebNMS Unix Service To uninstall WebNMS IoT as a Unix Service, execute the <WebNMS IoT Home>/bin/admintools/setup-service.sh script as follows:

# sh setup-service.sh uninstall

Copyright @ 2019 22


Using testwrapper file to start/stop WebNMS Service in Linux machines After installing WebNMS as UNIX Service in Linux machine, if you want stop, start, restart the WebNMS service, and use the testwrapper command. To stop WebNMS Service

• Execute ./testwrapper stop from the command prompt from <Web NMS Home> directory to uninstall WebNMS UNIX Service.

Example command: # ./testwrapper stop

To start WebNMS Service

• Execute ./testwrapper start from the command prompt from <WebNMS IoT Home> directory to install WebNMS as UNIX Service. For information on the parameters in wrapper.conf file, refer to Configurable Parameters in wrapper.conf file.

Example command: # ./testwrapper start

Detailed usage of the command is given below.

Usage of testwrapper file The command: ./testwrapper { console | start | stop | restart | status | dump }

command can be one of:

1. console run as a Console application

2. start run as UNIX service

3. stop stop running as UNIX service

4. restart restart as UNIX service

5. status run as a Console application

6. dump run as a Console application

Copyright @ 2019 23


Configuring Various Databases

• Configuring Hibernate for WebNMS IoT

• Database Supported

• Procedure to Configure WebNMS IoT for PostgreSQL

• Procedure to Configure WebNMS IoT for MySQL

• Procedure to Configure WebNMS IoT for MSSQL

WebNMS IoT Platform supports Hibernate and was tested with PostgreSQL, MySQL, and MSSQL. WebNMS supports Hibernate connection pooling, which is a store for all the database connections. Refer to the document on Connection Pooling for the detailed description. The Hibernate default value for the number of connections will be set for the product. Configuring Hibernate for WebNMS IoT Perform the configuration in the hibernate.cfg.xml file in the <WebNMS IoT Home>/classes/hbnlib directory. This configuration is common for all the databases.

Property Description Default Value (If any) For PostgreSQL connection.driver_class org.postgresql.Driver

com.p6spy.engine.spy.P6SpyDriver connection.url jdbc:postgresql://localhost/WebNmsD

B connection.username postgres connection.password dialect SQL dialect org.hibernate.dialect.PostgreSQLDialect databasename SQL dialect POSTGRESQL JDBC connection pool hibernate.c3p0.min_size 60 hibernate.c3p0.max_size 120 nontransaction.connection 20 hibernate.connection.autocommit true hibernate.c3p0.acquire_increment 3 hibernate.jdbc.batch_size 1000 hibernate.connection.isolation 2 current_session_context_class Enable

Hibernate's automatic session context management

thread

hibernate.cache.use_second_level_cache

true

hibernate.cache.provider_class org.hibernate.cache.EhCacheProvider hibernate.cache.use_query_cache true cache.provider_class Disable the org.hibernate.cache.NoCacheProvider

Copyright @ 2019 24


second-level cache

show_sql Echo all executed SQL to stdout.txt log file.

false

hbm2ddl.auto

The database will be updated with schema changes if any in between subsequent server startups.

update

hibernate.c3p0.acquireRetryAttempts 6 hibernate.c3p0.acquireRetryDelay 20000 hibernate.c3p0.breakAfterAcquireFailure

false

testQuery To check if the database is running. (Used internal)

select HOSTADDRESS from BEFailOver

hibernate.default_schema userName connection.schemaname Postgresql

specific parameter.

public

mapping resource - object mapping entries of the Topology, Map, Fault, and Performance modules are given here Database Supported Most of the RDBMS, which have a JDBC driver, are supported and in our lab we have tested the following databases extensively.

1. PostgreSQL

2. MySQL

3. MSSQL

Note:

• The databasename entry of the hibernate.cfg.xml file indicates the database (Example: POSTGRESQL, MYSQL, MSSQL) used by the WebNMS IoT server.

• Before moving the database files from the default database PostgreSQL to some other database, ensure that the tables related to collected data are properly reinitialized.

Procedure to Configure WebNMS IoT for PostgreSQL PostgreSQL 9.0.1 Professional Edition is the default database bundled with WebNMS IoT. WebNMS starts and initializes this database before starting the WebNMS IoT modules. Therefore, in Windows, Linux and Solaris environments, you can start the PostgreSQL daemon by invoking the script "startnms.bat/sh" present under <WebNMS IoT Home>/bin.

Copyright @ 2019 25


Note: After server shutdown, the PostgreSQL database should be shutdown separately by running the <WebNMS IoT Home>/bin/stopPostgresSQL.sh/bat. The database is not shutdown automatically on server shutdown because the database should be running if there is a need to take backups and for restoration process. To start the PostgreSQL database manually, run the <WebNMS IoT Home>/bin/startPostgresSQL.sh/bat script.

Procedure to Configure WebNMS IoT for MySQL

1. Edit the DB_CLASSPATH variable (which is by default set to postgresql driver) in setEnv.bat file under <WebNMS IoT Home> directory, and set the JDBC Driver for MySQL. Sample entry: Windows : set DB_CLASSPATH=%PGSQL_HOME%\driver\postgresql_jdbc4.jar;%NMS_CLASSES%\p6spy.jar;%NMS_HOME%\conf;%NMS_CLASSES%\log4j.jar;<AbsolutePath>\mysql_connector.jar

2. Copy the DatabaseSchema.conf file from <IoT_Home>/conf/MySQL directory to <IoT_Home>/conf directory.

3. Un-comment the following lines in the hibernate.cfg.xml file, and ensure the correct username/password is provided for the "connection.username" property .

  //REMOVE THIS 

4. Comment out the PostgreSQL database configuration lines :

  //CLOSE COMMENT 

Copyright @ 2019 26


5. Start the WebNMS IoT server.

Procedure to Configure WebNMS for MSSQL

1. Edit the DB_CLASSPATH variable (which is by default set to postgresql driver) in setEnv.bat file under <WebNMS IoT Home> directory to set the JDBC Driver for MSSQL. Set the JDBC Driver path to sqljdbc.jar or JTurbo.jar . An example entry in setEnv.bat file for MSSQL is given below. set DB_CLASSPATH=%NMS_HOME%conf/MSSQL/sqljdbc.jar or DB_CLASSPATH=%NMS_HOME%conf/MSSQL/JTurbo.jar

2. If the WebNMS Server is already started, then do a proper and normal shutdown. Do not terminate the process abruptly.

3. Copy the DatabaseSchema.conf file from <WebNMS IoT Home>/conf/MSSQL directory to <WebNMS IoT Home>/conf directory.

4. Un-comment the following lines in the hibernate.cfg.xml file, and ensure the correct username/password is provided for the "connection.username" property .

  //REMOVE THIS 

5. If JTurbo driver is use, then the following lines must be un-commented instead of the above lines.

  //REMOVE THIS 

6. Comment out the PostgreSQL database configuration lines :

  //CLOSE COMMENT 

7. Start the MSSQL Server.

8. Start the WebNMS Server.

Copyright @ 2019 28


Configuring Database Parameters

On selecting the database of your choice, there are certain configurations that you must effect for proper functioning. You can configure the database parameters like database location, driver name etc., by simply editing a configuration file. This document explains such possible configurations and answers the following questions:

• How to configure database location and data source name?

• How to configure the database driver?

• How to configure database user name and password?

• How to encrypt the database password?

• How to configure the database dialect?

• How to configure the database schema name?

• How to configure the default schema name?

• How to configure the connection and statement pooling in Hibernate?

All of the above parameters can be configured in the hibernate.cfg.xml file. Location of the Configuration file The hibernate.cfg.xml file is present under <WebNMS IoT Home>/classes/hbnlib/ directory. How to use the Configuration file? There are 5 sets of entries in the file one each for PostgreSQL, MySQL, MSSQL database applications. Un-comment only one set of entries based on the databases to be used and let the other set of entries remain commented. By default, PostgreSQL database entries remain un-commented and the other set of entries remain commented. The parameters in this file have to be altered before starting the WebNMS IoT Server. Any changes in this file, during server run-time, require a cold start of the server for the changes to take effect.

Note: The databasename entry in hibernate.cfg.xml indicates the database (e.g.: POSTGRESQL, MYSQL, MSSQL) used by the WebNMS server.

Configurable Parameters

The following database specific parameters can be configured using this file:

• Database location and data source name

• Driver Name

• User Name and Password

• Dialect

• Schema Name

Copyright @ 2019 29


How to configure database location and data source name? The location of the database can be configured using the connection.url property in hibernate.cfg.xml file. By default, the database location is set as "localhost". You can also enter the IP address or the DNS name of the machine in which the database server is running. The database for WebNMS IoT has the data source name as "WebNmsDB", by default. The table below explains the syntax:

Database Type url Syntax Example

MySQL jdbc:mysql://hostname/data source name jdbc:mysql://localh

PostgreSQL jdbc:postgresql://hostname/data source name jdbc:postgresql://losDB

MSSQL jdbc:sqlserver://host_name:port_number;databaseName=<databasename>

jdbc:sqlserver://locbaseName=WebNms

Note: This URL location is specific to database server and not to the WebNMS IoT Server. The database server and WebNMS IoT Server can run in separate machines.

How to configure the database driver? The JDBC driver class file for the database application used can be set against the connection.driver_class property in this file.

Database Type drivername Syntax MySQL com.mysql.jdbc.Driver

PostgreSQL org.postgresql.Driver

MSSQL com.microsoft.sqlserver.jdbc.SQLServerDriver You can have any JDBC compatible JDBC driver name of your choice. Ensure that you have configured the class path by setting the same in setEnv.bat/.sh located in <IoT_Home> directory. Example set DB_CLASSPATH=D:\DBTool\classes12.zip

How to configure database user name and password? User name and password are parameters required to login to the database. These parameters need to be configured only if applicable and can be done so using the connection.username and connection.password properties in the hibernate.cfg.xml file for the chosen database. By default, the user name is 'postgres' and password is ‘postgres’. For MySQL the blank password parameter is kept by default.

Copyright @ 2019 30


These parameters are used by the Server to connect to the database, if there are any problems the Server will not startup.

How to encrypt the database password? If required, the database password specified in hibernate.cfg.xml file can be encrypted for security reasons. For getting a password in the encrypted form, please follow the steps stated below: Step 1 Execute EncryptPassword.sh/bat file present under <WebNMS IoT Home>/bin/admintools with the following parameters: EncryptPassword.sh/bat username password encryptpassword where,

• username - an authorized user of the WebNMS system, say postgres

• password - the password for the above authorized user, say postgres

• encryptpassword - the database password that has to be encrypted

Step 2 The password in the encrypted form will be displayed on the screen. For example, if you want the encrypted form for the password 'tiger' the same will be displayed as: Encrypted Password for password "tiger" is: eK6q2X8. Copy that encrypted password. Step 3

• Add the connection.encryptedpassword property of <WebNMS IoT Home>/classes/hbnlib/hibernate.cfg.xml file, and add the encrypted password.

• Ensure that the connection.password property with no values is present in the <WebNMS IoT Home>/classes/hbnlib/hibernate.cfg.xml.

<property name="connection.password"></property> The above entry must be present below the connection.encryptedpassword property entry in the file.

• Now that the database password appears in the encrypted form, you may proceed with operations as usual.

Note:

• The WebNMS IoT Server need not be running when executing this file.

• Only authorized WebNMS IoT users can change the password to the database.

How to configure the database dialect? The dialect for the database application used can be set against the dialect property in this file.

Copyright @ 2019 31


Database Type drivername Syntax

MySQL org.hibernate.dialect.MySQL5InnoDBDialect PostgreSQL org.hibernate.dialect.PostgreSQLDialect

MSSQL org.hibernate.dialect.SQLServerDialect

How to configure the database schema name? The schema name for the database application used can be set against the connection.schemaname property in this file.

Database Type schemaname Syntax MySQL -

PostgreSQL public

MSSQL - How to configure the default schema name? The schema name for the database application used can be set against the hibernate.default_schema property in this file.

Database Type schemaname Syntax MySQL -

PostgreSQL <schemaName>

MSSQL -

Qualify unqualified tablenames with the given schema/tablespace in generated SQL.

How to configure the connection and statement pooling in Hibernate? In Hibernate, the transaction mode is always enabled. In WebNMS IoT with Hibernate persistence service.

• The number of non transaction connections will be configured using the nontransaction.connection property in the file. The default value is 3. This is a WebNMS specific parameter.

• The minimum number of Connections a pool will create at server startup can be configured using the hibernate.c3p0.min_size property in this file. The default value is 15.

• The maximum number of Connections a pool will maintain at any given time can be configured using the hibernate.c3p0.max_size property in this file. The default value is 15. The number of transaction connections that is available will be max_size - nontransaction.connection.

• The size of PreparedStatement cached per connection can be configured using the c3p0.maxStatementsPerConnection property in the c3p0.properties file located in

Copyright @ 2019 32


<WebNMS IoT Home>\classes\hbnlib\. The default value is 250.

For more details, please refer to the c3p0 documentation.

Uninstalling WebNMS IoT Server

• Reinitializing Database before Uninstallation

• Uninstalling WebNMS Server in GUI Mode

• Uninstalling WebNMS Server in Command Line Mode

• Uninstalling WebNMS Server in Silent Mode

To uninstall WebNMS, make sure you shutdown the WebNMS IoT server first, by following the procedure given in the section Shutting down server. Reinitializing Database before Uninstallation If the data in the database is not required, then it is recommended to reinitialize the database in order to conserve disk space. For deleting the data, execute the reinitialize_nms.sh/bat file present under the <WebNMS IoT Home>/bin folder. Executing reinitialize_nms.sh/bat causes all tables present in the default database schema to be dropped. If you have any custom tables, please ensure that these are manually deleted because reinitialize_nms.sh/bat does not drop any table that has been altered. If reinitialization is not performed, the data remains intact and can be reused. Uninstalling WebNMS Server in GUI Mode

Windows

For uninstalling the WebNMS IoT server, execute the uninstaller.exe file present under the <WebNMS IoT Home>/_uninst folder.

Linux

For uninstalling the WebNMS IoT server, execute the uninstaller.bin file present under the <WebNMS IoT Home>/_uninst folder.

Uninstalling WebNMS Server in Command Line Mode For uninstalling in command line mode, execute the command "./uninstaller.bin -is:javaconsole -console". Uninstalling WebNMS Server in Silent Mode For uninstalling in silent mode, execute the command "./uninstaller.bin -is:javaconsole -silent"

Note:

• Removing the entire folder where the product is installed will lead to improper uninstallation.

• Locked files (the files that are changed after installation) will not be removed after uninstallation

Copyright @ 2019 33

http://sourceforge.net/projects/c3p0


Licensing the Product

• Licensing Information

• Licensing Procedure

• Upgrading License

• Unique ID License

Licensing Information There are two types of licensing policies for WebNMS IoT :

• Trial User Policy: WebNMS provides an Evaluation (trial) period for 45 days for WebNMS IoT, which can be extended if required. The trial license file is available with the product. If you need to extend the trial license or obtain a new trial license, e-mail to [email protected].

• Registered User Policy: WebNMS provides the Registered user file after you purchase the product. To get the registered user file, e-mail to [email protected].

Licensing Procedure After installation, when you start the product, you are required to provide the licensing information in a License Agreement dialog box that is displayed. Follow the procedure given below:

1. In the initial screen, select I accept the License Agreement (on accepting the license agreement).

2. Click Next.

3. The User Type screen is displayed.

Copyright @ 2019 34




If you are an evaluation user, select Evaluation User and click Finish. Now, you are ready to use the product. If you are registered user, select Registered User and click Next. Perform the remaining steps.

4. The Licensee Details screen is displayed. Click Browse and locate the license file in your local machine.

5. Click Next.

6. The next screen displays list of users who are authorized to use the product in the User Name drop-down box. Select a user name.

Copyright @ 2019 35


7. Click Finish.

The licensing procedure is complete and the product is ready to use.

Copyright @ 2019 36


Upgrading License File This section provides you information on how to upgrade your license file

• from an expired trial license to a new trial license

• from a current (not expired) trial license to a new trial license

• from a trial license to permanent license

Expired Trial License to New Trial License 1. After the trial license has expired, when you start any of the WebNMS IoT services or

applications, an error message is displayed (refer to following image).

2. If you need a new trial license, contact our [email protected].

3. Place the trial license file in your local machine.

4. Start WebNMSLauncher.sh/bat located in <WebNMS IoT Home> directory. An error message is displayed.

5. Click OK. The WebNMS Software License Agreement dialog box is displayed.

6. In the next screen, click Browse and locate the license file in your local machine.

7. Click Next. The license information is displayed.

8. Click Finish.

Current Trial License to New Trial License (extension of validity period)

If you need to extend the validity of your trial license, perform the following procedure.

1. For extending the existing trial license, e-mail to [email protected]. A temporary license file is sent to you.

2. Place the license file in your local machine.

3. Start WebNMSLauncher.sh/bat located in <WebNMS IoT_Home> directory.

4. In the WebNMS IoT Launcher, from Help menu, choose Register. The WebNMS Software License Agreement dialog box is displayed.

Copyright @ 2019 37




5. In the next screen, click Browse and locate the license file in your local

machine.


7. Click Finish.

Trial License to Permanent License

The procedure for upgrading your license from trial to the registered version is stated in the next section of the document.

Unique ID License

WebNMS has provision to use Unique Mac ID based licenses in the product. The licenses generated based on this unique key can be applied in WebNMS IoT application installed in a particular machine. Follow the below steps to generate the unique ID :

1. Open the folder <WebNMS IoT Home>/bin

2. Run the UniqueIDLinux.sh file. The unique ID will be displayed.

In rare cases, there may be issues in running this script in the 64 bit machine, and the following error message may be displayed. UniqueIDLinux.sh: ./UniqueIDLinux: /lib/ld-linux.so.2: bad ELF interpreter: No such file or directory In this case, you need to use the files UniqueID.dll and UniqueIDLinux file which are compatible with 64 bit machine. Mail to [email protected] to receive these files. <WebNMS IoT Home>/bin folder and run the UniqueID.sh The result will look like :

Your Unique Machine ID is XXXXXXXXX Note: Please use the Unique Machine ID shown above to get Your License Key. Unique Machine ID is encoded version of the MAC address. This Unique Machine ID will be used only for key Generation. This information will not be disclosed to any other sources. Press any key to exit............

3. Mail the generated unique ID to [email protected]. The team will generate the license file based on the unique ID and mail you the license file to be used in the application.

Copyright @ 2019 38




Upgrading the License

• Trial License to Registered License

Trial License to Registered License The registered license can be applied over the WebNMS IoT application from the launcher using the Help > Register option. The Evaluation license will be upgraded to the Registered License. In this case of upgrading the license from the Launcher, the Administrator needs to have access to the server machine to upgrade the license. Alternatively, the Administrator can upgrade the license from the Client UI from any browser connected to the server. The UI-based license upgrade provides options to view the complete license information i.e. the License Information and Product Information before upgrading the license. Upgrading the License from the Launcher (Note: The Administrator needs to have access to the server machine to upgrade the license. )

1. For a permanent license, e-mail to [email protected].

2. Place the license file in your local server machine.

3. Start WebNMSLauncher.sh/bat located in <WebNMS IoT Home> directory in the server machine.

4. In the WebNMS Launcher, from Help menu, choose Register. The WebNMS Software License Agreement dialog box is displayed.

5. In the next screen, click Browse and locate the license file in your local machine.


7. Click Finish. At the bottom of the WebNMS Launcher, a message 'This evaluation copy will be valid for 37 day(s)' is displayed because the Launcher is not restarted. Ignore this message.Restart the Launcher and you will find that you are now a Registered User. You can verify this by choosing Help > About menu. The text "Product Licensed to: <user_name>" is displayed.

Upgrading the License from the Client UI This document provides step-by-step instructions to View and Upgrade the License from the Client UI connected to the server.

1. For a permanent license, e-mail to [email protected].

2. Place the license file in your local machine.

Copyright @ 2019 39


3. Click on the drop-down icon on the right of the Settings icon.

4. Click on Upgrade License option. The About popup screen will be displayed.

The product information, and details of license (evaluation license or registered license) obtained from WebNMS will be displayed in two tabs. The License Info tab displays the General Info, and the Device Info of the License. And the Installation Info tab displays the Product Info, System Info, Java Info, Memory Info, and Port Info of the WebNMS IoT product installation.

Note : The 'Shutdown on Expiry' and 'Grace Period' can be configured in the <WebNMS IoT Home>/NmsProcessesBE.conf file. By default, the 'Shutdown on Expiry' is false and therefore the server does not automatically shutdown on license expiry. When set to 'true' the server will shutdown automatically on reaching the license expiry. However the server will wait for the 'Grace Period' days before shutting down the server.

By default, the license threshold for alarms is set as 7 days in the product i.e. 7 days before the server shuts down, the application sends out Warning and Critical alarms. * Warning alarm is raised 7 days before shutting down the server. * Critical alarm is raised 1 day before shutting down the server. The Shutdown on Expiry feature can be enabled by setting the property value to true in the <WebNMS IoT Home>/conf/NmsProcesseses.conf file. Refer to the developer guide for more details.

Copyright @ 2019 40


Note: Administrator has the privilege to view both License Info and Installation Info tab. The users can view only the License Info. To provide access to a new group of users, ensure that the System Administration option under the Administration Operation tree node is selected.

5. Choose the registered license file using the Browse button. The license will be updated in the product.

Copyright @ 2019 41


6.Click on the Upgrade button.

Copyright @ 2019 42


Uninstalling Service Pack

• Overview

• Uninstalling the Service Pack

o UI mode

o Command Line mode

Overview You have the option of reverting the changes incorporated by the installation of a Service Pack. You can revert to the previous version of the Service Pack or to the base version of the application. Before you start the uninstallation process, make sure no application is running. Uninstalling the Service Pack There are two ways in which a Service Pack can be uninstalled.

• Through UI

• Through Command Line

Uninstalling the Service Pack Using Update Manager Through UI

The steps to revert to a previous version are as follows.

Note: When using MySQL and MSSQL database, the database driver jar must be added to the CLASSPATH in the UpdateManger.bat/sh script. This step is required for the additional migration process included in the service pack. Sample entry for MYSQL given below where the database driver jar is present in the <WebNMS IoT Home>/classes folder: CLASSPATH=$NMS_CLASSES/mysql-connector.jar:$NMS_CLASSES/AdventNetUpdateManagerInstaller.jar:$NMS_CLASSES/JimiProClasses.jar:$NMS_CLASSES

1. Start Update Manager: Run UpdateManager.bat/sh from <WebNMS IoT Home>/bin directory.

Copyright @ 2019 43

https://www.webnms.com/telecom/help/installation_guide/installation_and_setup/uninstalling_service_pack.html%23Overview


2. Select the service pack, which needs to be uninstalled, from the list. Click "Uninstall" button to proceed with the uninstallation.

3. The list of dependent service packs if any will be shown for your confirmation before proceeding with the process. Click Finish button to proceed.

Thus the specified Service Pack is uninstalled in the application. You can now continue with the screen (like uninstalling another Service Pack) or quit the tool by clicking the "Exit" button.

Note: The results of Update and Revert operations are displayed in the Log window. The message is saved in ConfChanges.log file in <WebNMS Home> /logs for reference.

Uninstalling the Service Pack Using Update Manager Through Command Line

1. Run the UpdateManager.bat/sh file under <WebNMS Home>/bin directory with the "-c" option. (UpdateManager -c). The options to install, uninstall, view installed ServicePack versions, and exit will be shown and you will be prompted to enter your choice.

2. Enter "u" to uninstall a Service Pack. The screen will show you the list of installed Service Packs and prompt you to select the one to be uninstalled.

3. Enter the number corresponding to the Service Pack to be uninstalled. You will see the uninstallation happening and the message "Uninstalled successfully" will be shown.

4. The screen will prompt you to mention whether you want to continue. Choosing "y" will take you back to the first step. Choosing "n" will close the application.

Single command Usage : sh UpdateManager.sh -u conf -c -option u -h <Product HOME directory> -version <Patch version>

Copyright @ 2019 44


Please refer to Update Manager Options for details on options.

Note: To see the details of the installed service pack please refer to the Viewing the Details of a Service Pack section in Installing Service Pack document.

Copyright @ 2019 45


Installing Service Pack

• Installing the Service Pack

o UI mode

o Command Line mode

o Command Line mode in Primary & Failover Setup

• Viewing the details of the Service Pack

o UI mode

o Command Line mode

Installing the Service Pack WebNMS IoT Platform periodically provides Service Packs which provide new features (requested by the customers), fixes for certain bugs and document updates in the form of HTML files. Service Packs can be downloaded from the web site, and updated into WebNMS using the Update Manager tool. There are two ways in which the Service Pack can be installed.

• Using the Update Manager through UI

• Using the Update Manager through Command Line

• Using Command Line in Primary & Failover Setup

Installing the Service Pack Using Update Manager Through UI

The Update Manager can be invoked by choosing Update Manager from the Options menu in the Launcher. Alternatively, you can invoke Update Manager by executing the file <WebNMS Home>/bin/UpdateManager.bat/sh for BE and <Web NMS FE Home>/bin/UpdateManager.bat/sh for FE. When you start the Update Manager, all the Service Packs that are already installed are listed and it provides the options to Install, Uninstall and view the details of any Service Pack.

Warning: Ensure that no application is running when applying the Service Pack. This prevents any files used by the application from being over-written. For example in the WebNMS server is running, stop the server and then install the service pack.

The steps to apply a Service Pack are as follows: Step 1 : Start Update manager - You can invoke the UpdateManager.bat/sh file in the <WebNMS Home>/bin directory or click the menu Options -> Update Manager or click the Update Manager icon from the Launcher tool bar. Step 2 : Select the Install option: Click "Browse" button and select the Service Pack file (.ppm) to be installed. When the Service Pack is selected, the Update Manager displays a Preview button alongside the Install and Readme buttons as shown in the screen below. Use the Preview button, to view the changes that will be effected for the selected Service Pack. Click Install button to install the Service Pack.

Copyright @ 2019 46


Step 3: Install the Service Pack - You can go through the Readme file of the Service Pack by clicking the "Readme" button and Install the Service Pack by clicking the "Install" button. If the Service Pack has some optional upgrades, it will prompt you to select the same if required and then continue.

Note: On clicking the "Install" button, the tool checks whether there is enough space for the installation of the service pack. If there is not enough space, the tool informs the user about the lack of space. You must clear the space and then proceed with the installation.

Step 4 : Configuration Updator Tool - The Configuration Updator tool is invoked to updates all the configuration files that are modified for the particular service pack. The screen prompts you to select one of the three radio button: Update, Revert or Query the configuration changes. A text field to get the JDK installation path, which will be used to compile the jsp files.

Select the Update option, enter the JDK installation path and click "Next" button. The list of configuration files that will be updated is shown in the next screen. If you want to update all the files you can select the "Select All Files" checkbox and click Update.

Copyright @ 2019 47


All the configuration files are updated in a smart manner without affecting the user changes in these files (if any). Then the jsp files will be compiled automatically. This completes the process of a service pack installation. The log message pane of the Configuration Update Tool lists the changes made to the Configuration Files. Click Close button once the updation of configuration files is completed. The screen image shows "Installation Completed", click Close to proceed to the next screen.

Note: To update only selected configuration files, select the required configuration files from the table and view the changes of each configuration file. Click on the Update button. The configuration files selected, along with the configuration files that are mandatory are updated by the tool.

Step 5 : View Readme and Logs: If you want to go through the Readme and the Logs created during the Service Pack update, check the "View Readme and Logs" option in the bottom-left corner of the screen and click the "Close" button. By default this option is checked. If you do not select this option and close, the main screen is shown. If you want to uninstall a Service Pack and revert to a previous version, refer to the Uninstalling Service Pack section.

Installing the Service Pack Through Command Line

In command line mode, the Update Manager can be invoked by the UpdateManager.bat/sh file. The command to invoke the Update Manager can be interactive or non-interactive. The interactive method prompts for input for installation option, to avoid any prompting, you can use the non-interactive mode. Usage: java com.adventnet.tools.update.installer.UpdateManager {options} Options are: [-help Displays this usage.] [-u (update_conf.xml file path)] [-h (the product home directory path)] [-c to invoke in commandline] [-option i(to install),u(to uninstall),v(to view the installed ServicePack vers ions)] [-ppmPath ServicePack file path] [-version ServicePack version to uninstall] [-g to invoke in GUI mode] [-language language(lowercase two-letter ISO-639 code)] [-country country(uppercase two-letter ISO-3166 code)] [-fileName propertiesfileName(Give the name of .properties file)]

Copyright @ 2019 48


[-ppmInfo ServicePack file path] Interactive Mode :

1. Run the UpdateManager.bat/sh file under <WebNMS Home>/bin directory with the "-c" option (UpdateManager -c). The options to install, uninstall, view installed Service Pack versions, and exit will be shown and you will be prompted to enter your choice.

2. Enter "i" to install a new Service Pack. The screen will prompt you to enter the path where the new Service Pack is located.

3. Enter the absolute path where the new Service Pack is placed. You will see the update happening and the message "Service Pack installed successfully" will be shown.

4. The screen will prompt you to mention whether you want to continue. Choosing "y" will take you back to the first step.

5. Choosing "n" will close the application.

Non-Interactive Mode : To install a Service Pack using Update Manager in a single command, you can use the following command sh UpdateManager.sh -u conf -c -option i -ppmPath <Patch file path> -h <Product HOME directory>

Note:

1. Preview option is not available for command line installation.

2. The Product HOME directory should be specified if the Update Manager is being invoked external to your product.

Using Command Line in Primary & Failover Setup Follow the steps provided below to install the Service Pack (.ppm) in the Failover setup.

• Login to the VM using ssh (in the linux system).

• Execute the below command to check the directory where the WebNMS IoT server is running. ps -ef | grep java

• The WebNMS IoT server's running directory will be displayed in the first line of the result along with the Process ID. Note : If VIP is used, you must login as super user to perform the server startup and shutdown scripts.

• Goto the <WebNMS IoT Home>/bin folder in the Primary Server (PS).

• Shutdown the Primary Server (PS) using the shutdown script ShutDown.sh <username> <password>. The Primary server will shut down and the standby Failover Server (FS) will start. Ensure the server is running by connecting to the Public IP providing the public IP's hostname and port in the browser. Now the web client must be displayed. Note : If VIP is used, ensure the VIP is released using the ifconfig command.

• Install the PPM using the following command in the Primary Server: sh UpdateManager.sh -u conf -c -option i -ppmPath <Absolute_Path_of_PPM> -

Copyright @ 2019 49


h <Absolute_Path_of_WebNMS_IoT_Home> -DJAVAHOME=<JDK_Home> -DLANGUAGE=English

• Start the Primary Server (PS) after installing the Service Pack. The primary server will now start running as the standby server. Ensure the server is running by connecting to the Public IP providing the public IP's hostname and port in the browser. Now the web client must be displayed.

• Goto <FailoverServer_Home>/bin, and Shutdown the Failover Server (FS) using the shutdown script ShutDown.sh <username> <password>. The Failover Server (FS) will be shutdown, and the Primary Server (PS) will be started.

• Install the Service Pack (.ppm) in the Failover Server (FS) using the following command : sh UpdateManager.sh -u conf -c -option i -ppmPath <Absolute_Path_of_PPM> -h <Absolute_Path_of_WebNMS_IoT_Home> -DJAVAHOME=<JDK_Home> -DLANGUAGE=English

• Start the Failover Server (FS). The server will be started as the standby server.

Viewing the Details of a Service Pack

There are two ways in which the Service Pack details can be viewed.

• Through UI

• Through Command Line

Viewing the Details of a Service Pack Through UI

You may want to know the details of an already installed Service Pack. The details are shown in two tabs namely, General and Readme. The details like the Service Pack name, its description, its size, its time of installation, and the list of files that are updated are shown in the General tab. While the Readme file is shown in the Readme tab. The steps to view the details of a Service Pack are as follows:

1. Start Update manager: Either run the UpdateManager.bat/sh file in the <Product Home>/bin directory or select the Update Manager icon from the WebNMS Launcher. The text area in the bottom of the screen lists all the Service Packs installed in the application.

2. View the Service Pack details: Select the Service Pack whose details are to be viewed. Click the Details button to get the details dialog. It has the two tabs: General and Readme.

3. Close the details dialog: Click the "Close" button to close the details dialog. Thus the main screen of Update Manager is shown.

Copyright @ 2019 50


Thus any Service Pack file content can be viewed. You can now continue with the screen (like viewing the details of another Service Pack) or quit the tool by clicking the "Exit" button.

Viewing the Details of a Service Pack Through Command Line 1. Run the UpdateManager.bat/sh file under <WebNMS IoT Home>/bin directory with

the "-c" option. (UpdateManager -c)The options to install, uninstall, view installed Service Pack versions, and exit will be shown and you will be prompted to enter your choice.

2. Enter "v" to view the details of the already installed Service Packs. The screen will shown you the list of Service Packs installed in the product.

3. The screen will prompt you to mention whether you want to continue. Choosing "y" will take you back to the first step. Choosing "n" will close the application.

Single command Usage: sh UpdateManager.sh -u conf -c -option v -h <Product HOME directory>

Note: The Product HOME directory should be specified if the Update Manager is being invoked external to your product.

Note for 64 bit Installation: If the service pack is installed over a 64 bit WebNMS 6 version, certain 64 bit specific files should be retained. The files under the folder <WebNMS IoT Home>/lib such as UniqueID.dll, and libUniqueID.so should be copied from the <WebNMS IoT Home>/Patch/<ServicePack_Name> folder to <WebNMS IoT Home>/lib folder.

Copyright @ 2019 51


Cloud Deployment

Cloud Deployments

• Data Center Installation

• Deployment IoT in Azure Cloud

• Deployment IoT in AWS Amazon Cloud

Data Center Installation

• Installing in Data Center

• Configuring Ports

Installing in Data Center The installation of IoT in a Data Center is same as Installing WebNMS IoT in Windows and Linux system. The detailed steps are provided in the "Installing WebNMS IoT" section. After installing the product in the Data Center, certain ports must be opened in the system to enable communication. Configuring Ports The following ports are needed to be opened in firewall when installing WebNMS IoT in a data center.

• WEBSERVER_PORT - 9090 (default value)

• M2MDATA_PORT - 9089 (default value)

Copyright @ 2019 53


Deploying IoT in Azure Cloud

• Introduction

• Deployment in Classic Deployment Mode

• Architecture

• Configuring a Virtual Machine

• Connecting with Linux VM

• Connecting with Windows VM

• Deployment Setup

• Deployment in Resource Manager Mode

• Troubleshooting

• Key Terms

Introduction This document provides the complete procedure involved in deploying WebNMS IoT in Azure Cloud Service using Azure CLI tool in Classic Deployment mode and the Resource Manager Mode using Powershell / Azure CLI tools.

Please refer to the Key Terms section to understand the terms used in this document. Deployment in Classic Deployment Mode Architecture

Single BE with Bundled Postgres DB

Copyright @ 2019 54


Single BE with Separate Postgres DB

Failover Setup

Configuring a Virtual Machine

1. Create a Virtual Network. Use azure network vnet create command to create a Virtual Network.

azure network vnet create -l "South Asia" "WebNMSVNet"

2. Create Reserved IP – Static (Public) IP Address which will be facing the internet. This reserved IP will be associated with our VM instance.

Copyright @ 2019 55


Use azure network reserved-ip create command to create a reserved IP.

azure network reserved-ip create "NMSReservedIP1" "South Asia"

3. Select the VM Image from the list - For creating VM we need to specify the Image name.

1. Command for Listing the VM Image names. Using the command : azure vm image list

2. From the list, select the desired OS Image.

Tested OS images:

1. Ubuntu 12 and 14 LTS Series from Canonical

2. Microsoft Windows 2012 R2

4. Create Virtual Machine using the below command.

azure vm create -z "Standard_DS1" -w "webnmsnetwork" -l "Southeast Asia" --ssh 22 -R WebnmsReservedIP webnmsubuntu4 0b11de9248dd4d87b18621318e037d37__RightImage-Ubuntu-14.04-x64-v14.2 esakkiraj Webnmsubuntu123@

5. Create Endpoints to enable access with internet using the below command.

Use azure vm endpoint create azure vm endpoint create

Note: Mandatory endpoints needed for running WebNMS IoT Solution are given below:

1. WebNMS webclient - 9090 (configured in setEnv.sh/bat as WEBSERVER_PORT )

2. WebNMS Device data handler – 9089 (configured in setEnv.sh/bat as M2MDATA_PORT )

6. Install JDK 1.7

7. Specific to Ubuntu VM: Install the necessary utility packages.

1. sudo apt-get update

2. sudo apt-get install zip unzip vim

Copyright @ 2019 56


Connecting with Linux VM

1. Ensure that Port 22 (default SSH) Endpoint is configured for this virtual machine.

2. Connect to the VM using the SSH command via Terminal.

Sample Entry:

ssh -p 22 [email protected]

Connecting with Windows VM

1. Ensure that Port 3389 (default RDP) Endpoint is configured for this virtual machine.

2. Connecting from Windows machine: Kindly refer to this RDP Doc

3. Connecting from MAC:

1. Install Microsoft RDP Client from App store.

2. Using the "New" button add the VM credentials to connect to.

3. After adding the VM, select the VM and click the "Start" button to start the remote desktop session.

4. After configuring a new VM we need to transfer files (WebNMS Builds, DB Data backup files, etc,.) to the VM from local machine. Below are the steps to :

1. Select the VM from the list.

2. Click Edit -> Redirect from the dialog box.

3. Click the "+" button below. Select Path and browse the folder which you need to share with the remote VM machine. Click Ok.

4. Start the Remote Desktop session as mentioned in the previous step. The folder shared can be found in "This PC" parallel to the default "C" drive. You can copy files & folders from there to your remote machine.

Copyright @ 2019 57


Copyright @ 2019 58


Deployment Setup

Single BE Server with Bundled Postgres 1. Create a VM using the steps specified in the previous topic.

2. Login into the VM through SSH. (Need to provide password for the SSH command)

3. Install WebNMS IoT 6.0 + SP1 (Use 64bit bundled PostgreSQL build)

4. Start webnms using startnms.sh/bat.

5. Access webnms web client using either the Reserved IP or DNS name of the vm. Usually DNS name will be <vm_name>.cloudapp.net.

Single BE Server with Separate DB 1. Create a VM and install WebNMS using the steps in the "Single BE Server with

Bundled Postgres" topic. Let’s say this VM as VM1.

2. Create another VM and install Postgres database in it. Let’s say this VM as VM2. VM1 and VM2 should be in the same Virtual Network to be able to communicate with each other with Private IPs.

3. Configure Postgres DB: Due to security constraints PostgreSQL will not serve request from other networks. Explicit configurations need to be done to serve requests from other servers.

4. postgresql.conf - Change the listen_address property value to '*'.

5. pg_hba.conf - Add the below entry. The address 10.0.0.0/8 is the cidr address notation of the VNet in which the VM resides. Now the postgres only serves the request from the 10.0.0.0 IPs.

Single BE Server with 'N' Server 1. Create a Single BE Server setup with steps provided in the previous topics.

2. Create another VM and Install WebNMS FE Build in the VM.

3. Configure the FE Server to connect with BE Server (created in Step1). Refer the Front End Server section in the below mentioned WebNMS Developer guide.

4. Based on the need multiple FE Server can be created and configured to connect with the BE Server.

5. Note: Make sure that all the VM (BE + FE + DB Server) should be in the same Virtual Network to be able to communicate using the Private IPs.

Failover Setup 1. Create two BE Server setup (one for Primary and another for Secondary setup).

2. Create FE Servers as per the requirement and configure it connect to the Primary BE.

3. Kindly refer the Failover Section in the WebNMS Developer guide to create a Failover setup.

Deployment in Resource Manager Mode Azure has two deployment modes, the Classic and Resource Manager Mode. There exists some minor difference in creating the build setup for WebNMS IoT Solution. The below points must be considered when creating VM in Resource Manager Mode.

Copyright @ 2019 59


1. Endpoint Configuration: Inbound & Outbound communication access permissions are configured using Network Security groups instead of straight forward Endpoint configuration which is done in Classic mode. Troubleshooting

Error Reason

Unable to start postgreSQL

1. Bundled postgres setup: When the files in <WebNMS IoT Home>/pgsql/bin dont have neccessary permissions to run. Use chmod 774 * inside <WebNMS IoT Home>/pgsql/bin to give permissions to run. 2. Separate Postgres installation: Check whether postgres is running properly and check for port configurations. Eg: ps -ef | grep postgres to check whether the process runs correctly. 3. Separate Postgres setup: Check whether security configurations are made properly. (Refer Step 2 in separate postgresql setup for configuration details). 4. If Windows machine: If "Permission Denied". Right the pgsql folder and Select "Properties" -> Security -> Edit. Select "Full Acess" for USERS group. Click Apply.

Libraries linker errors Install the packages libxrender-dev libxtst-dev Key Terms Microsoft Azure: Azure is an online cloud platform providing IaaS (Virtual Machines) and PaaS services. We can create a virtual machine (Windows or Ubuntu in our case) with different settings (RAM, HDD, and Network). VM (Virtual Machine): A Virtual Machine is a logical machine with desired OS (Supported) which is part of Azure cloud service. An instance also refers to a VM. Azure Deployment Mode: Classic vs. Resource Manager Mode.[Classic VS Resource Manager mode] Network Security Group (NSG): Instances can be grouped or attached to a security group which specifies Inbound & Outbound communication rules. (Such as Firewall access configuration to the VM instances). End Points: End Points are nothing but ports. For each VM created in Azure there can be endpoints configured through which external world can communicate with the VM. E.g.: SSH Endpoint is configured in the port 22. Inbound Rules (Ports): These are rules which allow inward communication to the VM from external world. Outbound Rules (Ports): These are rules which allow outward communication from the VM to the external world. Azure CLI: Officially provided CLI tools through which we can interact with our Azure Platform. Almost all operations are supported through CLI command. Eg. VM (Creation, Deletion, Starting, etc.) Image (OS Image): This is the image file provided by Azure for different OS which is used to create Virtual Machine from them. Virtual Network (VNet): Virtual Network is logical separation of network with provided address space. In Azure we can create VNet and create VMs within the VNet to make communication among VMs easier.

Copyright @ 2019 60


Reserved IP: Each VM on creation gets an IP Address and DNS name which is used to communicate with the external world. But if the VM is restarted for any case, a new IP is allocated. For overcoming this we create Reserved IP and associated them with VM which will be preserved even after restart.

Copyright @ 2019 61


Deploying IoT in AWS Amazon Cloud

• Introduction

• Architecture

• Configuring a Virtual Machine

• Connecting with Linux VM

• Connecting with Windows VM

• Deployment Setup

• Troubleshooting

• Key Terms

Introduction

The WebNMS IoT AWS Deployment Guide provides the complete procedure involved in deploying WebNMS IoT in Amazon Web Services Cloud. The terms used in this section are listed in the Key Terms section in this document.

Architecture

Single BE with Bundled Postgres DB

Single BE with Separate Postgres DB

Copyright @ 2019 62


Failover Setup

Configuring a Virtual Machine

1. Create an IAM User. Ref Link: http://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html

2. Create a Virtual Private Cloud. Ref Link: http://docs.aws.amazon.com/AmazonVPC/latest/GettingStartedGuide/getting-started-create-vpc.html

3. Create a Virtual Machine. Configure the VPC and Network Security Group for this instance. Ref Link: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance_linux

4. Create an Elastic IP and associate it with the VM. Ref Link: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html#using-instance-addressing-eips-allocating

Copyright @ 2019 63


5. Specific to Ubuntu VM: Install the necessary utility packages.

1. sudo apt-get update

2. sudo apt-get install zip unzip vim

Connecting with Linux VM

1. Make sure that Port 22 (default SSH) Endpoint is configured for this virtual machine.

2. Connect to the VM using the ssh command via Terminal. Eg: ssh -p 22 [email protected]

Connecting with Windows VM

1. Ensure that Port 3389 (default RDP) Endpoint is configured for this virtual machine.

2. For connecting from Windows machine: Kindly refer this RDP Doc

3. For connecting from MAC:

1. Install Microsoft RDP Client from App store.

2. Using the "New" button add the VM credentials to connect to.

3. After adding the VM. Select the VM and click the "Start" button to start the remote desktop session.

4. After configuring a new VM, files from local machine (WebNMS Builds, DB Data backup files, etc.) needs to be transferred to the VM. Below are the steps to achieve this:

1. Select the VM from the list.

2. Click "Edit" -> "Redirect" from the dialog box.

3. Click the "+" button below. Select Path and browse the folder which you need to share with the remote VM machine. Click Ok.

4. Start the Remote Desktop session as mentioned in the previous step. The folder shared can be found in "This PC" parallel to the default "C" drive. Copy files & folders from there to your remote machine.

Copyright @ 2019 64


Deployment Setup

Single BE Server with Bundled Postgres 1. Create a VM using the steps specified in the previous topic.

2. Login into the VM through SSH. (Need to provide password for the SSH command)

Copyright @ 2019 65


3. Install WebNMS IoT 6.0 + SP1 (Use 64bit bundled PostgreSQL build)

4. Start webnms using startnms.sh/bat.

5. Access webnms web client using either the Reserved IP or DNS name of the VM.

Single BE Server with Separate DB

1. Create a VM and install WebNMS using the steps in the "Single BE Server with Bundled Postgres" topic. Let’s say this VM as VM1.

2. Create another VM and install Postgres database in it. Let’s say this VM as VM2. VM1 and VM2 should be in same Virtual Network to be able to communicate with each other with Private IPs.

3. Configure Postgres DB: Due to security constraints PostgreSQL will not serve requests from other networks. Explicit configurations need to be done to serve requests from other servers. a. postgresql.conf - Change the listen_address property value to '*'. b. pg_hba.conf - Add the below entry. The address 10.0.0.0/8 is the cidr address notation of the VNet in which the VM resides. Now, Postgres only serves the request from the 10.0.0.0 IPs.

Single BE Server with 'N' Server

1. Create a Single BE Server setup with the steps provided in the previous topics.

2. Create another VM and Install WebNMS FE Build in the VM.

3. Configure the FE Server to connect with BE Server (created in Step1). Refer the Front End Server section in the WebNMS Developer guide.

4. Based on the need, multiple FE Servers can be created and configured to connect with the BE Server. Note: Make sure that all the VM (BE + FE + DB Server) should be in the same Virtual Network to be able to communicate using the Private IPs.

Failover Setup

1. Create two BE Server setup (one for Primary and another for Secondary setup).

2. Create FE Servers as per the requirement and configure it, and connect to the Primary BE.

3. Refer the Failover Section in the WebNMS Developer guide to create a Failover setup.

Copyright @ 2019 66


Troubleshooting

Error Reason

Unable to start postgreSQL

1. Bundled postgres setup: When the files in NMS_HOME/pgsql/bin dont have neccessary permissions to run. Use chmod 774 * inside NMS_HOME/pgsql/bin to give permissions to run. 2. Separate Postgres installation: Check whether postgres is running properly and check for port configurations. Eg: ps -ef | grep postgres to check whether the process runs correctly. 3. Separate Postgres setup - Check whether security configurations are made properly. (Refer Step 2 in separate postgresql setup for configuration details). 4. If Windows machine: If "Permission Denied". Right the pgsql folder and Select "Properties" -> Security -> Edit. Select "Full Acess" for USERS group. Click Apply.

Libraries linker errors Install the packages libxrender-dev libxtst-dev

Cannot Login using ssh ( in Ubuntu VM )

Default username for Ubuntu VM is ubuntu. (It’s not the IAM username you have created). Ref: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ TroubleshootingInstancesConnecting.html# TroubleshootingInstancesConnectingMindTerm

Key Terms Virtual Machines (Instances): Virtual machine is OS instance running in the AWS Cloud (physically running in any AWS region data center). We will use this VM to deploy our product and expose it to outer world using IP address. IAM User: In AWS there are two types of account. 1. Root account - This account is the root account which is used for AWS account management. AWS advices not to use this account for VM and other deployment configuration. 2. IAM User account - This type of account is used for deployment operations. This account can be set privileges for operations to be performed. Virtual Private Cloud: This is a dedicated Virtual network inside AWS Network where our VM will be residing. If needed, we can create Subnets within this VPC for placing different VMs inside subnets. Elastic IP: Each VM on creation will be assigned a private IP and Public IP. But in any situation on restart of VM a new Public IP will be assigned. Elastic IP comes handy in cases where you need Static IP address for VM which will be preserved even in times of restart.

Startup Options

Copyright @ 2019 67


Starting WebNMS IoT Server

There are two ways of starting the WebNMS IoT server, using the launcher or through command line. We shall discuss on these in this section of the document:

• Starting WebNMS IoT Server from Launcher

• Starting WebNMS IoT Server from Command Line

Copyright @ 2019 68


Starting WebNMS Server from Launcher WebNMS Launcher is a single point access for various WebNMS applications and tools that are bundled with WebNMS. You can perform various operations such as starting, shutting down, or reinitializing WebNMS Server by double-clicking on the respective icon or by selecting the Options ->Run menu from the menu bar. The application can also be run by right-clicking on a particular icon and selecting the Run option. Using WebNMS Launcher is much easier than starting, shutting down or reinitializing WebNMS server by selecting the respective batch file from the <IoT_Home> directory. The WebNMS Launcher UI is organized in two panels - the top panel and the bottom panel. The top panel shows all the options or applications that are part of WebNMS. The bottom panel shows the currently running applications in the form of tabs. The bottom panel also displays the error and exception messages of the respective applications that are running. Users can run the WebNMS Launcher, by invoking the script WebNMSLauncher.bat/sh. Running the script brings up the following screen.

On right-clicking the Launcher icons, either the menu option Open is displayed or a menu list with Run, Settings and Log is displayed.

1. Selecting the menu option Open advances the screen to the next screen containing information related to the icon.

2. Selecting the menu option Run executes the script related to the icon.

3. Selecting the menu option Settings allows you to set the classpath variable, log file name, port numbers etc., and other icon specific information. Sample Server Entries for Start IoT Server in Launcher is provided below :

Copyright @ 2019 69


Following are the applications and tools that can be invoked from WebNMS IoT Launcher.

• Start WebNMS Server

• Shut Down WebNMS Server

• Reinitialize WebNMS

Start IoT Server

Starts WebNMS Server.

To start the WebNMS IoT Server with a different database other than the default database from the launcher, follow the below steps:

1. Right click on the Start IoT Server icon in the launcher. 2. Click on Settings. 3. Click Add in the Classpath section, and browse and select the

database JDBC jar. 4. Click OK.

Shut Down IoT Server

This shuts down the WebNMS server, which is the appropriate way to kill the server.

Copyright @ 2019 70


Reinitialize WebNMS

"Reinitialize WebNMS" displays a UI to reinitialize WebNMS database.

Starting WebNMS from Command Line ( bin Directory)

This document explains the various ways for starting WebNMS Server from the bin directory on different platforms such as Windows and Linux. Ensure that the JDK path is set properly as stated in the Post Installation Step before starting the server.

Starting WebNMS Server on Windows • To start the WebNMS server, invoke the batch file startnms.bat from

<WebNMS_IoT_Home>/bin directory.

Starting WebNMS Server on Linux • To start WebNMS server, invoke the shell script startnms.sh from the

<WebNMS_IoT_Home>/bin directory.

• The server has to be run as root in order to enable it to bind port 162 which is the standard SNMP trap port. Otherwise WebNMS will not be able to receive traps.

Copyright @ 2019 71


Starting the Web Client

• Connecting to the Server

• Quick Tour and Get Started

Connecting to the Server This section of the document provides instructions to connect the user interface (from the web browser) to the server.

1. Open a JavaScript enabled Web Browser. Check for Supported Web Browsers.

2. Type http://<machine_name>:<port> in the address bar and press Enter. <machine_name> is the name of the machine where WebNMS IoT Server runs. By default, WebNMS Server runs on port 9090. Example:

3. On first login to the application after installation, the form to change the default password is displayed. The user needs to change the password and also accept the terms and conditions in the privacy policy to proceed with using the application.

Warning : The user will be able to proceed with the application only on accepting the Terms and Conditions after reading the Privacy Policy statement.

4. The login page is displayed. Web client option is selected by default. Enter a valid user name and password. This provides an authenticated access to WebNMS IoT. By

Copyright @ 2019 72


default, the user name and password are root and public respectively for unconfigured systems.

5. Click Login.

On performing this, the Web Client is launched in the Web browser. Quick Tour and Get Started

On connecting the user interface to the server for the first time (when the assets details are yet to be added in the application), the Welcome Screen of WebNMS IoT is displayed. Select any of the tabs Remote Site Management or Fleet Management, and click on Quick Tour or Get Started to proceed. Follow the steps provided below : Note : By default the Remote Site Management and Fleet Management tabs are displayed. This can be modified by removing the unwanted tab entry from the ONBOARDING_SOLUTION RemoteManagement,FleetManagement entry in the serverparameters.conf file in <WebNMS IoT Home>/conf folder.

• Select Remote Site Management or Fleet Management tab. Two buttons See a Quick Tour and Get Started are displayed. The Quick Tour provides an insight into the hierarchy in the Fleet and RTU creation process, whereas the Get Started will lead the user to the asset creation forms. (You can click outside the popup window or the Close button to exit the on boarding process.)

Copyright @ 2019 73


• Click on See a Quick Tour or Get Started.

Quick Tour

• Click on See a Quick Tour to display the help cards for onboarding of the assets. The help cards are displayed in the order of hierarchy in which the assets are to be created. The flow is given below: Remote Site Monitoring : Organization -> Region - > Site -> Template -> Gateway Fleet Management : Organization -> Device -> Vehicle -> Driver -> Client

• Click on the Next Tip button to view the next screen until the last screen. Sample Help Card - Organization

Copyright @ 2019 74


Note: Quick Tour can be viewed by clicking on the Settings > Quick Tour option from the top right corner of the client.

Get Started Remote Site Monitoring

• Click on Get Started in the Remote Site Monitoring tab to proceed to the asset creation form to create the Organization, Region assets etc., The forms are displayed in order of the hierarchy. The Remote Site Monitoring Help Wizard is displayed in the right pane of the screen. The wizard lists the steps in the onboarding process of Remote Site Monitoring. On reaching the last form i.e Site creation in the process, the Admin page is displayed. Select the Add/Update Template link to proceed with the template creation, and in the last screen choose, Save Changes & Associate Gateway link to complete the onboarding. Remote Site Monitoring Process Flow: Organization -> Region - > Site -> Template -> Gateway

Copyright @ 2019 75


• Click on Save & Next to save the details entered and to move to the next form. The details entered will be saved locally to help resuming with the process when continuing the process.

• Click on Back to move to the previous form.

• Click on Exit to exit the form. The form details will not be saved on exiting.

• Click Submit in the last form to save the entries. The message box is displayed with the completed message. Click on the button to proceed with the template create from the Admin page.

Fleet Management

• Click on Get Started in the Fleet Management tab to proceed to the asset creation form to create the Organization, Device assets etc., The forms are displayed in order of the hierarchy. The Fleet Management Help Wizard is displayed in the right pane of the screen. The wizard lists the steps in the onboarding process of Fleet Management. On reaching the last form i.e Vehicle creation in the process, the Admin page is displayed. Select the Add Driver link to proceed with the template creation, and the Add Client link to complete the onboarding. Fleet Management Process Flow: Organization -> Device -> Vehicle -> Driver -> Client

Copyright @ 2019 76


• Click on Save & Next to save the details entered and to move to the next

form. The details entered will be saved locally to help resuming with the process when clicked on the Continue button.

• Click on Back to move to the previous form.

• Click on Exit to exit the form. The form details will not be saved on exiting.

• Click Submit in the last form to save the entries. The message box is displayed with the completed message. Click on the button to proceed with the template create from the Admin page.

Note on Exit / Continue Onboarding : The onboarding process can be exited in between, and resumed later. On exiting, the form entries are stored locally and a blue button Click to continue onboarding shown in the image below will be displayed in the top right corner of the screen. Click on this button to resume the on boarding process anytime.

To log out from Web Client

• Click Logout link located at top right corner of the Web Client.

Copyright @ 2019 77


Reinitializing WebNMS

The process of reinitializing WebNMS database is referred to as reinitializing WebNMS IoT. WebNMS maintains data and configuration details in a relational database. The database tables used for storing configuration information is referred to as configuration tables and those created for storing data are referred to as data tables. Database tables are created both when WebNMS IoT server is started and at runtime. On reinitializing WebNMS IoT, all the data tables and configuration tables are dropped from the database. You can reinitialize the database either through the user interface or command line mode. Reinitializing Database Through UI Mode To reinitialize the database through the UI Mode,

• Run the script reinitialize_nms.bat/sh present in <WebNMS IoT Home>/bin without any arguments.

The Reinitialize WebNMS Database dialog box prompts you to confirm if you want to reinitialize the database. Clicking on the Yes button will drop all the data and configuration details stored in the database.

Reinitializing Database Through Command Mode Database can be reinitialized by invoking the following script: reinitialize_nms.bat/sh MODE <Parameter> where Parameter should be ALL When you try to reinitialize the database, a check is made to ascertain whether the WebNMS IoT server is running. If it is running, the database will not be reinitialized. The database will be reinitialized only when WebNMS IoT is not running. When the WebNMS IoT server is running with TCP as the mode of communication between BE and FE, the database can not be reinitialized through the reinitialize_nms.sh/bat script.

Copyright @ 2019 78


Internationalization Support To Internationalize Reinitialize NMS UI, edit the file ReinitializeNmsResources.properties present in the <WebNMS IoT Home>/html directory. The values for the keys should be substituted by new values.

Copyright @ 2019 79


Shutting Down WebNMS Server

The WebNMS IoT ShutDown process shuts down all the sub-processes and properly releases all the system resources. It is necessary that the shutdown process be properly executed to make sure that the system does not leave any operation incomplete in addition to leaving the database information in a consistent state. The WebNMS IoT server can be shutdown only by authenticated users and it is recommended that the server be shutdown using one of the standard ways. The following is the sequence of operations which take place during the WebNMS IoT Server shutdown process,

1. Stop all the schedulers

2. Notify the registered shutdown observers

3. Unbind all RMI registry objects

4. Shutdown all the sub processes (sub-modules), which will execute specific tasks

5. Shut down the rmiregistry process (if started by WebNMS IoT)

6. Disconnect all database connections

7. Stop pgsql (if started by WebNMS IoT)

8. Shutdown the webserver (if started by WebNMS IoT)

9. Exit (the main process)

The WebNMS BE Server can be shut down by any of the following ways,

• Sending a ShutDown request to the BE server through the TCP socket on which it is listening for connections from FE (the BE_PORT parameter). This is usually the preferred way of shutting down the BE server.

• Executing the ShutDown servlet in the webserver corresponding to the BE Server. This servlet invokes the ShutDown process in the BE server. This ShutDown process can not be invoked if the web server is not running in the BE server host.

• Executing the corresponding ShutDownAPI method from remote (using RMI). The ShutDownAPI will be bound in the RMI registry of the BE Server host. The ShutDown process can not be invoked if the RMI rmi registry process is not running in the BE Server host.

The shutdown process checks for the authenticity and the permissions of the user invoking the shutdown operation and allows only if the user has proper permissions. A standalone application is provided, which uses the above mentioned methods to ShutDown the WebNMS IoT server. First it tries through the TCP mode. If it fails, it uses the servlet mode. If the servlet mode also fails, it uses the RMI mode. The user name, password, host name and the ports (TCP, Web Server, RMI) are configurable in the application.

The WebNMS IoT Server can be shut down :

• By invoking the standalone application "Shutdown NMS Server" from the WebNMS IoT Launcher

• By invoking the script shutdown.bat/sh from <IoT_Home>/bin

• From the HTML Client

• Through Command Line mode

• Running the scripts from remote machine

Copyright @ 2019 80


• Automatically when the database connection is lost

Shutting down WebNMS IoT Server through the WebNMS Launcher Run WebNMSLauncher.bat/sh file from <WebNMS IoT Home>. Choose the application "Shutdown NMS Server". Right click on the icon and choose the "Run"option. A dialog box "Shut Down NMS Server" comes up for you to type in your password. Click on the OK button for the WebNMS Server to shut down. By invoking the script shutdown.bat/sh from <WebNMS Home>/bin

In Windows

Run ShutDown.bat from <WebNMS IoT Home>/bin. This invokes a UI which prompts the user to enter the password. On clicking "Settings", you can view your port where the WebNMS IoT is running, the RMI Registry Port and TCP Port. Click "OK" to successfully shut down.

In Linux

Invoke : sh ShutDown.sh. This invokes a UI which prompts the user to enter the password. On clicking "Settings", you can view your port where the WebNMS is running, the RMI Registry Port and TCP Port. Click "OK" to successfully shut down

Shutting down WebNMS Server from HTML UI To shutdown WebNMS Server from HTML UI, choose the System Administration panel or choose "File -> System Admin" from the tools menus. Choose the "Shut Down Server" option from the HTML page displayed. This opens up a new HTML page with the message "Are you sure you want to ShutDown the server". On clicking "Yes", the WebNMS server will be shutdown.

Note: Only the users with REALM admin, are allowed to shutdown the WebNMS IoT Server.

Shutting down WebNMS Server through Command Line mode WebNMS Server can be shutdown from the command line.

In Windows

Invoke :ShutDown.bat [User Name] [Password] In Linux

Invoke : sh ShutDown.sh [User Name] [Password]

You have to edit the script to meet specific requirements. The script that executes the Java program StandAloneShutDown has the following arguments.

• Host: Host can be the DNS name of the machine where the WebNMS server is running or its IP address.

• Port: The port on which WebNMS is running.

• UserName: This is the user name registered with WebNMS, who is authorized to shut down the WebNMS server. The default username is 'root'.

Copyright @ 2019 81


• Password: The password for the above mentioned user. The default password is

'public'.

Running the scripts from remote machine The script can also be run from a remote machine to shut down the WebNMS IoT server. In order to do that, the following steps have to be followed.

1. Create a temporary directory say WebNMSShutDown/ on the remote machine.

2. Copy the ShutDown.bat/sh script to this directory.

3. Copy the <WebNMS IoT Home>/classes/StandAloneShutDown.class to this directory.

4. Edit the classpath to point to the current working directory.

5. Edit the script to pass the correct arguments to the StandAloneShutDown class.

Note: You cannot shutdown the WebNMS IoT server, if you accidentally execute ShutdownWebSvr.bat/sh that is present in <WebNMS IoT_Home>/apache, which is used to shutdown the Web Server. In this case, you have to execute the StartWebSvr.bat/sh file under <WebNMS IoT_Home>/apache directory to restart the Web Server and then execute the ShutDown.bat/sh to shutdown WebNMS IoT server.

Internationalization Support To Internationalize Shutting down WebNMS UI, edit the ShutDownNmsServerResources.properties file present in <WebNMS IoT Home>/HTML directory. The values for the keys should be substituted by new values.

Copyright @ 2019 82

Date post:	29-Dec-2019
Category:	Documents
Upload:	others
View:	11 times
Download:	0 times

WebNMS IoT Platform 6.0 – Installation GuideJava Plug-in Version . Windows 10 59.0.2 65.x 1.7.0...

Documents