Prepare agents for connectors
Most connectors run on an agent, and some need software or permissions in place on that agent first. This guide covers what to set up so connectors run reliably. A job is only dispatched to an agent that matches the job's operating system and agent type. If nothing matches, the job can't be assigned.
A connector fails at run time because the agent is missing a driver, an interpreter, or access to a path. The failure looks like a job problem when it's really a setup gap on the machine.
File access
The Wait for File job can only watch files in directories the agent is allowed to use. By default the allowed directories are:
/tmp/var/tmp- the operating system temp directory
- the agent's working directory
To allow other locations, set the OPCON_ALLOWED_FILE_PATHS environment variable on the agent
to a comma-separated list of paths, then restart the agent. Setting this variable replaces
the default list rather than adding to it, so include any default directories you still need. A
path outside the allowed list fails immediately with an "outside allowed directories" error.
Script interpreters
The Run Script job uses the interpreter installed on the agent. OpCon Continuum does not provide it. Make sure the interpreter for the script types your Builders use is present:
| Script type | Requirement on the agent |
|---|---|
| Shell | Always available (cmd.exe on Windows, /bin/sh on Linux/macOS) |
| PowerShell | powershell.exe on Windows; PowerShell 7+ (pwsh) must be installed on Linux/macOS |
| Bash | /bin/bash present |
| Python | python (Windows) / python3 (Linux/macOS) installed and on PATH |
Database drivers and tooling
There is nothing to prepare on a Universal Agent for the SQL Database Executor job types: they do not run in this build. Every such job fails before it reaches the database, with External plugin sql-executor requires pluginDownloadUrl and pluginChecksum.
Legacy LSAM agents
The UNIX/Linux LSAM and Windows LSAM connectors don't use the Universal Agent. They run through the relay, which forwards jobs to your existing LSAM machines. For these to work:
- The relay must be running and the target LSAM machines reachable. A "no agent available" error for an LSAM command points here, not at the Universal Agent.
- A job's machine name must match the LSAM agent name registered with the relay.
- A legacy job runs as the batch user attached to it — a connection you define once; see Manage connections. On Windows, IBM i and SQL, a job with no batch user falls back to the machine's own default; on UNIX a batch user is required.
- Windows LSAM does not support embedded scripts on the command job. Per-job environment variables are supported.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| File job fails with "outside allowed directories" | The path isn't in the agent's allowed list | Add the location to OPCON_ALLOWED_FILE_PATHS (keep the defaults you need) and restart the agent. |
| Run Script job can't start the interpreter | Interpreter not installed on the agent (often pwsh or python3) | Install the interpreter on the agent and confirm it's on PATH. |
| LSAM command reports "no agent available" | Relay down or LSAM machine unreachable | Check the relay and LSAM connectivity. |
Related topics