|
|
This section explains how you can enable SSL communication in a Web
NMS combo
setup.
Creating Key, Certificate, and Truststore files for BE Server and Transport Provider Implementation
The first step in setting up the SSL communication is to create the key, certificate, and truststore files that are required for establishing the secure connection for the communication layer. Run the script file available under <Web NMS Home>/bin/createCertificate.sh/bat for creating the certificate (for the Web Server of BE) and copying the files to the respective folders.
The createCertificates.sh/bat script does the following:
Creates a private key (server.keystore).
Exports the private key to a public key (server.cer) and imports the public key to the Truststore file (Truststore.truststore).
Copies
the private key and public key to the respective locations.
|
|
Note: The certificate files server.cer, server.keystore, and Truststore.truststore will be created under the <Web NMS Home>/Certs folder. The server.keystore and Truststore.truststore is copied to <Web NMS Home>/conf folder and server.keystore is copied to <Web NMS Home>/apache/tomcat/conf folder.
|
Changing the Configuration Files
Certain configuration file modifications are required for enabling SSL. To enable SSL communication, modify the <Web NMS Home>/conf/NmsProcessesBE.conf file and the <Web NMS Home>/apache/tomcat/conf/backup/server.xml file.
NmsProcessesBE.conf
Do the following changes in this file located in <Web NMS Home>/conf directory.
|
#java com.adventnet.nms.startnms.NmsMainFE [NMS_FE_PORT WebNMSSocketPort] [USE_QUOTES_IN_DATABASE_TABLES true/false] [CLIENT_SERVER TCP/RMI/CORBA] [BE_FE TCP/RMI/CORBA] [BE_HOST back_end_host_name] [BE_PORT back_end_port_num] [COUNTRY country_code] [LANGUAGE language_code] [ROOT_DIR dir] [ KEEPALIVE_WINDOW_SIZE milliseconds] PROCESS com.adventnet.nms.startnms.NmsMainFE ARGS CLIENT_SERVER SSL |
Server.xml
Un-comment the following entry in the <Web NMS Home>/apache/tomcat/conf/backup/server.xml file.
|
<Connector port="SSL_PORT" maxThreads="150" minSpareThreads="5" maxSpareThreads="15" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" clientAuth="false" keystorePass="webnms" sslProtocol="TLS" keystoreFile="conf/server.keystore" connectionTimeout="-1"/>
|
serverparameters.conf
Configure the NMS_FE_SECONDARY_PORT in the serverparameters.conf file present under <WebNMS_Home>/conf directory. Ensure that the NMS_FE_SECONDARY_PORT value is different from the PORT_TO_LISTEN value specified in <WebNMS_Home>/conf/transportProvider.conf for SSL protocol.
|
NMS_FE_SECONDARY_PORT 3606
|
Changing the Server and Client-Side Script Files
There are certain script files in Web NMS that require to be edited for enabling SSL (https) as the default communication mode. The configurations to be done in the script files vary for different OS, namely Windows, Linux, or Solaris. The script file changes to be done for the different OS are given below:
Script Files Changes in Windows Machines
The below given server-side and the client-side script files require modification for enabling SSL communication, by default, for the Windows OS machines.
startnms.bat:
This file, located in <Web NMS Home>/bin
directory, is used to start the Web NMS BE server. Make the following
modifications (marked in bold face)
in this file in the com.adventnet.nms.startnms.NmsMainBE process:
1. Modify the -Dwebserver.port
value to %SSL_PORT%.
2. Add the -Dwebcontainer.port=%SSL_PORT%
entry.
3. Add the -Djavax.net.ssl.trustStore=conf\Truststore.truststore
entry.
|
:start1 . . -Dwebserver.port=%SSL_PORT%
-Xmx100m -Dresource_check="%WEBSERVER_PORT%,%WEBCONTAINER_PORT%,%TOMCAT_SHUTDOWNPORT%"
-Dssl.port=%SSL_PORT% -Dwebserver.rootdir=%WEBSERVER_HOME% |
startApplicationClient.bat: The standalone application client can be enabled by modifying the startApplicationClient.bat file located in <Web NMS Home>/bin directory.
Add the location of the truststore file in the startApplicationClient.bat file.
Provide the %SSL_PORT%
parameter.
|
%JAVA_HOME%\bin\java .... -Djavax.net.ssl.trustStore=conf\Truststore.truststore
com.adventnet.nms.startclient.WebNMSClient localhost %SSL_PORT% |
|
|
Note: To enable SSL mode for Windows XP machine, you need to install the Windows XP Service Pack1. |
Script Files Changes in Linux or Solaris Machines
The below given server-side and the client-side script files require modification for enabling SSL communication, by default, for Linux or Solaris OS machines.
startnms.sh: This file, located in <Web
NMS Home>/bin directory, is used to start the Web NMS BE server.
Add the following (marked in bold face)
in this file:
1. Modify the -Dwebserver.port value
to $SSL_PORT.
2. Add the -Dwebcontainer.port=$SSL_PORT
entry.
3. Add the -Djavax.net.ssl.trustStore=conf/Truststore.truststore
entry.
|
while(true) ... |
startApplicationClient.sh: The standalone application client is started from the file startApplicationClient.sh located in <Web NMS Home>/bin directory.
Add the location of the truststore file in the startApplicationClient.sh file.
Provide the $SSL_PORT parameter.
|
if [ $# -eq 0 ] then while(true) do $JAVA_HOME/bin/java -Djavax.net.ssl.trustStore=conf/Truststore.truststore -Xmx200m com.adventnet.nms.startclient.WebNMSClient $host $SSL_PORT |
Starting the Server and Client from Launcher
To Start the Server
Modify the launcher_conf.txt
file present in the <Web NMS Home>/conf
directory and include the arguments
-Dwebserver.port=8443 -Dssl.port=8443 -Djavax.net.ssl.trustStore=conf/Truststore.truststore
for the AppJavaOption property
as shown below :
|
<application> <property name="AppName" value="Start Web NMS Server"/> <property name="ToolTip" value="Starts the NMS Server"/> <property name="AppType" value="java"/> <property name="AppJavaOption" value="-Dpgsql.home=./pgsql
-Dwebserver.port=8443 ...
|
To Start the Application Client
Modify the launcher_conf.txt file and include the arguments -Djavax.net.ssl.trustStore=conf/Truststore.truststore for Application Client.
|
<property name="AppName" value="Application Client"/> <property name="AppType" value="java"/> <property name="AppJavaOption" <property name="Classpath" value=".;./classes/NmsClientClasses.jar;./classes/JimiProClasses.zip;./...... |
Starting the Server as a Windows/Linux Service
To start Web NMS server as Windows/Linux Service in the SSL communication mode, carryout the procedure as given below.
Edit the wrapper.conf_windows/wrapper.conf_linux file located in the <Web NMS Home>/conf directory and un-comment the following 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=-Djavax.net.ssl.trustStore=conf/Truststore.truststore #wrapper.java.additional.19=-Dssl.port=8443 ######## For SSL ends ############################# |
Applet and Web Start Client Configurations
The following points need to be ensured for enabling the SSL mode of communication for the Applet and the Web Start clients:
Place the <truststore_file>.truststore file in the browser's <JRE_HOME>jre/lib/security directory
Add an entry for permission in the java.policy file located in the <JRE_HOME>jre/lib/security as,
grant {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks", "";
permission javax.net.ssl.SSLPermission "setHostnameVerifier", "";
permission java.util.PropertyPermission "*", "read,write";
};
For invoking the Applet and the Web Start clients, the protocol name to be specified in the browser URL is "https". The server certificate is dynamically downloaded in the respective client.
|
|
Note: For WebStart client if your own UI is to be invoked instead of the default UI (i.e., WebNMSClient.java), then the NmsClientUtil.setProtocolforWebStart("https") method must be invoked before invoking the WebNMSClient's doConnect( ) method. |
To enable the Web Client to support SSL communication mode, you must do the following configurations for Windows OS machine:
Start the server and
connect the Web Client with the following URL:
http://machine-name:WEBSERVER_PORT (example: http://opti-lin2:9090)
> On Connecting, the default login page is shown.
https://machine-name:SSL_PORT (example: https://opti-lin2:8443) >
On Connecting, the certificate is shown.
|
|
Note: After configuring for SSL by following the steps provided in this document, by default, the server will start in http and https mode. But only the web client can connect to both modes simultaneously. In the case of Java client this feature is not available. |
Setting Up Failover in SSL Enabled Web NMS
If SSL-enabled WebNMS servers are running in a failover setup, the following changes has to be made in the Standby server:
Create a directory named "Certs" under STANDBY's <Web NMS_Home> and copy the Primary's Truststore.truststore file into this folder.
If the Standby server is running on Windows or Linux, make the following changes in the <NMS_Home>\bin\createCertificates.bat or <NMS_Home>\bin\createCertificates.sh as follows:
Windows
Comment, if EXIST
%CERTIFICATE_DIRECTORY% rmdir /S /Q %CERTIFICATE_DIRECTORY%
|
rem if EXIST %CERTIFICATE_DIRECTORY% rmdir /S /Q %CERTIFICATE_DIRECTORY% |
Make the following
changes to include the Secserver.cer.
|
Change %JAVA_HOME%\bin\keytool -export -keystore %CERTIFICATE_DIRECTORY%\server.keystore -alias bessl -storepass webnms -file %CERTIFICATE_DIRECTORY%\server.cer
to
%JAVA_HOME%\bin\keytool -export -keystore %CERTIFICATE_DIRECTORY%\server.keystore -alias secssl -storepass webnms -file %CERTIFICATE_DIRECTORY%\Secserver.cer
|
|
Change
%JAVA_HOME%\bin\keytool -import -keystore %CERTIFICATE_DIRECTORY%\Truststore.truststore -alias bessl -file %CERTIFICATE_DIRECTORY%\server.cer -storepass webnms -noprompt
to
%JAVA_HOME%\bin\keytool -import -keystore %CERTIFICATE_DIRECTORY%\Truststore.truststore -alias secssl -file %CERTIFICATE_DIRECTORY%\Secserver.cer -storepass webnms -noprompt
|
Linux
Comment, rm -rf $CERTIFICATE_DIRECTORY
> null.txt
|
#rm -rf $CERTIFICATE_DIRECTORY > null.txt |
Make the following
changes to include the Secserver.cer.
|
Change $JAVA_HOME/bin/keytool -export -keystore $CERTIFICATE_DIRECTORY/server.keystore -alias bessl -storepass webnms -file $CERTIFICATE_DIRECTORY/server.cer
to
$JAVA_HOME/bin/keytool-export -keystore $CERTIFICATE_DIRECTORY/server.keystore -alias secssl -storepass webnms -file $CERTIFICATE_DIRECTORY/Secserver.cer
|
|
Change
$JAVA_HOME/bin/keytool -import -keystore $CERTIFICATE_DIRECTORY/Truststore.truststore -alias bessl -file $CERTIFICATE_DIRECTORY/server.cer -storepass webnms -noprompt
to
$JAVA_HOME/bin/keytool -import -keystore $CERTIFICATE_DIRECTORY/Truststore.truststore -alias secssl -file $CERTIFICATE_DIRECTORY/Secserver.cer -storepass webnms -noprompt
|
The BETransKey.key and Truststore.truststore certificates created for SSL communication in Web NMS 4.7.x, can be migrated to Web NMS 5 and reused. This is achieved by importing the BETransKey.key and Truststore.truststore files. (If you have renamed these files, please substitute your file name instead of BETransKey.key and Truststore.truststore)
Copy BETransKey.key
created for Transport Provider implementation to <NMS5_Home>\conf
and <NMS5_Home>\apache\tomcat\conf.
(BETransKey.key is the output of keytool -genkey -alias betransssl
-validity 3000 -keystore BETransKey.key -storepass webnms -keypass webnms)
Copy Truststore.truststore file to <NMS5_Home>\conf.
Replace server.keystore
with BETransKey.key in <NMS5_Home>\conf\transportProvider.conf
and <NMS5_Home>\apache\tomcat\conf\backup\server.xml
files.
Complete the configurations specified in this document before starting
the server with the imported certificates.
To start the server only in the SSL_PORT (e.g., 8443), comment out the following entry in the <Web NMS Home>/apache/tomcat/conf/backup/server.xml file.
|
<Connector port="WEBCONTAINER_PORT" maxThreads="50" minSpareThreads="3" maxSpareThreads="10" enableLookups="true" acceptCount="100" connectionTimeout="0" disableUploadTimeout="true" URIEncoding="UTF-8" compression="force" compressionMinSize="1024" noCompressionUserAgents="gozilla, traviata" compressableMimeType="text/html,text/xml"/> |
In the case of Windows OS, in startnms.bat file present in <Web NMS Home>\bin directory, the CLASS_PATH should be replaced with CLASSPATH variable and the following CODEBASE entry should be removed:
-Djava.rmi.server.codebase=%CODEBASE_LIST%
In the case of Linux OS, in startnms.bat file present in <Web NMS Home>\bin directory, the following CODEBASE entry should be removed:
-Djava.rmi.server.codebase=$CODEBASE_LIST
What are the reasons for the "Gracefully Shutting down the Web NMS" server issue when starting the server in SSL.
The following are the possible reasons for the "Gracefully Shutting down the Web NMS server" in the SSL setup:
If the key and certificate files are not placed in the Web NMS folders as mentioned in the SSL document.
If the certificate for both the BE server and the TransportProvider implementation is not placed in one single truststore file.
If the machine name
(where web server is running) is not provided as the "Common Name"
while creating the server.keystore
file.
Can we have separate Key and Certificates for different client machines or is it only one Key and Certificate?
The Key and Certificates are the same for the clients connecting to a particular server. Need not create separate Key and Certificates for different client machines connecting to the same server.
|
|
