Agents

Download this manual as a PDF file

Agents allow a Restorepoint appliance to manage devices located on a remote or otherwise disjoint network, not directly routable by Restorepoint, without complex firewall changes, Network Address Translation, or VPNs. For instance, a Service Provider can set up a central Restorepoint appliance and deploy agents on customer networks and enable device backups on remote sites.

An Agent can be deployed as a Virtual or Hardware appliance on the remote network. The agent provides fast operations by locally performing all the tasks that would typically require extensive network interaction. Configurations, logs, etc. are processed locally by the agent, and uploaded to the master Restorepoint appliance.

Device firmware updates via agents are not yet supported.

Agents are only available with an Enterprise license.

Agent Firewall Requirements

An agent initiates and maintains an SSH connection to the master Restorepoint appliance to receive tasks to execute, upload and download device configurations, task output and logs, and download software updates.

Your firewall policy must allow SSH traffic (TCP port 22) from the agent to the master for an agent to function correctly.

Agent Installation

An agent virtual appliance is deployed in a similar manner to a Restorepoint appliance (for more information, see the section on Restorepoint Virtual Appliance). Agents are kept up-to-date with software updates via the connection to the master appliance.

Connecting the Agent to the Master

The agent initially establishes an SSH connection to the master using a one-time password that is generated when creating the agent on Restorepoint. After the password is accepted, the agent and the master communicate via a secure socket using the agent's RSA key.

Initial Setup

To setup an agent, you must configure the network parameters and the details of the connection to the master:

  1. Open the virtual machine console in your Virtual Infrastructure client.
  2. In the login prompt, enter the default username and password for the agent. If you are unsure which username and password to use, contact ScienceLogic Support.
  3. Follow the prompts to change the agent shell password.
  4. Select IP Address Configuration at the console menu:

    5. Image of the Restorepoint Agent Console

  1. Enter the settings for IP address, Netmask, Default gateway, and Primary DNS server as prompted.
  2. Enter y to confirm the settings. If the settings are applied successfully, the console menu will be redisplayed.
  3. Next, select Initial Restorepoint Master Setup:

    4. Image of the Restorepoint Agent Console

  1. Enter the IP address of the master Restorepoint appliance, and a one-time password to verify the Agent to the master (only used for initial pairing).

Adding an Agent to Restorepoint

To add a configured agent to Restorepoint, navigate to the Agents page (Administration > Agents) and click Add Agent. The following dialog appears:

Image of the Restorepoint Add Agent page

Enter the following details:

Name

A name for the agent.

Location

Where the agent is located. Pick an existing location, or enter a new one.

Domain (optional)

The domain of the devices that this agent will manage. For more information, see Administration Domains.

Email (optional)

The email for the user that is responsible for the upkeep of the agent.

Alert on disconnect

Select this checkbox to automatically email an alert if the agent goes offline. If the Email field is not filled in, the default notification address is used.

Alert on reconnect

Select this checkbox to automatically email an alert if the agent comes back online. If the Email field is not filled in, the default notification address is used.
Disable TFTP Server Select this checkbox to disable TFTP servers.
Disable FTP Server Select this checkbox to disable FTP servers.
Secondary To ID of an agent this agent is secondary to in a HA setup.
Secondary Master IP Address The IP address of the secondary master IP in an HA setup.
Use Agent Address Select this checkbox to enter the IP Address into the Address field.
Address The specified address must be the address the agent uses to connect to the master. The address option for agents will not work if multiple agents use the same NAT address.

Restorepoint will generate an eight-character password upon registering a new agent.

After the agent is added, Restorepoint will display the agent list. The address and port will be automatically filled in once the agent has connected successfully for the first time. Note that only one agent can be set up at a time.

Changing the Master IP Address

If the IP address of the master Restorepoint appliance changes, any agents connected to that master need to be reconfigured with the new master details. To reconfigure an agent with the new master details:

  1. SSH to the agent (or open the virtual machine console).

  2. Log in using the agent’s admin account.

  3. Select Change Restorepoint Master IP address in the console menu, and apply the new master IP address.

Do not use the option Initial Restorepoint Master Setup to set the new master IP address. If you use this option, it invalidates the master-agent authentication and would require re-pairing the agent to the master Restorepoint appliance.

Image of the Restorepoint Agent Console

Remote Operations Using Agents

Once you configure an agent, you can perform any operation (backup, restore, control etc.) on a device via the agent. The Restorepoint appliance will not connect directly to the device, the appliance will instruct the agent to perform the operation on its behalf.

To move an existing device to an agent, select one or more devices from the Device Management List, and click Edit, then select the correct Agent in the drop-down menu as shown:

Image of the Restorepoint Device Details page

Operations using agents are completely transparent for the user. For instance, bulk operations can be started for agent-managed and directly-managed devices simultaneously.

Managing Agents

You can view a list of the paired agents from the Administration > Agents page. To edit an agent’s settings, click the name of the agent.

The settings include the Name, Location, Domain, Email, whether to Alert on Disconnect/Reconnect, or allow you to factory Reset the Agent for re-pairing. There are additional settings for Debugging agent connections.

  • Debug > Start works similarly to Appliance Debugging. It records a debug log that can be viewed using the Debug > View button.
  • Debug > Info collects and displays a series of system information from the Agent, such as RAM usage, Disk usage, and Uptime.
  • Debug > Remote allows remote management of an agent. This option will displays a port number. You can connect to that port on your Restorepoint master appliance to redirect to the agent so that trickier issues can be diagnosed.

RPM Agent

The RPM agent is a standalone agent that you can deploy onto your operating system to connect to various devices.

RPM Agent Limitations

The following features are not supported on the RPM agent:

  • Storage on the agent
  • Encryption on the agent
  • Collection from plugins that use FTP or TFTP
  • Auto-upgrade of the RPM Agent

Installing and Updating the RPM Agent

To install or update the RPM agent, perform the following:

  1. Set SELinux to permissive.
  2. Run rpm -Uvh rpagent_standalone.X.rmp.
  3. A new, unprivileged user will be created along with a new group rpuser:restorepoint. This user and group are the owner of the Restorepoint installation under /var/restorepoint.

Configuring the RPM Agent

To run the RPM agent you must configure rpagent_standalone. You can choose to keep rpagent_standalone under the default directory /var/restorepoint/bin/agentconf.json or you can store it in a directory of your choice. To configure the RPM agent, perform the following:

  1. Follow the default configuration given in agentconf.min.json and store it under agentconf.json:

{
"SpoolDir": "/var/restorepoint/spool",
"BackupDir": "/var/restorepoint/backups",
"BinDir": "/var/restorepoint/bin",
"PluginDir": "/var/restorepoint/plugins",
"CertsDir": "/var/restorepoint/certs",
"ConfDir": "/var/restorepoint/bin",
"MasterAddress": "HOST",
"MasterPort": "",
"NATAddress": "",
"Password": "PASSWORD",
"ChangedAdmin": 0,
"SecondaryAddress": "",
"PushDevices": "",
"DisableTFTP": false,
"DisableFTP": false,
"RPPath": "/var/restorepoint"
}

  1. Replace HOST and PASSWORD (one-time password) to connect the agent for the first time. Keep the remaining configuration as is.
  2. A new service has been created for rpagent. Run the following:

systemctl enable rpagent
systemctl start rpagent

  1. The agent's logs are stored under /var/log/rpagent. If desired, you are able to configure the agent service to show the logs directly in journalctl. The agent service is stored under /usr/lib/systemd/system/rpagent.service.

Optional RPM Agent Configurations

Device Back-Connection

The Device Back-Connection optional configuration is a Beta feature.

To set up a Device Back-Connection, perform the following:

  1. Create a user with the correct SSH credentials and permissions. This user must be part of the restorepoint group to be able to access the spool directory.
  2. Add the following configurations to agentconf.json:

"BackConnectionUser": "",
"BackConnectionPassword": ""

Back-connection has only been tested for ssh/scp protocols.

Initial Master SSH Connection Port

To connect to a port other than Port 22 when performing initial SSH connection to the master, add the following to agentconf.json:

"MasterSSHPort": ""

The port you choose must be outside of system ports range (>1023).

Back Connection NAT

If needed, the agent can have a NAT address set for back connection. Devices that are managed by the agent will use the NAT address you set unless it is already set in Restorepoint. To set the agent's NAT address, update the following configuration value in agentconf.json:

"NATAddress": ""

TFTP and FTP Servers

This agent does not directly start TFTP and FTP servers. If you manually start a TFTP server on Port 69 on your appliance, these plugins may work as intended but they are untested.

Troubleshooting the RPM Agent

If you experience issues connecting the RPM agent, for example, by not correctly configuring SELinux before trying to connect the agent to the master, complete the following:

  1. Delete the contents of the folder /var/restorepoint/certs.
  2. Recreate the agent in Restorepoint.
  3. Setup the new password again on /var/restorepoint/binagentconf.json.
  4. Delete the auto-generate port if it exists.

Docker Agent

The Docker agent allows you to run multiple agents simultaneously and under any operating system you choose because you can run applications in different environments.

Installing and Configuring the Docker Agent

To install the Docker agent you must have a Harbor account so that you can acquire an API token to access the images contained in the ScienceLogic registry.

Acquiring the API Token

To use the Docker agent you must first acquire an API token from Harbor to authenticate via CLI.

To get your API token:

  1. Got to https://registry.scilo.tools
  2. Click the Login with OIDC Provider button
  1. The Harbor home page will load after authentication has been completed.
  2. Click on your username, found in the top-right corner, and then choose User Profile. The User Profile prompt appears with your username to authenticate.
  3. You will also see the CLI Secret field with contains your API key. Be sure to copy and paste this somewhere for later use.
  4. After you have your API key, click the Close button to close the session.

You are now able to use this username and API token to authenticate with the Harbor services.

Configuring rpagent

To run an rpagent image:

  1. Log in with your Harbor username and API token to authenticate to the ScienceLogic container registry:

docker login registry.scilo.tools -u <USERNAME> -p <API_TOKEN>

  1. Create an .env file (or any other name) and set the following two environment variables to run the image:
MASTER=<hostname|address>
PASSWORD=<password>
  • MASTER. Enter your Restorepoint appliance address or hostname.
  • PASSWORD. Enter the password generated by the Restorepoint appliance upon registering a new agent.

Restorepoint will generate an eight-character password upon registering a new agent.

  1. Run the container as follows:
docker run \
    -d \
    -it \
    -v $PWD/tmp:/mnt/cryptfs:Z \
    --network=host \
    --tmpfs /mnt/ram \
    --env-file .env \
    --name rpagent \
    --restart unless-stopped \
    registry.scilo.tools/sciencelogic/rpagent
  • -d. Daemonizes the container
  • -it. Allocates an interactive terminal (good for initial verification)
  • -v $PWD/tmp:/mnt/cryptfs:z. Mounts tmp in the current directory in the container as /mnt/cryptfs (tmp must be writable)
    • :Z. Configures the SELinux label for hosts that support SELinux.

ScienceLogic recommends you use caution with the :Z option as you can render your host machine inoperable which may require you to relabel host machine files by hand.

  • --network=host or --network=bridge. In host mode, the container will share the host's network stack. For more information, see Host Networking.
  • --tmpfs /mnt/ram. This is the in-memory storage for runtime data.
  • --env-file <file>. This file contains environment variables.
  • --name <name>. Name the running container.
  • --restart unless-stopped. This allows the container to keep running unless stopped by the Docker daemon.

Host Networking

ScienceLogic recommends that, because the Restorepoint agent container is required to accept incoming connections from other devices (SSH, SCP, SFTP), the preferred networking model is to assign an individual IP address to the container. When the container has its own IP address, you can run the SSH server on the standard Port 22 instead of Port 2222. It is possible to run with --network=host, however the Docker host firewall must be configured to forward the incoming connections to the container.

Additional Run Options

You have the option to override default options when configuring the Docker Agent. The following options can be set to override the defaults:

  • SSHDPORT. This is the port for the SSH/SCP/SFTP server. Bind port for SSHD (default: 2222).
  • CONFDIR. This is the path where the agent configuration file is stored (default: /var/restorepoint/bin)
  • SSHDHOSTKEYDIR. This is the path where SSH host keys are stored (default: /etc/ssh)
  • DEBUG. Setting DEBUG=1 will enable debug mode. This is useful for testing the setup for the first time.

The CONFDIR and SSHDHOSTKEYDIR parameters can be used to store configuration files on a mounted volume which makes them persistent if the container is replaced.

Troubleshooting the Docker Agent

If you experience a failed handshake between the agent and device, try resetting the agent in Restorepoint.

  1. Go to the agent's configuration modal and select the Reset checkbox.
  2. Re-enter the password you previously chose and click Save.
Retrying in 10 seconds ssh: handshake failed: ssh: unable to authenticate, attempted methods 
[none password], no supported methods remain