Installing Oracle Utilities Network Management System Software
Use the following procedures to install Oracle Utilities Network Management System software.
1. Log in as the administrative user (for example, nmsadmin).
2. Set the NMS_ROOT, NMS_HOME, and NMS_BASE environment variables. For example:
export NMS_ROOT=/users/nmsadmin
export NMS_HOME=/users/nmsadmin
export NMS_BASE=$NMS_ROOT/nms/product/2.6.0.0.0
3. Set the ORACLE_HOME environment variable. For example:
export ORACLE_HOME=/users/oracle/product/19.9
4. Set the ORA_SDTZ environment variable UTC.
export ORA_SDTZ=UTC
The default session time zone can be confirmed using the following SQL command:
select sessiontimezone from dual;
5. Set the JAVA_HOME environment variable to the 64-bit JDK installation directory. For example:
export JAVA_HOME=/opt/java8
6. Set PATH and LD_LIBRARY_PATH variables
export PATH=$NMS_BASE/3rdparty/bin:$ORACLE_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NMS_BASE/3rdparty/lib:$ORACLE_HOME/lib
7. Unzip the Oracle Utilities Network Management System “Base Software” zip file. For example:
unzip /path/to/filename.zip
8. In the /etc directory, create an empty file named nmstab.
nmstab is used as a repository of NMS installations on a machine. To install NMS, the following must be true:
• The NMS_HOME environment variable must be set.
• nmstab must exist and be writable.
The install script (nms-install) will check these requirements and update nmstab.
• NMS admin users must be members of the same group and nmstab be writable by that group.
If the group and nmstab requirements cannot be met, nms-install can be run with the noNmsTab option. However, if this is done, the nms-list-installs script and OEM integration will not be available.
nmsRoot (found in $NMS_ROOT/network/bin) must be run only once per machine as root to create nmstab. The name of the NMS group is passed as a parameter to this script. Optionally, the name of the owner to use for nmstab can be passed as the second parameter (root is used by default).
$NMS_ROOT/network/bin/nmsRoot
9. Run the install script:
cd network
./nms-install
Note: this could take several minutes to complete.
10. Remove the installation files before continuing:
cd ..
rm –rf network
11. If you already have an existing .profile, then append the following line to the bottom:
. $NMS_HOME/.nmsrc
This ensures that your environment is set correctly at login.
12. If you have an existing Oracle Utilities Network Management System resource file with a name other than $NMS_HOME/.nmsrc (.ces.rc, .cesrc, …), rename it to $NMS_HOME/.nmsrc. Move all project-specific environment variables out of the .nmsrc file into your .profile file or another resource file.
13. Change the environment variables set in the $NMS_HOME/.nmsrc file using the nmsrc configuration script by executing this command:
$NMS_BASE/bin/nms-env-config
Set each variable as appropriate for your environment.
Notes:
• Default Values
The first time you run nms-env-config you will need to pay close attention to the values that are presented to you as defaults, and ensure that they are set correctly. During subsequent runs you will be presented with the current settings for each variable as the default, and can simply press return at each prompt, reducing the time it takes to run the script.
When nms-env-config runs, it will flag variables that are not set to the defaults from the standard template. We encourage the use of defaults as much as possible to help facilitate customer support. However, it is up to the customer to decide if deviating from the defaults is appropriate for their environment.
• Upgrading from a Release Prior to 2.5.0.0.0
The RDBMS_ADMIN variable is new in 2.5.0.0.0. If upgrading from a release prior to 2.5.0.0.0, set RDBMS_ADMIN to the old value of RDBMS_HOST. Set the new value of RDBMS_HOST to be a different value from RDBMS_ADMIN that has an entry in tnsnames.ora that connects to the same database as the entry matching RDBMS_ADMIN.
• Oracle Wallet Security Configuration
All projects have to configure and maintain Oracle wallets for each Unix user that starts services that connect to the database.
The script prompts you to choose your wallet location, which sets the TNS_ADMIN environment variable (default: ~/etc/wallet). Then it asks you to create passwords and enter the database credentials. Your new Oracle wallet will then map the RDBMS_ADMIN and RDBMS_HOST environment variables to user names and passwords stored in the wallet.
RDBMS_ADMIN and RDBMS_HOST must have different values with entries in tnsnames.ora pointing to the same database instance. Example tnsnames.ora entry:
PRODSERV01ADM, PRODSERV01.world =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = db.example.com)
(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = PRODSERV01.world)
)
)
IVR_RBDMS_HOST also needs wallet credentials if you are using IVR.
SwService uses a separate Oracle wallet to store credentials it uses to connect to WebLogic Server. The script prompts you to choose a wallet location, and then sets the NMS_WALLET environment variable (default: $NMS_HOME/etc/nms_wallet). If the wallet does not exist it will be created. In that case you will be prompted to create the wallet password. Then the script asks you to enter credentials to be used by SwService. The credentials specified must be a valid WebLogic user that is a member of the group name specified by weblogic-service-group in $NMS_CONFIG/jconfig/build.properties (defaults to nms-service).
Note: WebLogic user authentication configuration is described in Chapter 13 of the Oracle Utilities Network Management System Configuration Guide. WebLogic users are defined in Authentication Providers within the security realm. Real users are typically configured via LDAP or some other directory service. However, for performance reasons, it is recommended that the user credentials used by external adapters (including SwService) be defined in a provider that is internal to the WebLogic installation and that the internal provider is configured to be the first one used; this avoids potential delays caused by latency to the network-based directory services. Ensure that the users defined in build.propeties are defined with the internal Weblogic provider: publisher.ejb-user, config.multispeak_runas_user, and config.ws_runas_user
This script should be run for each Unix user that runs NMS services.
Note: After running nms-env-config, you must log out and log back in to set the environment variables.
14. After making the above changes, log out and log in to set the environment variables. For a list of environment variables set by nms-env-config and their descriptions, see the “Environment Configuration” chapter of the Oracle Utilities Network Management Systems Configuration Guide.
15. Execute the following commands to copy the templates from $NMS_BASE/templates directory to $NMS_HOME/etc. If you have existing files in $NMS_HOME/etc, they will be backed up to <file>.bak.<timestamp>.
nms-install-templates
Starting Isis
Please refer to the “Isis Configuration” chapter of the Oracle Utilities Network Management System Configuration Guide for details on configuring and optimizing Isis.
1. Start Isis, as follows:
$ nms-isis stop
$ nms-isis start
2. When complete (which will take approximately one minute), type:
$ nms-isis status
This determines if Isis has successfully started and will return 1 if isis is running, 0 if isis is not running.
Create Database Environment
Note: this procedure is only necessary if you do not have an existing Oracle Utilities Network Management System database.
Use the following procedure to create a database environment: for an Oracle Utilities Network Management System.
Note: this step, the process of defining NMS roles, should only be executed once per Oracle RDBMS instance that is supporting one or more NMS instances.
1. Copy the nms_role.sql.template file to a a project specific directory where you can save configuration files that you only run when you are creating new NMS instances. The resulting nms_role.sql file defines the necessary Oracle roles to support an NMS instance.
Read the comments in the file regarding recommended use. For most projects the contents of this file should not need to be modified and it can be executed essentially as is.
$ mkdir $NMS_HOME/my_sql
$ cp $NMS_BASE/templates/nms_role.sql.template $NMS_HOME/my_sql/nms_role.sql
$ cd $NMS_HOME/my_sql
$ sqlplus system/<system_passwd>@$RDBMS_HOST < nms_role.sql
If this is the first time you have run this, you may see errors about dropping roles that do not exist, which can generally be safely ignored. To be sure run the file in again and make sure there are no errors on the second attempt (the script should drop and create the required roles without error).
2. Read through the comments in the nms.sql.template file. This file must be modified for your installation - often significantly. It is a template for creating the necessary Oracle usernames, schemas, and tablespaces to support an Oracle NMS instance.
For example, if your company name is Oracle Gas & Electric (oge), you might create a copy of the template for a test NMS instance like this:
$ cp $NMS_BASE/templates/nms.sql.template $NMS_HOME/my_sql/oge_nms_test.sql
3. Edit oge_nms_test.sql and follow the instructions (included as comments in the file) to suit your environment.
4. Run nms.sql as follows:
cd $NMS_HOME/my_sql
sqlplus sys/<system_passwd>@$RDBMS_HOST as sysdba <
oge_nms_test.sql
If this is the first time you have run this, you may see errors about objects that already exist (or may not exist), which can generally be safely ignored. To be sure, run the file in again and make sure there are no errors on the second attempt. On the second attempt the script should drop and create Oracle usernames and tablespaces without error.
5. Log in as the Oracle Utilities Network Management System Oracle RDBMS administrative user and test the connection to Oracle - using appropriate parameters based on what was provided in the oge_nms_test.sql file above. At the prompt, enter something similar to the following:
sqlplus oge_nms_test/oge_nms_test_passwd@$RDBMS_HOST
If the connection is successful, a SQL> prompt will appear. Enter exit to return to the shell prompt.
6. Log in as the Oracle Utilities Network Management System Oracle RDBMS read-only user and test the connection to Oracle - using appropriate parameters based on what was provided in the oge_nms_test.sql file above. At the prompt, enter something similar to the following:
sqlplus oge_nms_test_ro/oge_nms_test_ro_passwd@$RDBMS_HOST
If the connection is successful, a SQL> prompt will appear. Enter exit to return to the shell prompt.
Validation Model Setup
Use the following procedure to install an Oracle Utilities Network Management System installation verification network data model:
1. If you do not have an existing network data model to load at this point, you can use the OPAL validation model included in the Oracle Utilities Network Management System release.
2. Log in as the administrative user and run nms-env-config --base-config using the following variables:
NMS_CONFIG_ORDER="OPAL nms"
SYMBOLOGY_SET=${OPERATIONS_MODELS}/SYMBOLS/OPAL_SYMBOLS.sym
NMS_CONFIG=$NMS_HOME/OPAL
3. Log out and log back in again, ensuring the variables are set correctly.
Note: If you have previously installed the validation model, you should backup any existing local modifications before proceeding to step 4.
$ mkdir ~/OPAL-backup
$ cd $NMS_CONFIG
$ cp sql/OPAL_parameters.sql jconfig/build.properties jconfig/build.xml jconfig/nms*keystore jconfig/global/nms-client.keystore jconfig/global/properties/CentricityTool.properties jconfig/server/CentricityServer.properties ~/OPAL-backup/.
4. Copy the OPAL configuration in $NMS_BASE to NMS_CONFIG:
$ cd $NMS_HOME
$ rm -rf $NMS_CONFIG
$ cp -r -L $NMS_BASE/OPAL $NMS_CONFIG
5. If you backed up files from a previously installed validation model (in step 3), merge those files back into the newly copied $NMS_CONFIG directory (from step 4).
For each file, if the file from the backup does not exist in the new structure, simply copy it into place in $NMS_CONFIG. If $NMS_CONFIG already contains a file with the same name as the backup copy, then you will need to merge changes from the backup copy into the new file.
6. Run nms-make-symbols, nms-install-config, and nms-setup script to load the schema and configuration, as follows:
$ nms-make-symbols
$ nms-install-config --nojava
$ nms-setup -clean -reset
7. Enable write permissions for the web map directory so the user that runs the Java Application Server (for example, wls) can create files. This is done to enable the distribution of maps to web clients through the application server. If the Java Application Server is running on the same system as the NMS services, this location would be the $OPERATIONS_MODELS/ser directory:
$ cd $OPERATIONS_MODELS
$ mkdir ser
$ su
Password:
# chown wls:users ser
# exit
If the Java Application Server is running on a different system than the NMS services, verify the WEB_tempDirectory (as defined in ces_parameters config table where attrib='WEB_tempDirectory') exists on the system where the Java Application Server is running and that the directory is writable to the user running the Java Application Server.
8. Create the directory for the model files:
mkdir -p $OPERATIONS_MODELS/mp
9. Load the sample data:
$ LoadOPALModel
The script will load sql files, start a subset of Oracle Utilities Network Management System services, and then build the data model.
Web Application Configuration
Before installing the web applications, follow these steps:
1. Create backups of the following parameters files, if applicable. Note that NMS_PROJECT is the name of your configuration project, for example, OPAL.
$ cp $NMS_CONFIG/sql/NMS_PROJECT_parameters.sql
$NMS_CONFIG/sql/NMS_PROJECT_parameters.sql.bak
$ cp $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_1.sql $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_1.sql.bak
$ cp $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_2.sql $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_2.sql.bak
2. Copy the parameters files to your $NMS_CONFIG sql directory:
$ cp $NMS_BASE/product/sql/nms_parameters.sql
$NMS_CONFIG/sql/NMS_PROJECT_parameters.sql
$ cp $NMS_BASE/OPAL/sql/OPAL_site_parameters_1.sql $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_1.sql
$ cp $NMS_BASE/OPAL/sql/OPAL_site_parameters_2.sql $NMS_CONFIG/sql/NMS_PROJECT_site_parameters_2.sql
3. Navigate to the $NMS_CONFIG/sql directory.
$ cd $NMS_CONFIG/sql
4. In the $NMS_CONFIG/sql directory, modify the parameters (described in the table below) in NMS_PROJECT_parameters.sql, NMS_PROJECT_site_parameters_1.sql, and NMS_PROJECT_site_parameters_2.sql (NMS_PROJECT_site_parameters_2.sql is only necessary if using dual-environment configuration). Refer to the backup files made in step 1, if applicable.
Notes
The WebLogic Server (WLS) needs access to the nmsadmin data directory to get *.mad/*.mac files to turn into *.ser files for use by the NMS Viewer. The WLS can either be running on the same machine as the NMS services or on a different machine.
• If the WLS is running on the same system (not normally done), the WLS can be configured to read the nmsadmin data files directly using a specific file path (WEB_mapDirectory) and setting WEB_syncMaps = false.
• If the WLS is running on a different server than the NMS services (normally recommended), then you will need to set up a httpd server and set WEB_syncMaps = true.
NFS does not work as a solution to make the remote NMS server data directory available to the WLS server. NFS can have delays getting files to the WLS meaning the NMS WLS can potentially read old map data causing the NMS Viewer maps to have errors or show incorrect data. You can either install and configure your own httpd server (for example, Apache) or use the lighttpd http server, which is shipped with the base NMS product. Usage of lighttpd is discussed in the following section. The nms-lighttpd script may be used to start and stop the lighttpd process; the script is also shipped as part of the base NMS product and can be configured into your normal NMS startup/shutdown/restart process.
An httpd server is also required to serve up log files to the Oracle Utilities Network Management System Application Management Pack for Oracle Enterprise Manager. You can use your own server or use the lighttpd http server. The nms-lighttpd-oem script may be used to start and stop this instance of the lighttpd process. This script is also shipped as part of the base NMS product and can be configured into your normal NMS startup/shutdown/restart process.
Web Application Parameters
Element | Description | Example |
|---|
WEB_intersysName | The WEB_intersysName should match the implName of the CORBA gateway. Normally this will be InterSys_{user}. This is a site‑specific parameter. | InterSys_nmsadmin |
WEB_syncMaps | If false, it will look for the maps using a file location specified in WEB_mapDirectory. If it is true, it will instead load the maps using http and a web server would have to be installed on the NMS server with the data directory exposed. A standard httpd server is provided with the NMS release and can be started with the nms-lighttpd command. Configure WEB_mapDirectory, WEB_mapHttpdPort, WEB_mapHttpdAllowedIPs, and WEB_tempDirectory before starting the httpd server. | true |
WEB_mapDirectory | The location of the maps directory from the perspective of the WebLogic server. This can be either a file path or, if WEB_syncMaps is set to true, a location that starts with http://. If using the nms-lighttpd process, this would be set to: http://<nms-server-name>:<WEB_mapHttpdPort> Note: When WEB_syncMaps=false, WEB_mapDirectory is the same as $OPERATIONS_MODELS. In dual-environment configuration, each environment must have a different value for this parameter. This is a site‑specific parameter. | http://nms-vm:8888 |
WEB_mapHttpdPort | The port to use for the httpd server started with the nms-lighttpd command start process. This port must be an unique and available port on the NMS C++ Server system. If running multiple NMS environments on the same machine, please verify this value is unique for this machine. This is a site‑specific parameter. | 8888 |
WEB_mapHttpdAllowedIPs | List of IP addresses where you will be running the WEB Application Servers that are allowed to access the map files from the httpd server. Separate the IP addresses with vertical bar symbols (|) if there are multiple servers. This is used by the nms command start process. If this value is blank, it will not restrict any IP addresses from reading the map files. | 192.168.107.128|192.168.107.1|127.0.0.1 |
WEB_mapHttpdHost | The host name or IP address that the lighttpd httpd server listens for connections on. If specified, this should match the server name from the WEB_mapDirectory property. If not specified or left blank, it will default to 0.0.0.0 (bind to all network interfaces). This is a site‑specific parameter. | 192.168.107.18 |
Note: If you are using the lighttpd http server and make changes to WEB_mapDirectory, WEB_mapHttpdPort, WEB_mapHttpdAllowedIPs, or WEB_mapHttpdHost, you can restart the http server using these commands: nms-lighttpd stop nms-lighttpd start |
WEB_oemHttpdPort | The port to use for the httpd server started with the nms-lighttpd command start process. This port must be an unique and available port on the NMS C++ Server system. If running multiple NMS environments on the same machine, please verify this value is unique for this machine. This is a site‑specific parameter. | 8888 |
WEB_oemHttpdAllowedIPs | List of IP addresses where you will be running the WEB Application Servers that are allowed to access the map files from the httpd server. Separate the IP addresses with vertical bar (pipe) symbols (|) if there are multiple servers. This is used by the nms command start process. If this value is blank, it will not restrict any IP addresses from reading the map files. | 192.168.107.128|19 2.168.107.1|127.0.0.1 |
WEB_oemHttpdHost | The host name or IP address that the lighttpd httpd server listens for connections on. If specified, this should match the server name from the WEB_mapDirectory property. If not specified or left blank, it will default to 0.0.0.0 (bind to all network interfaces). This is a site‑specific parameter. | 192.168.107.18 |
Note: If you are using the lighttpd http server and make changes to WEB_oemHttpdPort, WEB_oemHttpdAllowedIPs, or WEB_oemHttpdHost, you can restart the http server using these commands: nms-lighttpd-oem stop nms-lighttpd-oem start |
WEB_tempDirectory | This is the directory to store cached and serialized map files. It should be a directory writable by the WebLogic Managed Server. This is a site‑specific parameter. | /users/nmsadmin/dist/maps |
WEB_corbaInitRef | The initial reference of the CORBA naming service. It is in the format of NameService=corbaloc:iiop:1.2@[host]:[port]/NameService. The {host} and {port} should match the values of the NMS server's CORBA naming service. This is a site‑specific parameter. | NameService=corbaloc:iiop:1.2@server. example.com:17821/NameService |
WEB_watermark | This is transparent text that will display across the windows of an application diagonally. It can be used to make it very obvious what environment you are currently a part of. If you do not wish to use this feature, do not define this value. | Production Test |
WEB_envName | This is the name of the environment that will display in the main window header under the logged in users’ name. It can either be the same value as the watermark or an additional name as desired, such as the name of the system. | Production Test |
WEB_envType | This parameter specifies the NMS environment type. Currently, the recognized values are: • training: This environment type is required to use the Training Simulator. It allows Trainer user type and the creation/execution of Training Scenario sheets. • production: This environment type should be used in production. It disallows the Reset Model functionality (used by Training Simulator, but can be configured for use in non-production environments for testing purposes). Other values can be used, but do not have any effect other than indicating that this is neither a training nor production environment. | production |
WEB_documents | This parameter controls the disk location where documents are stored for the Manage Documents Window. This is a subdirectory of the $OPERATIONS_MODELS directory and defaults to drawings. | drawings |
MBS_GEO_PROJ_COORDSYS | The projection of the geographic data being loaded into the NMS model. This parameter is required to convert map geographic coordinates to latitude/longitude values. This is used to request maps from web map servers and other functions within the Web Workspace client such as Coordinate display in the Viewer. Use the Proj website as a reference on setting this value: https://proj.org/ Most projects can specify this as a epsg number; you can use this website to find the espg value: https://epsg.io/ If you need to define a custom projection, that can be done using the +proj= format. | epsg:3734 or +proj=lcc +lat_1=41.7 +lat_2=40.43333333333333 +lat_0=39.66666666666666 +lon _0=-82.5 +x_0=600000 +y_0=0 +ellps=GRS80 +units=us-ft +no_defs |
MBS_LL_PROJ_COORDSYS | The target Lat/Long specification to be used when converting coordinates from the geographic coordinates to Lat/Long. This parameter is required to convert map geographic coordinates to latitude/longitude values. Us the references specified above in the MBS_GEO_PROJ_COORDSYS to learn how to set this value. Most projects will set this to epsg:4326 fro Lat/Long. | epsg:4326 |
Note: The WEB_ properties may be set by adding a startup parameter to the WebLogic managed server's startup parameter. For example, to configured a watermark for a particular managed server, add this:
"-Dwatermark=Read Only System"
5. If services are not running, you need to run the following command:
sms‑start
Note: The load will fail if services are not running. For example, services would not be running if you are performing a new project installation.
6. When the above changes have been made, run the following commands:
$ cp $NMS_CONFIG/sql/NMS_PROJECT_parameters.sql $NMS_HOME/sql
$ ISQL NMS_PROJECT_parameters.sql
7. Starting with Java SE 7 Update 21 in April 2013 all Web Start Applications like Oracle Utilities Network Management System are encouraged to be signed with a trusted certificate for the best user experience. Please follow the steps in the Security Certificates in Oracle Utilities Network Management section found in the Security chapter of the Oracle Utilities Network Management Security Guide.
For purposes other than Production, and if you do not have certificates issued by trusted certificate authorities, you may use the nms-gen-keystore script to generate self-signing certificates:
$ nms-gen-keystore
You will be prompted for your server name (as entered in a browser) and your organization.
Note: Future update releases of Java will require changing Java security settings on the client to continue to run self-signed applications.
8. Verify that the version of WebLogic you are running matches the supported version of WebLogic defined in the $NMS_CONFIG/jconfig/build.properties.
# The WebLogic version to deploy to.
weblogic.version = 12.2.1.3.0
9. Edit key.server.name to reflect the DNS name or IP address of the host or cluster that the client will connect to.
10. Verify the value of client.url in $NMS_CONFIG/jconfig/build.properties. This is the URL that the clients will use to contact the managed server. It should start with t3s:// if encryption is used (which is recommended) or t3:// if the link should not be encrypted.
11. The publisher.ejb-user in $NMS_CONFIG/jconfig/build.properties should be a user that is defined as part of the nms-service group. This account will be used when WebLogic performs an internal operation that is not done in response to a user action.
Note: If the build.properties file does not exist in $NMS_CONFIG/jconfig/, you will need to create it. See “Create or Modify the Project build.properties File” section in the Oracle Utilities Network Management System Configuration Guide Java Application Configuration chapter for details.
12. If you wish to configure WebLogic to not use SSL/HTTPS, then edit $NMS_CONFIG/jconfig/build.properties. Add or change (uncomment) the following line:
option.no_force_https
13. If you will be running multiple instances of Oracle Utilities Network Management System, you will need to create JDBC Data Sources for each WebLogic managed server, each with a unique JNDI name (see WebLogic Runtime Configuration below). To change the JNDI name from the default of jdbc/intersys, edit $NMS_CONFIG/jconfig/build.properties and modify the following line (you may need to uncomment the line):
config.datasource = jdbc/intersys/nmsadmin
14. If you are running the application as part of a WebLogic cluster, uncomment the following line:
enable.cluster = true
15. Once all files are in place, build the configuration by running:
cd
nms-install-config --java
Copy Supporting Files from the NMS Distribution to the WebLogic Domain
Certain files are required to be installed into the domain level of the WebLogic server. Since WebLogic installations vary, it is necessary to manually copy these files to your WebLogic domain.
As you use the instructions below to copy the files, substitute your system’s appropriate values for each of:
• $NMS_BASE
• WLS_HOME
• domain_name
• user
• hostname
Alternative 1
If the WebLogic Server is located on the same system as the NMS installation.
1. Copy the contents of the wls directory recursively using cp:
$ cp -L -r $NMS_BASE/dist/install/wls/.
$WLS_HOME/user_projects/domains/domain_name
Alternative 2
If the WebLogic Server is located on a different system than the NMS installation.
1. Copy the contents of the wls directory recursively using scp:
$ scp -r user@hostname:$NMS_BASE/dist/install/wls/.
WLS_HOME/Oracle/Middleware/user_projects/domains/domain_name
2. Having copied the files, restart the WebLogic Managed Server that will be running NMS.
Configuring NMS Security Roles
The following are the LDAP groups that are used by NMS. It is recommended that separate groups be defined for each of these for best security. However, it is also possible to use the same group for multiple types.
NMS Generic User
There are up to three generic users that may need to be defined in LDAP, and assigned to the “service_users” mentioned below. If you wish to use different names for any of them, the names can be configured in $NMS_CONFIG/jconfig/build.properties.
• nms-service: This account is used to connect to the Corba Publisher, and is set by property “publisher.ejb-user”. This account is required in every NMS installation.
• mobile-proxy: this account is used by the NMS Web Services ear, and is set by property “config.ws_runas_user”. This is not required unless the Web Services ear is deployed.
• multispeak-user: this account is used by the NMS MultiSpeak ear, and is set by property “config.multispeak_runas_user”. This is not required unless the MultiSpeak ear is deployed.
If these users do not already exist in the WebLogic security domain, they need to be created. See the User Authentication chapter in the Oracle Utilities Network Management System Configuration Guide for information on how to either configure LDAP or add local users in WebLogic.
NMS Groups
• view_only_users: Users that can only view NMS data.
• call_entry_users: Users that can update call entry.
• service_alert_users: Users that can update service alert.
• standard_users: Users that can modify any NMS data.
• nms-scada-control: Users that can initiate SCADA outbound field control requests.
• service_users: Adapter and the publisher.ejb-user defined in build.properties.
• nms-twofactor: Users that should be authenticated using two-factor authentication.
NMS Roles
• NmsRead: calls to view NMS data.
• NmsWrite: calls to update NMS data.
• NmsScadaControl: calls that initiate a SCADA outbound field control request.
• NmsCallEntry: calls used only by Call Entry.
• NmsUpdate: calls that update the database. These are also protected by application by the allowed_update_tables entries in CentricityServer.properties.
• NmsService: calls that should only be run by adapters and internal accounts.
• NmsCustom1: This is an unused role that can be used for project specific requirements.
• NmsCustom2: This is an unused role that can be used for project specific requirements.
• NmsCustom3: This is an unused role that can be used for project specific requirements.
• NmsMultifactor: Indicates that the user should use two-factor authentication when logging in.
NMS Roles to Groups Mapping
• NmsRead: view_only_users, call_entry_users, service_users, standard_users, nms-scada-control
• NmsWrite: standard_users, service_users, nms-scada-control
• NmsCallEntry: call_entry_users, standard_users, service_users
• NmsUpdate: service_alert_users, standard_users, service_users, nms-scada-control
• NmsService: service_users
• NmsMultifactor: nms-twofactor
Groups can be configured by modifying and running the roles.py python script, which can be found in the scripts directory under the WebLogic domain directory.
Open and review the script. If you have a need to create custom groups, other than what is set for the defaults in NMS, then modify the top portion of the script:
view_only_users = "nms-view-only"
call_entry_users = "nms-call-entry"
service_alert_users = "nms-service-alert"
standard_users = "nmsuser"
scada_control_users = "nms-scada-control"
service_users = "nms-service"
mobile_proxy = "nms-mobile"
No further changes to the script are required.
Run the following two commands:
. $WL_HOME/server/bin/setWLSEnv.sh
Note: This script will set the correct environment variables in your terminal.
$WL_HOME/../oracle_common/common/bin/wlst.sh roles.py
The script will output messages and prompt you for WebLogic details. For example:
Initializing WebLogic Scripting Tool (WLST) ...
Welcome to WebLogic Server Administration Scripting Shell
Type help() for help on available commands
WebLogic domain name: nms (this is the specific domain where NMS will be running)
Please enter your username: weblogic (this is the administrative user login for WebLogic)
Please enter your password: (this is the password for your WebLogic admin user)
Please enter your server URL [t3://localhost:7001]: (url for the administration console; the default may work for you)
Connecting to t3://localhost:7001 with userid weblogic ...
Successfully connected to Admin Server 'AdminServer' that belongs to domain 'nms'.
Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, the SSL port or Admin port should be used instead.
NMS Roles updated
Once this has completed, you must stop and restart WebLogic.
Please see the “Manage Security Roles” topic in the Oracle WebLogic Server Administration Console Online Help for more information.
Modifying or Adding Security for Individual EJB Methods
If there is a requirement to modify the base ejb security configuration, it is possible to do so with deployment descriptors. Before attempting to do this, it is important to have a good understanding of WebLogic groups and roles, as well as deployment descriptors. See the Oracle WebLogic Server documentation for details.
• The deployment descriptor for cesejb.ear should be saved to $NMS_CONFIG/jconfig/override/cesejb.jar/META-INF/ejb-jar.xml
• The deployment descriptor for fwserver.ear should be save to $NMS_CONFIG/jconfig/override/fwserver.jar/META-INF/ejb-jar.xml
The following example defines a special role for Session.runScript. Note that defining security for a method using deployment descriptors replaces any existing security configuration:
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
version="3.0">
<assembly-descriptor>
<security-role>
<role-name>NmsCustom1</role-name>
</security-role>
<method-permission>
<role-name>NmsCustom1</role-name>
<method>
<ejb-name>Session</ejb-name>
<method-intf>Remote</method-intf>
<method-name>runScript</method-name>
</method>
</method-permission>
</assembly-descriptor>
</ejb-jar>
It is up to the project to define the role using the WebLogic Administration Console. See the Oracle WebLogic Server documentation for details.
WebLogic Server Runtime Configuration
For information on creating and installing to a WebLogic cluster, which requires the Enterprise edition of WebLogic, see the KM document 1911737.1:
https://support.oracle.com/rs?type=doc&id=1911737.1
For information on using a customer provided load balancer, see KM document 1910405.1.
https://support.oracle.com/rs?type=doc&id=1910405.1
If you wish to use multiple instances of WebLogic, but not part of a cluster or using a load balancer, see the KM document 1215414.1:
https://support.oracle.com/rs?type=doc&id=1215414.1
If you have multiple WebLogic servers that aren't part of a WebLogic cluster, enable this setting in CentricityServer.properties:
# If your project has multiple web gateways that aren't in a
# cluster, then set this to true.
# Also ensure that the gateway are on different servers, or each has
# a unique servername as specified by the command line
# argument nms-servername:
# -Dnms.servername=my_server_name
multiple_weblogic_servers = true
Create a Managed Server
1. Access the WebLogic Server Administration Console by entering the following URL:
http://hostname:port/console
Here hostname represents the DNS name or IP address of the Administration Server, and port represents the number of the port on which the Administration Server is listening for requests (port 7001 by default).
2. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
3. In the left pane of the Console, expand Environment and select Servers.
4. Click New.
5. For the Server Listen Address, enter an IP address or DNS name that resolves to an IP address of the server.
6. Change the Server Listen port to an unused port.
7. Click Advanced and then set RMI JDBC Security to Secure.
8. Click Finish.
9. In the Servers table, click the server name to open the Settings page.
10. Click the Tuning tab.
11. Make sure that Enable Native IO is not selected.
12. If necessary, click Advanced to access advanced tuning parameters.
13. In the Muxer Class field, enter:
weblogic.socket.NIOSocketMuxer
14. Select the Control tab, select your managed server, and click the Start button to start your managed server.
15. On the server's Configuration: General page, click the View JNDI Tree link.
The JNDI tree for the server appears in a new Administration Console window.
16. In the new Administration Console window, select the top node in the JNDI Tree Structure.
17. Select the Security tab and then the Policies sub-tab.
18. Under Methods, choose lookup.
• Add Conditions
• Select Allow Access to Everyone.
• Click Finish
19. Under Methods, choose All.
• Click Add Conditions, select Role, click Next.
• In the Role Argument Name field, enter Admin.
• Click Add and then Finish.
20. Click Save.
21. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure Database Connectivity
In WebLogic Server, you configure database connectivity by adding data sources to your WebLogic domain. To create a JDBC data source in your domain, you can use the Administration Console:
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the Domain Structure tree, expand Services, then select Data Sources.
3. On the Summary of JDBC Data Sources page, click New, and then select Generic Data Source.
4. On the JDBC Data Source Properties page, enter or select the following information:
• Name - Enter a name for this JDBC data source.
For example: JDBC Data Source-nms.
• JNDI Name - Enter the JNDI path to where this JDBC data source will be bound.
Use jdbc/intersys for the JNDI path.
Note: If you will have multiple instances of Oracle Utilities Network Management System running from this WebLogic installation, make the JNDI name unique (for example, jdbc/intersys/nmsadmin) and change “config.datasource” in $NMS_CONFIG/jconfig/build.properties to match this string.
• Database Type - Select Oracle for the DBMS of the database that you want to connect to.
• Click Next to continue.
• On the JDBC Data Source Properties page, select *Oracle’s Driver (Thin) for Instance connections; Versions:Any from the Database Driver drop‑down list.
• Click Next to continue.
5. On the Transactions Options page
• Select Supports Global Transaction.
• Select Emulate Two‑Phase Commit.
• Click Save.
6. On the Connection Properties page, enter values for the following properties:
• Database Name - Enter the name of the database that you want to connect to. Exact database name requirements vary by JDBC driver and by DBMS.
• Host Name - Enter the DNS name or IP address of the server that hosts the database.
• Port - Enter the port on which the database server listens for connections requests.
• Database User Name - Enter the database user account name that you want to use for each connection in the data source. This should match the ORACLE_READ_WRITE_USER variable in .nmsrc.
• Password/Confirm Password - Enter the password for the database user account.
• Click Next to continue.
7. On the Test Database Connection page, review the connection parameters and click Test Configuration.
• WebLogic attempts to create a connection from the Administration Server to the database. Results from the connection test are displayed at the top of the page. If the test is unsuccessful, you should correct any configuration errors and retry the test.
• If the JDBC driver you selected is not installed on the Administration Server, you should click Next to skip this step.
• Click Next to continue.
8. On the Select Targets page, select the servers or clusters on which you want to deploy the data source.
9. Click Finish to save the JDBC data source configuration and deploy the data source to the targets that you selected.
10. Perform steps 4-10 for the read-only user. The JNDI path for the user should be the same as previously entered, but with a _readonly appended at the end. Therefore, the default should be jdbc/intersys_readonly. Be sure to use the read-only user credentials that were created earlier (matching the ORACLE_READ_ONLY_USER variable in .nmsrc).
11. Perform steps 4-10 for the spatial database connection if your system uses spatial landbase in the Web Workspace Viewer. The JNDI path should be jdbc/spatial.
12. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Create a JMS Server in Your Domain
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the Administration Console, expand Services and then Messaging and then select JMS Servers.
3. On the Summary of JMS Servers page, click New.
Note: Once you create a JMS server, you cannot rename it. Instead, you must delete it and create another one that uses the new name.
4. On the Create a New JMS Server page:
• In Name, enter a name for the JMS server. For example: JMSServer-nms.
• In Persistent Store, leave this field set to none, then the JMS server will use the default file store that is automatically configured on each targeted server instance.
• Click Next to proceed to the targeting page.
5. On the Selects Targets page, select the server instance or migratable server target on which to deploy the JMS server.
6. Click Finish.
7. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Create a JMS System Module in Your Domain
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the Administration Console, under Services expand Messaging and select JMS Modules.
3. On the Summary of JMS Modules page, click New.
Note: Once you create a module, you cannot rename it. Instead, you must delete it and create another one that uses the new name.
4. On the Create JMS System Module page:
• In Name, enter a name for the JMS system module. For example: SystemModule-nms.
• Click Next to proceed to the targeting page.
5. On the Targets page, select the server instance or cluster target on which to deploy the JMS system module, and then click Next.
6. On the Add Resources page, select the checkbox to immediately add resources to the newly created JMS Module.
7. Click Finish.
8. On the Configuration page, click New above the Summary of Resources table.
9. On the Create a New JMS System Module Resource page, select Connection Factory from the list of JMS resources and then click Next.
10. On the Connection Factory Properties page, define the connection factory's basic properties:
• In Name, enter a name for the connection factory. For example: ConnectionFactory-nms.
Note: Once you create a connection factory, you cannot rename it. Instead, you must delete it and create another one that uses the new name.
• In JNDI Name, enter ConnectionFactory.
11. Click Next to proceed to the targeting page.
12. For basic default targeting, accept the default targets presented in the Targets box and click Finish. The configured connection factory is added to the module's Summary of Resources table, which displays its default targets.
13. On the Configuration page, click New above the Summary of Resources table.
14. On the Create a New JMS System Module Resource page, select Distributed Topic from the list of JMS resources, and then click Next.
15. On the JMS Distributed Destination Properties page, define the distributed topic's basic properties:
• In Name, enter a name for the distributed topic. For example: MsgBean-nms.
Note: Once you create a distributed topic, you cannot rename it. Instead, you must delete it and create another one that uses the new name.
• In JNDI Name, enter topic/MsgBean.
16. Click Next to proceed to the targeting page.
17. For basic default targeting, accept the default targets presented in the Targets box and then click Finish. The JMS system module resource is added to the module's Summary of Resources table, which displays its default targets.
18. On the Configuration page, click New above the Summary of Resources table.
19. On the Create a New JMS System Module Resource page, select Distributed Topic from the list of JMS resources, and then click Next.
20. On the JMS Distributed Destination Properties page, define the distributed topic's basic properties:
• In Name, enter a name for the distributed topic. For example: MsgRegister-nms.
Note: Once you create a distributed topic, you cannot rename it. Instead, you must delete it and create another one that uses the new name.
• In JNDI Name, enter topic/MsgRegister.
• Change the Forwarding policy to: Partitioned
21. Click Next to proceed to the targeting page.
22. For basic default targeting, accept the default targets presented in the Targets box and then click Finish. The JMS system module resource is added to the module's Summary of Resources table, which displays its default targets.To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure T3 Protocol
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the left pane of the Console, expand Environment and select Servers.
3. On the Servers page, click on the server name.
4. Select Protocols > General.
5. In the Maximum Message Size field, enter 50000000.
Note: These settings apply to all protocols in the server's default network configuration.
6. Click Save.
7. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure the Arguments to Use When Starting a Server in Your Domain
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the Administration Console, expand Environment and select Servers.
3. On the Servers page, click the name of the server.
4. Under Configuration, select Server Start tab.
5. Determine the amount of memory to set aside for WebLogic. This is set by the -Xms and ‑Xmx parameters. The -Xms is the amount that should be allocated at startup, and the ‑Xmx is the maximum amount it should use. To ensure that the maximum memory is allocated at start-up and eliminating the need for extra memory allocation during program execution, we recommend setting ‑Xms and ‑Xmx to the same value. We recommend aggressive maximum memory (heap) size of between 1/2 and 3/4 of physical memory. The minimum should be 4096m. In the example below, replace 4096m with the value you wish to configure.
6. On the Server Start page, add the following JVM parameters:
-Xms4096m
-Xmx4096m
-Dweblogic.system.StreamPoolSize=0
-XX:+UseG1GC
-javaagent:lib/nms_monitor.jar
-Djavax.xml.parsers.DocumentBuilderFactory= com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl
-Djava.awt.headless=true
-Dweblogic.jndi.allowGlobalResourceLookup=true
-Dweblogic.jndi.allowExternalAppLookup=true
-Doracle.xdkjava.security.resolveEntityDefault=false
-d64
-XX:+UnlockCommercialFeatures -XX:+FlightRecorder
Configure the location of the log4j configuration file by setting:
-Dlog4j.configurationFile=<fiull path to nms-log4j.xml>
If it is desired that the hostname be something other than what the operating system returns, add a startup flag to the app server:
-Dnms.servername=[server_name]
Replace [server_name] with the name you wish to log. Overriding the name may be helpful if multiple app servers are on the same machine.
If using a web map server to supply web maps to the web viewer, and if your WebLogic system requires a proxy server to access the external web map server, and if the system you are running WebLogic on does not have a system wide proxy server configuration, you will need to configure WebLogic to access the web map server using your network proxy server using the JVM start up parameters.
Note: See the Java SE Documentation for details on configuring the JVM for proxies.
Typically, to configure the JVM to use a proxy server, you will need to set JVM startup parameters:
• If the web map server uses http:
-Dhttp.proxyHost=proxy-hostname
-Dhttp.proxyPort=port#
-Dhttp.nonProxyHosts=
host1|host2|192.168.107.*|localhost|127.0.0.*
• If web map server uses https:
-Dhttp.proxyHost=proxy-hostname
-Dhttp.proxyPort=port#
-Dhttp.nonProxyHosts=
host1|host2|192.168.107.*|localhost|127.0.0.*
List the host names, IP addresses, or IP masks to any local system your JVM will need access to that does not require the proxy server. Be sure to include your local machine, DB system, and NMS core server system at a minimum. The nonProxyHosts lines cannot contain quotes or the managed server startup will fail.
Configuring Java Mail
There is a vast amount of information related to this on the web and under the WebLogic documentation. For a simple SMTP configuration, the following steps should be followed.
1. Log into WebLogic Administration Console.
2. In the Domain Structure tree at the center left, expand the Services node.
3. Select the Mail Sessions sub-node.
4. Click New.
5. For the JNDI Name, enter mail/nmsMail.
6. In the JavaMail Properties field, enter the following properties:
mail.smtp.port=25
mail.host=internal-mail-router.SomeDomain.com
mail.transport.protocol=smtp
Note: You will need to know the port, host and transport protocol of your mail option. For more information, see the WebLogic documentation.
7. Click Next and select the server for your NMS environment.
8. Click Finish.
9. The managed server will need to be restarted for the changes to properly take affect.
10. In your Java configuration, modify $NMS_CONFIG/jconfig/CentricityTool.properties:
# The protocol to send emails from the client. Valid entries
# are SMTP and MAPI. MAPI will bring up the default email
# client to send the email. SMTP will bring up a simple dialog
# from within NMS to send the email.
email_protocol = SMTP
11. In your Java configuration, modify $NMS_CONFIG/jconfig/server/CentricityServer.properties
# If SMTP is used instead of MAPI to send emails, this is the
# query to return the email address for a given username.
# This is also used by Web Switching for sending automated
# emails normally initiated via a sheet's state transition request.
# If an email_from value is not configured for automated switching # sheet emails, then the calling user's ID is used.
# This query can be used to translate a user ID to an email address.
# username_to_email = select ? || '@oracle.com' email from dual
Web Switching Singleton Service
The Web Switching Singleton Service is used to process Web Switching specific requests like creating Open and Close Miscellaneous Log steps for SCADA actions. It also processes model verification updates to steps that have been involved in model changes. (This service is disabled when the product Switching is not licensed.)
1. If you have a non-clustered project environment where multiple application servers are running, add the following command line argument for only the non-Web Switching instances:
-Dnms.disable-swman-static-service=true
Note: There must be only one server that is running Web Switching unless NMS is running on a WebLogic cluster.
2. Click Save.
3. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure Keystores
Before You Begin
• Obtain private keys and digital certificates from a reputable certificate authority such as Verisign, Inc. or Entrust.net.
• Create identity and trust keystores.
• Load the private keys and trusted CAs into the keystores.
Configure the Identity and Trust Keystores
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the left pane of the Console, expand Environment and select Servers.
3. Click the name of the server for which you want to configure the identity and trust keystores.
4. Under Configuration select Keystores.
5. In the Keystores field, select the method Custom Identity and Java Standard Trust for storing and managing private keys/digital certificate pairs and trusted CA certificates.
6. In the Identity section, define attributes for the identity keystore.
• Custom Identity Keystore: The fully qualified path to the identity keystore nms-ssl.keystore. This will be in the $NMS_HOME/java directory.
Note: if your WebLogic Server is running on a different server than the NMS installation, nms-ssl.keystore will need to be copied to a location where it is accessible to the account running WebLogic.
• Custom Identity Keystore Type: The type of the keystore. Generally, this attribute is Java KeyStore (JKS); if left blank, it defaults to JKS.
• Custom Identity Keystore Passphrase: The password you will enter when reading or writing to the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore so whether or not you define this property depends on the requirements of the keystore.
7. Click Save.
8. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure the SSL Listen Ports for a Server
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the Administration Console, expand Environment and select Servers.
3. On the Servers page, click the name of the server.
4. Under Configuration select General.
• Select SSL Listen Port Enabled so that the server listens on the SSL listen port.
• If you want to disable the non-SSL listen port so that the server listens only on the SSL listen port, deselect Listen Port Enabled.
5. Click Save.
6. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Configure SSL
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the left pane of the Console, expand Environment and select Servers.
3. Click the name of the server for which you want to configure SSL.
4. Under Configuration select SSL, and set the SSL attributes for the Private Key Alias (defaults to nms-key) and Private Key Passphrase.
5. Click Save.
6. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Set the Default Authenticator Control Flag
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the left pane, select Security Realms, then click the name of the realm you are configuring. Select myrealm.
3. Under Providers select Authentication.
The Authentication Providers table displays the name of the Authentication and Identity Assertion providers.
4. Click the name of the provider you want to configure. Select DefaultAuthenticator.
5. Under Configuration select Common and set the Control Flag to SUFFICIENT.
6. Click Save.
7. To activate these changes, in the Change Center click Activate Changes.
Create and Configure an Active Directory Authentication Provider
Note that any of the WebLogic Authentication Provider types can be used. Here, ActiveDirectoryAuthenticator is used as an example.
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. In the left pane, select Security Realms and click the name of the realm you are configuring (defaults to myrealm).
3. Under Providers select Authentication and click New.
The Create a New Authentication Provider page appears.
4. In the Name field, enter a name for the Authentication provider. For example, enter ldap-provider.
5. From the Type drop-down list, select the type of the Authentication provider and click OK. Select ActiveDirectoryAuthenticator.
6. Under Providers select Authentication and click the name of the new Authentication provider to complete its configuration.
7. Under Configuration select Common and set the Control Flag to SUFFICIENT.
8. Click Save.
9. Under Configuration select Provider Specific and set the desired values for your Active Directory server. The following configuration is given for example purposes only.
For Connection:
Host: server.example.com
Port: 389
Principal: cn=Administrator,cn=Users,dc=example,dc=com
Credential: The credential (usually a password) used to connect to the LDAP server.
For Users:
User Base DN: cn= Users,dc=example,dc=com
User Name Attribute: Ensure this matches the attribute specified in the User Base DN (for example, “cn”).
10. Click Save.
11. To activate these changes, in the Change Center, click Activate Changes.
12. After you finish configuring Authentication providers, restart WebLogic Server.
IMPORTANT: verify that users and groups from your authenticator are configured by looking at the Users and Groups tab for your security realm.
Configure Local LDAP
1. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
2. Under Domain, select [domain], Security, Embedded LDAP, and then select the Refresh Replica At Startup check box.
3. Click Save.
Deploying Oracle Utilities Network Management System in WebLogic Server
To deploy the Oracle Utilities Network Management System application in your domain, follow these steps:
1. Login in as the user account that will run the WebLogic Application Server.
2. Access the WebLogic Server Administration Console by entering the following URL:
http://hostname:port/console
Here hostname represents the DNS name or IP address of the Administration Server, and port represents the number of the port on which the Administration Server is listening for requests (port 7001 by default).
3. If you have not already done so, in the Administration Console Change Center, click Lock & Edit.
4. In the left pane of the Administration Console, select Deployments.
5. If there is a deployment from a previous installation, complete the following two actions before proceeding to step 6:
• Select the check box to the far left of the deployed cesejb application. Click Stop and choose Force Stop Now to stop the application.
• Select the check box to the left of the deployed cesejb application. Click Delete (located at the top or bottom of the Deployments table), to delete the cesejb application. Click Yes to confirm your decision.
6. In the right pane, click Install.
7. In the Install Application Assistant, locate the cesejb.ear to install. This will be in the $NMS_HOME/java/deploy directory.
8. Click Next.
9. Specify that you want to target the installation as an application.
10. Click Next.
11. Select the servers and/or cluster to which you want to deploy the application. The cesejb.ear should be deployed to its own managed server or cluster; therefore, either select a managed server/cluster that does not have other applications or interfaces deployed to it or move existing deployments to a separate instance.
Note: If you have not created additional Managed Servers or clusters, you will not see this assistant page.
12. Click Next.
13. Update the following additional deployment setting:
• Change the deployed name of the application from cesejb to something unique.
14. Click Next.
15. Review the configuration settings you have specified, and click Finish to complete the installation.
16. If you chose to immediately go to the deployment's configuration screen, click the tabs to set additional configuration settings for the application or module.
If you chose to change this information later, you are returned to the Deployments table, which now includes your newly-installed application or module.
17. To activate these changes, in the Administration Console Change Center, click Activate Changes.
Note: Ensure that your deployment is listed as “Active” in the deployments table. If it is “New” or “Prepared,” something has not started correctly.
18. A restart of the WebLogic managed server(s) that will be running Oracle Utilities Network Management System is not required for these changes to take effect unless you are instructed to do so at this time.
19. Open a browser and navigate to: http://hostname:port/nms
Here hostname represents the DNS name or IP address, and port represents the port for the WebLogic Server.
Troubleshooting
1. If there are deployment issues and you want to validate the connection to the CORBA gateway, open the WebLogic log file, which will display diagnostic information including any issues with the database and CORBA gateway configuration.
2. Performance issues: Some WebLogic default parameter settings are not optimal for a significant production NMS installation. Below are some options NMS has successfully deployed to make WebLogic more responsive and resilient. Values provided are representative but should not be considered definitive – variations may be appropriate for your installation.
WebLogic Managed Server Specific Changes
1. On the left, click Environment > Servers
2. Click the managed server name
3. Click the Server Start tab
4. Add the option below to the Arguments (server startup options) field:
• -Dweblogic.security.providers.authentication.ldap.socketTimeout=3
• Specifies the maximum number of seconds to wait for the connection to any one host specified in the Host attribute.
• Default=0 which sets no socket timeout
5. Click the Save button.
6. Restart the managed server for this change to take effect, but wait to restart until after you have made any other potential LDAP Provider Changes noted below.
7. Repeat this process for any other managed server
LDAP Provider Setting Changes
NOTE: These changes will affect all managed servers within a given WebLogic domain.
The default LDAP cache within WebLogic may be disabled or too small. Timeouts may be disabled for accessing an LDAP server and maybe inappropriate for accessing a replicated LDAP server environment (some form of replicated Active Directory access – for example). Modify default values by completing the following steps in the WebLogic Server Administration Console:
1. Select the Provider Specific page for the LDAP Authentication provider
• Security Realms > myrealm > Providers > Authentication > your LDAP Authentication provider > Provider Specific
2. Scroll down to the General section
3. Suggest the following (or similar) changes:
• Set "Change Connect Timeout" to 10.
• Maximum time in seconds to wait for the connection to the LDAP server to be established.
• Default=0 which means no maximum time limit.
Most production NMS installations will have an alternate LDAP server if the primary is not responding.
• Change "Parallel Connect Delay" to 1
• Delay in seconds when making concurrent attempts to connect to multiple LDAP servers.
• Default=0 which means it will not retry if there is no response.
• Change "Results Time Limit" to 1000
• The maximum number of milliseconds for the LDAP server to wait for results before timing out.
• Default=0 which means wait indefinitely.
• Make sure "Cache Enabled" is checked
• Specifies whether a cache is used with the LDAP server
• Default is enabled.
• Change "Cache Size" to 4096KB
• Size of the cache (in kilobytes) that is used with the LDAP server
• Default=32KB
• Change "Cache TTL" to 3600 seconds ( 1 hour )
• Time-to-live for cache (in seconds) used with the LDAP server
Every WebLogic access from an NMS client is authenticated – not just the initial login. The result of this authentication can be cached to reduce load on an external LDAP server but (by default for peak security) this cache is very modest. The default configuration can result in a significant authentication load on your LDAP servers under peak (NMS user count) and load.
Values from 1 to 4 hours are suggested for consideration.
• Default is 60 seconds
• Click the Save button.
4. At the top of the page, click on the "Performance" tab.
• Change "Group Hierarchy Cache TTL" to match the "Cache TTL" value above.
• Maximum number of seconds a group membership hierarchy entry is valid in the LRU cache.
• Default is 60 seconds.
• Click the Save button.
5. Restart the WebLogic Managed Server (full domain) for changes to take effect.
Installing Flex Operations
The Flex Operations browser client uses the same architecture as the Operations Mobile Application (OMA). If you are licensed for both applications, just follow the full installation instructions from the Oracle Utilities Network Management System Operations Mobile Application Installation & Deployment Guide to set up both applications. If you are only licensed for Flex Operations, follow the instructions below:
• Mobile Gateway Server Installation
• Deploy the Mobile Gateway
• Configuring WebLogic to Handle HTTP Basic Challenges Correctly
• NMS Server Configuration
• GeoJSON Map Generation
• Configuring OMA Object Attribute Viewer
• Configuring OMA For Schematic Maps
• Configuring OMA Search Options
• Operations Mobile Application Project Setup
• The entire chapter
Authenticating Flex Operations Users
Flex can be configured to either authenticate a user by the configured LDAP provider that is running the Flex Operations gateway (nms-ws.ear) or by the server that is running cesejb.ear. The default is cesejb.ear. This is controlled by setting the following parameter in WebService.properties:
# Where Flex clients should be authenticate. The choices are
# cesejb and nms-ws
authenticate = cesejb
Please note that even if the Flex user is configured in the
nms-ws domain, the role configuration still must be configured in the domain running
cesejb.ear. (See
“NMS Roles to Groups Mapping” for information.)
Installing Web Clients
The Oracle Utilities Network Management System Web Clients may be run from a browser as a Java Web Start application or by installing individual Java client applications.
Allowlisting
The following are executables and libraries that are part of the application that may need to be added to allowlists by anti-virus software:
• MapiSend.exe
• msvcp71.dll
• msvcr71.dll
• SendSignal.exe
• SendSignal64.exe
• ShellExecute.exe
They will be installed in %APPDATA%\Roaming\.nms\exe
Java Web Start
If the Java Web Start version is chosen, there is no client installer needed. The user opens the NMS application landing page and clicks a link to one of the Java applications, such as Web Workspace.
Example
URL: https://[web-gateway]/nms/
Web Workspace Java Web Start link:
https://[web-gateway]/nms/nmswebstart?appName=WebSwitching.jnlp
Java Client Installation
The Java client applications installer is created by the Oracle Utilities Network Management System Configuration Assistant, which is also a Java application. Therefore, to create the installer, the Configuration Assistant must be run (at least once) using Java Web Start.
Install Prerequisite Software
The client installer creation process requires the following applications be pre-installed on the PC that will run the Configuration Assistant.
• NSIS (Nullsoft Scriptable Install System) is an open-source Windows installer development tool; project on SourceForge (http://sourceforge.net/projects/nsis/).
• Launch4j is a tool that wraps Java applications in a Windows executable file; available on SourceForge (http://launch4j.sourceforge.net/).
• Java Standard Edition JDK. This should match the version you wish to include as part of the client installation. Normally you would choose the latest JDK. (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
Note: see the Oracle Utilities Network Management System Quick Install Guide for supported software versions.
Create Environment Variables
1. Create the following system environment variables, as necessary, to ensure that the Configuration Assistant can find the applications.
• NSIS Environment Variable
Name: NSIS_HOME
Value: Path to NSIS.exe.
Note: If NSIS was installed in the default location, the environment variable does not need to be added.
• Launch4j Environment Variable
Name: LAUNCH4J_HOME
Value: Path to launch4j.exe.
Note: If Launch4J was installed in the default location, the environment variable does not need to be added.
• JDK Environment Variable
Name: JAVA_HOME
Value: Path to the root of the JDK (where the jre and bin subfolders are located).
2. After setting the environment variables, reboot your PC.
Create Installer
To create the installer, open Configuration Assistant and do the following:
1. Select Create Client Installer... from the Actions menu.
A save dialog will open that allows you to modify the file name and location; neither the name nor location will affect how the applications are ultimately installed.
2. Click Save.
Note: if the file already exists at that location, you will be asked to confirm replacement.
3. The client installer creation process will call NSIS, which will open and display a log of its activities in the MakeNSISW window. When the process is complete, NSIS will allow you to run the installer (using the Test Installer function) or Close the application.
Install Client Applications
1. If MakeNSISW is still open, click Test Installer to run the client installer. If it is not open, navigate to the location where the installer was saved and double-click the installer file name or icon (depending on your view). The Oracle Utilities NMS Setup Wizard dialog will open.
2. On the Choose Install Location page, select the destination folder and click Next.
3. On the Choose Components page, select the components to install from the list of licensed products. Click Install.
4. When the installation is complete, click Close.
Note: Start menu application shortcuts will be created under All Programs in the Oracle Utilities NMS folder.
Updating Clients
Client installers must be recreated whenever a new release (major release, service pack, or patch) is implemented.
1. Uninstall the existing applications from each client PC.
2. Follow the “Create Installer” task using the updated Configuration Assistant.
3. Follow the “Install Client Applications” task.
Deploying Patch Bundles
Steps to Deploy a Patch Bundle in Dual-Environment Configuration
This section describes the general steps for deploying a patch bundle in dual-environment configuration. This involves two NMS Administrative Users:
• Active – the user where NMS is currently running
• Staging – the user where this patch bundle will be installed
Each of these users has a corresponding WebLogic managed server. These will be called the Active managed server and Staging managed server.
All steps are to be performed on the Staging user unless otherwise noted.
Note: See the README.txt that comes with the patch bundle for specific instructions.
1. Take note of the changes for this patch as documented in the Product Fix Design document(s). This patch may require a manual migration.
2. Identify which administrative user is staging. This command will output "A" for the active user and "S" or "None" for the staging user.
$ nms-version --get-stage
3. If you are deploying this to production, copy the new configuration and manual migrations to the production server.
4. Log in as the NMS Administrative User that is staging (for example, nmsadmin2).
5. Remove the previous installation directory, if one exists.
$ cd ~
$ rm -rf network
6. Unzip the nms.<version>-date-platform.zip file found within the downloaded zip file.
$ unzip nms.<version>-date-platform.zip
7. Run the install script.
$ cd network
$ ./nms-install
Note: If you have not created an /etc/nmstab file, add the ‑noNmsTab option to nms-install.
8. Remove the installation files before continuing.
$ cd ~
$ rm -rf network
9. Stop any running services and Isis.
$ sms-stop -aiS
10. Run nms-install-config.
$ nms-install-config
11. Start nms-setup.
Note: You can continue to the next step without waiting for this to finish.
$ nms-setup
12. Undeploy the old ear from the Staging managed server.
13. Restart the Staging managed server.
14. Complete Steps 1 - 19 in Deploying Oracle Utilities Network Management System in WebLogic Server on page 3-30 for the Staging managed server.
15. Wait for nms-setup to complete.
16. Verify that nms-setup succeeded. If there are manual migrations that were missed, the setup will stop. If so, complete any manual migrations and try again starting at step 9.
17. On the Active Administrative User, force users out of the system
Action any.pub* ejb enable_login false
18. On the Active Administrative User
Note: You can continue to the next step without waiting for this to finish.
19. Stop the Active Managed Server, stop any running services and Isis.
$ sms-stop -aiS
Note: You can continue to the next step without waiting for this to finish.
20. On the Staging Administrative User, run nms-post-setup
$ nms-post-setup
21. Re-start services. The Staging environment has become the new Active environment.
$ sms-start
Users will be able to log into the system shortly after sms-start finishes.
Steps to Deploy a Patch Bundle Without Dual-Environment Configuration
This section describes the general steps for deploying a patch bundle.
Note: See the README.txt that comes with the patch bundle for specific instructions.
1. Take note of the changes for this patch as documented in the Product Fix Design document(s). This patch may require a manual migration.
2. If you are deploying this to production, copy the new configuration and manual migrations to the production server.
3. Log in as the NMS Administrative User (for example, nmsadmin).
4. Remove the previous installation directory, if one exists.
$ cd ~
$ rm -rf network
5. Unzip the nms.[version]-date-platform.zip file found within the downloaded zip file.
$ unzip nms.[version]-date-platform.zip
6. Run the install script.
$ cd network
$ ./nms-install
Note: If you have not created an /etc/nmstab file, add the ‑noNmsTab option to the nms-install command.
7. Remove the installation files before continuing.
$ cd ~
$ rm -rf network
8. Force users out of the system.
Action any.pub* ejb enable_login false
9. Stop any running services and Isis.
$ sms‑stop -aiS
10. Run nms-install-config.
$ nms-install-config
11. Start nms-setup with the -post option.
Note: You can continue to the next step without waiting for this to finish.
$ nms-setup -post
12. Undeploy the old ear.
13. Restart the managed server.
15. Wait for nms-setup to complete.
16. Verify that nms-setup succeeded. If there are manual migrations that were missed, the setup will stop. If so, complete any manual migrations and try again starting at step 8.
17. Re-start services.
$ sms-start
Users will be able to log into the system shortly after sms-start finishes.
Steps to Deploy a Patch Bundle using Failover Patching
This section describes the general steps for deploying an NMS patch bundle using failover patching. This patches an NMS environment on a separate site while users are live at the original site. For this section, environment #1 on Site A is active with live users. The patch will be applied on environment #2 at Site B. In practice, the environment numbers may be swapped. If so then change these steps accordingly.
Prerequisites:
• Two or more NMS sites configured for failover patching as described in the Site Guard chapter of the Configuration Guide.
• Dual-environment configuration on all sites.
• Oracle Flashback Database must be enabled in Oracle RDBMS.
• NMS previously installed and configured at Site B.
• SSH password-less login must be enabled between the NMS servers on Site A and Site B.
All steps are to be performed on the NMS staging (non-active) environment unless otherwise noted.
Note: See the README.txt that comes with the patch bundle for specific instructions.
1. Take note of the changes for the patch as documented in the Product Fix Design document(s). Any given patch may require one or more specific manual migrations.
2. On Site A, identify which administrative user is the staging environment (where the NMS patch will be applied). The command below will output “A” for the Active NMS administrative user environment and “S” or “None” for the Staging NMS administrative environment.
$ nms-version –-get-stage
3. If you are deploying to production, copy the new configuration and manual migrations to the NMS staging user environment of Site A.
4. On Site A, log in as the NMS Administrative User that is staging (for example, nmsadmin2).
5. Remove the previous installation directory, if one exists.
$ cd ~
$ rm -rf network
6. Unzip the nms.<version>-date-platform.zip file found within the downloaded zip file.
$ unzip nms.<version>-date-platform.zip
7. Run the install script.
$ cd network
$ ./nms-install
Note: If you have not already created an /etc/nmstab file, add the -noNmsTab option to nms-install.
8. Remove the installation files before continuing (recommended).
$ cd ~
$ rm -rf network
9. Stop any running services and the Isis message bus.
$ sms-stop -aiS
10. Run nms-install-config.
$ nms-install-config
11. Start nms-setup.
$ nms-setup
12. Verify that nms-setup succeeded. If there are manual migrations that were missed, the setup will stop. If so, complete any manual migrations and try again starting at step 9.
13. Login as the staging user on Site B and stop NMS services and the Isis message bus there.
sms-stop -aiS
14. Logout from the staging user at Site B.
15. Undeploy the old ear from the Staging managed server at both Site A and Site B.
16. On Site A, logged in as the NMS Staging administrative user, run nms-sync-site to sync the patch to Site B.
$ nms-sync-site patch site-b.example.com
17. In Oracle Enterprise Manager, open the Generic System for Site A.
18. Select the menu item Generic System -> Site Guard -> Operations.
19. Select the operation plan for upgrading Site B and click Execute Operation.
20. Click Yes.
21. Click on the link to the procedure to follow the progress. This procedure performs the following steps.
• Create a guaranteed restore point on the Site A RDBMS.
• Transition all NMS end users at Site A (as a group) to Read Only mode.
• Failover RDBMS from Site A to Site B.
Note this is different than an RDBMS Switchover. In failover mode both RDBMS instances (one at each site) end up as operationally independent read/write RDBMS instances. At this point RDBMS transactions at one site will NOT automatically be propagated to the other site.
• Start WebLogic Node Manager and AdminServer at Site B.
22. On Site B run the post setup script with the NMS_MODEL_SOURCE environment variable unset.
Note: You can continue to the next step without waiting for this to finish.
$ NMS_MODEL_SOURCE= nms-post-setup
23. On Site B, run nms-install-config for Java.
$ nms-install-config –-java
24. Complete Steps 1 - 19 in Deploying Oracle Utilities Network Management System in WebLogic Server on page 3-29 for the Staging managed server on Site B.
25. Wait for nms-post-setup to complete.
26. Re-start services. The Staging environment on Site B is now active.
$ sms-start
27. Optional: If desired, the environment on Site B can be validated, and then reset back to the current state.
• Login with the sysdba role on the Site B database and create a guaranteed restore point. Any unique name can be chosen for this restore point (two restore points cannot have the same name).
SQL> create restore point "VALIDATE_NMS" guarantee flashback database;
• Perform core/smoke/sanity tests to validate patch properly installed on Site B.
• Once validated, stop NMS services and WebLogic managed server.
$ sms-stop -a
$ nms-wls-control stop
• Login with the sysdba role on the Site B database and rollback the database to the guaranteed restore point that was set above. Recommend dropping the restore point at the end so the name of the restore point can be recycled when applying the next patch – not required.
SQL> shutdown immediate;
SQL> startup mount;
SQL> flashback database to restore point "VALIDATE_NMS";
SQL> shutdown immediate;
SQL> startup;
SQL> drop restore point "VALIDATE_NMS";
• Start NMS services and WebLogic NMS managed server.
$ sms-start
$ nms-wls-control start
28. Route relevant external adapters (integrations) to Site B. This will be different for each adapter.
29. Inform users to logout from NMS at site A and login to NMS at site B. This can be done in OEM via the Send Message button in the Application Management Pack for Oracle Utilities NMS or on the command-line with an Action command:
$ Action -java any.any display_oem_message "Login to upgraded NMS at site-b"
• Login to the active environment and site A. Stop NMS services and WebLogic managed server
$ sms-stop -aiS
$ nms-wls-control stop
30. Reinstate the database at Site A as standby. This can be done from Oracle Enterprise Manager with the following steps:
• In Oracle Enterprise Manager, open the database instance for Site B.
• Select the menu item Availability -> Data Guard Administration.
• Click on the Database must be reinstated link in the Data Guard Status for the Site A database.
• Click Reinstate.
• Click Yes on the Confirmation screen.
• Choose the Database Host Credentials and click Continue.
31. Login with the sysdba role on the Site A database and drop the guaranteed restore point created by Site Guard
SQL> drop restore point "BEFORE_PATCH_NMS";
32. At this point, the active environment and the staging environment have switched at all sites. The remaining steps are performed in the active environment at the various sites.
33. On Site B, run nms-sync-site to sync the patch to Site A and any other configured sites.
$ nms-sync-site patch site-a.example.com
$ nms-sync-site patch site-c.example.com
34. At each site other than Site B, perform the following steps
• Run nms-install-config for Java to generate an NMS EJB deployment that matches the current patch.
$ nms-install-config –-java