Starting the RM Agent as a service on Windows

To ensure that the RM Agent starts by itself when the host machine is restarted, you can set up the environment in such a way that the RM Agent can be started as a service.

Before you begin

Previously to starting a Resource Monitoring Agent as a service on Windows, you need to have:

Java 8 installed on the host machine.
HCL OneTest™ Server added to the PATH environment variable.
an offline token to connect the agent securely with appropriate permissions. You can create an offline token from the User menu of the Resource Monitoring dashboard or you can re-use your active offline token. The token expires if it is not used for a month.

Procedure

Set the following environment variable before executing the command line that starts the Resource Monitoring Agent:
```
set HCL_ONETEST_OFFLINE_TOKEN=(Enter your offline token here)
```
Download the latest release of winsw from this page. You can choose to download WinSW.Net2.exe or WinSW.Net4.exe depending on the version of .Net framework that you already have on the host Windows machine.
Create a folder on your local hard drive like RMAgent-winservice.
Copy the downloaded executable to this new folder and rename the file to RMAgent-winservice.exe.
Create a new text file in the same folder and name it RMAgent-winservice.xml.

Copy and adapt the following content to this new file:

<service>
      <id>RMAgent-winservice</id>
      <name>Resource Monitoring Agent</name>
      <description>This service runs the Resource Monitoring Agent, part of the HCL Quality Server provided by HCL.</description>
      <executable>java</executable>
      <arguments>-jar %BASE%\RMAgent.jar --serviceUrl=https://<service-host>/rm --projectId=<projet-id> --trustServiceCertificate --autoUpgradeDownloadThen=execute:cmd,/c,start,%BASE%\auto-upgrade.bat</arguments>
      <onfailure action="restart" delay="10 sec"/>
      <logmode>rotate</logmode>
</service>

Note:

Replace <service-host> by the host name of the machine that runs HCL Quality Server.
Replace <project-id> by the project which is the number you find in the service URL.

Create a new text file in the same folder and name it auto-upgrade.bat.

To upgrade the agent jar file automatically, copy the following content to this new file:

@echo off
for /f "tokens=*" %%a in ('dir /b /od %BASE%\com.hcl.test.rm.agent-*.jar') do set newest=%%a
%BASE%\RMAgent-winservice.exe stop
del %BASE%\RMAgent.jar
mklink %BASE%\RMAgent.jar %BASE%\%newest%
%BASE%\RMAgent-winservice.exe start

Start the command prompt as an administrator and change the directory to the newly created directory RMAgent-winservice.
Download the agent jar file from the Resource Monitoring web page and save it to the same directory.
In the command prompt, type the following command to create a symbolic link named RMAgent.jar to the agent jar file:
```
mklink RMAgent.jar com.hcl.test.rm.agent-<version-and-datetime>.jar
```

Type the following commands:

RMAgent-winservice install

RMAgent-winservice start

In the Services Windows application, you can check whether the service is up and running.
To ensure that the RM Agent is connected with the Resource Monitoring Service, open the Resource Monitoring web page and look at the RM Agents menu.

What to do next

The RM Agents write the logs to the same folder in files named RMAgent-winservice.out.log, RMAgent-winservice.err.log and RMAgent-winservice.wrapper.log. Look at those files if the Windows Service for the Agent is not started or if it does not appear to be connected to the Resource Monitoring Service.

For information about other winsw commands, see its documentation.

Feedback