Best PracticesHow-Tos

How to install Workato on-premise agent as a Linux systemd service

On-prem agent on Linux
Read Time: 4 minutes

Workato’s On-Prem Agent provides secure connectivity for applications, databases, and devices that are protected by corporate firewalls. You can install and configure the Workato OPA on different operating systems based on your needs. You can also set up the On-Prem Agent as a Linux systemd service.

Why configure OPA as a Linux systemd service?

By default Workato On-Prem Agent for Linux is distributed as a tar.gz file which makes it, on one hand, universal, but on the other hand, it can not be used as a system service out-of-the-box. The agent does not need any specific privileges so you can just download the archive and test it without executing a single command as root. However, when testing is over, you may want to run this agent instance as a systemd service to make it start and stop automatically with the server. In this guide, we’ll step through this process in detail.

Create user and set filesystem permissions

First let’s create a non-privileged user, group, and home directory:

mkdir /opt/workato
groupadd -r workato
useradd -c "Workato On-Premise Agent" -g workato -s /sbin/nologin -r -d /opt/workato workato

This user has a minimal set of privileges. It can not make any changes to Linux system files. So no matter which code is executed, this Linux system will stay untouched and secure.

Then you need to download and unpack the agent. You can find the latest actual URL at ‘Tools’ -> ‘On-prem Groups’ -> {Your Group} -> ‘Add Agent’ or (in case agent was added earlier) you map press three dots button and select ‘Download installer’. Be sure to select Linux OS during Agent creation here. Now you can download the package and unpack it

# curl https://workato-public.s3.amazonaws.com/agent/workato-agent-linux-x64-X.Y.Z.tar.gz --output ~/workato-agent.tar.gz
# cd /opt/workato
# tar -xzf ~/workato-agent.tar.gz --strip 1
# chown -R workato:workato .

After this agent’s home folder should look like that:

# ls -la
total 12
drwxr-xr-x. 7 workato workato   66 Feb  5 17:08 .
drwxr-xr-x. 3 root    root      21 Feb  5 16:58 ..
drwxr-xr-x. 2 workato workato  125 Dec 12 02:06 bin
drwxr-xr-x. 2 workato workato   56 Feb  5 17:09 conf
drwxrwxr-x. 4 workato workato  129 Dec 12 02:06 jre
drwxr-xr-x. 2 workato workato 8192 Dec 12 02:06 lib
drwxr-xr-x. 2 workato workato   40 Dec 12 02:06 lib_ext

Copy certificate, private key, and config file

Now we need to identify this agent’s instance by supplying the agent key granted by Workato. For security reason, you can download it in your browser only. So please do so and then upload it to the server using secure FTP

$ scp ~/cert.zip root@yourserver.com:~

Note: for Windows users, I’d suggest using WinSCP or FileZilla at this step.

When the key is transferred, you should unpack it into conf folder:

# cd /opt/workato/conf/
# unzip ~/cert.zip

You also need to create /opt/workato/conf/config.yml file. Its contents depend a lot on your enterprise IT landscape. Workato documentation contains a lot of samples that can help you to connect almost any kind of on-prem app to Workato.

Testing the agent

Now you should be able to run this agent as a non-privileged user from the command line. Let’s do this to verify our setup

# su -s /bin/bash -c '/opt/workato/bin/run.sh' -g workato workato
Running Workato Agent using console.
2021-02-05 19:01:00.172Z [main] INFO     com.workato.agent.Config - [JRE] Oracle Corporation version 1.8.0_131
2021-02-05 19:01:00.177Z [main] INFO     com.workato.agent.Config - [OS] Linux amd64 4.18.0-80.4.2.el8_0.x86_64
2021-02-05 19:01:00.649Z [main] INFO     com.workato.agent.Main$1 - Refreshing com.workato.agent.Main$1@553a3d88: startup date [Fri Feb 05 19:01:00 UTC 2021]; root of context hierarchy
...
2021-02-05 19:01:09.444Z [main] INFO     c.w.agent.http.Server - Connector started on /127.0.0.1:3000
2021-02-05 19:01:10.341Z [main] INFO     c.workato.agent.net.Agent - Gateway ping successful: sg1.workato.com:443 version 2.2.3
2021-02-05 19:01:10.740Z [main] INFO     c.workato.agent.net.Agent - Gateway ping successful: sg2.workato.com:443 version 2.2.3
2021-02-05 19:01:11.229Z [agent-control-thread] INFO     c.workato.agent.net.Agent - Connected to gateway sg1.workato.com.
2021-02-05 19:01:11.294Z [agent-control-thread] INFO     c.workato.agent.net.Agent - Connected to gateway sg2.workato.com.

You can also visit the on-prem groups page of your Workato account to verify that the agent managed to connect. You can shut down the agent by pressing Ctrl+C.

Run agent as a systemd service

Now we can be sure that agent installation succeeded, let’s run it as a system service. For this purpose we need to create the service configuration file:

# cat > /lib/systemd/system/workato.service <<EOF
# Systemd unit file for default Workato On-Premise Agent
#
# To create clones of this service:
# DO NOTHING, use workato@.service instead.

[Unit]
Description=Workato On-Premise Agent
After=syslog.target network.target

[Service]
Type=simple
WorkingDirectory=/opt/workato
ExecStart=/opt/workato/jre/bin/java -Djava.security.egd=file:/dev/urandom -cp "/opt/workato/lib/*" com.workato.agent.Main
User=workato

[Install]
WantedBy=multi-user.target
EOF

In this example, I’m using Java Runtime Environment (JRE) bundled with Workato On-Prem Agent. If you want to use a different JRE, you should replace /opt/workato/jre/bin/java it with let’s say /usr/bin/java.

Now we can start the service:

# systemctl start workato
# systemctl status workato
● workato.service - Workato On-Premise Agent
   Loaded: loaded (/usr/lib/systemd/system/workato.service; enabled; vendor preset: disabled)
   Active: active (running) since Fri 2021-02-05 17:46:27 UTC; 33s ago
 Main PID: 14359 (java)
    Tasks: 35 (limit: 4998)
   Memory: 211.5M
   CGroup: /system.slice/workato.service
           └─14359 /opt/workato/jre/bin/java -Djava.security.egd=file:/dev/urandom -cp /opt/workato/lib/* com.workato.agent.Main
...

Now when service is running we can also enable it to start with the host:

# systemctl enable workato
Created symlink /etc/systemd/system/multi-user.target.wants/workato.service → /usr/lib/systemd/system/workato.service.

What’s next?

You can start using your agent now and build recipes. In case of any trouble the agent reports to the system log. By default, it is located in /var/log/messages and you can watch it using a tail command like that:

# tail -f /var/log/messages
...
Feb  5 19:23:57 ip-172-31-3-22 java[14629]: [main] INFO     o.a.c.c.StandardService - Starting service [Tomcat]
Feb  5 19:23:57 ip-172-31-3-22 java[14629]: [main] INFO     o.a.c.core.StandardEngine - Starting Servlet engine: [Apache Tomcat/9.0.38]
Feb  5 19:23:58 ip-172-31-3-22 java[14629]: [main] INFO     o.a.c.h.Http11Nio2Protocol - Starting ProtocolHandler ["https-jsse-nio2-127.0.0.1-3001"]
Feb  5 19:23:58 ip-172-31-3-22 java[14629]: [main] INFO     c.w.agent.http.Server - Connector started on /127.0.0.1:3001
Feb  5 19:23:58 ip-172-31-3-22 java[14629]: [main] INFO     c.workato.agent.net.Agent - Gateway ping successful: sg1.workato.com:443 version 2.2.3
Feb  5 19:23:59 ip-172-31-3-22 java[14629]: [main] INFO     c.workato.agent.net.Agent - Gateway ping successful: sg2.workato.com:443 version 2.2.3
Feb  5 19:24:00 ip-172-31-3-22 java[14629]: [agent-control-thread] INFO     c.workato.agent.net.Agent - Connected to gateway sg2.workato.com.
Feb  5 19:24:00 ip-172-31-3-22 java[14629]: [agent-control-thread] INFO     c.workato.agent.net.Agent - Connected to gateway sg1.workato.com.

Conclusion

Thus, in this guide, we installed Workato on-premise agent to the Linux host and configured systemd service. Now this agent will start and stop together with the operating system. Log messages are saved to Linux syslog and can be rotated, monitored, and archived using a wide range of tools.