Nectar Foundation APM Installation Guide

Overview

This guide explains how to install, upgrade, and uninstall Nectar Foundation.

Note

For additional information, contact Nectar Support at support@nectarcorp.com.

For information on onboarding a particular module (RIG > Module Configuration), refer to the configuration guide for that module.

To provide feedback on Nectar documentation, email:

documentation@nectarcorp.com

This section discusses the following:

• Technical Notes
• General Data Protection Regulation
• System Requirements
• Important Notes
• Installer Log
• Installation History
• Installation Path and Service Names with Stacking

System Requirements

This section provides the following system requirements:

• Operating System
• System Architecture
• Memory
• Disk Space

Operating System

The installers are supported on the following operating systems:

Table 1-1 Supported Operating Systems

System Architecture

The installers can be used to install a 64-bit system.

Windows

For Windows, the installer requires a 64-bit system.

Linux

For Linux, the installers require a 64-bit system, as the bundled JREs are 64-bit.

Memory

The installer validates system memory based on the installation type:

Table 1-2 Memory

Disk Space

The Windows and Linux installers are both self-extracting (SFX) archives. You must consider the following disk space requirements:

• Size of the installer file, which is run to perform the installation:

Windows - .exe file

Linux - .bin file

• Size of the content extracted by the installer file (which is run to perform the installation)
• Size of the installation on disk

The following table provides the recommended free disk space requirements:

Additional Notes:

Table 1-3 Free Disk Space Requirements

• In the default locations for deployed installer and default locations for actual installations:
  • denotes a partner-specific value. Default value is nectar, but may vary with branding installers.
  • denotes the version of the installer, such as 8.6.
• The Program Files (x86)directory in the Windows default location is for a 64-bit system.
• Nectar Foundation for Windows does not remove the deployed installer files after execution of the installer.
• Location must also be taken into account, for example:

When installing a Windows 64-bit RIG on a 64-bit Windows system, all installer-related files are stored on the C drive, such as:

• 
  
  • Installer executable is uploaded to the desktop in the following folder:

C:\Users\

• 
  
  • Windows installer deploys to the following folder:

C:\Program Files (x86)\Common Files\UCF\

• 
  
  • Installation is installed to the following folder:

C:\Apps\

At least 1.35GB of disk space is required to complete the installation

• These numbers are minimums based on the largest installer file size, its content, and the resulting installation. These numbers are rounded up slightly from those values. The required size for any installer-related file may be less than these recommended values. However, these values are safe.
• On Windows, if the installer fails to extract, check free space on the drive represented by the value of the %COMMONPROGRAMFILES(x86)% environment variable. On Linux, check the free space on the disk associated with folder /opt/support. If sufficient free space is unavailable, then efforts should be taken to clean up the system.
• Table 1-3 shows the recommended free space for a new installation. This is only the free space required to complete the installation. It does not account for the free space required for database content that may increase over time. Make sure to have additional free space on the installation drive to account for use over time.
• An upgrade uses additional space in the installation directory. It copies any upgraded files to the rollback directory during the upgrade. As a rule, the same recommended free space values for an installation apply to upgrades.

Important Notes

Restrict Older Versions of TLS on Nectar Foundation

This procedure can be applied to a RIG, EIP, CIP (Farm or Wayside), or Backup server. The following configuration disables both TLS v1.0 and TLS v1.1 as well as less secure digest and cypher algorithms for use in high-security environments. Make sure that you restart the service after making these changes.

For JRE 1.7.0:

Modify specified properties in the jre/lib/security/java.security configuration file of the server being configured as follows:

jdk.certpath.disabledAlgorithms=MD2, MD5, RSA keySize < 1024, DSA keySize < 1024 jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, MD5withRSA, \

RSA keySize < 2048, DSA keySize < 2048, DH keySize < 2048, \ RC4, 3DES_EDE_CBC, DES40_CBC, SHA1

For JRE 1.8.0:

Modify specified properties in the jre/lib/security/java.security configuration file of the server being configured as follows:

jdk.certpath.disabledAlgorithms=MD2, MD5, SHA1 jdkCA & usage TLSServer, \ RSA keySize < 1024, DSA keySize < 1024, EC keySize < 224

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, MD5withRSA, \ RSA keySize < 2048, DSA keySize < 2048, DH keySize < 2048, \

EC keySize < 224, RC4, 3DES_EDE_CBC, DES40_CBC, SHA1, anon, NULL

Modify the rigWrapper.properties file as follows:

additional.1 = -Djdk.tls.ephemeralDHKeySize=2048

Note

Use the next available number for the above property index.

How to Enable Older Versions of TLS

Starting with OpenJDK runtime 1.8.0_292 included with release 2021.1, configuration file jre/lib/security/java.security includes settings to disable TLS v1.0 and TLS v1.1 by default.

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, \

    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \

    include jdk.disabled.namedCurves

In order to enable corresponding version of TLS one needs to remove the respective algorithm name from the list shown above and restart the RIG.

Microsoft SQL Server Configuration

Prior to Release 5.6.2, MicrosoftS SQL Server was configured in the server.properties file as follows:

mssql.location = 10.65.128.111

mssql.port = 1433 mssql.dbname = testDB mssql.username = testRIG mssql.password = testPass

Beginning with Release 5.6.2, it is configured in application.properties file as follows:

#SQL Server

datasource.sqlserver.url=jdbc:sqlserver:10.65.128.111:1433;databaseName=testDB datasource.sqlserver.username=testRIG

datasource.sqlserver.password=testPass datasource.sqlserver.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver datasource.sqlserver.max-active=10000

datasource.sqlserver.min-idle=10 datasource.sqlserver.idle-timeout-millis=10000 datasource.sqlserver.customProperties=

Upgrade to Release 7.x

For Cisco deployments, you must offboard any server configurations before upgrading to v7.0. For more information on offboarding, see Cisco UCM VKM Configuration Guide.

When the Installer detects the Cisco UCM VKM module, it will display a warning message, informing the user to offboard any systems before completing the upgrade. Once the Cisco UCM system(s) have been offboarded, you can re-run the upgrade process and select the CUCM Override to complete the upgrade.

This is not required when upgrading from one 7.x release to another.

Reboot after Upgrade - Windows

A reboot must be performed following an upgrade when:

• Upgrading a RIG or IPOffice.
• Upgrading a PA.

Note

Failure to perform the recommended reboot may result in one of the following not starting:

• RIG service (RIG or IPOffice)
• Transponder process (PA)

However, the required reboot is only applicable to the main service. A reboot is not

required when upgrading the backup service.

Upgrade Backup Server - Windows and Linux

Beginning with Release 6.0, it is recommended to upgrade the backup service to v5.5.4, which is the default version for that release. This is necessary for security enhancements required for connection to a CIP or EIP.

Database Mode - Windows and Linux

By default, the database for an installation is configured in Embedded mode, which means only the RIG service can access it. In order for external access to occur, the database must be configured in Network mode. The installer can perform this configuration change automatically.

When installing a new installation, the database mode will be selectable during the installation. It defaults to embedded mode, but can be set to be installed in Network mode

When upgrading, the installer analyzes the existing installation. If it finds that the installation's database is already in Network mode, then there is no prompting for the database mode. If it finds that the installation's database is in Embedded mode, then the database mode will be selectable. It defaults to Embedded, unless ciscoUCM or lyncModule is detected in the installation's etc/server.properties file.

Note

Database mode conversion is one-way. The default is Embedded mode, and the installer can convert it to Network mode, as described above. It cannot convert it to Embedded mode from Network mode.

GUI Default Mode - Windows and Linux

The default mode of the installer is GUI. The installer performs checks to ensure a display is available. If it does not detect a display, output is displayed on the command line, indicating no display was found. The installer should be executed in Silent mode.

On Windows, typically there is always a display.

On Linux, a typical installation may be performed through a headless console, e.g., through an SSH connection. In this scenario, execution of the Linux installer file should successfully deploy the installer under /opt/support, but will subsequently fail, indicate no display is detected, and to use Silent mode to proceed.

If the Linux installer is executed through a terminal window in a Linux desktop environment, the display should be detected, and the installer should successfully launch in GUI mode.

Parameter and Launch Errors - Windows and Linux

Error output is provided by the installer. For example, for issues with parameters used or their values, or if a display is not detected, the installer outputs error text.

However, this error text may not be visible, depending on how the installer was launched:

• Under Windows, no output is visible when launching the installer exe file directly, even when executed from a Command Prompt. This is due to the installer being a 7 Zip self-extracting archive. The installer itself is automatically run by 7 Zip after the archive is deployed, but its output is never passed to the command line. If launched in this way and the installer never appears, check the log file for errors.
• To see direct command output under Windows, the installer must be executed using the

installer.bat file deployed with the installer.

• Under Linux, command output should always be visible in a shell, whether the installer was launched from the executable BIN file, or from the bundled installer.sh script deployed with the installer.

One PA Installation Supported - Windows and Linux

Only one PA instance is supported on a system.

Note

While the installer does not enforce this rule, no more than one PA installation should be installed on a system.

Installer Log

The installer logs activity to a file, which provides a record of the installer history. This file can be used when installation problems occur.

• The Windows log is located at - C:\Program Files (x86)\Common Files\UCF\ucf_

• The Linux log is located at /var/log/ucf_.

The default value for is nectar, but may vary in branded partner installers.

Installation History

The installer maintains an installation history file specific to each installation. This is useful as a record of installer actions performed against a specific installation.

The installation history file is called install_history.txt and is located in the actual installation directory of each Nectar Foundation installation.

Installation Path and Service Names with Stacking

The installer is bundled with properties that describe the default installation path and service names and descriptions. For a non-branded installer, the defaults are:

• Install Location
  • Windows:C:/Apps/nectar
  • Linux:/opt/ucf/nectar
• Main Service Name:NectarRIG
• Main Service Description:Nectar RIG Server
• Backup Service Name:NectarRIGBackup
• Backup Service Description: Nectar RIG Backup

Note

When installing on a system for the first time (no other Nectar Foundation installations exist), the installer assumes these values (assuming they are not modified by the user).

When stacking or installing additional instances of Nectar Foundation, the installer ensures that there are no conflicts with the new installation location and service name/description values, and those of any existing installations. The method it employs to ensure there are no conflicts is very simple:

• If any of the new installation location and/or service name/description values conflict with the values of any existing installation, it appends _2 or 2 to the default installation location and service name/description values to get a new set of installation location and service name/description values.
• This process is repeated, using _3 or 3, _4 or 4, etc., until no conflicts are detected with any of the incremented installation location and service name/description values.

Preparation and Execution

Preparation and execution provides the following:

• Installer Files
• Upload Installer File
• Execution

Installer Files

Installer File Naming Convention

The installer files follow a common naming convention as follows:

The components of the installer file names are:

Note

The installer files depicted throughout this guide are examples. Make sure the correct file is selected for upload, based on the desired platform and product version.

In addition, previous installers used the product acronym, CMP, and more current files use the product acronym, UCF.

Windows

A standard RIG installation also installs IPOffice and PA.

In GUI mode, when the installer is executed, there is a Type selection for RIG and PA. By default, it is pre-selected for RIG. In silent mode, the default type is RIG, but can be set using the -t/--type option.

The installer file is a 7Zip SFX archive file that automatically runs the Nectar Foundation installer once extracted.

Linux

In GUI mode, when the Linux installer is executed, there is a Type selection for RIG and PA. By default, it will be pre-selected for RIG. In silent mode, the default type is RIG, but can be set using the -t/--type option.

The installer file is a self-extracting script archive that automatically runs the Nectar Foundation installer once extracted.

Upload Installer File

Before performing an installation, the installer file must be uploaded to the target system.

• If there is no existing Nectar installation, the file must be transferred using any available file transfer mechanism, e.g., FTP/SFTP, SCP, etc.
• If there is an existing Nectar installation, then it is possible to transfer the file using the Nectar Foundation Client File Manager. For information on how to use the File Manager, see RIG Administration Guide.

While the files can be uploaded anywhere on the target systems, it is recommended to upload to the user’s Desktop directory, e.g., C:\Users\Administrator\Desktop, or C:\Apps on Windows, and to /tmp or /opt/support on Linux. It is recommended to not upload the installer file to an actual installation directory, e.g., C:\Apps\nectar on Windows or /opt/ucf/nectar on Linux.

Execution

Installer File - Windows

Follow these steps to perform a GUI installation:

1. Open Windows Explorer and navigate to the location where the installer file was uploaded.
2. Right-click on the installer file and select Run as Administrator to execute the installer with administrative privileges.

Figure 2-1 Run As Administrator

The installer extracts the installation files; then runs the extracted installer file.

Figure 2-2 Extracting

From this point, the installer executes in GUI mode, displaying the License dialog after successfully initializing.

Installer File - Linux

Follow these steps to perform a Linux installation:

1. SSH to the Linux system onto which the installer was uploaded, or open a terminal window, if running a desktop environment.
2. Navigate to the location where the installer was uploaded.
3. Make sure installer is executable, for example:

[root@centos-70-01]# chmod 755 NECTAR-UCF-Linux-8.6.bin

1. Execute the installer, for example:

[root@centos-70-01]# ./NECTAR-UCF-Linux-8.6.bin

The installer deploys the installation files; then runs the deployed installer.

Note

If the installer reports an error that it is unable to detect a display, then change the directory to the location to which the installer deployed using the installer.sh script to execute in silent mode.

Installer Script - Windows and Linux

For both Windows and Linux, execution of the installer file deploys the installer files to a pre- determined location. Once it is deployed, it is not necessary to run the installer file again.

Navigate to the location where the installer was deployed, and use one of the following to run the Installer:

• installer.bat (Windows)
• installer.sh (Linux)

This script can be used to launch the installer in GUI (default) mode or to perform silent installations.

Downgrades

The installer can be used to perform downgrades. Downgrades are effectively performed by upgrading, but selecting/specifying the Version override. There are limitations to downgrading.

Perform Installation

Installation provides the following:

• GUI Installation
• Silent Installations

Note

The same installer is used for Windows and Linux. Although the dialog images shown were captured on a Windows system, the Linux dialogs are essentially the same, providing the same content.

Following a successful installation:

• Proceed to the RIG Administration Guide to access and administer the newly installed RIG.
• Proceed to the Perspective Administration and User Guide to access and administer the newly installed PA.

GUI Installation

Follow these steps to perform a GUI installation:

1. Launch the installer in GUI mode using one of the following:
   • installer exe file (Windows)
   • installer.bat script (Windows)
   • installer bin file (Linux)
   • installer.sh script (Linux)

Figure 3-1 Launch the Installer

1. When the Nectar End User License Agreement - Disclaimer window appears, read to the bottom of the license text; then click Accept.

Figure 3-2 License Agreement

The Enter/Select Target Installation Directory and Service Data window appears.

1. Accept default values or modify the installation data, as needed.
   • Perform a New Install (select, if displayed)
   • Installation Directory
   • Main Service Name
   • Main Service Description
   • Backup Service Name
   • Backup Service Description
   • Installation Type: RIG (default) or PA

View the following example in Figure 3-3.

Figure 3-3 New Installation

Note

If you attempt to perform a new installation and one or more existing installations are present (see Figure 3-4), the installation fields appear in the upper area of the window and the existing installation(s) are listed in the lower area.

An example of this would be when you want to install more than one RIG on the same server. In this case, you will have an existing installation(s), while you are performing a new installation.

If you want to upgrade an existing RIG, see Perform Upgrades for more information.

Figure 3-4 New Installation with an Existing Installation

Note

If there is a need to keep the services from starting as part of the installation, un-check the Start Services check box (see Figure 3-4).

To enable the Advanced configuration options, select the Advanced check box (see Figure 3-4).

1. Click Next.
2. Perform one of the following:
   • For a RIG installation without selecting the Advanced check box, go to Step 6.
   • For a RIG installation with the Advanced check box selected, go to Step 7.
   • For a PA installation without selecting the Advanced check box, go to Step 8.
   • For a PA installation with the Advanced check box selected, go to Step 9.
3. For a RIG installation without selecting the Advanced check box:
4. Modify prompted information, as needed:

Figure 3-5 Un-Checked Advanced - RIG

Note

By default, the installer assumes that the database should be installed in

Embedded mode.

To install database in Network mode, select the Network database mode radio button. This enables the Database Port field, which can then be modified, as needed.

1. Click Next.
2. Confirm installation information:

Figure 3-6 Confirm Install

1. Click Install.
2. Proceed to Step 10.
3. For a RIG installation with the Advanced check box selected:
4. Modify prompted information, as needed:

Figure 3-7 Checked Advanced - RIG

Note

By default, the installer assumes that the database should be installed in

Embedded mode.

To install database in Network mode, select the Network database mode radio button. This enables the Database Port field, which can then be modified, as needed.

1. Click Next.
2. Confirm installation information:

Figure 3-8 Checked Advanced - RIG

1. Click Install.
2. Proceed to Step 10.
3. For a PA installation without selecting the Advanced check box:
4. Modify prompted information, as needed:

Figure 3-9 Un-Checked Advanced - PA

Note

By default, the installer assumes that the database should be installed in

Embedded mode.

To install database in Network mode, select the Network database mode radio button. This enables the Database Port field, which can then be modified, as needed.

1. Click Next.
2. Confirm installation information:

Figure 3-10 Confirm Installation

1. Click Install.
2. Proceed to Step 10.
3. For a PA installation with the Advanced check box selected:
4. Modify prompted information, as needed:

Figure 3-11 Checked Advanced - PA

Note

By default, the installer assumes that the database should be installed in

Embedded mode.

To install database in Network mode, select the Network database mode radio button. This enables the Database Port field, which can then be modified, as needed.

1. Click Next.
2. Confirm installation information:

Figure 3-12 Confirm Installation

1. Click Install.
2. Proceed to Step 10.
3. The installation starts.

View the following example:

Figure 3-13 Installing

Look for Install Complete! for confirmation.

1. Click Exit.

Figure 3-14 Install Complete!

Silent Installations

Silent installations should be initiated at a command prompt/terminal using the installer.bat (Windows) or installer.sh (Linux) scripts. These script are located where the installer was deployed.

Perform silent installations using one of the following methods:

• Default Values
• Custom Installer Properties File
• Command Line Options

Default Values

When performing a new installation on a clean system with no other Nectar installations - and no customizations are required to the default values - a silent installation can be performed by executing one of the following with the -Ms/--silent and -Oin/--install options:

• installer.bat script (Windows)
• installer.sh script (Linux) For example:

Note

The default installation type is a RIG. If you do not specify the type, a RIG will automatically be installed.

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --install

Note

To install a Perspective agent, you must specify the type.

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --install --type PA

For more information on available command line options, see Command Line Options.

Custom Installer Properties File

A silent installation does not allow you to specify the installation location or the service names, nor any of the other prompted information. A custom installer properties file can be used to specify this information.

Follow these steps to create a custom installer properties file:

1. Copy the rigInstaller.props file in the deployed installer location.

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>copy rigInstaller.props rigInstaller_Stack_1.props

1. Perform the following actions:
   1. Edit the new properties file, rigInstaller_Stack1.props, using a text editor and the following information.

Note

The following sample content is provided to create a new properties file for a silent installation.

The rigInstaller.props file may have different content than what is shown; change only the items in red or green. The lines in red should already be present; modify only when necessary.

installName = Nectar PA Installer destinationCIP = nectar-cip1.nectarvoip.com destinationPort = 443

primaryLogin = rigSatellite primaryPassword = rigSatellite mainServiceName = NectarRIG mainDescription = Nectar RIG Server backupServiceName = Nectar RIG Backup backupDescription = Nectar RIG Backup installDB=false

inputHomeServer = true defaultDirectory=C:/Apps/nectar/ customer=Nectar

site = Nectar Customer type = RIG minimumMemory.PA = 2000 ireType = HotSpot ireArchitecture = 64-bit

description = New Description serverName = NewServerName

Note

The serverName value must not contain spaces.

If it contains spaces, the associated service will not start properly.

• 
  
  1. Modify the following field values to be unique on the system being installed.

Note

It is critical that their values do not match any other existing installation.

mainServiceName mainDescription backupServiceName backupDescription defaultDirectory

• 
  
  1. Add the lines in green, as needed:
     • The description field can be omitted, in which case, a default description will be used.
     • The serverName field can be omitted, but a new server name with the format

 will be used.

1. Once the file is configured, use the installer.bat (Windows) or installer.sh (Linux) file along with a propsFile value to specify the new properties file as follows:

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --install rigInstaller_Stack_1.props

The installation starts; progress messages output to the console.

Note

If the silent installation fails due to a memory requirement, it can be re-executed along with the overrideMemory option:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat -- silent --install rigInstaller_Stack_1.props --memory-override

Command Line Options

A silent installation does not allow you to specify the installation location or the service names, nor any of the other prompted information. This is especially apparent when installing a stacked installation, in which case, command line options will likely be required to resolve port conflicts.

For example, an installation performed on a clean system with no other Nectar installations will use the following port values by default:

• mother:443
• server:80
• telnet:21
• ftp:20
• ssh:22

If different port values are not specified, an attempt to perform a second silent installation will fail, because of port conflicts as it would attempt to use the same default port values already used by the first installation.

Command line options can be used to specify custom port values.

For example:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent --install -

-mother-port 9443 --server-port 980 --telnet-port 921 --ftp-port 920 --ssh-

port 922

This command would attempt an installation using the following port values:

• mother:9443
• server:980
• telnet:921
• ftp:920
• ssh:922

If there are no other conflicts, the installation would proceed.

Other custom values can be specified using the following command line options:

• -dir/--install-dir
• -mn/--main-name
• -md/--main-desc
• -bn/--backup-name
• -bd/--backup-desc
• -c/--customer
• -s/--site
• -d/--description
• -r/--remote-server
• -p/--remote-port
• -n/--server-name
• -u/--username
• -w/--password
• -Ab/--bind-address

For more information on available command line options, see Command Line Options.

Perform Upgrades

This section provides the following:

• GUI Upgrades
• Silent Upgrade

Note

The same installer is used for Windows and Linux. Although the dialog images shown were captured on a Windows system, the Linux dialogs are essentially the same, providing the same content.

GUI Upgrades

This section details how to perform GUI upgrades while connected to the system being upgraded through a Nectar Client. Silent upgrades can be performed this way as well using Command Line instead of Remote Desktop. Linux upgrades have to be performed using Command Line.

Upgrades are managed using the Nectar installer with a few manual steps and include the following:

• Upgrade the Backup Server Using CIP
• Upgrade Main/Primary Server Using CIP

Note

The subsections that follow imply that the Backup service should be upgraded prior to upgrading the Main/Primary service. However, the order should generally not matter.

The installer will stop and re-start any associated service during an upgrade, if the associated service is running. If an associated service is not running prior to the upgrade, the installer will not start it as part of the upgrade process.

Upgrade through CIP

When upgrading through a CIP connection, it is critical that the main service only be upgraded when connected to the system via the backup service, and the backup service will only be upgraded when connected to the system via the main service. Otherwise, connectivity will be lost during the upgrade process.

Upgrade the Backup Server Using CIP

Follow these steps to upgrade the backup server:

1. Navigate to RIG > Admin > Remote Desktop.

This action connects to Nectar Foundation through the primary service where the backup service can be upgraded.

Figure 4-1 RIG > Admin > Remote Desktop

1. Log in to the RIG with the RDC credentials.
2. Launch the installer in GUI mode using one of the following:
   • installer exe file (Windows)
   • installer.bat script (Windows)
   • installer bin file (Linux)
   • installer.sh script (Linux)

Figure 4-2 Launch the Installer

1. When the Nectar End User License Agreement - Disclaimer window appears, read to the bottom of the license text; then click Accept.

Figure 4-3 License Agreement

1. Select the following to target the backup service of the existing installation:

• Target an Existing Installation
• Modify Operation: Upgrade
• Targeted Service: Backup

Be sure to select the intended installation to upgrade.

Figure 4-4 Upgrade Installation

Note

If one existing installation is present, one entry appears in the lower pane (see

Figure 4-4).

If multiple installations are present, they all appear in the lower pane.

The following dialog displays the Upgrade Type radio buttons, if the type of the installation is ambiguous as detected by the installer:

Figure 4-5 Installation - Ambiguous

If Upgrade Type appears, select the actual type of the installation, such as RIG or PA; then click Next.

Figure 4-6 Select Type

Note

It is important that the correct type be selected when this dialog appears. The selection should not be made based solely on Detected Type value. The intent is to allow explicit specification of the actual installation RIG, when the installer detects ambiguity. If it's really a RIG installation and the installer shows Detect Type as PA, then RIG should be selected. But, if it is really a PA installation, then PA should be selected.

1. Ensure Backup Service is shown as the affected service; confirm that the target installation data represents the installation to be upgraded.

Figure 4-7 Confirm Upgrade

If the Upgrade Type radio buttons appeared previously, then ensure that the Upgrade Type

field reflects the actual type of the installation.

1. Click Upgrade.

Figure 4-8 Upgrade Type and Affected Service(s)

The backup service will be upgraded.

Figure 4-9 Upgrading

Look for Upgrade Complete! for confirmation.

Figure 4-10 Upgrade Complete!

1. Click Exit.
2. Log off the RDC session.

Upgrade Main/Primary Server Using CIP

Follow these steps to upgrade the main/primary server:

1. With the backup server online, right-click on Backup: Online.

Figure 4-11 Backup: Online

1. From the Satellite: [Backup] panel, navigate to BACKUP RIG > Admin > Remote Desktop.

Figure 4-12 BACKUP RIG > Admin > Remote Desktop

This action connects to Nectar Foundation through the backup service where the primary service can be upgraded.

1. Log in to the RIG with the RDC credentials.
2. Launch the installer in GUI mode using one of the following:
   • installer exe file (Windows)
   • installer.bat script (Windows)
   • installer bin file (Linux)
   • installer.sh script (Linux)

Figure 4-13 Launch the Installer

1. When the Nectar End User License Agreement - Disclaimer window appears, read to the bottom of the license text; then click Accept.

Figure 4-14 License Agreement

The Enter/Select Installation Directory and Service Data window appears.

1. Select the following to target the backup service of the existing installation:

• Target an Existing Installation
• Modify Operation: Upgrade
• Targeted Service: Main

Select the intended installation to upgrade.

Figure 4-15 Upgrade Installation

Note

If one existing installation is present, one entry appears in the lower pane (see

Figure 4-15).

If multiple installations are present, they all appear in the lower pane.

1. Click Next.
2. Select one of the following for the Database Mode:

Embedded

• Network

Figure 4-16 RIG Identity

Note

If the database is already configured for Network mode, this dialog box will not appear.

Network will be pre-selected, if ciscoUCM or lyncModule are detected in the installations etc/server.properties file. Otherwise, Embedded is selected.

• 
  
  • If Network is selected, the Database Port field is enabled, allowing specification of the port used for the network database.

Figure 4-17 Database Port

• 
  
  • The following dialog displays the Upgrade Type radio buttons, if the type of the installation is ambiguous as detected by the installer:

Figure 4-18 Installation - Ambiguous

If Upgrade Type appears, select the actual type of the installation, such as RIG or PA.

Figure 4-19 Select Type

Note

It is important that the correct type be selected when this dialog appears. The selection should not be made based solely on Detected Type value. The intent is to allow explicit specification of the actual installation RIG, when the installer detects ambiguity. If it is a RIG installation and the installer shows Detect Type as PA, then RIG should be selected. But, if it is a PA installation, then PA should be selected.

1. Click Nectar 10 Integration to enable Nectar 10 integration.

1. Click Next.

Figure 4-20 Enable Nectar 10 Integration

1. Ensure Main Service is shown as the affected service; confirm that the target installation data represents the installation to be upgraded. Ensure the Database Mode field reflects the selected or configured database mode. View the following example depicting an Embedded database mode:

Figure 4-21 Main Service - Embedded

View the following example depicting a Network database mode:

Figure 4-22 Main Service - Network

If present, ensure that the Upgrade Type field reflects the actual type of the installation as selected in previous step.

1. Click Upgrade.

Figure 4-23 Main Service - Upgrade Type

The Main/Primary Service will be upgraded.

Figure 4-24 Upgrading

Look for Upgrade Complete! for confirmation.

1. Click Exit.

Figure 4-25 Upgrade Complete!

1. Log off the RDC session.

Upgrade Directly on System

The installer can also be used to upgrade a system directly. Because the upgrade is initiated locally, without going through a connection via a CIP, any of the main, backup, or both services can be upgraded.

To perform an upgrade locally on a system, the steps are a subset of Upgrade Main/Primary Server Using CIP for upgrading the main service, with a few modifications.

1. Begin with Step 4.
2. On Step 6, ensure Both is selected as the targeted service
3. On Step 11, ensure Both Main and Backup Services is shown for Affected Service(s).
4. Stop after Step 13.

Silent Upgrade

Note

For Cisco deployments, you must offboard any server configurations before upgrading to v7.0. For more information on offboarding, see Cisco UCM VKM Configuration Guide.

When the Installer detects the Cisco UCM VKM module, it will display a warning message, informing the user to offboard any systems before completing the upgrade. Once the Cisco UCM system(s) have been offboarded, you can re-run the upgrade process and select the CUCM Override to complete the upgrade.

Silent installations should be initiated at a command prompt/terminal using the installer.bat (Windows) or installer.sh (Linux) scripts. These script are located where the installer was deployed.

A silent upgrade does not allow you to specify the targeted installation, e.g., by installation location or service name. Instead, this information must be specified on the command line by specifying a targetPath or targetService value.

For example:

• With a targetPath value:

Note

• To upgrade the main RIG, you would specify --main.
• To upgrade the backup, you would specify --backup.
• To upgrade the main RIG and backup, you would specify --both. For more information, see Target Services.

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent -- upgrade "C:\Apps\nectar_4" --main

• With a targetService value:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent -- upgrade "nectarrig 4"

The upgrade starts; progress messages output to the console.

Note

If the silent upgrade fails due to a version requirement, it can be re-executed along with the overrideVersion option:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent

--upgrade "C:\Apps\nectar_4" --main --version-override

If the silent upgrade fails due to a memory requirement, it can be re-executed along with the overrideMemory option:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent

--upgrade "nectarrig 4" --memory-override

Target Services

By default, the upgrade option only targets the main/primary service. This can be overridden using the main, backup, or both options.

• To upgrade the main service only, specify the main option:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent -- upgrade "C:\Apps\nectar_4" --main

• To upgrade without specifying main, backup, or both options:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent -- upgrade "nectarrig 4"

• To upgrade the backup service only, specify the backup option:

C:\Program Files (x86)\UCF\nectar\8.6\64bit>installer.bat --silent -- upgrade "C:\Apps\nectar_4" --backup

• To perform a full upgrade of both the main and backup services, specify the both option:

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --upgrade "C:\Apps\nectar_4" --both

Perform Uninstalls

Uninstall provides the following:

• GUI Uninstall
• Silent Uninstalls

Note

The same installer is used for Windows and Linux. Although the dialog images shown were captured on a Windows system, the Linux dialogs are essentially the same, providing the same content.

GUI Uninstall

On Windows and Linux, an uninstall can be performed by running the installer. On Windows, an uninstall can also be performed using Windows Programs and Features with a specific installation targeted.

Uninstall through Windows Programs and Features

Follow these steps to uninstall an installation using Windows Programs and Features:

1. Click Start > Control Panel > Programs > Programs and Features.
2. Select the installation to uninstall; then select Uninstall.

Figure 5-1 Uninstall or Change a Program

Figure 5-2 Launch the Installer

1. When the Nectar End User License Agreement - Disclaimer window appears, read to the bottom of the license text; then click Accept.

Figure 5-3 License Agreement

The Confirm Uninstall window appears.

Figure 5-4 Confirm Uninstall

1. Confirm the installation to be uninstalled; then click Uninstall. The targeted installation will be uninstalled.

The Uninstalling Installation window appears with the message, Starting Uninstall ....

Figure 5-5 Uninstalling Installation

1. Look for the message, Uninstall Complete!

1. Click Exit.

Figure 5-6 Uninstall Complete!

Uninstall Using Installer

Follow these steps to uninstall using the GUI installer:

1. Launch the installer in GUI mode using one of the following:
   • installer exe file (Windows)
   • installer.bat script (Windows)
   • installer bin file (Linux)
   • installer.sh script (Linux)

Figure 5-7 Launch the Installer

1. When the Nectar End User License Agreement - Disclaimer window appears, read to the bottom of the license text; then click Accept.

Figure 5-8 License Agreement

1. Select the following to target the installation to uninstall:

Target an Existing Installation

• Uninstall

1. Select the installation to uninstall.

1. Click Next.

Figure 5-9 Enter/Select Target Installation Directory and Service Data

Figure 5-10 Confirm Uninstall

1. Confirm the installation to be uninstalled; then click Uninstall.

The Uninstalling Installation window appears with the message, Starting Uninstall ....

Figure 5-11 Uninstalling

1. When the message, Uninstall Complete!, appears, click Exit.

Figure 5-12 Uninstall Complete!

Silent Uninstalls

Follow these steps to perform a silent uninstall:

1. Silent installations should be initiated at a command prompt/terminal using the installer.bat (Windows) or installer.sh (Linux) scripts. These script are located where the installer was deployed.
2. A silent uninstall does not provide the opportunity to select or specify the targeted installation, for example, by installation location or service name. This information must be specified on the command line by specifying a targetPath or targetService value.
   • With targetPath:

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --uninstall "C:\Apps\nectar_4"

• 
  
  • With targetService:

C:\Program Files (x86)\Common Files\UCF\nectar\8.6\64bit>installer.bat -- silent --uninstall "nectarrig 4"

The uninstall starts; progress messages output to the console.

Configure a RIG as an EIP

The Enterprise Intelligence Platform (EIP) is a system module that is typically deployed on a separate server with the option of a HA cluster. The EIP contains registration and communication proxy systems. It provides users with a centralized, consolidated, global single sign-on view for environments that have multiple RIG deployments or must run the Nectar Intelli-Q module.

The EIP enables global dashboards that act as a launch point or provide a consolidated view of customer dashboards from multiple downstream RIGs. The dashboards also provide centralized alarming of all RIGs.

Users/responders can also use the system to:

• Securely connect to downstream RIGs.
• Pass commands.
• Subscribe to information channels between user/responder and the equipment to which a RIG is providing proxy access.

For large enterprise deployments, the Unified Communications Management Platform (UCMP) can provide a similar hierarchical system that enables EIP to connect to an external CIP that is typically housed in a service provider network.

This section explains how to:

• Request Licenses
• Configure RIG Connectivity to EIP

Request Licenses

In order for a RIG to be configured as an EIP:

• Must contain the “mother” license to provide access to the Mother Module.
• Can optionally contain “head alarm” license to provide access to the Intell-Q features.

When you order a RIG license and plan to configure the RIG as an EIP, submit a request to Nectar to include these licenses. If you have these licenses, the EIP Mother Module and Intell-Q features are automatically installed along with the RIG.

For information on using Intelli-Q, see the CIP EIP Administration Guide.

With these licenses enabled, you can see the Mother Module, which contains the Location pane to the left and the Intelli-Q pane to the right:

Figure 6-1 Location and Intelli-Q Panes

Configure RIG Connectivity to EIP

RIGs can either communicate through the EIP to the CIP, or register directly to both the EIP and CIP. Review this with your Nectar Channel Account Manager and Nectar Engineering to determine the preferred method for your solution.

Dual Registration

Dual Registration requires that RIGs have the ability to communicate via TCP port 443 to the three CIP addresses and EIP address. The username and password used below can be the superUsername/superPassword, or any user/password created on the EIP. No permissions should be given to the registration username. An Organization is required. Nectar recommends using “EIP” for the Organization name on the RIG and EIP.

1. Install, register, license using the RIG installer and CIP as with any other RIG.
2. Open a Maritime Terminal on each RIG and configure a new Arbitrary Channel Connection:

channel addArbitraryConnection 443 

1. Navigate to Configure > Distributed on the EIP to add the RIG to the Location list.

Proxy Registration

Proxy registration should only be used when the RIGs cannot communicate directly to the CIP. (The EIP will be a single point of failure for the communication of all RIGs to the outside world.)

1. Open a Maritime Terminal on each RIG by navigating to RIG > Admin > Maritime Terminal:

Figure 6-2 RIG > Admin > Maritime Terminal

1. Configure a new Arbitrary Channel Connection as follows:

channel addArbitraryConnection 443 

1. Log into your EIP.
2. Navigate to Configure > Distributed.
3. Right-click on each RIG and select Advanced > Turn Proxy On (see Figure 6-3).

Figure 6-3 Turn Proxy On

Command Line Options

Below is the –h/--help output from the v8.6 installer. This help can only be displayed from the installer batch files after the installer is extracted. However, the options can be passed directly to the installer executable.

usage: [-Mg | -Ms | -Mc][-Ono | -Oin [

[-ri] [-cs | -nc] [-OVv] [-OVj] [-OVm] [-OVd] [-OVr] [-OVa] [-y]

[-l] [-h] [-Pi 

Mode Options:

-Mg,--guiUse GUI mode

-Ms,--silentUse silent/non-interactive mode

-Mc,--consoleUNSUPPORTED: Use console/interactive mode

Operation Options:

-Ono,--noneUnspecified operation (default)

-Oin,--install [

-Oup,--upgrade [

-Ore,--repair [

installation

-Oun,--uninstall [

-Omo,--modify [

-Oex,--extract [

Install Options:

-f,--props-file 

-dir,--install-dirInstallation directory

-mn,--main-nameMain service name

-md,--main-descMain service description

-bn,--backup-nameBackup service name

-bd,--backup-descBackup service description

-t,--type 

-ns,--no-startDo not start installed services

Upgrade/Uninstall Options:

-Tp,--target-path 

-Ts,--target-service 

Upgrade Options:

-ut,--upgrade-type 

-Sm,--mainUpgrade main service only (default)

-Sb,--backupUpgrade backup service only

-S2,--bothUpgrade main and backup services

-ri,--reinstall-servicesUninstall and re-install service(s) over upgrade

-cs,--correct-service-namesCorrect pre-5.3.1 incorrect

service names

-nc,--do-not-correct-service-namesIgnore pre-5.3.1 incorrect service

name

Override Options:

-OVv,--version-overrideIgnore version check for upgrade

-OVj,--jre-overrideIgnore JRE checks

-OVm,--memory-overrideIgnore failed memory checks

-OVd,--disk-overrideIgnore failed disk space checks

-OVr,--arch-overrideIgnore system architecture checks

-OVa,--admin-overrideIgnore failed administrator checks

Miscellaneous Options:

-y,--cased-dirsUse case-sensitive directory names

-l,--disclaimerDisplay disclaimer text

-h,--helpDisplay this help

Internal Options:

-Pi,--installer-path 

-Ps,--start-path 

-L,--logger 

Configuration Options:

-c,--customer 

-s,--siteSite value (infospot.properties)

-d,--descriptionDescription value (infospot.properties)

-r,--remote-serverServer value (infospot.properties)

-p,--remote-portPort value (infospot.properties)

-n,--server-nameServer name value (server.properties)

-u,--usernameUsername value (infospot.properties)

-w,--passwordPassword value (infospot.properties)

Advanced Configuration Options:

-Ab,--bind-addressBind address value (server.properties)

-Am,--mother-portMother port value (server.properties)

-Ap,--server-portServer port value (server.properties)

-At,--telnet-portTelnet port value (server.properties)

-As,--ssh-portSSH port value (server.properties)

-Af,--ftp-portFTP port value (server.properties)

-Ak,--socket-portSocket port value (server.properties)

Database Mode Options:

-DBn,--derby-networkConfigure networked derby database (rigWrapper.properties and server.properties)

-DBe,--derby-embeddedRetain default embedded derby database (rigWrapper.properties and server.properties)

-DBp,--derby-portDerby network database port (rigWrapper.properties

and server.properties)

Modes (Default: --gui)

• 
  
  • 
    
    1. gui: -Mg/--gui gui mode is the default mode.

All operations work in gui mode. However, console output may not be available, depending upon how the application was launched.

All operations present a GUI presence by default, except extract. For all other options (other than extract), GUI dialogs should appear. If not, examine the installer log file.

silent: -Ms/--silent

silent mode is not really “silent”. It produces console output, but it is non-interactive. It does not require any responses to prompts. The operation operates with the default parameters (specified in the properties files bundled with the installer or internal defaults) or with parameters based on provided command-line options. Refer to the sections on usage for additional information.

console: -Mc/--console

console mode is not currently implemented. Like silent mode, it runs and produces output on a console. However, unlike silent mode, it can provide for an interactive installation – required data/input will be prompted.

Operations (Default: none)

In gui or console modes, if no operation option is specified and the installer detects no existing installations, then the installer only provides the ability to perform a new installation. On the other hand, if the installer detects one or more existing installations, then it provides the ability to perform a new installation and modify the existing installation(s) that it detects.

If the targetPath or targetService options are specified, then the operation defaults to a

modify operation, if an operation is not specified.

If the propsFile option is specified, then the operation defaults to an install operation, if an operation is not specified.

none: -Ono/--none

This operation is used, if no other operation is specified. Only supports gui mode and allows user to select desired operation through dialogs.

install: -Oin/--install [

This operation is used to install a new instance of the application.

For gui or console modes, the installation parameters can be modified prior to the actual installation.

If no existing installation is found, the install defaults to the values specified in the bundled installer properties files and internal defaults, unless overridden by the specification of custom installer ini files by specifying a propsFile value.

If one or more existing installation(s) is found, the default or customer installation path and service names and descriptions will be modified, if necessary, until they do not match any existing installation. This allows for stacked installations.

The install option supports specifying a propsFile value immediately following the install

option without using the propsFile option.

upgrade: -Oup/--upgrade [

This operation is used to upgrade an existing instance of the application.

If a mode is not specified, then the ability to modify the installation parameters for an existing installation is not allowed.

If the targetPath or targetService value or option is not specified, all existing installations are available for selecting in gui and console modes. A single installation must be selected in order to proceed with the upgrade.

If the targetPath or targetService value or option is specified, and the provided target path value matches that of an existing installation, then that is the targeted installation.

Alternatively, the upgrade option can be used with a specified targetPath or targetService value. Specify the targetPath or targetService path value immediately following the upgrade option and omit the targetPath or targetService option itself.

For silent mode, targetPath or targetService value must be specified with the update

operation or with the targetPath or targetService option.

For gui and console modes, a specified targetPath results in only the matching installation being available for the upgrade operation.

Typically, an upgrade is only allowed if the installed version is less than the version being installed. This can be overridden on the command line using the overrideVersion option.

repair: -Ore/--repair [

This operation is used to repair an existing installation. Internally, it is identical to an upgrade

operation.

Typically, a repair is only allowed, if the installed version is the same as the version being installed. This can be overridden on the command line using the overrideVersion option.

Note

The repair option has been removed from the GUI, but it is still available as a command line option. However, the upgrade option should be used instead with the overrideVersion option, if necessary. For now, these operations are functionally identical, aside from the version checks performed prior to making modifications to the targeted installation.

uninstall: -Oun/--uninstall [

This operation is used to uninstall an existing installation.

If the targetPath or targetService value or option is not specified, all existing installations are available for selection in gui and console modes. A single installation must be selected in order to proceed with the uninstall.

If the targetPath or targetService value or option is specified, and the provided target path value matches that of an existing installation, then that is the targeted installation.

Alternatively, the uninstall option can be used with a specific targetPath or targetService value. Specify the targetPath or targetService value immediately following the uninstall option and omit the targetPath or targetService option itself.

For silent mode, targetPath or targetService value must be specified with the uninstall

operation or with the targetPath or targetService option.

extract: -Oex/--extract [

This operation is used to extract the installer files to a user-specified directory. By default, when the 7Zip SFX installer runs, it extracts all of the installer files to a temporary location available only when the initial installation is running. The extract option is used to extract the installer files to a permanent directory, from which an additional/custom installation can be executed.

The extract operation requires use of the targetPath option to specify the full path to the location to extract the installer files.

Alternatively, the extract option can be used with a specific targetPath value. Specify the targetPath value immediately following the extract option and omit the targetPath option itself.

modify: -Omo/--modify [

This is an internal use option used by the uninstall configuration in Windows Programs and Features.

Install Options

propsFile: -f/--props-file

The propsFile option is used with a silent install to specify all of the relevant installation details prompted for during an installation. Typically used for a silent install, the is expected to be a copy/modified version of either the install.properties or rigInstaller.props file. Customizations can be made in the copied file to change the target installation path, service names and descriptions, destination CIP server and port values, default username and password, as well as customer and site values.

Also supported, but not typically included in the install.properties or rigInstaller.props

files are the description, serverName, and installName fields.

• The description value is usually prompted and specified with the Site and Customer values.
• The serverName value is usually prompted for a DA or PA installation, but can be defaulted to

• The installName value is typically not prompted, but is specified from the installer properties files. It is also used in configuring the Windows Programs and Features uninstaller as part of the uninstaller name.

The propsFile option is intended for use with a silent install to specify all of the relevant installation details prompted for during an installation.

installDir: -dir/--install-dir

The installDir option is used to specify the default installation directory from the command line. It overrides the value present in the default rigInstaller.props file or any corresponding value in a user-specified installer properties file using the propsFile option.

mainName: -mn/--main-name

The mainName option is used to specify the default main service name from the command line. It overrides the value present in the default rigInstaller.props file or any corresponding value in a user-specified installer properties file using the propsFile option.

mainDesc: -md/--main-desc

The mainDesc option is used to specify the default main service description from the command line. It overrides the value present in either the default rigInstaller.props file, as well as any corresponding value in a user-specified installer properties file specified using the propsFile option.

backupName: -bn/--backup-name

The backupName option is used to specify the default backup service name from the command line. It overrides the value present in the default rigInstaller.props file or any corresponding value in a user-specified installer properties file using the propsFile option.

backupDesc: -bd/--backup-desc

The backupDesc option is used to specify the default backup service description from the command line. It overrides the value present in the default rigInstaller.props file or any corresponding value in a user-specified installer properties file using the propsFile option.

type: -t/--type

Generally, the type is used for PA. The PA is installed using a PA installer, where PA is the default type. This has consequences for the memory requirements of the machine on which the installation is taking place, as well as for other JVM-specific settings.

Initial type is determined from the content of the installer properties file bundled with the installer. On the command line, it can be set to a specific type. The remaining sub-sections detail the specific types the installer recognizes.

RIG

Denotes the type of installation to be a RIG. This is the default for a RIG installer.

DA

Denotes the type of installation to be a DA. This is a legacy installation type. If specified, the type

defaults to PA.

IPOffice

Denotes the type of installation to be an IPOffice. This is a legacy installation type, and as of v5.5, the IPOffice capability is bundled with RIG. If specified, the type defaults to RIG.

PA

Denotes the type of installation to be a PA.

CIP

Denotes the type of installation to be a CIP. This type of installation is not supported by the installer. If specified, the type defaults to RIG.

noStart: -ns/--no-start

The noStart option causes the installer to NOT automatically start services during a new install.

By default, the installer starts both the main and backup services following a new installation. Use the noStart option to alter this behavior and not start the services following a new installation.

Upgrade/Uninstall Options

targetService: -Ts/--target-service

The targetService option is used to specify a service name associated with an existing installation. It is used with a silent upgrade, repair, or uninstall to identify the target installation upon which to perform the specified operation.

The targetService will be used to match an existing installation by the main/primary Windows Service Name. This is not the main/primary Windows service Display Name as it appears in the Windows Services list, the main/primary Windows service Description, or the backup Windows Service Name.

Usage for Linux is undefined, as Linux is not currently supported with the new installer.

If both targetPath and targetService options are specified, the last one appearing on the command line is used.

Note

This option is no longer necessary. A service name value can be specified immediately following the upgrade, uninstall, or modify option, without using this option.

targetPath: -Tp/--target-path

The targetPath option is used to specify the installed location for an existing installation. It is used with a silent upgrade, repair, or uninstall to identify the target installation on which to perform the specified operation.

The targetPath option is also used to specify the target directory for the extract option.

If both targetPath and targetService options are specified, the last one appearing on the command line is used.

Note

This option is no longer necessary. A path value can be specified immediately following the upgrade, uninstall, modify, or extract option, without using this option.

Upgrade Options

upgradeType: -ut/--upgrade-type

The upgradeType option specifies the type to use when upgrading an existing installation with an ambiguous type. An installation has an ambiguous type, if the installer is unable to determine how it should be upgraded. This results from installations that can be a RIG or a PA.

If such an installation is encountered, an upgrade for the installation will fail its initial checks, unless an upgrade type is specified.

Targeted Services

These options are only applicable to upgrade (and repair) operations. They specify which services associated with a targeted installation are to be upgraded. An upgrade requires the service being upgraded to be stopped. Specifying main or backup allows an upgrade to one of the services to take place while the other service remains running – critical for the use of the installer when used through a tunnel connection served by one of the services.

If no targeted service option is specified – either on command line or through GUI radio buttons – the installer defaults to only upgrading the main service.

When using installer through a tunnel connection, the service being targeted must not be the one serving the tunnel connection.

• When targeting the main service, it is critical to ensure that the tunnel is being served by the backup service before proceeding with the upgrade.
• Similarly, if targeting the backup service, it is critical to ensure that the tunnel is being served by the main service before proceeding with the upgrade.

main: -Sm/--main

Specifies that the upgrade (or repair) operation targets the main service only of the installation that is being upgraded. Only the main service will be stopped; the backup service remains in its existing state.

This option results in all upgradable directories and files being copied into place in the targeted installation except content specific to the backup service (such as the backup directory and its upgradable content) and content common to both the main and backup services, such as the jre-static directory under Windows.

backup: -Sb/--backup

Specifies that the upgrade (or repair) operation targets the backup service only of the installation being upgraded. Only the backup service will be stopped; the main service remains in its existing state.

This option results in all upgradable directories and files being copied into place in the targeted installation except content specific to the main service (such as all content other than the backup directory and its upgradable content) and content common to both the main and backup services, such as the jre-static directory under Windows.

both: -S2/--both

Specifies that the upgrade (or repair) operation targets both the main and backup services of the installation being upgraded. Both the main and backup services will be stopped.

This option results in all upgradable directories and files being copied into place in the targeted installation, including content specific to both the main and backup services and content common to both the main and backup services, such as the jre-static directory under Windows.

reinstall: -ri/--reinstall-services

The reinstall option specifies that during an update/repair operation, the services should be uninstalled prior to copying new files into place; then re-installed.

On Linux, this is the default behavior.

On Windows, the default behavior is NOT to uninstall and re-install services during an upgrade/ repair operation. This option can be used to force Windows installer to uninstall and re-install services.

Service Name Correction

For some branded partners, the service names were set to NectarRIG and NectarRIGBackup in the initial installer properties file from which the installer derives its values to use during an installation. In release 5.3.1.2, the installer was modified to detect and correct these service names, but there was no consideration of the actual partner when detecting, so in a few cases, the detection and correction matched service names that were actually correct.

As of release 5.6.1, the installer effectively takes the partner into consideration, as each partner has a setting for an internal installer property specifying whether to attempt to detect and correct service names that are incorrect. This property is only enabled for those partners that initially had incorrect service names.

The two command line options that follow are used to override the internal installer property that now drives the detection and correcting of service names that are incorrect.

correctServiceNames: -cs/--correct-service-names

Specifies that the installer should attempt to detect and correct services names that are incorrect.

This command line option overrides the internal installer property driving the detection and correcting of service names that are incorrect.

doNotCorrectServiceNames: -nc/--do-not-correct-service-names

Specifies that the installer should not attempt to detect and correct service names that are incorrect.

This command line option overrides the internal installer property driving the detection and correcting of service names that are incorrect.

Override Options

overrideVersion: -OVv/--version-override

The overrideVersion option is used with a silent upgrade or repair to override any version checks against the installer version and the targeted/installed version.

overrideJre: -OVj/--jre-override

The overrideJre option is used with a silent upgrade or repair to override checks against the installer-bundled JRE and the targeted/installed JREs. This can be used to allow an installation with a 64-bit system. It cannot be used to perform the opposite: an installer with a 64-bit JRE will be blocked from installing on a 32-bit system.

overrideMemory: -OVm/--memory-override

The overrideMemory option is used with a silent install, upgrade, or repair to override any memory checks against the system.

overrideDisk: -OVd/--disk-override

The overrideDisk option is used with a silent install, upgrade, or repair to override any disk checks against the system. Use with caution. The install attempts to determine the free space on the targeted disk drive, as well as how much space is needed for the action being performed.

overrideArch: -OVr/--arch-override

The overrideArch option is used with a silent install, upgrade, or repair to override any architecture checks against the system.

forceNotAdmin: -OVa/--admin-override

The forceNotAdmin option is used to bypass the admin checks in the installer. Use with caution. This should be used only when the admin checks are erroneously blocking an installation, when the user has the necessary privileges to perform the installation.

Miscellaneous Options

casedDirs: -y/--cased-dirs

The installer assumes Windows directories are case-insensitive by default, as this is the default mode for Windows directories. This can be overridden by specifying the casedDirs option on the command line. If provided, the installer running on Windows performs case-sensitive directory comparisons. Otherwise, the installer performs case-insensitive directory comparisons.

This option has no effect on Linux, as Linux directories are case-sensitive by default.

disclaimer: -l/--disclaimer

The disclaimer option outputs the Nectar End User License Agreement Disclaimer text to the console. If specified, all other options are ignored. The installer immediately exits after displaying the disclaimer text.

help: -h/--help

The help outputs the command-line help.

Note

This only appears when running installer on the command line using the installer.bat file or installer.sh file after first extracting the installer to a local directory using the extract option.

Internal Options

installerPath: -Pi/--installer-path

The installerPath option is an internal use option used to specify the full path to the installer files.

startInPath: -Ps/--start-path

The startInPath option is an internal use option used to specify the current working directory from which the installer is started.

logger: -L/--logger

The logger option is an internal use option used to control additional logging to the installer log file. is a colon-separated list of logger levels and categories, for example,

-L debug:properties:commands.

The follow logger levels are supported:

• info - [default level] - Provides general log level for enabled categories.
• debug - Provides the debug log level for enabled categories; logs more than the info level.
• trace - Provides trace log level for enabled categories; logs more than the debug level.
• all - Logs all levels for enabled categories. The following logger categories are supported:
• any - Used to enable all logging categories.
• main - [enabled by default] - Is the main category that logs general installer functions.
• gui - Enables logging of gui mode functions.
• installations - Enables logging of installations for existing installations found by the installer.
• installationdata - Enables logging of installation data for existing installations found by the installer.
• properties - Enables logging of properties used by the installer. With debug enabled, provides dump of properties.
• platform - Enables logging of platform-related functions.
• options - [enabled by default] - Enables logging of the processing options.
• commands - Enables additional logging of commands directly executed by the installer. With debug level enabled, logs all command output and exit codes from the executed commands.
• extcfg - Enables logging during the processing of external configuration.
• files - Enables file-specific logging. With debug level enabled, provides trace of file activity during installation and upgrade/repair.

Configuration Options

customer: -c/--customer

The customer option is used to specify the customer value set in the main etc/ infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

site: -s/--site

The site option is used to specify the site value set in the main etc/infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

description: -d/--description

The description option is used to specify the description value set in the main etc/ infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair.

server: -r/--remote-server

The server option is used to specify the server value set in the main etc/ infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

port: -p/--remote-port

The port option is used to specify the port value set in the main etc/infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536.

serverName: -n/--server-name

The serverName option is used to specify the servername value set in the main etc/ server.properties file and the backup/etc/server.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

In the backup/etc/infospot.properties file, the value specified will have -backup concatenated to the end. For example, a specified server name value of serverX would be serverX in the main etc/server.properties file and serverX-backup in the backup/etc/ server.properties file.

username: -u/--username

The username option is used to specify the username value set in the main etc/ infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

password: -w/--password

The password option is used to specify the password value set in the main etc/ infospot.properties file and the backup/etc/infospot.properties file. It is only applicable for an installation. It is not applicable for an upgrade or repair.

Advanced Configuration Options

bindAddress: -Ab/--bind-address

The bindAddress option is used to specify an IP address to set as the bindAddress value in the main etc/server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair.

motherPort: -Am/--mother-port

The motherPort option is used to specify the port value to set as the motherPort value in the main etc/server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536, or *.

serverPort: -Ap/--server-port

The serverPort option is used to specify the port value to set as the serverPort value in the main etc/server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536, or *.

telnetPort: -At/--telnet-port

The telnetPort option is used to specify the port value to set as the telnetPort value in the main etc/server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536, or *.

sshPort: -As/--ssh-port

The sshPort option is used to specify the port value to set as the sshPort value in the main etc/ server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536, or *.

ftpPort: -Af/--ftp-port

The ftpPort option is used to specify the port value to set as the ftpport value in the main etc/ server.properties file. It is only applicable for an install; it is not applicable to an upgrade or repair. The port value can be any value between 1 and 65536, or *.

socketPort: -Ak/--socket-port

The socketPort option is used to specify port value to set as the socketport value in the main etc/server.properties file. It is only applicable for an install; it is not applicable for an upgrade or repair. The port value can be any value between 1 and 65536, or *.

Database Mode Options

derbyNetwork: -DBn/--derby-networked

The derbyNetwork option is used to pre-select the conversion of the derby database to network

mode during an install or upgrade/repair. This only applies to the main service.

The installer automatically pre-selects network mode, if the targeted installation for an upgrade is already in network mode, or if the targeted installation has modules ciscoUCM and/or lyncModule configured in its main etc/server.properties file.

derbyEmbedded: -DBe/--derby-embedded

The derbyEmbedded option is used to pre-select to keep the derby database in embedded mode during an install or upgrade/repair. This only applies to the main service.

This has no effect if the derby database is already converted to network mode.

derbyPort: -DBp/--derby-port

The derbyPort option is used to specify the port value to use when converting an installation to networked (externalized) mode during an installation or upgrade/repair.

This option applies to the main service.

This has no effect if the derby database is already converted to network mode.

The default port value is 1527, but a different/unique value must be specified when stacking installations.

The port value can be any value between 1 and 65536.

7Zip Option

The following 7Zip Option is not output with the installer help.

-gm2

This is not a parameter for the Nectar installer, but is instead an option for the 7 Zip SFX archive. If specified, the 7 Zip SFX archive will not display a progress dialog during the initial 7 Zip SFX extraction.

To use, the –gm2 option must be the first parameter passed to the 7 Zip SFX archive installer. Or, it must precede any or all of the Nectar installer-specific options.

If passed to the installer.bat file that provides for silent installations after using the extract

operation option, the –gm2 option has no effect.

Field and Data Descriptions

There is a subset of data that the installer uses to perform installations and upgrades. Usually, the installer's default values can be used without modification. Whether the defaults are accepted or modifications are made, it is important to understand how the values are used and where they are configured. This understanding is critical to diagnosing installer issues and is also important for understanding the configuration applied by the installer.

This appendix contains the following sections:

• Installer Job Aid Template
• Field Names

The default values discussed in these sections are for the default "Nectar" branded installer. It is important to note that some partner installers are custom-branded for the specific partner.

For example, a fictitious partner name Good Service, Inc. may have a default-branded installation directory C:\Apps\goodservice or /opt/ucf/goodservice, and a default main service name GoodServiceRIG, etc.

Make note of where the installer's actual defaults differ from the Nectar-branded defaults. When this or other documents reference the Nectar-branded default values, be sure to substitute the partner-branded values, as well as any values modified during the actual installation.

Installer Job Aid Template

This section provides the following Installer Job Aid template that can be used to collect information for an installation.

Field Names

The following sections provide details on the various fields and how they are used.

Installation Directory

This is the directory to which a new installation will be installed.

• For Windows services, it is used in installing both the main and backup services, in the full path to the main service’s Server.exe file, and the backup service’s BackupServer.exe file.
• For Linux services, it is configured in the service scripts on a system using init.d, and in the service unit files on a system using systemd. In both cases, it is used to configure the installation’s location for the installed services.

Main Service Name

• The main service name is used when configuring the main service for an installation.
• It can be used to locate and view status for the associated service, as well as to manipulate (e.g., start or stop) the associated service.
• It is unique from the backup service name, as well as all service names for any stacked RIG installations.
• Take note of the installed service names.
  • On Windows, the main service name can be used for one of the following:
    • Manipulate the main service or view the main service status using the NET and/or SC

commands from a Windows Command Prompt.

• 
  
  • 
    
    • Identify the main service using the Windows Services window, from which the main service can be manipulated or viewed.
  • On Linux, the main service name can also be used to manipulate the main service or view the main service status. Because the services for an installation are installed and configured differently, depending on the init system used by the Linux system, the server.sh script installed along with the installation can be used to manipulate the main service or view the main service status, regardless of whether the Linux system is utilizing the init.d or the systemd init systems.

For more information on the server.sh script, see Linux Services and the server.sh Script.

• Be aware that if the default service names are changed, then the actual service names used during installation must be substituted for the default service name values referenced in this or any other documents.

Note

Notice the main service name used when stacking, as the installer ensures the default name is unique among all stacked RIG.

For additional information, see Installation Path and Service Names with Stacking.

Main Service Description

• The main service description is used when configuring the main service for an installation.
• The main service description is generally informational. While it is associated with an installed service, it merely provides a more readable description of the associated service.
• It is unique from the backup service description, as well as all service descriptions for any stacked RIG installations.

Backup Service Name

• The backup service name is used when configuring the backup service for an installation.
• It can be used to locate and view status for the associated service, as well as to manipulate (e.g., start or stop) the associate service.
• It is unique from the main service name, as well as all service names for any stacked RIG installations.
• Take note of the installed service names.
  • On Windows, the backup service name can be used for one of the following:
    • Manipulate the backup service or view the backup service status using the NET and/ or SC commands from a Windows Command Prompt.
    • Identify the backup service using the Windows Services window, from which the backup service can be manipulated or viewed.
  • On Linux, the backup service name can also be used to manipulate the backup service or view the backup service status. Because the services for an installation are installed and configured differently depending on the init system used by the Linux system, the server.sh script installed along with the installation can be used to manipulate the backup service or view the backup service status, regardless of whether the Linux system is utilizing the init.d or the systemd init systems.

For more information on the server.sh script, see Linux Services and the server.sh Script.

• Be aware that if the default service names are changed, then the actual service names used during installation must be substituted for the default service name values referenced in this or any other documents.

Note

Notice the backup service name used when stacking, as the installer ensures the default name is unique among all stacked RIG.

For additional information, see Installation Path and Service Names with Stacking.

Backup Service Description

• The backup service description is used when configuring the backup service for an installation.
• The backup service description is generally informational. While it is associated with an installed service, it merely provides a more readable description of the associated service.
• It is unique from the main service description, as well as all services descriptions for any stacked RIG installations.

Installation Type

• The installation type describes the type of installation, RIG or PA.
• Beyond the obvious functional differences between a RIG and a PA, the type selected also affects how an installation or upgrade is performed. When installing or upgrading a RIG, there are differences between the files that the installer installs or upgrades; then configures, when compared to a PA installation.

Upgrade Type

• The upgrade type describes the type of installation, RIG or PA. More specifically, it is used by the installer, in concert with the installation type value, to determine how the installer upgrades a system.
• When prompted for this value during an upgrade, it is critical that the value selected matches the type of the actual installation. Make note that the detected type that the installer presents may not be representative of the actual installation type.

Database Mode

• Database mode can be selected as either embedded or networked.
• If networked is selected, then the associated properties files will be configured.
  • The default host and location values are 0.0.0.0 for derby.host.name in rigWrapper.properties and localhost for networkderby.location in etc/ server.properties. The default location value is also localhost as part of datasource.derby.url in application.properties.
  • The host and location values are not configurable by the installer.
• If embedded mode is selected, the rigWrapper.properties and etc/server.properties

keys/values are not configured.

Database Port

• Database mode can be selected as either embedded or networked. If networked is selected, then the associated properties files will be configured.
• The default port value is 1527 for both derby.host.port in rigWrapper.properties and networkderby.port in etc/server.properties. The default port value is also 1527 as part of datasource.derby.url in application.properties.
• If networked mode is configured, the port value must be unique on the system. When stacking RIGs, all stacked RIGs must use a different database port value.
• If embedded mode is selected, the rigWrapper.properties and etc/server.properties

keys/values are not configured.

Derby Datasource URL

• This field defines the derby connection criteria used by the RIG server. The field contains multiple component values in a single string. The value differs, depending upon the database mode.
  • Embedded database mode: jdbc:derby:rigDB;create=true
  • Networked database mode: jdbc:derby://localhost:1527/rigDB;create=true

Note

Notice the default location value localhost and the default port value 1527 in the value used for networked database mode.

• In a stacked RIG scenario, the port value for networked database mode differs from the default value, as specified by the user during conversion to networked database mode when installing/upgrading.

Derby Datasource Driver

• This field defines the derby driver used by the RIG server to establish connection to database. The value differs, depending upon the database mode.
  • Embedded database mode: org.apache.derby.jdbc.EmbeddedDriver
  • Networked database mode: org.apache.derby.jdbc.ClientDriver

Customer

• The customer value is informational only. It is not used for any functional purpose by the RIG itself.
• It should be used to provide a useful and unique description for the partner or customer utilizing the RIG or PA.
• When looking through lists of distributed RIGs on a CIP or EIP, or PAs on a CIP, EIP, or RIG, the customer value is one of the values that can be used to filter the list down when searching for a specific Nectar Foundation instance.

Site

• The site value is informational only. It is not used for any functional purpose by the RIG itself.
• It should be used to provide a useful and unique description for the physical (or virtual) site/ location of the RIG or PA.
• When looking through lists of distributed RIGs on a CIP or EIP, or PAs on a CIP, EIP, or RIG, the site value is one of the values that can be used to filter the list down when searching for a specific Nectar Foundation instance.

Description

• The description value is informational only. It is not used for any functional purpose by the RIG itself.
• It should be used to provide a useful and unique general description of the RIG or PA.
• When looking through lists of distributed RIGs on a CIP or EIP, or PAs on a CIP, EIP, or RIG, the description value is one of the values that can be used to filter the list down when searching for a specific Nectar Foundation instance.

Server Name

• The server name value provides a unique identity for the two services associated with a RIG installation. The installer automatically generates a server name value to use, based on the first MAC address it finds on the system along with an epoch millisecond value for the current time.
• While a custom server name value can be provided, it is not recommended.
• The values that are configured in the etc/server.properties file and the backup/etc/ server.properties are not identical, but they do use the same base value. The RIG and its connected CIP/EIP, or the PA and its connected RIG, require these values to be configured in a specific manner:
  • Server name values must not contain spaces.
  • More critically, the backup server name value configured in backup/etc/ server.properties must be the same value as the main server name value configured etc/server.properties, with -backup appended.

For example, if the main server name value is A9-D3-43-2C-2A-9E-1457312818, then the backup server name value should be A9-D3-43-2C-2A-9E-1457312818-backup.

Destination CIP Address (RIG Only)

• The destination CIP address value provides the address or name of the CIP or EIP system to which the RIG connects.
• This value is configured for a RIG using the same properties files and key names as are used by a PA for the RIG address.

RIG Address (PA Only)

• The RIG address value provides the address or name of the RIG system to which the PA connects.
• This value is configured for a PA using the same properties files and key names as are used by a RIG for the destination CIP address.
• By default, the installer uses a special name, perspectiveController, as the RIG address. This triggers the PA to perform a specific DNS lookup to find the RIG to which it should connect. For more information, see Perspective Administration and User Guide.

RIG: Destination CIP Port (RIG Only)

• The destination CIP port value provides the port the RIG should use when connecting to the CIP or EIP configured as the destination CIP address.
• This value is configured for a RIG using the same properties files and key names that are used by a PA for the RIG port.

RIG Port (PA Only)

• The RIG port value provides the port the PA should use when connecting to the RIG configured as the RIG address.
• This value is configured for a PA using the same properties files and key names as are used by a RIG for the destination CIP port.

User Name

• The username value is configured with an initial default value used in two ways:
  • It is used by the RIG or PA when connecting to the associated CIP or EIP, or RIG, (as configured in the infospot.properties files).
  • It is used to allow initial connectivity to the RIG or PA, from the associated CIP or EIP, or RIG, or from a RIG client (as configured in the server.properties files).
• The default values should be changed only if it is known in advance that the CIP or EIP to which the RIG will connect, or the RIG to which a PA will connect, utilize a different default username from the standard default username values.
• The standard default username values differ between a RIG and a PA.

Password

• The password value is configured with an initial default value used in two ways:
  • It is used by the RIG or PA, when connecting to the associated CIP or EIP, or RIG, (as configured in the infospot.properties files).
  • It is used to allow initial connectivity to the RIG or PA from the associated CIP or EIP, or RIG, or from a RIG client (as configured in the server.properties files).
• The default values should be changed only if it is known in advance that the CIP or EIP to which the RIG will connect, or the RIG to which a PA will connect, utilize a different default password from the standard default password values.
• The standard default password values differ between a RIG and a PA.
• The password value is initially configured as plain text in the infospot.properties and the server.properties files. Once the main or backup service starts, the plain text values are converted and updated in these files to encrypted values.
  • An encrypted value is denoted by a hash value enclosed in parentheses and prefixed with ENC, for example, ENC(V/PPNKMDk2oRJ472CYz1hR7ggiu7VkS2jBTsBh2Ww08\=).
  • The encryption is one-way, so it is technically not possible to decrypt the password if lost or forgotten.
  • The password values can be reset to plain text values in the infospot.properties and server.properties files. Once changed to plain text values, the associated service must be re-started to pick up the updated password.

Note

When resetting the username and password values, it may be necessary to remove any authChallenge key/value from the etc/server.properties file in order for the RIG to re-connect to the CIP or EIP.

Bind Address

• The bind address value is used by the RIG to bind to any IP address on the system, or to a specific address on the system.
• To allow the RIG to listen on any IP address on the system, enter * as the bind address value.
• When stacking, * can be used, or a specific IP address can be selected.

Note

The bind address value selected has implications for the port values used.

• For example, if there is a dedicated network interface for every stacked RIG, then an explicit and unique IP address can be selected for each stacked RIG installation, and the default port values can be used (unless there are port conflicts with the system itself).
• However, if * is used for the bind address for two or more stacked RIGs, then those stacked RIGs must use unique port values (or use * to select an ephemeral port or disable the associated service, if supported).

Mother Port

• The mother port value is used by the RIG to provide an HTTPS connection to which the RIG client can connect.
• When stacking, the mother port values used must be unique across all stacked RIGs (taking the bind address values into account) and on the system itself.
• It is also important to take any firewall configuration into account. To access the RIG via a RIG client from another system, the firewall on the system on which the RIG is installed must be configured to allow connectivity to the mother port.

Server Port

• The server port is used by the RIG to provide an HTTP connection, through which the RIG client can be downloaded. For example, if the default server port value of 80 is retained for a RIG installed on a server with IP address 192.168.1.55, the client is accessible via http:// 192.168.1.55:80.
• When stacking, the server port values used must be unique across all stacked RIGs (taking the bind address values into account) and on the system itself.
• It is also important to take any firewall configuration into account. To access the RIG via a RIG client from another system, the firewall on the system on which the RIG is installed must be configured to allow connectivity to the server port.

Telnet Port

• This is the port value used by the RIG to host a Telnet service.
• To use an ephemeral port value, enter * as the port value.
• Typically, for a single installation, the default value can be used. Be aware of any pre-existing Telnet servers on the same system, which could result in a port conflict.
• When stacking, the values used for the different stacked RIGs must be unique (taking the bind address values into account), unless an ephemeral port value is specified.
• Telnet is used for connectivity from a CIP/EIP to the RIG, so it cannot be disabled. If there are potential port conflicts, enter * to use an ephemeral port.

SSH Port

• This is the port value used by the RIG to host an SSH service.
• To force the RIG to not start the SSH service, enter * as the port value.
• Typically, for a single installation, the default value can be used. Be aware of any pre-existing SSH services on the same system that could result in a port conflict.
• When stacking, the values used for the different stacked RIGs must be unique (taking the bind address values into account), unless the SSH service is disabled by using * as the port value.

FTP Port

• This is the port value used by the RIG to host an FTP service.
• To force the RIG to not start the FTP service, enter * as the port value.
• Typically, for a single installation, the default value can be used. Be aware of any pre-existing FTP services on the same system that could result in a port conflict.
• When stacking, the values used for the different stacked RIGs must be unique (taking the bind address values into account), unless the FTP service is disabled by using * as the port value.

Socket Port

• This is an internal port value.
• The default value is * and should not be changed.

Feedback, Overrides, and Blocks - Windows

Note

The following examples are not inclusive of all the possible override or block scenarios.

Pay close attention to the feedback provided on the installer dialogs (or in command line and/or log output for operations executed in silent mode).

Feedback Types

There are four types of feedback:

Table C-1 Feedback Types

GUI Components

The override check boxes are on a single row on the lower area of the GUI dialogs. The check boxes can change. A different set can be shown for a new installation and an existing installation. Also, some check boxes are dynamic. Some are displayed but disabled; only enabled when necessary, while others are not displayed at all until necessary.

The Feedback row has the ability to show multiple feedback lines. Only one line is displayed at a time, but they cycle. If there are multiple feedback lines, a different line is displayed about every five seconds. Two left/right arrow buttons located to the far right of the Feedback row are enabled when there is more than one feedback line. This allows the user to manually cycle through the feedback.

Information only detail provides information about the new or existing installation being targeted. The Details appear on the row above the row of Overrides check boxes.

The following example shows the initial dialog for a new installation with Details, Overrides, and

Feedback components highlighted.

Figure C-4 New Installation

The following example shows the initial dialog for a new installation with at least one existing installation and override and feedback components highlighted.

Figure C-5 New Installation With an Existing Installation

The following example shows the initial dialog for modifying (in this case, uninstalling) an existing installation, with override and feedback components highlighted.

Figure C-6 Modifying an Existing Installation (Uninstalling)

The following example shows a prompt dialog for installation data, with Feedback components highlighted. This type of dialog does not contain Details or Overrides row, but it does contain Feedback components.

Figure C-7 Feedback

The following example shows a prompt dialog for installation data with Feedback components highlighted. It also contains feedback about a bad field value. This type of dialog does not contain Details or Overrides row, but it does contain Feedback components.

Figure C-8 Feedback - Bad Field Value

Architecture Override and Block

The installer will block when attempting to use a 64-bit installer on a native 32-bit system. View the following example that shows the Feedback line indicating BLOCKED and the disabled Next button.

Figure C-9 Install Block

Note

Nectar no longer supports 32-bit installations.

Command-Line Architecture Override

The overrideArch command line option can be used to pre-select the Architecture override check box for GUI mode installations and upgrades. It also provides a means to bypass architecture compatibility checks for silent mode.

When used in silent mode, any output, including that logged to the installer log file, indicates that architecture compatibility checking failed, but it also indicates that the checks were overridden, allowing the installation or upgrade to proceed.

The following is an example command of a silent upgrade using a previously extracted installer with the overrideArch option specified:

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- silent --upgrade --target-path "C:\Apps\nectar_4" --arch-override

Memory Override

The installer allows an override when the detected system memory is insufficient for the installation type selected. For a RIG installation, there is currently no minimum memory requirement. However, a PA requires 4GB (Centos) or 8GB (Windows) of system memory. The following two examples depict this.

If the detected system memory does not meet the requirement, the Memory override check box is enabled (see Figure C-10). The Feedback line details the memory detected and the memory requirement. The Next button is disabled.

Figure C-10 Memory Override - Problem

Figure C-11 shows the checked Memory override check box and the enabled Next button.

Figure C-11 Memory Override - Resolved

Command-Line Memory Override

The overrideMemory command line option can be used to pre-select the Memory override check box for GUI mode installations and upgrades and provides a means to bypass memory requirement checks for silent mode.

When used in silent mode, any output, including that logged to the installer log file, indicates that memory checking failed, but it also indicates that the checks were overridden, allowing the installation or upgrade to proceed.

The following is an example command of a silent upgrade using a previously extracted installer, with the overrideMemory option specified:

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- silent --upgrade --target-path "C:\Apps\nectar_4" --memory-override

Disk Space Block and Override

The installer will block when attempting to install to the root directory of a drive. This is input feedback with the root location as an invalid value. It does not appear as BLOCKED, but the installer is blocked from proceeding. The Next button is disabled until a valid installation directory is entered. View the following example.

Figure C-12 Disk Space - Problem

The installer will not allow an installation or upgrade when the detected disk space is insufficient for the selected operation. The installer determines:

• Available space on the target disk drive for an installation or upgrade.
• Space currently in use by an installation for an upgrade.
• Amount of space required for the specific operation selected.

If the amount of available disk space does not meet the required space for the operation, the Disk Space override check box remains disabled. The Feedback line details the disk space detected and the disk space requirement. The Next button is also disabled. View the following example.

Figure C-13 Disk Space - Problem

Note

This blocking behavior can be bypassed using the overrideDisk command line option. However, this should be used cautiously when there is sufficient disk space on the specified disk drive, but the installer has detected insufficient disk space.

Command-Line Disk Space Override

The overrideDisk command line option can be used to pre-select the Disk Space override check box for GUI mode installations and upgrades and provides a means to bypass disk space requirement checks for silent mode.

When used in silent mode, any output, including that logged to the installer log file, indicates that disk space requirement checking failed, but it also indicates that the checks were overridden, allowing the install or upgrade to proceed.

The following is an example command of a silent upgrade using a previously extracted installer, with the overrideDisk option specified:

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- silent --upgrade --target-path "C:\Apps\nectar_4" --disk-override

Version Override

The installer allows an override when attempting to upgrade an installation that is not older than the version bundled in the installer. Figure C-14 shows the Version override check box, associated Feedback, and the disabled Next button.

Figure C-14 Version - Problem

Figure C-15 shows the checked Version override check box and the enabled Next button.

Figure C-15 Version - Resolved

Command-Line Version Override

The overrideVersion command line option can be used to pre-select the Version override check box for GUI mode installs and upgrades and provides a means to bypass version checks for silent mode.

When used in silent mode, any output, including that logged to the installer log file, indicates that version checking failed, but it also indicates that the checks were overridden, allowing the installation or upgrade to proceed.

The following is an example command of a silent upgrade using a previously extracted installer, with the overrideVersion option specified:

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- silent --upgrade --target-path "C:\Apps\nectar_4" --version-override

JRE Override

The installer allows an override when attempting to upgrade an installation that is running a different JRE architecture than the JRE bundled in the installer. Figure C-16 shows the JRE override check box, associated Feedback, and the disabled Next button.

Figure C-16 JRE - Problem

Figure C-17 shows the checked JRE override check box and the enabled Next button.

Figure C-17 JRE - Problem

Note

The JRE check box only appears when there is a potential incompatibility detected.

Command-Line JRE Override

The overrideJre command line option can be used to pre-select the JRE override check box for GUI mode installations and upgrades and provides a means to bypass JRE architecture compatibility checks for silent mode.

When used in silent mode, any output, including that logged to the installer log file, indicates that JRE architecture compatibility checking failed, but it also indicates that the checks were overridden, allowing the installation or upgrade to proceed.

The following is an example command of a silent upgrade using a previously extracted installer, with the overrideJre option specified:

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- silent --upgrade --target-path "C:\Apps\nectar_4" --jre-override

Type Block

The installer will block when attempting to upgrade an installation whose type is not compatible with the installer.

View the following example where the existing installation is detected to be a CIP. The Feedback

line indicates BLOCKED, and the Next button is enabled.

Missing Files Block

Figure C-18 Type Block

The installer will block an upgrade to an existing installation, if it detects missing critical files. The installer recognizes an installation by scanning the Windows services for a specific signature. The installation must also have the following properties files that are critical to the service:

• rigWrapper.properties
• etc/infospot.properties
• etc/server.properties
• backup/rigWrapper.properties
• backup/etc/infospot.properties
• backup/etc/server.properties

If any of these files are not found, the upgrade operation will be blocked.

View the following example that shows the Feedback line that indicates BLOCKED and the Next

button is disabled.

Input Feedback

Figure C-19 Missing Files Block

The installer validates the values entered into most of the fields it displays. Some fields are validated to ensure that an actual value is entered, and the field is not empty. Other fields are validated to verify the value against internal requirements. For example, if installing a new installation on a system where at least one other installation occurs, all of the installation directory or service name and description fields must be unique from the values used by any other installation. Port values are validated against their respective valid values.

When input validation fails, the field value is highlighted in red, a corresponding Feedback line is displayed, and the Next button is disabled. Once the field value is corrected, the Next button is enabled, and the installation can proceed.

Figure C-20 shows input feedback for the Installation Directory field.

Figure C-20 Input Feedback - Installation Directory

Figure C-21 shows input feedback for the Description field. The other highlighted fields indicate additional feedback. (In this example, an existing installation is already using these five port values.) The Feedback lines will cycle, changing about every five seconds, so that each Feedback line is displayed. The left/right arrow buttons to the far right of the Feedback line can be used to manually cycle through the feedback lines. The Next button is disabled. It will be enabled when all input validation issues are resolved.

Figure C-21 Input Feedback - Description

Installation Details

Detailed information for existing installations can be viewed by double-clicking on an associated row in the existing installations list, or click in the Details cell of the existing installation row (see Figure C-22).

Figure C-22 Detailed Information - Existing Installation

Figure C-23 shows the Installation Details:

Figure C-23 Installation Details

The three Main fields and three Backup fields may display with a different background color. This indicates that something is flagged against one or both of the main or backup services for the associated installation. If highlighted, there should be corresponding information highlighted in the Details dialog content (see Figure C-24).

Figure C-24 Installation - Different Background

Figure C-25 shows the installation details:

Figure C-25 Installation Details

Start Services Checkbox

During a new installation, the installer by default starts both the main and backup services as part of the installation. The behavior can be modified by unchecking the Start Services checkbox.

Figure C-26 Start Services - Checked

If not checked, the services will not be started as part of the installation and will have to be started manually or automatically following a reboot.

Figure C-27 Start Services - Not Checked

Command Line No Start Services Option

The noStart command line option can be used to force the installer to not Start Services

following a new installation. This can be used in both silent and GUI modes.

In GUI mode, it un-checks the Start Services checkbox for a new installation.

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat --no- start

Advanced Checkbox

The Advanced checkbox can be used during a new installation or an upgrade.

For a new installation, check the Advanced checkbox to enable the installer to display additional configuration fields on the Enter Info dialog.

Figure C-28 New Installation - Advanced Checkbox

For an upgrade, check the Advanced checkbox to enable an additional Reset Service(s)

checkbox on Windows.

Figure C-29 Target Existing Installation - Advanced Checkbox

Figure C-30 Advanced Checkbox with Reset Service(s)

Reset Services(s) Checkbox

The installer's handling of existing services during an upgrade differs between Windows and Linux.

• On Linux, the service(s) associated with the upgrade of an installation are uninstalled before the installation files are upgraded; then reinstalled after the installation files are upgraded, all as part of the upgrade process.
• On Windows, the service(s) associated with an installation by default are NOT uninstalled and re-installed as part of the upgrade process. This retains any custom authorization configuration that is manually added to the services.

Note

Removing the services will cause loss of the custom configuration.

The Reset Service(s) checkbox can be used to alter the default behavior of the installer under Windows.

Figure C-31 Target an Existing Installation - Advanced

If checked, the installer uninstalls and re-installs the service(s) for an upgrade of an installation.

Figure C-32 Reset Service(s)

Command Line Reinstall Services Option

The reinstallServices command line option can be used to force the installer to reinstall or reset services during an upgrade. This can be used in both silent and GUI modes.

In GUI mode, it pre-selects the Reset Services checkbox for an upgrade. This option is only applicable to Windows installer.

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -- reinstall-services

Correct Name Checkbox

Some partner service names were originally left unbranded, e.g., NectarRIG and

NectarRIGBackup instead of something like PartnerRIG and PartnerRIGBackup.

The installer detects based on an internal installer property, which is set/enabled only for partners who originally had incorrect service names. It was also enhanced in GUI mode to not automatically correct service names. Instead, if enabled, and an incorrect service name is detected, a Correct Names check box appears in the Overrides check box row when Upgrade is selected.

Figure C-33

On Windows, the Reset Service(s) check box also appears, and must be checked to enable the

Correct Names check box. On Linux, only the Correct Names check box appears.

Figure C-34

When checked, the Main Name and Backup Name for the associated installation appears with the corrected name. Pressing Next to proceed with and ultimately complete the upgrade results in the main and/or backup service name being corrected, depending on which of Main, Backup, or Both services are targeted for the upgrade.

Command-line Correct and Do Not Correct Service Names Options

The correctServiceNames and doNotCorrectServiceNames command line options are used to override the default installer property controlling whether the installer detects and corrects incorrect service names. The correctServiceNames option forces the installer to detect incorrect service names, and if found, correct them when upgrading an associate service/ installation. The doNotCorrectServiceNames option forces the installer to not detect incorrect service names, and therefore not perform corrections.

For Windows, the correctServiceNames option must be specified along with the reinstallServices option in order for service name detection and correction to function. It is not necessary to specify the reinstallServices option on Linux.

C:\Users\Administrator\Desktop\NECTAR-CMP-PA-Installer-8.6>installer.bat -do- not-correct-service-names --reinstall-services

Upgrade Failures and Rollbacks

Rollback Concepts

In the event of a file copy failure during the upgrade process, the installer provides a simple approach to reverting to the previous installed state: rollback directory.

During an upgrade, the new files in the installer are scanned, with only a subset of those files eligible for upgrade. If any of those files already exist in the installation directory, the current/ installed versions of the files are copied into the rollback directory located in the install location. In addition, some items, such as the jre subdirectory, are copied into the rollback directory; then deleted from the install directory to allow for the new jre subdirectory that is included with the installer.

The installer maintains up to 11 rollback directories:

base rollback directory and up to 10 additional directories labeled rollback.0, … rollback.9

The installer copies the existing files into the rollback directory during the upgrade. However, prior to upgrading, any existing rollback directory will be renamed to rollback.0, with an existing rollback.0 directory renamed to rollback.1, etc., up to rollback.9.

Support for multiple rollback directories was added to support upgrading one service, main or backup, at a time, and provided that rollback content was available for each phase of the two- part upgrade.

It is possible for upgrade-eligible files to be locked, because they are executing or open by another process. In this case, the attempt to copy the new file into place during the upgrade fails.

The installer keeps track of the failed copies. If any are detected, it lists the failed files in the output on the upgrade dialog, as well as in the installer log file at C:\nectar_installer.log. If this occurs, the installer output indicates a failure. At this point, there are two ways to proceed to return the system to its previous state:

• Perform an Automated Rollback (GUI Mode Only)
• Perform a Manual Rollback

Perform an Automated Rollback (GUI Mode Only)

The installer indicates a failure during copy operations.

Figure D-35 Failure During Copy Operation

Follow this step to perform an automated rollback:

1. Click Rollback.

The Upgrading Installation window updates to indicate when rollback completes.

Figure D-36 Automatic Rollback

Note

If you exit before performing the rollback, the only alternative to recover the upgrade is to perform a manual rollback.

For more information, see Perform a Manual Rollback.

Perform a Manual Rollback

If a manual rollback is necessary, it is almost certain that one or both services are no longer installed. Following the manual rollback, the services will have to be re-installed manually.

• In Windows mode, a manual rollback is necessary when Exit is selected instead of Rollback, skipping the opportunity to perform an automated rollback. For more information on automated rollback, see Perform an Automated Rollback (GUI Mode Only).
• In Silent mode, the installer does not provide an option to perform an automated rollback, so the only recourse when the upgrade fails is to perform a manual rollback.

The manual rollback process involves copying all files and directories in the rollback directory up one level to the install directory. This can be accomplished using the Windows command prompt (with administrative privileges) and the Windows xcopy command.

In the following example, xcopy is issued from the install directory with parameters rollback and .

plus /E /F /R /Y to copy all files and directories in the rollback directory to the current directory.

C:\Apps\nectar>xcopy rollback . /E /F /R /Y

Performing a manual rollback from the command line is the recommended method, because it allows visual confirmation of the files being restored, or possible errors while restoring.

Care should be taken with the rollback directory contents. You can delete them once an install is completed. However, if kept, they could potentially be used to revert an installation at a later time. In this case, care should be taken to ensure that the appropriate services are stopped before performing a manual rollback, to ensure that no files are open during the copy process.

As stated earlier, the rollback directory contains the most recent rollback files. The next most recent is labeled rollback.0, continuing up to rollback.9. In the case of a two-stage upgrade, where backup service and main service are upgraded individually, there will be at least two rollback directories: rollback for the last upgraded service and rollback.0 for the next-to-last upgraded service.

To re-install the main service using Server.exe, refer to the following example:

C:\Apps\nectar>Server.exe -install

This example installs:

• Main service using the command: C:\Apps\nectar\Server.exe
• Nectar RIG Server as a Windows service.

To re-install the backup service using backup\BackupServer.exe, refer to the following example:

C:\Apps\nectar\backup>BackupServer.exe -install

This example installs:

• Backup service using the command: C:\Apps\nectar\backup\BackupServer.exe
• Nectar RIG Backup as a Windows service

Once re-installed, the services can be restarted using one of the following:

• Windows Services window
• Manually using the Windows command prompt

Repeat or Perform Another Operation

After completing a GUI-based installer operation, the installer may present the Again button.

Figure E-37 Perform Another Operation

Click Again to cause the installer to re-initialize (re-scan the system to pick up any changes recently made); then present the user with an initial installer window, allowing another new installation, upgrade, or uninstall to be performed.

Note

The License dialog is skipped when using the Again button.

Linux Services and the server.sh Script

Linux Services

The Linux installer fully supports both init.d and systemd. If installed on a system on which the init system is init.d, it installs the services under the init.d init system. If installed on a system on which the init system is systemd, it installs the services under the systemd init system.

With Nectar Foundation services being implemented under two different init systems - with two different command sets for working with services - the server.sh script was implemented as a common means to manage Nectar Foundation services independent of the underlying init system.

init.d Services (CentOS 6.x)

Nectar Foundation init.d services are implemented as init.d scripts. Nectar Foundation used two scripts, rig and rig-backup, that were installed under /etc/init.d. These scripts, which are executed either directly or through the service command, control the execution of the services for the Nectar installation under /opt/rig. The chkconfig command is used to enable or disable the services.

Stacking is supported. The installed init.d scripts use the service names as the file names of the init.d scripts. Template scripts called rig and rig-backup are bundled with the installer, but they are installed using the actual service names. For example, the default service names for a non-branded installer are NectarRIG and NectarRIGBackup. The installer would therefore install init.d service scripts /etc/init.d/NectarRIG and /etc/init.d/NectarRIGBackup.

systemd Services (CentOS 7.x)

Nectar Foundation systemd services are implemented as systemd unit files. The Nectar installer bundles two service unit template files, rig.service and rig-backup.service. These files are renamed using the actual service names, e.g., NectarRIG.service and NectarRIGBackup.service, and installed to /usr/lib/systemd/user.

The primary command for working with system services is systemctl. This command is used to enable, disable, start, and stop services as well as to list service status.

server.sh Script

The server.sh script is intended to be a common script command to work with Nectar Foundation services, regardless of the underlying init system or how the Nectar Foundation services are installed. Its syntax is similar to that of the legacy service command for working with init.d services.

Below is an example of help for the server.sh script:

Generally, server.sh requires specification of a service(s) to target. There are multiple ways a target service(s) can be specified:

• Using the main, backup, or both service tags - In order to use these service tags to identify a service, server.sh also needs to know the actual service names. It determines service names by the content of the install.properties file. To find this, it needs to know the associated installation directory. An installation directory can be specified using the path option. Otherwise, the current working directory is the installation directory. If the server.sh script cannot find the install.properties file, then it will be unable to proceed using these service tags. Examples:
  • From any directory:

/opt/support/ucf/nectar/8.6/server.sh path /opt/ucf/nectar main status

• 
  
  • Executed from within an actual installation directory, e.g., /opt/ucf/nectar:

server.sh status both

• Using the name option - A service name can be specified using the name option. While the service name should not generally contain spaces, if it does, then the name will need to be enclosed in double-quotes. For example:
  • For service name NectarRIG:

server.sh name NectarRIG status

• 
  
  • For service name NECTAR RIG SERVICE:

server.sh name "NECTAR RIG SERVICE" status

When executed with no options, the server.sh script presumes the list option. To list details for all Nectar Foundation services found:

As seen in the output above, the list output produces a table-like list of the services found. The list is wide, so lines may wrap. The following table provides the columns produced in the output:

Table F-2 List Output

When the server.sh script is used to perform an action against a service, the output includes the actual command executed by the script, the output from the executed command, and the exit code of the executed command.

For example: