Skip to main content

Set up and manage relays

A relay lets your on-prem legacy LSAM machines run jobs that OpCon Continuum dispatches from the cloud. You install it on your side, it connects outbound to OpCon (no inbound firewall changes), and it hands work to the LSAM machines behind it.

What this solves

Your legacy LSAM machines live on-prem, but the scheduler runs in the cloud, and opening inbound firewall holes to reach them is a non-starter. The relay bridges that gap with a single outbound connection, so cloud-scheduled work reaches on-prem machines without exposing them.

How a relay connects​

  • It connects outbound only: nothing inbound needs to be opened to the internet.
  • It authenticates with a credentials.json file you download when you register it.
  • One relay can front several legacy agents, and a legacy agent group can span more than one relay.

1. Get the relay software​

On Agents → Legacy Agents & Groups, choose Download Relay — in the toolbar, or in the empty state if you have no relays yet. The dialog names the latest published version and its publish date, and offers a download button for each platform that release covers.

This creates no relay and issues no credential, so it is safe to do before you have decided anything.

Do this before registering, not after

Earlier builds offered the artifact only on the Register Relay success screen, so getting the binary meant registering a relay — and because reopening that dialog resets it, a download that failed left you registering a second relay to try again. If a runbook of yours says to register in order to download, it can be simplified.

If Download Relay is greyed out, hover it: the tooltip distinguishes a lookup still in progress, nothing published, a release that covers no platform offered here, and a lookup that actually failed. The last one is worth chasing; the others are not faults.

2. Register the relay​

To register a relay, complete the following steps:

  1. Go to Agents → Legacy Agents & Groups and choose Register Relay.
  2. On the success screen:
    • Download credentials.json — the file the relay needs to authenticate. Do this before you close the dialog.
    • Note the connection details shown: the AGENT_SERVICE_URL and path prefix for your environment. Each has a copy button, and the installer takes them as arguments.
    • Copy the install commands for your platform. They are pre-filled with this environment's URL and the release's version.
The credential is download-only, and the secret cannot be retrieved

The Client ID and Client Secret are never displayed and cannot be copied — they exist only inside the credentials.json you download. If you lose that file you do not need to start over: regenerate the credentials instead.

You still need this step even if you already downloaded the relay

The artifact on its own is not runnable: the installer does not set the connection environment, and the relay cannot authenticate without credentials.json.

3. Install the relay​

Both platforms follow the same three moves: extract, install, then replace the placeholder credentials and start the service. The installer does not start the relay, and it places a placeholder credentials.json that the relay cannot authenticate with.

cd ~/Downloads
tar -xzf opcon-relay-<version>-linux-x64.tar.gz
cd opcon-relay-<version>
sudo ./install/install.sh --agent-service-url <url>
sudo cp /path/to/credentials.json /etc/opcon/credentials.json
sudo systemctl enable --now opcon-relay

The installer puts the app under /opt/opcon-relay, writes your settings to /etc/opcon/relay.env, and logs to /var/log/opcon-relay. To change a setting later, edit relay.env and sudo systemctl restart opcon-relay.

It also gives the service a state directory at /var/lib/opcon-relay, which is where the relay keeps what it needs to resume after a restart. /etc/opcon stays read-only, which is the point: earlier Linux relays kept that state in the config directory and so could never write it, and a restart lost track of the legacy jobs that were running and did not recover OpCon MFT or OpCon RPA runs in flight. If you are running a Linux relay from an earlier build, re-run the installer — there is nothing of your own to configure. See Surviving a relay restart.

Copy your credentials.json onto the placeholder rather than deleting and replacing it — that keeps the restricted ownership and permissions the installer applied.

The installers take the connection details as arguments, so you do not set environment variables by hand. Use the values from the register dialog: --agent-service-url / -AgentServiceUrl is required and the installer aborts without it, and the path prefix (for example /agent-api) is for cloud environments — leave it empty for local or dedicated setups.

Reinstalling resets every option you do not re-pass

Re-running the installer to upgrade or change a setting rebuilds the relay's settings from its arguments, so any option you passed the first time and omit the second reverts to its default — and hand edits to relay.env are lost. Re-pass the whole set. An existing credentials.json is kept.

Good to know

No runtimes to install. The Linux and Windows packages are self-contained and bundle everything the relay needs, so you do not need Node.js or .NET on the host. Every download also contains a README.md with the full numbered steps and parameter tables for that release.

4. Confirm it's running​

On any platform, GET http://localhost:8080/health returns 200 once the relay is ready, and 503 while it's still starting. In OpCon, the relay appears and its legacy agents come online.

To check the service itself:

systemctl status opcon-relay shows the service, and journalctl -u opcon-relay shows its logs. The LSAM Connector also writes lsam-connector-<date>.log into /var/log/opcon-relay, cleaned up for you — see Logs, rotation and retention. Earlier Linux relays could not write that file at all; its output went only to the journal.

5. Give each legacy agent a default event environment​

Machines behind a relay can raise Continuum events themselves — a job or process writes a file of event syntax into the agent's MSGIN directory and the agent sends it up the connection it already holds. Every legacy agent needs one thing set before that works: a Default event environment, on its register/edit dialog under Agents → Legacy Agents & Groups.

Until it's set, those events are silently lost

An unset Default event environment refuses every event the machine raises, and the machine deletes the event file before the platform sees it, so nothing appears in the event log to tell you. Set it as you register each agent. See Events raised by a legacy agent.

Each event line also needs a credential the platform recognises

Every line a machine raises ends with a login ID and a token, and Continuum now verifies that pair — a line whose credential fails is rejected and never becomes an event. A token carried over from a legacy OpCon server is not one it recognises.

For each emitter, create a Continuous service account named for the login ID the file already uses, and put its secret where the old token was. The file format, the scripts and the login ID all stay as they are. Grant the account only the roles it needs — copying an administrator login is how a full-admin token ends up on every machine. See the credential pair.

Rotate credentials​

If the client secret is lost or you want to cycle it, regenerate the credentials on the relay instead of deleting and re-registering it. To regenerate the credentials, complete the following steps:

  1. Open the relay and choose Regenerate credentials.

  2. Confirm by typing the relay's name.

  3. Download the new credentials.json. As on the register dialog, the new client ID and secret are never displayed — the file is the only copy, and you cannot retrieve the secret later. If you lose it, regenerate again.

  4. Replace the file on the relay host and restart the service. Regenerating does not do this for you, so the relay keeps using its old credentials until you do:

    PlatformReplaceThen
    Linux/etc/opcon/credentials.jsonsudo systemctl restart opcon-relay
    WindowsC:\ProgramData\OpCon\Relay\credentials.jsonRestart-Service OpConRelay

The old credentials stop working immediately after rotation. A lost secret can't be used to connect once you've rotated.

Stopping a relay​

Stop the relay cleanly — sudo systemctl stop opcon-relay or Stop-Service OpConRelay — whenever you have the choice. A clean stop is reflected in OpCon in about a second, and it leaves the relay's legacy agents OFFLINE, which holds queued legacy-group jobs in WAIT_MACHINE until the relay comes back.

Expect notifications for the agents, not just the relay. A clean stop raises an Agent Offline event for each legacy agent it takes down, alongside the Relay Offline for the relay itself — so anyone subscribed to agent connectivity hears about a planned restart. That is the point: the relay's heartbeat raises an Agent Online for each of them on the way back up, and until recently there was no matching Offline, which made every planned restart look like a run of unexplained outages. If a maintenance window should be quiet, silence the triggers rather than skipping the clean stop.

If the relay disappears without warning instead — killed, power lost, network dropped — it takes about five minutes of missed check-ins to be noticed, and its legacy agents go UNKNOWN. Queued legacy-group jobs hold through that too, and resume when the relay reconnects. The five-minute window is deliberate: a shorter one would put every queued legacy job on that relay through a hold for a brief network blip.

Good to know

For planned maintenance, stopping the service cleanly gets you the honest status in about a second instead of five minutes. On earlier builds it was worth more than that — an abrupt loss used to fail the group's queued jobs rather than holding them — so if you have read that advice before, the reason for it has changed even though the advice hasn't.

Keep it secure​

  • Protect credentials.json with restrictive permissions (the installers do this for you, so keep them if you replace the file manually).
  • The relay needs no inbound internet ports. Port 8080 (/health) is only for local health checks.
  • Treat the client secret like a password: never share or commit it.
  • On Windows, leave the log folders to the installer. It restricts both to Administrators and SYSTEM (Users: read) and refuses a folder anyone else could plant files in, because the service and the retention task write and delete there as SYSTEM.

Log housekeeping on Windows​

You do not have to prune relay logs by hand. The installer registers a daily scheduled task, \OpCon\OpConRelay-LogRetention (03:00, SYSTEM), which rotates the relay's logs and deletes rotated ones older than -LogRetentionDays — 30 days unless you pass something else. The active relay-stdout.log and relay-stderr.log are never deleted, and the LSAM Connector keeps its own newest 10 daily files.

Two things to watch:

  • Re-pass -LogRetentionDays when you reinstall, like every other installer option, or it goes back to 30.
  • If rotated logs pile up anyway, look at the task's Last Run Result. A non-zero result means it refused to prune — usually because the log folder is a junction or is no longer owned by Administrators or SYSTEM.

Uninstalling removes the task and deletes only the relay's own log files; a folder holding anything else is left in place, and -KeepLogs keeps both folders as they are. See Logs, rotation and retention.

Keep the relay up to date​

A relay runs on your infrastructure and isn't upgraded for you, so it can fall behind the platform. Four things currently depend on it being current, and each looks like a product fault rather than a version gap:

  • Output files from UNIX and IBM i agents. An older relay asks for them the way only a Windows agent expects. On UNIX the agent answers with its own global log files, which are then stored as that job's output and reported as a success — so an Operator reads the wrong file believing it is the job's. On IBM i nothing comes back.
  • Advanced exit criteria. A Builder who sets Exit Criteria Result, a range condition, or more than five conditions on a legacy job will find the job's dispatch refused on an older relay. It fails loudly rather than guessing, but the job doesn't run.
  • IBM i job submission. An older relay sends a job name holding a character an IBM i job name can't contain, so the agent refuses the submission and the job ends immediately in Initialization error.
  • OpCon MFT, OpCon RPA and EASE agents. Each relay reports, on every check-in, whether it can serve each of these three REST-reached agent types — on separate flags, so a relay able to serve one is not thereby able to serve another. Registering an agent of a type the relay has not reported is refused in the dialog (Upgrade the relay to register MFT agents., This relay must be upgraded to run OpCon RPA agents. or This relay must be upgraded to run EASE agents.), an already-registered agent of that type behind a fallen-behind relay is never given work, and an RPA or EASE job placed on that relay's pool is refused rather than queued. This one at least says so plainly — see Relays and Serving EASE agents.

Nothing in the platform can tell an out-of-date relay from a job with no output, so when legacy behaviour goes wrong on only some platforms, check the relay build first. Download Relay on the Legacy Agents & Groups toolbar names the latest published version and serves it, so you can compare it against what you are running without touching your relay registrations.

Upgrade the relay with the platform release, not separately

A legacy job's output files are named by the relay when the job is dispatched, and the request that lists them is built by the platform when someone views them. Both sides apply the same naming rule, and that rule changed on both at once — so a mismatch in either direction stops new jobs' output from being found. There is no safe side to be on: plan the relay upgrade alongside the platform release rather than after it.

Two things to tell your Operators about jobs that ran before the upgrade:

  • Their output files keep their old names on the agent permanently. Output someone already viewed stays available; output nobody viewed comes back empty, and no upgrade order fixes that.
  • Refresh from agent on one of those jobs re-reads from the agent, so it replaces an old stored listing with an empty one. That's deliberate — a listing the platform can't vouch for is dropped rather than kept.

Running jobs is unaffected. This is only about retrieving their output.

Output listings are now checked against the job that asked for them

Files whose names don't belong to the requesting job are discarded. Before this, a request a UNIX agent didn't recognise came back with the agent's own global log and error files, which were stored and served as that job's output — so an Operator could read another job's output believing it was their own. Windows listings aren't filtered; they carry no job name to match on.

When something's wrong​

SymptomLikely causeFix
A UNIX or IBM i job's output files are empty or hold the agent's own logsThe relay predates per-platform output requestsUpgrade the relay, then have the Operator use Refresh from agent on the affected jobs.
A legacy job never starts, refused on its exit criteriaThe relay predates Exit Criteria Result, range conditions, or tables over five rowsUpgrade the relay, or have the Builder use up to five plain conditions with Exit Criteria Result Fail.
A UNIX or IBM i job that ran before a relay upgrade lists no output filesIts files were written under the old naming ruleExpected and not repairable — the names on the agent don't change. Output viewed before the upgrade is still stored. Re-run the job for output under the current rule.
An IBM i job fails at once with Initialization error, and the agent reports a submission failureThe relay predates the IBM i job-name fixUpgrade the relay. IBM i enablement is still in progress.
Startup error about credentials.json keysThe file was edited or is out of dateRe-download it from the register dialog and use it unchanged.
Opaque 403 / 404 on startupWrong AGENT_SERVICE_URL or missing path prefixUse the exact connection values shown in the register dialog.
Relay stays "unhealthy"It never finished starting (credentials or connectivity)Check the relay logs; verify the credentials and connection variables.
Legacy agents show Unknown (amber)The relay is stale/down, not the agentsCheck the relay's health and connectivity first.

Related topics