Document toolboxDocument toolbox

Remote Agent Installation, Configuration and Upgradation

Owned by Jonas Gonzalez
Last updated: Nov 29, 2024
5 min read
[ 1 Installing the Remote Agent (version >= 2.2.1) ] [ 1.1 Unix ] [ 1.1.1 Install and Run the Agent ] [ 1.2 Windows ] [ 1.2.1 Install and Run the Agent ] [ 1.3 Verifying the Installation ] [ 2 Configuration ] [ 2.1 Unix ] [ 2.1.1 Install and Run the Agent ] [ 2.2 Windows ] [ 2.2.1 Install and Run the Agent ] [ 3 Upgrade Remote Agent ]

Installing the Remote Agent (version >= 2.2.1)

You can download and install the remote agent on a Unix or Windows system.

For Unix, the system must have systemd and minimum glibc version 2.12. To check the glibc version, run the command

ldd --version

The remote agent package for Unix contains the following files.

Remote agent package for Unix

lhub-remote-agent/ |____ remote-agent-supervisor : The executable supervisor application to manager agent. |____ remote-agent : The executable agent application. |____ agent.config : The agent configuration file. |____ install_and_run.sh : The script to install and run the agent.

The remote agent package for Windows contains the following files.

Remote agent package for Windows

lhub-remote-agent/ |____ remote-agent-supervisor : The executable supervisor application to manager agent. |____ remote-agent : The executable agent application. |____ agent.config : The agent configuration file.

  • remote-agent-supervisor is the executable supervisor application which manages the agent.

  • remote-agent is the executable agent application.

  • agent-config is the agent configuration file.

To download a remote agent package to a Unix or Windows system:

  1. On the Settings > Advanced Settings page, click the Unix or Windows button for the remote agent. A zip file containing the remote agent software is downloaded to your local system.

  2. Unzip the file to a convenient location.

Unix

Follow the steps to install and upgrade the remote agent for Unix.

Install and Run the Agent

  1. Navigate to the directory on the Unix system that contains the unzipped remote agent package.

  2. Run the following script as root. The script sets up the remote agent as a Unix service and starts it.

sudo bash install_and_run.sh

Windows

Follow the steps to install and upgrade the remote agent for Windows.

Install and Run the Agent

  1. Navigate to the Windows folder that contains the unzipped remote agent package.

  2. Open a command window and run the following commands. The first command installs the remote agent as a Windows service, and the second starts the remote agent.

.\remote-agent-supervisor --startup=auto install
.\remote-agent-supervisor start

Minimum Requirement for Windows Version

The remote agent requires Windows Server 2016 or newer.

You can manage the remote agent as you would for any other Unix or Windows service. By default, the agent restarts automatically when the system reboots.

Verifying the Installation

After executing above step please check for the following

  1. The supervisor.log file should have these lines

``` {text}2022-07-19 09:47:00.691 INFO agent_win_service.py:SvcDoRun:42 [Dummy-2] - Started Logichub Remote Agent Supervisor. 2022-07-19 09:47:00.695 INFO commands.py:restart:26 [Thread-1] - Initializing remote agent restart process 2022-07-19 09:47:00.702 INFO commands.py:restart:28 [Thread-1] - Remote agent client termination complete 2022-07-19 09:47:03.908 INFO commands.py:start_ra_client:82 [Thread-1] - RA Client Initiated successfully. 2022-07-19 09:47:03.939 INFO supervisor.py:run:76 [Thread-1] - Commands Received: [] 2022-07-19 09:47:03.939 INFO supervisor.py:run:83 [Thread-1] - Sleeping for 180 seconds

2. The `agent.log` file should have these lines ``` {text}2022-07-19 09:47:03.878 INFO agent_win_service.py:SvcDoRun:42 [Dummy-3] - Started Logichub Remote Agent. 2022-07-19 09:47:03.878 INFO StatisticsLogger.py:start_statistics:24 [Thread-2] - scpu: 0.0, smem: 84.68997572926685, cpu: 0.0, mem: 1.947382882264047 2022-07-19 09:47:03.878 INFO socks_server.py:__init__:14 [Thread-1] - Listening to socks5 proxy on 127.0.0.1:9011 2022-07-19 09:47:03.878 INFO lh_client.py:start_websocket:64 [Thread-1] - Attempting to connect to wss://logichub-server:logichub-port/agent/connect with id: RANDOM-ID ... 2022-07-19 09:47:03.878 INFO lh_client.py:listen:107 [Thread-1] - Other event: connecting 2022-07-19 09:47:03.908 INFO lh_client.py:listen:107 [Thread-1] - Other event: connected 2022-07-19 09:47:03.924 INFO lh_client.py:listen:88 [Thread-1] - Connected to Logic hub 2022-07-19 09:47:03.924 INFO stoppable_thread.py:start:29 [Thread-1] - Starting heartbeat stoppable thread 2022-07-19 09:47:03.939 INFO lh_client.py:listen:107 [Thread-1] - Other event: poll 2022-07-19 09:47:03.939 INFO lh_client.py:listen:107 [Thread-1] - Other event: pong 2022-07-19 09:47:08.940 INFO lh_client.py:listen:107 [Thread-1] - Other event: poll 2022-07-19 09:47:08.940 INFO lh_client.py:listen:107 [Thread-1] - Other event: pong 2022-07-19 09:47:13.940 INFO lh_client.py:listen:107 [Thread-1] - Other event: poll

Configuration

  1. SUPERVISOR_FREQUENCY_IN_SECONDS

This property sets the frequency at which supervisor polls the service to fetch for commands. By default it's set to be 3 minutes. It's value should be at least 10 seconds otherwise the remote agent won't work.

On Unix machines the systemd service file will go into error and on Windows machine the supervisor will keep running but the logs will contain this line.

``` {text}2022-07-19 07:03:35.499 ERROR main.py:validate:27 [Thread-1] - Frequency value 1 must be at least 10 seconds. It might overburden service.

  1. HTTPS_PROXY

If your infrastructure doesn't allow direct access to logichub instance from the machine remote agent is installed on then we can specify the above property to route all the HTTPS requests from remote agent to this server.

To check if it's correctly set look for this line in log file

``` {text}2022-07-19 09:44:55.908 INFO main.py:set_proxy:16 [Thread-1] - Setting HTTPS Proxy to be https://www.proxyserver:proxyport.com

  1. NO_PROXY

If you want to avoid proxy for certain URL then the URL should be put here. Ideally, this shouldn't be required since remote agent only try to connect to the logichub instance.

``` {text}2022-07-19 09:44:55.908 INFO main.py:set_proxy:16 [Thread-1] - Setting No Proxy to be https://www.proxyserver:proxyport.com

The remote agent package for Windows contains the following files.

Remote agent package for Windows

  • remote-agent is the executable agent application.

  • agent-config is the agent configuration file.

To download a remote agent package to a Unix or Windows system:

  1. On the Settings > Advanced Settings > Remote Agents page, click the Unix or Windows button for the remote agent. A zip file containing the remote agent software is downloaded to your local system.

  2. Unzip the file to a convenient location.

Unix

Follow the steps to install and upgrade the remote agent for Unix.

Install and Run the Agent

  1. Navigate to the directory on the Unix system that contains the unzipped remote agent package.

  2. Run the following script as root. The script sets up the remote agent as a Unix service and starts it.

sudo bash install_and_run.sh

Windows

Follow the steps to install and upgrade the remote agent for Windows.

Install and Run the Agent

  1. Navigate to the Windows folder that contains the unzipped remote agent package.

  2. Open a command window and run the following commands. The first command installs the remote agent as a Windows service, and the second starts the remote agent.

.\remote-agent --startup=auto install
.\remote-agent start

Minimum Requirement for Windows Version

The remote agent requires Windows Server 2016 or newer.

You can manage the remote agent as you would for any other Unix or Windows service. By default, the agent restarts automatically when the system reboots.

Upgrade Remote Agent

  1. Go to Settings > Advanced Settings > Remote Agents

  2. Download the latest remote agent (compatible with the milestone release) for your operating system.

  3. Keep the logs and agent.config file of the previous remote agent in case you need it.

  4. Remove the old remove agent directory and follow the remote agent installation guidelines.

Check if the remote agent version on the remote agent page is updated.