Docs

# Acure Agents and Coordinators

# Basic information

Acure Agent is a program installed and configured on individual computers and servers to execute Task scripts for Data Streams.

Agents are connected to the Acure platform through Coordinators using an API key for authorization.

Acure Coordinators provide connectivity to Agents and distribute Data Stream tasks between connected Agents.

Image

Main features of Agents:

  • Processing incoming scripts of Tasks.

  • Generating the resulting artifact and sending its data to the stream.

  • Direct launch of commands for interaction with the OS console (sh, bash, windows command, powershell).

  • Run parallel execution of multiple tasks.

  • Connection of integration plugins with:

    • Zabbix
    • SCOM
    • vCenter

By default, all Tasks are executed on the system Acure Agent, which is included in the system distribution.

The system Agent receives tasks through the system Coordinator (label SharedAgents).

Image

Examples of using Agents are presented as ready-made Tasks scripts for data collection.

# Coordinator management

Managing Coordinators implies the ability to perform the following actions:

  • Create or remove a Coordinator,
  • Stop or start a Coordinator,
  • Change basic settings of a Coordinator,
  • Reissue an API key for connecting agents,
  • Add or remove common tags for agents,
  • Configure access rights to a Coordinator.

# Adding a Coordinator

  1. Go through the main menu to the section Data collection→Agents.
  2. Click the Add Coordinator button in the upper right corner of the screen.
  3. Fill in the fields:
    • Owner of the coordinator,
    • Name of the coordinator,
    • Add tags to the coordinator.

      Tags are used to assign tasks to the coordinator in the Data stream configuration template. If you add the SharedAgents tag to your own coordinator, the job scheduler will also distribute data stream tasks with the default SharedAgents tag to your coordinator.

  4. Click the Add button and a new coordinator will be created.

# Deleting a Coordinator

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want to delete.
  3. Using the context menu, select Delete.
  4. In the dialog box confirm the deletion of the coordinator.

You can also remove a coordinator from the coordinator management page. To do this, open the required coordinator and in the upper right corner click Delete.

# Reissue an API key for a Coordinator

If it is necessary to block the agent's access to the coordinator or for other purposes, the user can Reissue the API key.

After the API key is reissued, all agents connected to the coordinator will lose connection with the system. To connect them, replace API keys in agent configurations with the new one. To generate a new API key:

  1. Go through the main menu to the section Data collection→Agents.
  2. Go to the desired coordinator Settings tab.
  3. In the upper right corner, click on the ︙ icon and select the Update API-Key menu item.
  4. In the dialog box, confirm to reissue the API key.
  5. The new API key will be copied to the clipboard and also visible next to the coordinator's name.

# Starting and stopping Coordinators

After adding a coordinator to the system the default state of the coordinator is Started - the coordinator distributes tasks for execution to the agents connected to it.

Stopping the coordinator means that:

  • Tasks will no longer be distributed to agents connected to the coordinator.
  • Agents can connect to the coordinator, but they will not receive assignments for execution.

# Starting a Coordinator

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want to start.
  3. Using the context menu select Start.
  4. If the start is successful, you will see a corresponding message.

The coordinator can also be started from the coordinator management page. To do this, open the required coordinator and in the upper right corner click Start.

# Stopping a Coordinator

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want to stop.
  3. Using the context menu select Stop.
  4. In case of a successful stop, you will see a corresponding message.

The coordinator can also be stopped from the coordinator management page. To do this, open the required coordinator and in the upper right corner click Stop.

# Coordinator settings

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want and click on it.
  3. Click the Settings tab.
  4. Change if necessary:
    • Owner of the coordinator,
    • Name of the coordinator,
    • Add or remove the required tags.

      Adding tags is carried out by means of the "Enter" button, which is pressed after entering the name of the tag.

# Monitoring connected Agents

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want and click on it.
  3. Click the Agents tab.

The Agents tab displays information about all the agents connected to the coordinator:

  • Last contact - last time the agent was active.
  • Name - the agent name specified in the agent configuration file.
  • Type - Dynamic or Static (more about agent types).
  • Status - Active or Not Available.
  • Version - version of the connected agent.

The number next to the name of the tab informs about the number of agents connected to the coordinator.

Static agents that are not active at the moment can be removed from the list of those connected to the coordinator. To remove these agents, click the Remove button next to the agent version.

Connecting multiple agents with the same name is not allowed. Agent names are checked within the Userspace when connecting.

# Monitoring assigned Tasks

To view information about assigned tasks on the coordinator, follow these steps:

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want and click on it.
  3. Click the Tasks tab.
  4. The Tasks tab displays information about the assigned jobs from the data stream configuration template:
    • Last start - the time of the last start of the task on the agent.
    • Last status - the execution status of the last task on the agent.
    • Task owner - the data stream to which the task belongs.
    • Name - the name of the task in the data stream configuration template.
    • Tags - information about the tags that connect the coordinator with the task in the agent configuration template.
  5. You can sort the list of tasks by the fields:
    • Last start
    • Last status
    • Task owner
    • Name

Image

Search on the Tasks tab is carried out by the Name and Task Owner fields.

# Access rights

To grant access to the coordinator to a Workgroup, follow these steps:

  1. Go through the main menu to the section Data collection→Agents.
  2. Find the coordinator you want and click on it.
  3. Click the Access tab.
  4. On the Access tab, add necessary access rights:
    • to View the coordinator for a specific Workgroup,
    • to Edit the coordinator for a specific Workgroup.

Additionally, you can grant Viewing access rights to the coordinator for all Workgroups, including future by clicking on the corresponding switch. This feature is only available to Userspace Adminstrators.

# Access rights to View

  • Ability to select a coordinator for the distribution of tasks between his agents.
  • View all information about the coordinator (except for the API key), without the possibility of editing it.

# Access rights to Edit

  • Ability to choose a coordinator for the distribution of tasks between his agents.
  • Manage agent coordinator (stop and start coordinator).
  • Change all editable parameters of the coordinator.

# Connecting an Agent

Before connecting the Agent, it must be downloaded and configured.

Download Agents using following links:

- Agent for Windows (opens new window)

- Agent for Linux (opens new window)

To connect an Agent, you must have a coordinator API key. If there is no coordinator, go back to adding a coordinator.

The Agent connects to the Acure Coordinator via the SignalR protocol by specifying the access token (API key) and the base URL of the system.

Help

# Agent workflow

The coordinator distributes Tasks to Agents connected to it.

A number of Tasks can be given to the Agent at the same time, not exceeding the SlotsCount parameter of the Agent's configuration file.

# Agent types

An Acure agent can be configured as a static or dynamic Agent:

  • Static Agents are Agents whose status is controlled by the Coordinator. When a Static Agent is connected, the Coordinator registers it in the list of connected Agents and controls its status.

  • Dynamic Agents are Agents that are visible in the system when they are active. When a Dynamic Agent is disabled, the agent disappears from the list of agents connected to the Coordinator.

To control the agent type, use the Name configuration parameter - the name of the agent:

  • If the Name parameter is not specified – the coordinator sets the agent to type dynamic and assigns an automatically generated name.
  • If the Name parameter is specified – the coordinator sets the agent to a static type and registers it with the specified name.

# Installing an Agent

# Linux

  1. Create a directory and open it:

    mkdir -p /opt/acure-agent && cd /opt/acure-agent

  2. Download the latest version of the acure-agent

  3. Unzip the downloaded archive into the current directory:

    unzip acure-agent.zip

  4. Make the acure-agent binary executable:

    chmod +x ./acure-agent

  5. Next, make a proper configuration file.

# Windows

  1. Download the latest version of the acure-agent.
  2. Unzip the downloaded archive into a folder, for example: C:\acure-agent\acure-agent.exe.

# Configuring an Agent

Create a configuration file acure-agent.conf in the same directory with the executable. Fill it in with following:

# Base URI of the Acure system
BaseUri="https://acure.domain.com"
# Coordinator API key for agent authorization
ApiKey="fc63b95b-0393-430a-b8d0-46a8c4813675"
# File storage path (optional)
FileStorage=""
# Timeout for tasks execution in seconds (optional)
Timeout=100

# Plugin settings (optional)
[Plugins]
# Path to DLL plugins linux
CSharpPath="/opt/acure-agent/plugins"
# Path to DLL plugins linux windows
# CSharpPath="c:\acure-agent\plugins\"

# Coordinator connection settings (optional)
[Connection]
# Connection setup timeout in seconds
Timeout=10
# The number of attempts to establish a connection
RetryCount=12

# Agent information (optional)
[Agent]
# Name
Name="acure-agent-hostname"
# Description
Description=""
# Number of slots for completing tasks
SlotsCount=2

Replace the values of configuration file parameters with your own:

  • BaseUri - the base URI of the Acure system

  • ApiKey - API key of the coordinator for agent authorization

# Plugin Connection

The following plugins are supported in the current version of agents:

  • nagiosCheckConnection – plugin used in the configuration template Nagios default to check the connection with the Nagios monitoring system.
  • nagiosEventsDataFlow – plugin used in the configuration template Nagios default for data collection.
  • scomCheckConnection – plugin used in the configuration template SCOM default to check the connection with the SCOM monitoring system.
  • scomEventsDataFlow – plugin used in the configuration template SCOM default for data collection.
  • vmwareEventsDataFlow – plugin used in the configuration template vCenter default to collect data about changes in topology.
  • vmwareTopologySync – plugin used in the configuration template Zabbix default to synchronize the topology of the information system.
  • zabbixCheckConnection – plugin used in the configuration template Zabbix default to check the connection to the Zabbix monitoring system.
  • zabbixCheckVersion – plugin used in the configuration template Zabbix default to check Zabbix version.
  • zabbixEventsDataFlow – plugin used in the configuration template Zabbix default for data collection.

To connect a plugin to an agent, unzip the plugin archive into the CSharpPath = /opt/acure-agent/plugins directory and restart the agent.

# Starting an Agent

Help

# Supported commands:
  • start - Start the agent. (Usage: acure-agent [options] start)
# Supported options:
  • --config <config> - path to the configuration file.
  • --insecure - do not use SSL certificate verification (default: disabled).
  • -?, -h, --help - show help.

# Start in Linux

To start the agent as a service, place the configuration file acure-agent.service in the directory/etc/systemd/system/:

[Unit]
Description=Acure Agent Service
Documentation=https://docs.acure.io/

[Service]
Type=notify
WorkingDirectory=/opt/acure-agent
ExecStart=/opt/acure-agent/acure-agent start --config /opt/acure-agent/acure-agent.conf
StandardOutput=syslog

[Install]
WantedBy=multi-user.target
Alias=acure-agent.service

The service is controlled via the systemctl commands:

  • Load new systemd configuration file (executed when theacure-agent.service file changes)
sudo systemctl daemon-reload
  • Check service status systemd
sudo systemctl status acure-agent.service
  • Start service systemd
sudo systemctl start acure-agent.service
  • Open systemd service logs
sudo journalctl -u acure-agent.service -f

# Start in Windows

To run acure-agent as a Windows service, you must create and register the service as Administrator using the command line utility Windows Service Control Manager.
Example:

# Create service
sc.exe create acureAgent binPath= "C:\acure-agent\acure-agent.exe start --config C:\acure-agent\acure-agent.conf" 
# Start service
sc.exe start acureAgent 
# Stop service
sc.exe stop acureAgent 
# Remove service
sc.exe delete acureAgent

# Connecting in legacy-mode

If you need to connect acure-agent running on the operating system:

  • Windows Server 2008
  • Windows 7
  • Windows Server 2012
  • Windows 8
  • Windows 8.1

The system administrator of the Acure infrastructure needs to allow ingress-nginx-controller configuration to use cipher supported by legacy operating systems.

To do this, add the following option to configMap of ingress-nginx-controller:

kubectl edit cm -n ingress-nginx ingress-nginx-controller
...
  ssl-ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256 :ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
...

If you encounter DLL loading errors when running acure-agent on one of these Windows OS, you must additionally install Microsoft Visual C++ 2015 Redistributable (x64)

# Checking connection

The successful launch and connection of the agent to the platform is indicated by an entry in the log file:

sudo journalctl -u acure-agent.service -f
Nov 23 13:37:39 elk acure-agent[102088]: [2021-11-23 13:37:39 +03:00 INF] Establishing connection.
Nov 23 13:37:44 elk acure-agent[102088]: [2021-11-23 13:37:44 +03:00 INF] Connection established.
  1. Go to the section Data collection→Agents.
  2. Open the Coordinator to which the Agent was connected.
  3. Go to the Agents tab and make sure that Agent is connected.

Image

⚠️ If the domain on which Acure is running is signed with a self-signed security certificate, you must add the --insecure parameter to the Agent start line.

Attention

After successful connection of the Agent, go to configuring Tasks for data collection.