PlaidLink

• 1: PlaidLink Agents
• 2: Installation
• 3: Configure
• 4: Upgrade

1 - PlaidLink Agents

Description

Sometimes it’s necessary and desireable to access data or run processes from a remote system that does not allow external access. This is common in enterprise environments behind firewalls. PlaidCloud allows this ability by using PlaidLink, which enables remote systems access behind a firewall or where direct access from PlaidCloud is not desired.

PlaidLink uses an agent-based system. This means that an agent, the remote user, is installed on a system inside the firewall or other restricted area. The agent can then connect to PlaidCloud by using an outbound initiation process over a secure HTTPS websocket connection. It is as secure as any other encrypted web connection and usually does not require you to open non-standard ports. Before gaining access, the agent must identify itself by sending its agent identifier. From this, if the agent has a successful authentication process, the agent is granted access to the approved operations.

PlaidLink can be installed on Windows, Unix, and Linux systems and can run under low privilege users. On Windows systems, PlaidLink can operate as a Windows Service with full control from the Service panel. On linux or unix systems, it can run as a deamon process.

PlaidLink can also run as a stand-alone Docker container or as a Kubernetes pod.

Managing Agents

To manage agents:

1. Open Analyze
2. Select “Tools”
3. Click “PlaidLink Agents”

This brings you to the PlaidLink Agents Table where you can view, modify, and obtain credentials for the list of available agents.

Creating an Agent

To create an agent:

1. Open Analyze
2. Select “Tools”
3. Click “PlaidLink Agents”
4. Click “Add PlaidLink Agent”
5. Complete the required fields
6. Click “Create”
7. Assign the agent to the necessary security groups to access resources needed to perform its job
8. Assign the agent to the necessary Document accounts to access documents needed to perform its job

Obtaining Agent Credentials

To configure PlaidLink agents on the remote system, you must first obtain the agent’s identifying information in order to maintain security. This information includes both a public and a private key.

To obtain these keys:

1. Open Analyze
2. Select “Tools”
3. Click “PlaidLink Agents”
4. Click the edit icon

This will open a form where you can view the public and private key values.

Regenerating Agent Credentials

It is a good idea to periodically regenerate the public and private keys and update the configuration of remote systems in order to maintain security.

To regenerate the credentials:

1. Open Analyze
2. Select “Tools”
3. Click “PlaidLink Agents”
4. Click the regenerate icon

Once the credentials have been regenerated, they can be obtained in the same way a new agent’s credentials are obtained (described above).

Enabling and Disabling an Agent

To disable an agent:

1. Open Analyze
2. Select “Tools”
3. Click “PlaidLink Agents”
4. Uncheck the “Active” checkbox

Running Multiple Agents

PlaidLink is designed to allow operation of multiple agents using a single service installation. Such a streamlined installation system permits one install to handle agents from multiple workspaces and / or agents with different levels of permissions for task execution.

To enable multiple agents, you simply add the agent credentials to the PlaidLink configuration file.

Running Multiple PlaidLink Services

Similar to running multiple agents within one PlaidLink service, it is also possible to run multiple PlaidLink services.

This is sometimes necessary depending on use of system based security or network access restrictions that prevent communication across network boundaries.

Compute, Memory, and Disk Requirements

The PlaidLink service is extremely lightweight and only needs minimal compute and memory to operate. When processing significant data volumes it may be necessary to increase compute resources and especially memory.

Normally, the agent will happily run with 5% of CPU and 200MB of memory. For intense data operations, it is recommended to allocate an entire CPU and at least 4GB of RAM. For dynamic resource allocation systems like Kubernetes, it is fine if the agent has access to burstable resources rather than reserved resources.

Disk space for the agent is minimal too. Agent operations utilize disk space as a data buffer when transferring large amounts of data. Typically, 8GB of space is fine for normal operations. For intense data operations it is recommended that you scale disk up according to the expected data volumes. There is no set amount because it depends on several factors including CPU speed, network speed, amount of data, etc... However, a good place to start is 20GB and adjust from there.

Networking Requirements

The PlaidLink Agent is designed to operate with minimal configuration required. It does not require any special VPN or network configuration other than allowing standard HTTPS network traffic. Agents communicate over the same protocol as normal web browser based traffic.

The agent service always initiates communication with PlaidCloud so there is no need to configure ingress access in firewalls.

2 - Installation

Download the agent

Check the releases on PlaidCloud.com for PlaidLink

Extract the agent

Extract the downloaded zip file to an install location of your choice. Generally, this location will be:

C:\Users\<Username here>\src\plaidlink

Create a configuration file

Copy the config-dist.yaml file in the agent's directory to %ProgramData\plaidcloud\, and rename this copy config.yaml

(Edit this configuration with the values retrieved from PlaidCloud)

Install the agent's service

Run the install_windows_service.bat file in the agent's install directory OR

From an administrator command prompt, navigate to the agent's install directory and run:

.\PlaidLink.exe install

Running the agent

Type Services into Windows' search bar and open the service manager. In the list of services, find PlaidCloud Agent.

Right-click the service and select "Start" to start the agent.

Freezing updates

If at any point you want to disable the agent's auto-update feature, open the agent's 'yaml' configuration file, and at the root level of the file, add a line that reads freeze_updates: true, and restart the agent's service.

3 - Configure

The PlaidLink Agent works in conjunction with the PlaidCloud service. The PlaidLink Agent provides the connection necessary to operate with systems not accessible directly such as databases and file systems. The agent performs a number of essential actions including:

• Reading and writing to databases
• Reading and writing files to network drives and servers
• Checking for sensor conditions
• Interacting with SAP ECC and SAP S/4HANA through Remote Function Calls (RFCs)
• Interacting with SAP Profitability and Cost Management (PCM)
• Sending messages and notifications to remote systems

Create an Agent on PlaidCloud

PlaidLink Agent management takes place within the Analyze tab of PlaidCloud. The first step is to create a new PlaidLink Agent instance on PlaidCloud.

To create a new PlaidLink Agent

1. Select the Analyze tab
2. Select the tools menu from the top
3. Click PlaidLink Agents
4. Create a new Agent with an appropriate name for the environment or server that it will be installed on for remote operations

To view the Agent public and private keys

1. Click on the edit icon to view the form
2. At the bottom of the form you will find the public and private keys that were randomly generated during the Agent creation process

To randomly generate new keys

1. Click on the Regenerate icon for the Agent record
2. Once the keys are regenerated, don’t forget to update the agent configuration file with the new keys on the remote server.

Document Account Access

If the agent will need to have access to a Document account for uploading or downloading files, it must be granted permission to access the Document account.

To grant account access

1. In the Document tab select Manage Accounts
2. Once the table of accounts appears, click on the agent icon for the account which the new Agent should have upload/download rights
3. Drag the new agent into the Assigned Agents column
4. Save the access control form.

Data Connection Access

If the agent will need to have access to a data connection such as a database, it must be granted permission to access the external data connection information.

To grant connection access

1. In the Analyze tab select the Tools menu
2. Click External Data Connections
3. Once the table of data connections appears, click on the agent icon for the connection, which the new Agent should have usage rights
4. Drag the new agent into the Assigned Agents column and save the access control form.

Next Step: Installing PlaidLink (Agent) on a Remote System

Follow these Installation Instructions to install PlaidLink on the remote system.

4 - Upgrade

A manual upgrade of PlaidLink may be necessary if the agent does not have sufficient privileges to update itself when new versions are released or a manual upgrade process is desired.

Download the agent

Check the releases on PlaidCloud.com for PlaidLink

Stop the Current Agent

Type Services into Windows' search bar and open the service manager. In the list of services, find PlaidCloud Agent.

Right click on the PlaidCloud Agent service and select Stop. Once the service successfully stops, continue on.

Extract the agent

Navigate to the current location of the installed agent.

C:\Users\<Username here>\src\

Rename the current installation folder so that it will no longer be referenced. For example Plaidlink_Old_12122022

Extract the downloaded zip file to an install it in this location. Generally, this location will be:

C:\Users\<Username here>\src\plaidlink

Start the agent

Return to the Services window. Right click on the PlaidCloud Agent service and select Start.

Type Services into Windows' search bar and open the service manager. In the list of services, find PlaidCloud Agent.

Right-click the service and select Start to start the agent. Once the agent shows in the Running state, the agent is now operational again on the new version.