|
Classic file types are no longer available for use as of January 2021. You can transition your classic files or download a PDF. Learn More

Workiva Support Center

Restarting a GroundRunner

Restarting a GroundRunner

  • Last updated on

Use these steps to get GroundRunner running again after it has stopped.

Important: Throughout this document, references to the "GroundRunner" means starting the "GroundRunnerMonitor" process (this is "GroundRunnerMonitor" on Linux and "GroundRunnerMonitor.exe" on Windows).
Do not start either the GroundRunner (Linux) or GroundRunner.exe (Windows) directly — the monitor is responsible for managing its operation.

Prerequisites

  • Access to the host machine where GroundRunner is installed
  • The installation directory where the binaries reside
  • Permission to start services or processes on the machine

Verify binaries

Before attempting to start the GroundRunner, use the following commands to confirm the binaries are still present in the installation directory. Your installation directory may vary.

For Linux

ls /path/to/groundrunner/installation/GroundRunner
ls /path/to/groundrunner/installation/GroundRunnerMonitor

For Windows

dir C:\path\to\groundrunner\install\GroundRunner.exe
dir C:\path\to\groundrunner\install\GroundRunnerMonitor.exe

If either binary is missing, you must restore that binary from a backup or re-install it before proceeding.

Instructions

Linux

Note: The instructions below are for systemd-based Linux distributions. If your system uses a different init system or process supervisor, please consult your distribution's documentation for the equivalent service management commands.

If you do not know the service name, you can search for it using the following command:
sudo systemctl list-units | grep -i groundrunner

If the service is not recognized or cannot be found, the GroundRunnerMonitor may not have been registered as a systemd service. See If you do not run GroundRunner as a monitored service below.

Start systemd service

  1. If GroundRunnerMonitor was configured as a systemd service, start it with the following command. Be aware that your service name may vary depending on how it was configured.
    sudo systemctl start <service-name>
  2. Verify it is running:
    sudo systemctl status <service-name>
  3. (Optional, but recommended) Enable the service so it starts automatically after a system reboot:
    sudo systemctl enable <service-name>

Windows

Using the Services console

  1. Open the Services console:
    1. Press Win+R.
    2. Enter services.msc
    3. Press Enter.
  2. Find the GroundRunner service in the list, right-click it and select Start.
    Start GroundRunner Service
    The Status column should update to "Running".
    GroundRunner Running Status

If you do not see a "GroundRunner" service listed, GroundRunnerMonitor.exe may have been set up as a foreground process.

Using the Command line

Alternatively, you can use the command line. If you do not know the name of the service:

  1. Press Win+R.
  2. Enter cmd.
  3. Enter sc query to get a list of all services.
  4. Locate your service name.
  5. Enter sc start <service-name>.
  6. Enter sc query <service-name> to verify it is running.
    The "STATE" field value should be 'RUNNING'.
  7. (Optional but recommended) Configure the service to start automatically after a system reboot.
    • Using the command line
      1. Press Win+R.
      2. Enter cmd.
      3. Press Enter.
      4. Enter sc config <service-name> start=auto in the command window, and press Enter.
    • Using the Services console
      1. Press Win+R.
      2. Enter services.msc.
      3. Press Enter.
      4. In the Services console:
        1. Right-click the GroundRunner service.
        2. Click Properties.
        3. Set Startup type to "Automatic".
          Set Startup to Automatic
        4. Click OK.

 

Verification

After starting the GroundRunner, verify that the expected version (9.21.1) is reported in the Workiva Chains application and is showing as "Running".

GroundRunner Running Status

 

Notes

  • Always run GroundRunnerMonitor, not GroundRunner directly —The GroundRunnerMonitor process is responsible for managing the lifecycle of GroundRunner, including applying automatic updates. Running the GroundRunner binary directly bypasses this management and will result in missed updates and unexpected behavior.
  • Custom configurations — If your environment uses a service manager other than systemd or the Windows Service Control Manager, perform the equivalent start and status check for your configuration.
  • Do not rename the binaries — The auto-upgrade mechanism relies on the default executable names (GroundRunner, GroundRunnerMonitor and GroundRunner.exe, GroundRunnerMonitor.exe)to detect and apply future updates.
  • API Grant regeneration — You do not need to regenerate the API Grant after rebooting the GroundRunner server. As long as the GroundRunner service restarts correctly after the reboot and reconnects to Workiva, the existing API Grant remains valid.
  • Antivirus scanning and GroundRunners — We consider the best practice to exclude the entire GroundRunner installation directory and its tmp subfolder from antivirus scanning, rather than excluding individual .exe files. This prevents similar blocks on other plugin executables.

 

Configuring GroundRunner as a monitored service

Linux (systemd)

Configure GroundRunnerMonitor as a systemd service. If a unit file does not already exist for GroundRunnerMonitor, one will need to be created. SUSE's guide to setting up a systemd service is a useful reference for this process, though it is a third-party resource and your specific environment may require adjustments.

In your systemd unit file, ensure the following settings are present under [Service] so that the process restarts automatically on exit or failure:

[Service]
Restart=always
RestartSec=10

After creating or updating the unit file, use the following commands to reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable <service-name>
sudo systemctl start <service-name>

Windows

Register GroundRunnerMonitor as a Windows service. Once registered, configure the service to restart on failure. Either:

Using the Services console

  1. Press Win+R.
  2. Enter services.msc.
  3. Press Enter.
  4. In the Services console, right-click the GroundRunner service.
  5. Click Properties.
  6. Select the Recovery tab.

  7. Set the First failure, Second failure, and Subsequent failures values to "Restart the Service".

    Recovery Tab Settings
  8. Click OK.

Using the command line

  1. Press Win+R.
  2. Enter cmd.
  3. Press Enter.
  4. Enter the following command and press Enter:
    sc failure <service-name> reset=0 actions=restart/10000/restart/10000/restart/10000
    This tells Windows to restart the service after 10 seconds on each failure.

 

If you do not run GroundRunner as a monitored service

We recommend that GroundRunnerMonitor be run as a restartable service on the host operating system, rather than as a foreground process, because a foreground process will not survive terminal disconnections, machine restarts, or automatic updates — and any of these will require manual intervention to get GroundRunner running again. For information on installing GroundRunners, see the Workiva Support page: Install and manage GroundRunners.

 

Video demonstrations

These videos illustrate the processes described above.

For Linux

For Windows

Use these steps to get GroundRunner running again after it has stopped. Important: Throughout this document, referenc...