Install and manage GroundRunners

GroundRunners enable chain commands to interact with on-premises systems or remote data sources not otherwise accessible over the internet. They're typically installed on a dedicated server, such as the one that hosts your connected data source, by an IT professional or someone otherwise familiar with your organization's network settings.

Before setting up a GroundRunner, we recommend reviewing the Chain Builder security architecture.

Requirements

A compatible operating system is required, and if your GroundRunner will access shared resources such as a Windows Universal Naming Convention (UNC) path, then a user account with sufficient privileges is needed as well.

A Java Runtime Environment (JRE) is not installed with the GroundRunner during the initial GroundRunner installation.

After setup is completed and the GroundRunner is running, it will automatically download a JRE as needed to run commands that depend on Java. No installation or admin intervention is required, and the retrieved JRE will not affect existing JRE installations if they exist on the host.

Alternatively, if you have organizational requirements that require the use of a particular JRE, the SHARED_LIBRARY_OVERRIDES environment variable can be set to point to the system installation. In this case, the GroundRunner will not automatically download the Workiva standard JRE, and will use the provided system JRE installation.

Workiva-supplied JREs are licensed under GPL v2, and are covered by the classpath exception.

Note: To use custom certificates with your Java installation, see Using custom certificates with GroundRunners.

At this time, GroundRunners can be installed on the following operating system families with no external library dependencies:

Windows and Windows Server
Linux distros and derivatives:
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (for testing only)

Workiva strives to support all modern versions of the OS families listed above. However, we cannot support any operating system that has been designated as "end of life" by its vendor. These older operating systems pose potential security risks and should be updated to a current version as soon as possible. Learn more about our end-of-life policy.

Note: Each operating system's support schedule is set by the individual vendor. For example, Microsoft's support for Windows 7 ended on January 14, 2020; Workiva's support for Windows 7 ended on the same date.

Hardware requirements

While GroundRunners require limited server resources, we recommend at least:

512MB of available random access memory (RAM)
100GB of available disk space

Note: To help calculate the required disk space, know that a chain with five commands that each produce 10MB ephemeral outputs requires 50MB to complete.

The recommended host configuration includes a virtual machine configured with:

Two to four processors

Note: ARM-based processors are not compatible with GroundRunners.
8GB of system memory
A solid state drive (SSD) storage device

This server must be available 24/7 to communicate with the GroundRunner.

By default, GroundRunners use a local administrative account without access to remote resources such as shared drives.

To access a shared resource such as a Windows UNC path, start the GroundRunner under a user account with adequate privileges to the resource. If using a user account other than the default local system administrator, grant it permissions to manage the GroundRunner's installation directory to enable automatic updates.

Role requirements

On the Workiva platform

On the Workiva platform, you need a role that grants access to the Chain Builder settings and the ability to manage Runners. There are two:

Chain Owner: This is the primary role required. Users with this role can access the "Downloads" section in Chain Builder to retrieve the latest GroundRunner installation files and manage the "Runners" tab to activate or monitor the service.
Org Chain Security Admin: This organizational-level role also has the authority to manage connections and runners across multiple workspaces.

On the server

Because a "manual update" involves stopping services and replacing executable files on the physical or virtual machine where the GroundRunner is installed, the user must have administrative privileges on the host server.

Windows: You must have the ability to run the Command Prompt as an Administrator and access the Windows Service Manager (to stop and restart the GroundRunner service).
Linux/macOS: You must have sudo or root access to move files into the installation directory and restart the background process.

Download the GroundRunner

To download a GroundRunner for installation or manual update:

On the Workiva Home sidebar, click Chains.
On the Chain Builder sidebar (this is a new tab), click Connections.

Alternatively, you can click the user profile icon in the top right, select Chains admin, and then Workplace Settings.
Click Downloads in the top menu bar.
Find the GroundRunner for your operating system, and click Download for it.
Once it has downloaded successfully to your computer, select the appropriate instructions from the set below, and follow them to install the GroundRunner.

Install the GroundRunner

The Microsoft Installer (MSI) requires .NET 3.5 or higher.
If you can't meet this requirement, you will have to install the GroundRunner using the command line interface instead.

To install the GroundRunner:

Unzip GroundRunner.zip to a new folder, and open the folder.
Run GroundRunner.msi to open the GroundRunner Setup wizard.
Click Next.
Review and accept the terms in the license agreement, and click Next.
For the Destination Folder, enter the path where the GroundRunner will be installed, (for example: C:\Program Files\GroundRunner\) and click Next.
In Platform company token, enter your company token.
In Platform auth host:
- For APAC, enter h.apac.wdesk.com/s/chains-reaper.
- For EMEA, enter h.eu.wdesk.com/s/chains-reaper.
- For the United States, Central America, and South America, enter h.app.wdesk.com/s/chains-reaper.
If using a proxy server, enter its URL and port in Proxy host.
(For example, http://yourproxy:3000.)
To bypass the proxy server, enter a comma-separated list of hosts under No proxy host.
Click Next, Install, and Finish.
Once installed, right-click on the GroundRunner from the Windows Service Manager and select Start.

Your GroundRunner has now been installed and is ready for activation.

To install via command line interface, you must download the GroundRunner's installation to its own directory within your program files (for example c:\Program Files (x86)\wdata). You can then unzip the installation file and extract it to the root of that directory.

You can then install the GroundRunner:

In the Windows command window, enter
```
c:\Program Files (x86)\wdata\installer.exe install
```
and accept all defaults.
- Select "windows" for the init system.
  
  You need to specify that the GroundRunner is to operate as a Windows service for it to be supported with automatic updates. GroundRunners should only be run as a service, except for testing purposes.
- For the path, create a Files folder within the new directory
  (for example, C:\Program Files (x86)\Wdata\Files).
- For the authorization hostname (AUTH_HOST):
  - For APAC, enter h.apac.wdesk.com/s/chains-reaper.
  - For EMEA, enter h.eu.wdesk.com/s/chains-reaper.
  - For the United States, Central America, and South America, enter h.app.wdesk.com/s/chains-reaper.
- Enter your company token.
Delete all files from the directory except the GroundRunner executable directory.
Select whether to run the GroundRunner as a service or a foreground process.
- If running as a service, do one of the following:
  - In the command dialog, enter sc start GroundRunner.
  - In Windows Service Manager, start the GroundRunner service.
- If running as a foreground process, in the command dialog enter:
```
cd c:\Program Files (x86)\wdata GroundRunner.exe
```

Your GroundRunner is now installed and ready for activation.

Step 1. Install the GroundRunner

Download the GroundRunner's installation file to its own directory,
for example: /home/user_name/wdata/.

Note: "/home/user_name/wdata" is provided as an example. Follow your organization’s policy for service install locations.
In a command dialog, unzip the installation file using:
```
unzip GroundRunner.zip
```
Enter the GroundRunner's details.
1. Enter ./installer install
2. For the authorization hostname (AUTH_HOST):
  - For APAC, enter h.apac.wdesk.com/s/chains-reaper.
  - For EMEA, enter h.eu.wdesk.com/s/chains-reaper.
  - For the United States, Central America, and South America, enter h.app.wdesk.com/s/chains-reaper.
3. Enter your company token.
Delete all files from the directory except the folder that was created during the installation process.

Step 2. Set up your GroundRunner as a systemd service (Linux)

In order to ensure GroundRunner automatic updates work, and for good GroundRunner hygiene, the GroundRunner needs to be installed as an enabled, restartable, systemd service. Please refer to your Operating Systems’ documentation and organization policy about how to run the GroundRunner as a systemd service.

For basic configurations, we have the following systemd unit file requirements for auto-updates to work properly:

Ensure the ExecStart executable points to the GroundRunnerMonitor binary and NOT the
GroundRunner binary.
Set Restart=always.
Do not set StartLimitBurst or StartLimitIntervalSec, as these may prevent the GroundRunner from restarting due to transient errors. If you wish for the GroundRunner to not get in a fast restart loop, you can configure RestartSec.
Enter systemctl enable to enable the systemd GroundRunner service unit so that the GroundRunner will survive a reboot.

Workiva does not officially support running a GroundRunner as a foreground process. This may be useful for testing a configuration, but, once a GroundRunner is configured, it should be set up as a long-lived, background process.

Operating GroundRunners on macOS (Testing Only)

Workiva supports GroundRunners on macOS for testing purposes only. While macOS GroundRunners are capable of running the same commands as the Linux and Windows versions, Workiva does not officially support launchd as a valid service manager. This is because Apple discontinued support for their macOS server software in 2022. Apple laptops and desktop computers are not suitable for running GroundRunners.

Activate the GroundRunner

After installing your GroundRunner, you must activate it within Chain Builder.

On the Chain Builder sidebar, click Connections.
Click Runners at the top, and then click Pending Registration.
Enter a short, descriptive name for the runner.
For example "<datasource>-GroundRunner".
Click Activate.

Manually update a GroundRunner

While this is rarely required, you may need to manually upgrade a GroundRunner.
Refer to the Workiva Support page GroundRunner Manual update for instructions on how to do this.

Uninstall a GroundRunner

If you no longer need a GroundRunner, you can uninstall it.

From Windows Settings, go to Apps & features, select GroundRunner (64 bit), and click Uninstall.

Stop the GroundRunner service.
- If it is running as a service, use Windows Service Manager, or enter
  sc stop GroundRunner in a command window.
- If it is running as a foreground process, press Ctrl+C.
In the command dialog, as an administrator, enter
installer.exe uninstall.
Delete the GroundRunner executable directory.

In the command dialog, stop the GroundRunner service and delete its executable directory (e.g., /home/<username>/wdata/Contents).

Installing a custom JRE

If required, you can install your own JRE to support a GroundRunner. The Java version of this JRE must match the one required for the Groundrunner. Other than the Oracle Essbase and Oracle Hyperion Financial Management (HFM) GroundRunners, all GroundRunners use the same JRE version. For information on how to install a custom JRE, see Disable Workiva shared libraries.

GroundRunner configuration settings and outbound domains

To enable communication with its data source, you may need to open firewall ports on the server where the GroundRunner is installed. To change the configuration settings of some GroundRunners, you can edit the GroundRunner.config file in the directory where the binaries are installed.

Configuration	Settings
PORT	0 to 65535. By default, GroundRunners use port 8821 to communicate with one another. However, a port is required only if GroundRunners on different servers share command outputs inside your network.
COMPANY_TOKEN	Leave as default, unless the GroundRunner is configured for a different tenant.
LOG_LEVEL	Info or debug
PROTOCOL	Leave as default.
HTTP_PROXY_URL	If using a proxy server, enter its URL and port (if necessary). For example, `http://yourproxy:3000` Note: GroundRunners may use proxy servers, but not those authenticated via New Technology LAN Manager (NTLM). Instead, allow the server's IP address.
LONG_POLL	If using a proxy server, set to true to instruct the runner to use long-polling to retrieve commands. To ensure performance, use long-polling only if web sockets aren't supported by your proxy server or firewall.
NO_PROXY	To bypass the proxy server, provide a comma-separated list of hosts to reach directly instead. To include multiple hosts based on a common pattern, use the * wildcard.
GROUNDRUNNER_CERT	Needed if using more than one GroundRunner and wishing to send encrypted information to the second GroundRunner. This must be used in conjunction with PORT. You must also specify the PROTOCOL field as HTTPS when activating the runner.
GROUNDRUNNER_CERT_KEY	Needed if using more than one GroundRunner and wishing to receive encrypted information from a second GroundRunner. This must also be used in conjunction with PORT.
DISABLE_WEBSOCKETS	Websockets are required to run transformations. When disabled, any commands using transformations will be skipped entirely.

Note: Your self-signed certificate must have a Subject Alternative Name (SAN). If it does not, when your GroundRunner attempts to download files, it will show an error message referencing the missing SAN.

If your network must allow outbound domains, these apply to GroundRunners:

Domain	Purpose
`h.app.wdesk.com` `h.apac.wdesk.com` `h.eu.wdesk.com`	The main subdomains for common Workiva services, including Wdata.
`*.wdesk.com`	The main domain for the production Workiva platform.
`..wdesk.com`	The subdomains for supporting components in the Workiva platform.

Security

GroundRunners never collect or aggregate data; they retain data only during transmission. An extended validation (EV) certificate always encrypts and protects traffic between a GroundRunner and its data source via DigiCert®.

Note: To secure on-premises data, CloudRunners can share output with GroundRunners, but GroundRunners can't share file outputs with CloudRunner.

Troubleshoot GroundRunner errors

If you receive these errors when a chain runs, check the command's GroundRunners.

Tip: To help ease troubleshooting, you can create a chain to automatically download a GroundRunner's log file to a table.

Error message	Cause	Resolution
Failed to communicate with agent—this command was not executed	The command couldn't communicate with its GroundRunner. If this happens, the GroundRunner didn't start or a network disruption occurred between the GroundRunner and Chain Builder.	Verify: The GroundRunner's service is working. The GroundRunner's server is connected to the internet.
Unable to download resources associated with command. Please contact Support if error persists.	The runners associated with these chain's commands can't communicate with one another. This often occurs when commands use different runners and the CloudRunner is trying to use a file output from a GroundRunner-based command.	Use the same runner with all commands in the chain. If the chain's commands require multiple runners, verify no commands with GroundRunners pass file outputs to commands that use the CloudRunner.
Error starting command: `exec: \"\\[connector].exe\": file does not exist" commandExecutorId=[ID]`	A malware- or antivirus-application incorrectly identified the connector and intercepted its communication with the GroundRunner.	Exclude the GroundRunner installation directory from the application's scans.
Certificate Errors	Using Self Signed Certificates	In many cases, it will be convenient to use self-signed certificates to encrypt GroundRunner communication. If you are using a self-signed certificate, be sure that the Common Name of the certificate matches the URL at which the server can be accessed. For example, if your GroundRunner is listening on port 8821 and you can access the server from your network `localhost`, the certificate's Common Name would be "`localhost`".
Intermittent chain failure with error: "Connection reset by peer"	When multiple runners are installed on the same machine, they must each have a unique GUID. If the same GUID is used, the runners may overlap and enter into an update loop -- causing occasional chain failures.	We recommend a complete reinstall of the GroundRunner.
Commands are skipped on GroundRunner but succeed on CloudRunner	Websockets are required to run transformations. When websockets are disabled any transformations will be skipped entirely.	Open your config file and set `DISABLE_WEBSOCKETS=false`.
Error reading from socket. `Retrying connection: read tcp <IP>:<Port>-><IP>:<Port>: wsarecv: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.`	Internal firewall or network issue	Engage your internal IT or network team to review the logs and configuration in order to resolve the error.
read <IP>:<Port>-><IP>:<Port>: `wsarecv: An existing connection was forcibly closed by the remote host`	Internal firewall or network issue	Engage your internal IT or network team to review the logs and configuration in order to resolve the error.

Additional resources

Support

Community

Workiva Support Center