Installing and Configuring the Agent

This chapter provides instructions for installation and initial configuration of the Nectar Endpoint Client Agent on a Windows system.

Running the Nectar Endpoint Client Agent Setup Wizard

For installation on Windows systems, the Nectar Endpoint Client Agent installation software is provided as an executable file that includes a menu-driven setup wizard to assist in installing the Nectar Endpoint Client Agent and configuring the agent for initial use. 

After installation, right click the Endpoint Client Utility icon and select settings to edit the agent's configuration or uninstall the agent (see Uninstalling the Agent).

 To begin the installation of the Nectar Endpoint Client Agent:

1. If you have not done so already, save the Nectar Endpoint Client Agent setup executable to a directory on the host system where the Nectar Endpoint Client Agent will be installed.

2. In Windows Explorer, double-click the file name to launch the Nectar Endpoint Client Agent setup wizard. 

3. On the setup wizard welcome screen, click Next to continue. 

   

4. On the End-User License Agreement screen, after reading the terms of the software license agreement, select I accept and then click Next.

   

5. The Ready to Install screen displays that agent configuration can be handled using the system tray icon after setup.

   

6. Next, the Endpoint Client will install.

7. Now, the Agent Identification screen will appear. The following steps will configure each field:

   

   1. The Agent Name field indicates the name that will be displayed in the Controller interface when the agent connects to the Controller. Enter “^^u” to automatically report the logged in username at the time of a given test execution.

   2. The Agent Description field is an optional field that can be used to identify the agent or indicate a location such as a city, location/zip code, office name, floor, network, etc.

   3. Enter the provided Organization ID and Group ID (same for all agents) to assign the agent to its corresponding resource group and license key. For assistance in retrieving the IDs, contact support@nectarcorp.com or your support partner.

   4. Under Management Domain, enter the provided Domain Name and Passphrase (same for all agents) for the administrative domain to which this Nectar Endpoint Client Agent will be assigned. For assistance in retrieving these fields, contact support@nectarcorp.com or your support partner.

   5. Under Controller Connectivity, enter the Address as “neccontroller.us.nectar.services” and enter port “443”, and check the Fixed box.

   6. Test the connection by clicking Test. The Log will indicate whether the connection attempt to the specified address was successful by displaying “Reachable [OK}”. If the connection is unsuccessful, confirm that the IP address/hostname and port are correct and that the Controller is running.

   7. Last, click “Apply Settings”. The button will appear greyed out, and the settings will be sent to the controller.

      
      

8. The Endpoint Client Utility will now appear in your system tray:

   

9. Right click on the icon to display the status menu, or to reconfigure the client’s settings. (Bandwidth metrics will not immediately appear)

Silent Installer

You can run this command from your computer or some kind of push program. Be sure you have a copy of the installer in the target directory when running it. Modify the following to match your deployment:

• NectarEPClientInstaller64-3.1.156.exe - change the version to match the one to be deployed

• AGENT_ORGID=YOURORGID - modify to match your organization ID

• AGENT_GRPID=YOURGRPID - modify to match your group ID 

• MGMT_DOMAIN_PASS=YOURPASSPHRASE - modify to match your organization domain passphrase

There are 4 main commands for installing the Endpoint Client, with options for a fresh installation vs. an upgrade, and for whether the system tray icon will be visible

Fresh Installation with System Tray

NectarEPClientInstaller64-3.1.156.exe /s /v"/qn AGENT_NAME=^^u AGENT_ORGID=YOURAGENTORGID AGENT_GRPID=YOURGROUPID MGMT_DOMAIN_PASS=YOURDOMAINPASS MGMT_DOMAIN_NAME=nectarusprod CONTROLLER_CSV=neccontroller.us.nectar.services AGENT_LOG_LEVEL=DEBUG"

Upgrade with System Tray

NectarEPClientInstaller64-3.1.156.exe /s /v"/qn REINSTALLMODE=vomus REINSTALL=Nectar_x64_Binaries ADDLOCAL=Nectar_x64_Tray AGENT_NAME=^^u AGENT_ORGID=YOURAGENTORGID AGENT_GRPID=YOURGROUPID MGMT_DOMAIN_PASS=YOURDOMAINPASS MGMT_DOMAIN_NAME=nectarusprod CONTROLLER_CSV=neccontroller.us.nectar.services AGENT_LOG_LEVEL=DEBUG"

Fresh Installation without System Tray

NectarEPClientInstaller64-3.1.156.exe /s /v"/qn INSTALLTRAY=0 AGENT_NAME=^^u AGENT_ORGID=YOURAGENTORGID AGENT_GRPID=YOURGROUPID MGMT_DOMAIN_PASS=YOURDOMAINPASS MGMT_DOMAIN_NAME=nectarusprod CONTROLLER_CSV=neccontroller.us.nectar.services AGENT_LOG_LEVEL=DEBUG"

Upgrade without System Tray

NectarEPClientInstaller64-3.1.156.exe /s /v"/qn REINSTALLMODE=vomus REINSTALL=Nectar_x64_Binaries ADDLOCAL=ALL INSTALLTRAY=0 AGENT_NAME=^^u AGENT_ORGID=YOURAGENTORGID AGENT_GRPID=YOURGROUPID MGMT_DOMAIN_PASS=YOURDOMAINPASS MGMT_DOMAIN_NAME=nectarusprod CONTROLLER_CSV=neccontroller.us.nectar.services AGENT_LOG_LEVEL=DEBUG"

Uninstalling the Agent

To uninstall the Nectar Endpoint Client Agent, from the Windows Control Panel, open the Apps & Features menu. In the list of installed programs, locate and select Nectar Endpoint Client Agent and then click Uninstall.   

Ports and Protocols

During setup, the Nectar Endpoint Client Agent setup wizard will offer to automatically create Windows firewall exceptions for the ports used by the agent and Controller. If you disable this option or are using a third-party firewall, ensure that the following local and remote ports are open in your firewall configuration to allow the agent to function properly.

Local Ports:

Remote Ports:

* Default port number. A different port number can be assigned during setup/configuration of the Controller (see the Nectar EPC-Controller SSE Installation Guide or Nectar EPC-Controller MSE Installation Guide for details).

Test Interface IP Addressing

When running an active test on an agent, it is necessary to select a specific local interface and IP address to be used as the test interface. It is therefore strongly recommended that a static IP address be assigned to any network interface that will be used to run tests, rather than using DHCP to assign addresses automatically. If dynamic addressing is used and a test interface IP address changes, it will cause all tests currently running on the old IP address to fail, along with any tests scheduled to run using the old IP address.

Dynamic or static IP assignment can be used for the management domain interface used to communicate with the Controller, if it is a dedicated interface that will not be used to run tests. For any interface that will be used as a test interface, static IP addressing is advised.

Troubleshooting

This section provides recommended steps for troubleshooting common agent installation and operation issues.

Diagnosing Unexpected Agent Behavior

Each time the Agent is started, a new Syslog-style log file, C:\Windows\System32\config\systemprofile\AppData\Local\Nectar\EPClient\Agent directory.  This log file may be examined in the event of a problem with the operation of the agent. Up to the last 10 log files are preserved in rotation (named nectarpc.0 through nectarpc.9). You may be asked to provide these log files to Nectar Support.

Agent Will Not Connect to the Controller

If the agent has been configured with the address and port number for the Controller but is unable to connect to the Controller, a firewall on the Controller host may be blocking connections on the port used to listen for incoming agent connections (default is TCP 443). Ensure that the firewall on the Controller host is configured to allow connections on this port, or as an alternative, try to manually add the agent in the Nectar EPC-Controller Reporter UI. 

Instructions for configuring the Linux firewall using firewalld in Red Hat Enterprise Linux/CentOS 7.x or iptables in RHEL/CentOS 6.x are provided as an appendix in the Nectar EPC-Controller SSE Installation Guide and Nectar EPC-Controller MSE Installation Guide.

Problems Running Tests

If the agent was installed and configured successfully but is unable to execute tests, check to make sure that the agent is not being blocked by the firewall. For a list of ports that must be open for the agent to function properly, refer to Ports and Protocols.