Agent installation

An AppControl Agent is a key component that enables communication between your infrastructure and the AppControl gateway. It is responsible for executing commands, checking the status of components, and relaying important information to ensure smooth operation and monitoring of your applications.

The agent is designed to be cross-platform, meaning it can be deployed on both Linux and Windows systems, offering flexibility across diverse environments. Furthermore, it is optimized to be lightweight, consuming minimal CPU and memory resources. This ensures that the agent runs efficiently in the background without impacting the performance of the host system.

With a simple installation process and low resource footprint, AppControl Agents are an essential part of managing your applications, regardless of the platform or scale.

Latest Available versions

All binary versions are listed here: All binaries versions

All docker versions are listed here: All docker versions

Microsoft Windows Platform

Note:

We recommand to use cmd.exe as a shell to install the agent. We don't offer the support for installation through powershell.

To install XComponent AppControl Agent under Windows OS, unzip the following file into an installation directory. The configuration file ( config.dat ) is located in the same directory. Refer to the agent configuration section to customize the configuration. You have 2 options:

• Install an run the agent as a Microsoft Windows Service
• Run the agent in interactive mode (in a cmd.exe)

Option 1. Install and start the agent as a Microsoft Windows Service

• To register the program in the service registry of the Microsoft� Windows machine execute the following command in a prompt (cmd.exe) with administrative permissions:

C:\appcontrol>xcAgent --install --servicename XComponentAppControlAgent
XComponent App Control Agent, version 9.9
Copyright © Invivoo Software 2022
XComponent AppControl service name: XComponentAppControlAgentXComponent AppControl service display name: XComponent AppControl AgentXComponentAppControlAgent is installed.

• We can either specify the display service name during registration:

C:\appcontrol>xcAgent.exe --install --servicename appcontrolagent --servicedisplayname "Agent AppControl"
XComponent App Control Agent, version 9.9
Copyright © Invivoo Software 2022
XComponent App Control service name: appcontrolagent
XComponent App Control service display name: Agent AppControl
appcontrolagent is installed.

• Uninstalling the agent can be done also with the following command line:

C:\appcontrol>xcAgent.exe --uninstall --servicename appcontrolagent
XComponent App Control Agent, version 9.9
Copyright © Invivoo Software 2022
appcontrolagent has been uninstalled.

• Start the service XComponent AppControl Agent

Option 2. Run the agent in interactive mode from a prompt (cmd.exe)

Run cmd.exe and then go to the agent folder.

C:\appcontrol>xcAgent.exe --console
XComponent AppControl Agent, version 7.0.0-R1
Copyright © Invivoo Software 2022

Adding a Microsoft Windows firewall port rule (optional step)

If you need to communicate with the agent from another computer, you should need to create a firewall rule to open the agent's port.

In this case the agent's port is 12567, the command above creates the correct rule on the firewall.

Run cmd.exe (with Administrative permissions) and then execute the following command.

C:\>netsh advfirewall firewall add rule name="AppControl-AgentRule" dir=in action=allow protocol=TCP localport=12567

You can check that the rule is correctly created with this command:

C:\>netsh advfirewall firewall show rule name="AppControl-AgentRule"

Please refer to the following link to check if the agent port is reachable.

Note:

If you are using another firewall or and anti-virus, you should refer to the corresponding documentation.

Enterprise Linux

At the moment EL versions of XComponent AppControl Agent are Rocky Linux and Alma Linux.

To install XComponent AppControl Agent under EL, untar the following Alma tar.gz into an installation directory (Tarball file). The configuration file ( config.dat ) is located in the same directory. Refer to the agent configuration section to customize the configuration.

Replace /home/xc/xcagent with your own installation folder.

/home/xc/xcagent $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/xc/xcagent/libs
/home/xc/xcagent $ ./xcAgent.bin --file /home/xc/xcagent/config.dat

XComponent AppControl Agent, version 7.0.0-R1
Copyright � Invivoo Software 2022

Agentless Linux & Unix

From an XComponent AppControl Linux agent, you can enable AgentLess mode via SSH2. This mode allows a Linux XComponent AppControl Agent to forward actions provided by the AppControl server under a non permanent Ssh channel to the IP address and account configured in the agent configuration file. Refer to the agent configuration section to customize the configuration.

Docker Installation

The docker image of the agent is available here on docker hub.

You can pull the docker image using the following command line:

root $ docker pull xcomponent/appcontrol-agent:latest

Environment variables exposed by the docker image are the following:

Some Technicals Points:

1. If your agent needs to access to local resources (eg: scripts), you have 2 ways to achieve this:
   • Inherits from this docker image and create your own image
   • Or you can map a directory to the docker image

Running the docker image:

root $ docker run -p 12567:12567 xcomponent/appcontrol-agent:latest

Agent Configuration

The default configuration file is name config.dat. It's located near the XComponent AppControl Agent configuration file.

<config>
  <item key="networkAddress"     value="127.0.0.1" />
  <item key="port"               value="12567" />
  <item key="checktimeout"       value="20" />
  <item key="logdirectory"       value="log" />
  <item key="tempdirectory"      value="tmp" />
  <item key="maxlogsizeinmo"     value="5" />
  <item key="nbdaystodeletelogs" value="10" />
  <item key="executionthreshold" value="30" />
  <!--Log level : NONE, INFO, TRACE, ERROR -->
  <item key="loglevel"           value="INFO" />
  <item key="trustedservers"     value="127.0.0.1" />
  <item key="sshhost"            value="127.0.0.1" />
  <item key="sshkeydirectory"    value="sshkeys" />
</config>

Environment variables configuration

Config.dat configuration supports environment variables as a value.

Under Microsoft Windows:

In config.dat you can use environment variables with the following pattern: %VARIABLE%.

<config>
...
  <item key="tempdirectory" value="%TEMP%" />
...
</config>

Under Linux/Unix:

In config.dat you can use environment variables with the following pattern: $VARIABLE.

<config>
...
   <item key="tempdirectory" value=”$TEMP" />
...
</config>

Note:

Each item key of the config.dat file can be overriden  by an environment variable named XC_MYITEMKEYINUPPERCASE. The priority is the following:
1. If an XC_... variable exists the agent will use it
2. The values in the config.dat are used only if the XC_... variables don't exist.

Example:
if an env variable named XC_TEMPDIRECTORY exists, this value will be used instead of the variable 'tempdirectory' defined in the config.dat.

Checking that agent's port is opened

In some situations, we need to check that the agent's port is correctly bind and accessible from another computer.

1. Checking that the agent binds on its port (locally):

curl localhost:12567

If the agent is running, the expected message is:

curl: (52) Empty reply from server

If the agent is not running, the message is:

curl: (7) Failed to connect to localhost port 12567 after 2267 ms: Couldn't connect to server

1. Checking that the agent binds on its port (from a remote machine):

curl mymachine:12567

If the agent is running, the expected message is:

curl: (52) Empty reply from server

If the agent is not running or unreachable (for example behind a firewall), the message is:

curl: (7) Failed to connect to mymachine port 12567 after 2267 ms: Couldn't connect to server

Note:

You can use the AppControl Gateway to both check agent connectivity and also to execute commands on the agent host.

Please refer to the following link