Script Integration Engine guides

The Script Integration Engine (SIE) lets rConfig collect a configuration by running a script on the rConfig server instead of opening an SSH or Telnet session itself. These guides explain when that trade is worth making, how the engine hands device data to a script and takes the result back, and what to design for. The step-by-step setup stays in the SIE documentation; these pages explain the design behind it.

When a script beats a connection template

Most devices never need SIE. A connection template drives SSH or Telnet, and rConfig handles the session, prompts and paging. SIE is for the devices where that model breaks down.

The device or source	Best fit	Why
Standard CLI over SSH or Telnet	Connection template	No code to maintain. rConfig owns the session.
A REST endpoint that returns the config in one request	API Collections	Built-in authentication types, retries and scheduling, with no script.
Interactive menus, restricted CLIs, or prompts a template can’t drive	SIE (usually Expect)	The script scripts the conversation.
An API that needs several calls, such as trigger an export, poll, then fetch	SIE (usually Python)	API Collections requests each endpoint on its own; a script can chain the steps.
Jump hosts, extra authentication steps or vendor export tools	SIE	The script orchestrates the whole sequence.
Something that isn’t a network device, such as a database schema	SIE	Anything a script can print can be versioned.

The SIE docs name proprietary appliances, legacy systems, IoT devices and SCADA or OT equipment as typical candidates. The worked examples cover a Radware Alteon load balancer, a Zyxel GS1900 switch whose restricted CLI a connection template can’t drive, a Meraki API backup and a database schema dump.

The cost is ownership. A connection template is configuration; a script is code that your team writes, tests, secures and keeps working across device firmware and rConfig upgrades. The SIE Developer Notice places that responsibility with you.

How the engine runs a script

SIE reuses the normal rConfig model: devices, connection templates, command groups and commands. The script slots in where a CLI command would normally go.

Part	Role in SIE
Connection template	Sets `protocol: script`, the timeouts, and the failure criteria used to judge the run.
Command	The full command line: interpreter path, script name and the device variables. It sits in a command group like any other command.
Device	Uses the script template and the command group, and holds the IP address and credentials the script receives.
Script directory	Scripts live in one folder under the rConfig storage path. Scripts elsewhere are not found.
Feature flag	SIE is off by default and is enabled per server.

When a scheduled backup or a manual debug run reaches an SIE device, rConfig builds the command line, substitutes the variables, runs the script and captures what comes back.

Data in: variables on the command line

rConfig replaces placeholders in the command with values from the device record: {script_path}, {device_ip}, {device_name}, {device_username}, {device_password} and {device_enable_password}. Use only the ones the script needs, in whatever order the script reads its arguments. The parameter reference lists what each one holds.

One consequence to design for: credentials arrive as plain text arguments. Scripts must not echo or log them.

Data out: stdout is the config

Stream	What rConfig does with it
stdout	Stored as the configuration, then versioned, diffed, searched, checked for compliance and reported on like any SSH backup.
stderr	Kept for error logging and troubleshooting.
Exit code	Checked against the failure criteria.

Because stdout becomes the stored config, two habits matter. Keep diagnostics on stderr, or they are stored as part of the config. And make the output repeatable: if the output varies between runs against an unchanged device, every run shows up as a change.

How a run passes or fails

A script that exits cleanly can still have failed, for example by printing a login error. SIE judges each run against the template’s failure criteria rather than the exit code alone.

Check	Default and behaviour
`exit_codes`	Omit it and any non-zero exit fails the run. List codes to fail only on those, or use an empty list to ignore exit status.
`error_patterns`	Any match fails the run. Case-insensitive substring match across stdout and stderr.
`success_patterns`	Optional. When set, at least one must appear.

Success patterns use OR logic because one template often serves several commands with different output. List an indicator for each script, plus a common fallback such as the device prompt. Keep error patterns specific: a bare error can match legitimate config text.

The criteria also cover cases that would otherwise slip through. A script that exits 0 with no output stores an empty configuration unless the criteria catch it, and a script killed by the template timeout leaves no version at all. The failure criteria reference has the full set of examples.

Which user runs your scripts

Scripts run as whichever user runs the download. Scheduled tasks and downloads started from the UI run inside Horizon, which from V8.4.1 runs as the web server user (apache on RHEL family systems, www-data on Ubuntu). Older deployments may have run Horizon as root, so scripts that quietly depended on root can stop working after the upgrade.

rConfig doesn’t offer a way to run scripts as root. The design is least privilege: give the web user access to exactly what a script needs, and test as that user, because a run started by hand as root can pass while the scheduled run fails. The main docs list what typically breaks and the supported fixes.

Choosing a language

SIE runs any interpreter installed on the server. The docs describe where each common choice fits.

Language	Fits best when
Expect	The device needs an interactive login and command and response sequence. The Alteon walkthrough uses it.
Python	You call REST APIs, process JSON or XML, or need more logic than a shell script holds.
Bash	Simple command chaining and text handling.
Perl	Heavy regex work, or existing Perl scripts you want to keep.

The rConfig templates repository holds runnable script and template pairs, including a starter template to copy.