Installing Frends Agent
How to install Frends Agent on different platforms.
In this guide you will learn how to configure an isolated Frends Environment and install an on-premise Frends Agent to start executing your integrations on-premise with only logging and configuration done in the cloud.
Requirements
You will need the following prerequisites to follow this guide.
Admin permissions to a Frends Tenant
You will need to have the Administrator role for the Frends Tenant the Agent will be installed to.
You should also have an Environment and an Agent Group prepared in Frends. You can follow the guide about Creating new Environments & Agent Groups for this.
Server requirements
You will need a server you have administrator access to, in order to install the Frends Agent.
In addition, the server should fulfill the following requirements.
Operating system
Microsoft Windows 10, 11, or Windows Server 2019 or later.
Ubuntu Server 22.04 LTS or newer.
Local or Active Directory user account that is in local admin group on the server.
Alternatively, an operational Kubernetes or Docker environment for containerized deployment.
Software
Latest Agent versions require .NET 8.0 runtime to be installed on the server.
Legacy Agents running on Microsoft Windows platform require .NET Framework 4.7.2 runtime.
Hardware minimum requirements
The host machine can have at minimum 2 vCPU, 4 GB of RAM, and 32 GB of disk space if the Agent is not under a heavy load. This could be the case if the Agent is used in the Development Environment.
Hardware recommendations
The host machine should ideally have 4 vCPU, 8 GB of RAM, and 100 GB of disk space.
Memory, disk space and vCPU depends largely on the usage of your Agent. More memory may be required if there are hundreds of Processes or, for example, if you have Processes doing XSL transformations on large XML files. More disk space may be required if you plan on storing a large number of files.
It is usually better to have two Frends Agents with less capable hardware than one with powerful hardware.
Connectivity requirements
Hosting a Frends Agent on your server requires the following details to be set up and confirmed.
Outbound connectivity
Frends 5.7 and later require outbound access to the following:
Frends UI: <tenant>.frendsapp.com on port 443
Azure Service Bus: Ports 443, 5671 and 5672 are needed to be open towards Azure Service Bus
Azure Blob Storage: Port 443 is needed for Azure Blob Storage
You can check the Microsoft's documentation about Azure Service Bus and Azure Blob Storage. As the IP addresses of the Azure services may change, these may have to be opened without IP restrictions.
Azure Service Bus is used to allow the Agent to communicate with the Frends Core, that is located in Azure cloud. This in turn enables the connectivity between the Frends UI and the Agents.
Azure Blob Storage is needed to store larger logging data and messages that do not fit in a single Azure Service Bus message (over 200 kb), as well as to retrieve compiled Processes during Process or Agent deployment.
Alternatively, if outbound connectivity is limited for the Agent and ports 5671 and 5672 cannot be opened outbound to the Azure Service Bus. As a workaround the transport type can be set to AMQP Websockets by adding ;TransportType=AmqpWebSockets to the Azure Service Bus connection string. After this the Azure Service Bus connection will use port 443 for outbound connections.
Inbound connectivity
The Frends Agent operates through Azure Service Bus, which has the connectivity requirements listed above. As such, the server will not receive any inbound connections directly to it for standard operations.
For REST APIs published to your Agent Groups and thus Agents, there will be inbound connectivity for all the API requests, on the ports defined for your Agent. In order for the published API to be accessible, the ports need to allow inbound connections through firewall.
Alternatively for publishing REST APIs, a Gateway Agent can be set up instead. It will act as a gateway and a load balancer for Agents behind it, publishing the APIs without giving direct access to the actual Agents performing the processing. This way the servers hosting the Agents will not require external inbound connectivity, but the API Gateway Agent will require it instead.
Testing connectivity
You can test ports from the machine that is going to be hosting the Frends Agent with either a Powershell command or a Unix command.
Note that if you restrict the outgoing connections, get the correct URL for those tests from the appsettings.secrets.json configuration file.
Configuring Frends for new Agent
You should have an Environment and an Agent Group prepared in Frends. You can follow the guide about Creating new Environments & Agent Groups if not.
With the Agent Group set up, you can create the Agent configuration to it. You can follow this guide for more details: How to configure an Agent in Frends.
Database Initialization
If you want to use your own, external database, follow the instructions below. Remember to set up the connection string for your Agent Group in Frends as well in this case.
Otherwise, continue to installing the Frends Agent with included SQLite or LocalDB database.
Database for Cross-Platform Agents
If you are planning to use your own database for Agents or a shared database for the High Availability configuration, make sure you have available or install or create a SQL Server 2016 or later, PostgreSQL, Azure SQL Database instance or SQL cluster, and make sure the planned Agent machines can reach this database.
A database user is also necessary to be set up before setting up the database. The user should have at least db_datareader, db_datawriter and execute permissions.
For running the Database Initializer tool to set up the database for Frends Agents you will need a user in the database with database admin role, or a connection string providing the admin capabilities. The tool will perform the following actions:
Create a database
Create a login
Create stored procedures
Alter tables
Create backup jobs
Run backup jobs
In order to create the necessary database tables and content, download the Database Initializer from your Frends Control Panel, available in the Administration > Environments view by selecting the target Agent Group. Database Initializer can be downloaded either directly from the download options for each Agent, or by enabling the Allow new agents to connect to Agent Group option under Advanced settings, and then downloading the Kubernetes configuration package.
After downloading and extracting the archive, run Frends.DatabaseInitializer.exe from the command line with the following parameters:
Frends.DatabaseInitializer.exe -c [SqlServerConnectionString] -n Frends.Agent.Data.Initialization.Migrations.SqlServerAgentStore -u [FRENDSAgentDatabaseUsername] -p [FRENDSAgentDatabasePassword] --doNotCreateBackupJobsReplace the content in square brackets to fit your environment and setup:
SqlServerConnectionString: Connection string to your database, that has at least alter permissions to the database
FRENDSAgentDatabaseUsername: Username for the user account to use by Frends
FRENDSAgentDatabasePassword: Password for the user account
You can learn more about how to use and alter the tool's actions by running the following command:
> Frends.DatabaseInitializer.exe --help
Frends.DatabaseInitializer 2.0.0.0
Copyright c 2022. All rights reserved.
USAGE:
Deploy local agent database for a user:
Frends.DatabaseInitializer --connectionstring "Data Source=(local);Initial Catalog=FRENDS;Integrated Security=True"
--migrationNamespace Frends.DatabaseInitializer.AgentStore --sqlUserName HFWS460\FrendsUser
Upgrade an existing Configuration store database to Azure:
Frends.DatabaseInitializer --assemblyFile .\Frends.DatabaseMigrations.dll --connectionstring
"Server=tcp:[serverName].database.windows.net;Database=myDataBase;User
ID=[LoginForDb]@[serverName];Password=myPassword;Trusted_Connection=False;Encrypt=True;" --doNotCreate
--migrationNamespace Frends.DatabaseMigrations.ConfigurationStore
-c, --connectionstring Required. Connection string to the FRENDS database, e.g. 'Data
Source=(local);Initial Catalog=FRENDS;Integrated Security=True'
-l, --logConnectionstring When migrating configuration store to 5.4, some data is migrated from the
logStore to the configuration store. In that case this parameter is needed.
-u, --sqlUserName Username of the SQL user, e.g. 'DOMAIN\FrendsUser'
-p, --sqlUserPassword Password of the SQL user when using SQL logins
-m, --giveUserTableManagementRights (Default: false) Should the SQL user be allowed to manage the tables, used
e.g. for reorganizing indexes
-a, --assemblyFile The assembly with the fluent migrations to run. If not given, the internal
agent database migrations will be run.
-n, --migrationNamespace (Default: Frends.DatabaseInitializer.AgentStore) The namespace from which to
run the migrations. If not given, the Agent store migrations will be run.
--scriptMigrationNamespace The namespace from which to run embedded Entity framework SQL migration
scripts. If not given, no SQL script migrations will be run.
--doNotCreate (Default: false) Switch for disabling the creation of the database and user
--doNotMigrate (Default: false) Switch for disabling the database migration
--doNotEnableSnapshotIsolation (Default: false) Switch for disabling the default enabling of snapshot
isolation (it is e.g. not supported for Azure SQL)
-t, --timeout (Default: 240) The command timeout (in seconds) used by the SQL commands,
default value 240
--collation (Default: Latin1_General_CI_AS) The collation of the database to create,
default value Latin1_General_CI_AS
--showSql (Default: false) Outputs the executed SQL
--doNotCreateBackupJobs (Default: false) If flag is included backup jobs for the sql server will not
be created
--doNotSetSimpleBackupRecoveryModel (Default: false) If flag is included recovery mode will not be changed to
simple
--backupRetentionMonths (Default: 2) Define retention months for backup data, default is 2 months
--help Display this help screen.
--version Display version information.Database for Legacy Agents
Legacy installer for the Agent Store database is built into the Legacy Agent installer.
You can give the following options on the command line to alter the Agent Store's options.
DONOTCREATEDB = Do not create DB, pass --doNotCreate switch to database initializer. It won't try to create the database and user (required for Azure or stricter DBs where the customer creates the DB and user beforehand). Migrations are run.
DONOTMIGRATEDB = Do not Migrate DB, pass --donotmigrate switch to db initializer. It won't run any migrations
BACKUPRETENTIONMONTHS = How many months should the backup retention to be set for the backup jobs, pass the --backupRetentionMonths switch to db initializer.
DONOTCREATEBACKUPJOBS = Do not create Backup jobs, pass the --donotcreatebackupjobs switch to the db initializer. Skips creating backup jobs. This is only done for new databases created by the initializer.
NODBINIT = Do not run the database initializer, skips running the db initializer altogether.Being in the User group for the Agent user account should be enough to run the Database Initializer. The installer tries to add the Frends Agent user to the Performance Log Users which is needed for the Performance Counters to work.
Due to technical limitations, a Legacy Agent cannot work without an external database. If the Agent Store database is not provided the Agent installer will install a LocalDB on the same machine. That LocalDB is restricted to be used only with one Agent. Thus, you cannot install multiple Legacy Agents on the same machine without an external database. Cross-Platform Agents don't have this limitation.
Installing the Agent
With the Agent set up in Frends, you can start the installation of an Agent to your machine. It is usually a very straightforward process, but you can use the following step-by-step instructions that explain how you can install it.
When installing the cross platform Agents for any platform, you can optionally use additional application settings to override default values. You can learn more about the available settings from Agent application settings.
Installation on Linux machines
First, make sure you have installed .NET and ASP.NET Core on your Linux server. The latest version of Frends requires .NET 8.0. Follow these instructions based on your Linux distribution to install these: https://docs.microsoft.com/en-us/dotnet/core/install/linux.
From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings.
Then, download the preconfigured binary package for the Agent by selecting Preconfigured Linux binary package from the Agent download options. Unzip the package wherever you want. Ensure it is downloaded in an available directory when running the commands below.
After extraction, open and review file unzipped-agent-dir/secrets/appsettings.secrets.json. You can modify it if required to match your server environment.
With these steps, you are ready to run the deployment script. The script will perform the following tasks:
Copy Agent files to
/opt/frends-agent-linux/Create a Daemon service for the Agent called
frendsagent
Change your working directory to the Agent directory and run these commands line by line:
sudo chmod 700 ./Deploy-FRENDS-Agent.sh
sudo ./Deploy-FRENDS-Agent.sh installAfter installation, you can control the Agent with the following commands.
Start, stop and check status of the service:
sudo systemctl start frendsagent
sudo systemctl restart frendsagent
sudo systemctl stop frendsagent
sudo systemctl status frendsagentChecking the Agent logs:
tail -f /var/log/FRENDS/FRENDSAgentService.logInstallation on Windows machines
First, make sure you have installed .NET 8.0 ASP.NET Core Runtime Hosting Bundle and .NET 8 Desktop Runtime x64 or SDK from https://dotnet.microsoft.com/en-us/download/dotnet/8.0.
From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings. Then, download the Windows installer from the Agent download options.
Unzip the downloaded package into a folder, for example named "Frends Agent Installer". The folder should have the following files:
appsettings.secrets.json is the dynamically generated Agent configuration settings
config.json is for custom Agent settings
Frends.Agent.WindowsInstaller.msi is the installer
After extraction, modify the config.json file to add the Frends user details to it. It is possible the details are already in the json file.
To install the Agent, run Frends.Agent.WindowsInstaller.msi and follow the installer.
When completed, the Agent should become active in the Frends UI.
Windows installation troubleshooting
Error logs for troubleshooting:
Event Viewer -> Windows Logs -> Application
C:\Program Files (x86)\HiQ Finland\Frends Agent\logs
Error: .NET v6.0 or later required
If you encounter this error, please make sure you have the correct ASP.NET version. Installation steps can be found in the prerequisites section at the beginning of this article.
Error: Could not find configuration file
If you encounter this error, please make sure you have extracted the contents of the Windows Installer folder into a separate location, and are running the Frends.Agent.WindowsInstaller.msi file from there.
Error: InstallAgentService failed
If you encounter this error, please make sure that the Domain name, username, and password inside the config.json folder are the same as the ones found in Windows Powershell after running the hostname command, and the Local User was created in the previous step.
Installation on Kubernetes
To install Frends Agent on Kubernetes, you need to make sure the target Agent Group has cross platform option enabled. In addition for containerized deployment you need to enable the Allow new Agents to connect to the Agent Group option enabled. Both of these options are enabled from the Frends Control Panel, in Environment and Agent Group settings, under Advanced settings.
Unlike for standard Frends Agent installation, you do not need to configure the Agent in your Frends Tenant beforehand. Enabling the option will allow the Agents to connect to your Agent Group automatically after deployment.
Then, download the configuration file by clicking on the Download Kubernetes configuration link.
The downloaded archive will contain the following files:
deploy directory. This is the working directory. You should run the kubectl commands detailed in README.md from here. When running the commands ensure you are running them from this directory.
README.md this file contains kubectl commands, instructions and information specific to your Agent deployment.
FRENDS-Agent-Deploy.yaml this yaml file defines the deployment and service configuration for your Agent
DatabaseInitializer.zip used to initialize an SQL database for use as a Shared State Store.
secrets directory. This contains the appsettings.secrets.json file and the place to copy your optional SSL certificate (pfx). The contents of this directory are used to create Kubernetes Secrets for your deployment.
appsettings.secrets.json this json file contains application settings specific to your Agent deployment.
To complete the deployment, follow the steps defined in README.md.
In order to configure the Agent for your use case, you can check the configuration options at Agent application settings.
There are multiple different ways to give the application settings to a container.
Directly bundle the appsettings.json inside the container image
Set the configuration into the container environment variables
Pass the configuration as environment variables for Docker or Docker Composer
Check here for the docker documentation
Here is the documentation for docker-compose
You can pass the configuration for Kubernetes either as:
environment variables as documented in Kubernetes docs
secrets directly from the appsettings.secrets.json file, as explained in the README.md file
Using existing SSL certificates with Kubernetes
By default the Frends Agent generates self signed certificates for API and HTTP endpoints. It is also possible to secure API and HTTP endpoints with your own SSL certificates.
For more information and configuration examples see Configuring SSL Certificates for Kubernetes.
Configuring resource usage limits
By default the following CPU/Memory resource limits are set for Frends Kubernetes nodes:
resources:
requests:
memory: "500Mi"
cpu: "300m"
limits:
memory: "4000Mi"
cpu: "1000m"Requests represent the minimum amount of resource (Memory/CPU) a container needs to start. The container will be scheduled to run on a Kubernetes Node providing there are sufficient resources available. Setting these values too high could prevent the Agent from being deployed if there are no Nodes with sufficient free resources.
Limits represent the maximum amount of resource (Memory/CPU) a running container is permitted to consume on a Kubernetes Node. If the limits are too high the container can cause problems for other deployments/containers running on the same Node.
If a container hits the Memory limit it will be terminated (Out of memory). The container would then be restarted (re-scheduled onto an appropriate Kubernetes Node)
If a container hits the CPU limit it will be throttled, slowing down Process executions.
We recommend that appropriate resource limits be established specific to your own Frends Agents through testing and monitoring.
More detailed information can be found in the Kubernetes Documentation.
Installation on Docker
From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings.
Then, download the configuration files from the Agent download options by selecting the Configuration only option.
You will also need the current Frends version number from your Frends Tenant, which you can find under the profile menu, on top right corner. The version number might be 6.1.1.2773 as an example.
Alternatively, you can use for example curl command to get the version number, using command like curl https://tenantname.frendsapp.com/api/navigation/getUIVersion.
Use the following command to launch a Docker Container:
docker run -it -v {full local path to config.json}:/app/secrets/appsettings.secrets.json frendsplatform/frends-agent-linux:{FrendsVersion}Replace the {full local path to config.json} and {FrendsVersion} with the actual path and version value you have. The -v parameter mounts the downloaded local agent config json file in the container under /app/secrets/appsettings.secrets.json.
Actual command might look like the following on Windows OS:
docker run -it -v c:\downloads\downloaded_agent_config:/app/secrets/appsettings.secrets.json frendsplatform/frends-agent-linux:6.1.1.2773In order to configure the Agent for your use case, you can check the configuration options at Agent application settings.
There are multiple different ways to give the application settings to a container.
Directly bundle the appsettings.json inside the container image
Set the configuration into the container environment variables
Pass the configuration as environment variables for Docker or Docker Composer
Check here for the docker documentation
Here is the documentation for docker-compose
You can pass the configuration for Kubernetes either as:
environment variables as documented in Kubernetes docs
secrets directly from the appsettings.secrets.json file, as explained in the README.md file
Legacy installation on Windows
In order to perform installation of legacy Frends Agent, make sure the target Agent Group has cross platfrom option disabled. Legacy Agent cannot be installed into a cross platform Agent Group, and vice versa.
With the cross platform option disabled, select Installation package from the download options for the configured Agent. Note that the download options for non-cross platform Agent Groups and Agents are different than if the cross platform option is enabled.
After downloading the Agent, copy the Agent installer package to your chosen server and un-zip the installer package to a temporary location. It's a good practice to archive the Agent installer packaged on the server if you might want to re-install the Agent later, though you can also always download the installer from the Frends Environment View.
The un-zipped installer package should have two files: a config file and the Frends.Agent.Installer.Bundle. Double click the Frends.Agent.Installer.Bundle to start the installation. You can configure the installation location during the process, which by default is set to Program Files folder.
If the installation was successful, you are now done! You have a working Frends Agent installed on your server and you can start deploying and executing integrations with it.
Verifying the Agent is working
After you have installed your Frends Agent you can now see the new Agent in the Environment and Agent Group selector in the Process View. If you select your Environment you should see a message: "No Processes". This means that we can now deploy a Process to the Environment to verify that everything works as it should.
If the Process deployment and activation succeeded, you should see that the Trigger for your Process, in the Triggers column, is highlighted in blue. Hovering the mouse over it will also tell you that the Trigger is active on the listed Agents.
You can also check the deployment directory in the newly installed Frends Agent server, for example on Windows:
C:\Users\{YOUR AGENT USERNAME}\AppData\Local\Frends Technology\Frends Agent\processesInside the folder you can see all the integration Processes as well as their versions deployed to the Agent and all of their source code and compiled code that the Agent executes.
You can also monitor your Agent from the Services app on the device the Agent is installed on. In the Status column you can observe whether your Agent is running or not.
Here it is possible to start, pause and stop the Agent. It may take a few minutes for the Agent to stop running.
High Availability & other installation variations
Agents and Agent Groups can be configured in different ways for different kinds of needs.
Multiple Agents in an Agent Group with a shared SQL database
If a central SQL Server, PostgreSQL or Azure SQL Database instance is available and an Agent Group has a connection string set for it, the Agents will use a shared SQL database called Shared State Store and all Triggers are available in High Availability mode, meaning all connected Agents can execute any Trigger.
This is the most common mode of installing multiple Agents in one Agent Group and should be used in most cases.
Multiple Agents without a shared SQL database
If there's no central database available or the connection string is not set, all the Agents will use a local database for storing configuration information by themselves.
The first deployed Agent in Agent Group will be the "Primary Agent". This Agent will be able to execute all Triggers. Other Agents will be able to run HTTP, API and Service Bus Triggers in the Agent Group. If this mode is selected, Schedule and File Triggers cannot be run in High Availability mode, meaning only the Primary Agent will run those Triggers.
This mode of installation is useful if you do not have a SQL Server but still want to have redundancy and load balancing for HTTP and API Processes.
Last updated
Was this helpful?