Skip to content
Guides & References

How your script talks to rConfig

What rConfig passes to an SIE script, what it keeps from stdout, stderr and the exit code, and the rules every script should follow.

Script Integration EngineUpdated
On this page

How your script talks to rConfig

An SIE script has one job: print a configuration to stdout and exit with a status that tells the truth. This page sets out exactly what rConfig hands a script, what it does with what comes back, and the conventions every recipe in this library follows. Get these right once and every script you write behaves the same way in rConfig.


How rConfig calls your script

The command in the command group is a full command line. rConfig replaces the placeholders, splits the result on whitespace and runs it directly. The first word is the interpreter and the second is the script:

/usr/bin/python3 {script_path}my-backup.py {device_ip} {device_username} {device_password}
Placeholder Replaced with
{script_path} The scripts folder, with a trailing slash: /var/www/html/rconfig8/current/storage/app/rconfig/scripts/
{device_ip} The device’s IP address
{device_name} The device’s name
{device_username} The device’s username
{device_password} The device’s password
{device_enable_password} The enable password, or nothing if none is set
{deviceid} The device’s numeric ID in rConfig

{deviceid} is written without an underscore, unlike the others.

Where the credentials come from

The username and passwords come from the device’s credential set, applied before the placeholders are filled. That includes vault credential sets (HashiCorp Vault, Idira (CyberArk) and Delinea Secret Server): rConfig fetches the secret from the vault, and the script receives it through {device_password} like any other. A script never needs its own vault code to use vaulted device credentials.

Four rules that follow from how the command is run

There is no shell. rConfig runs the interpreter with an argument list, not through bash -c. Pipes, redirects, &&, $VARIABLES, ~ and wildcards are passed to your script as literal text, and quotes are not removed. Anything that needs a shell belongs inside the script.

Every value is split on whitespace. A password with a space in it arrives as two arguments. An empty value in the middle of the line disappears completely and every argument after it moves up one place. At the end of the line it arrives as a single empty argument. Put optional values, such as {device_enable_password}, last, and have the script cope with that argument being empty or missing.

Leftover braces fail the run. After substitution, any text still in {braces} stops the run with Unresolved placeholders found. That catches a mistyped placeholder, and also a password that happens to contain braces.

Arguments are visible on the server. While a script runs, its arguments, credentials included, show in the process list to anyone logged in to the rConfig server. Keep shell access to the server restricted, and see get your server ready for scripts for keeping other secrets in files instead.


What rConfig does with what comes back

Stream What happens to it
stdout Stored as the configuration for that command, then versioned, diffed, searched and checked like any other backup.
stderr Not stored as config. Checked against the failure criteria and shown when a run fails.
Exit code Checked against the failure criteria.

Every line of stdout is trimmed

rConfig removes the spaces and tabs at the start and end of every line before it saves the output. Indentation does not survive. JSON stays valid, because JSON ignores that whitespace, but anything that relies on indentation for meaning (YAML, Python-style nesting, an indented tree from a vendor tool) arrives flattened. If the structure matters, print it in a form that does not depend on indentation. The cleaning output recipe shows how to flatten JSON into one path = value line per setting, which diffs and searches well.

Make the output repeatable

rConfig compares each run with the last one. If two runs against an unchanged device print different text, every run is a change. Common causes: timestamps, uptime, session IDs, API response metadata, and lists or object keys that come back in a different order each time. Remove them in the script or exclude them with diff exclusions. The cleaning output recipe covers both.


The conventions every recipe follows

The recipes in this library all use the same small set of habits. They make a failed run look failed, every time.

  1. Config on stdout, everything else on stderr. Progress messages, warnings and debugging go to stderr, so they never end up in the stored config.
  2. A success marker on stderr. The last thing the script does is print a line starting SIE-OK: to stderr. The template’s success_patterns lists that exact text. A run that dies half way, or prints nothing, never gets that far.
  3. ERROR: and a non-zero exit on failure. Any failure prints a line starting ERROR: to stderr and exits with 1. The template lists ERROR: in error_patterns, so the run fails by pattern as well as by exit code.
  4. exit_codes left out of the template. With no exit_codes key, any non-zero exit fails the run. A list such as [1, 2, 255] turns that around: only those codes fail, so a crash that exits with 127 or 139 is recorded as a success.

The template that goes with those conventions:

sie-script-template.yml
main:
name: "SIE - My backup script"
desc: "Runs my-backup.py and stores its stdout as the configuration"
connect:
timeout: 60 # Seconds each script may run in total
idletimeout: 60 # Seconds each script may go without printing anything
idleTimeout: 60 # Same setting, camelCase spelling, as the repository templates set both
protocol: script
# exit_codes is deliberately left out: any non-zero exit fails the run.
failure_criteria:
error_patterns:
- "ERROR:"
success_patterns:
- "SIE-OK:"

And a minimal Python script that follows these rules. Every recipe is a fuller version of this shape:

sie-skeleton.py
#!/usr/bin/env python3
"""Skeleton SIE script: config to stdout, everything else to stderr."""
import sys
def note(message):
print(message, file=sys.stderr)
def fail(message):
print(f"ERROR: {message}", file=sys.stderr)
sys.exit(1)
def main():
if len(sys.argv) < 4:
fail("usage: sie-skeleton.py <ip> <username> <password>")
ip, username, password = sys.argv[1:4]
note(f"collecting from {ip}")
config = "hostname example-device\n" # replace with the real collection
if not config.strip():
fail("collection returned nothing, refusing to store an empty config")
sys.stdout.write(config)
note("SIE-OK: collection complete")
return 0
if __name__ == "__main__":
sys.exit(main())

How failure criteria are judged

rConfig checks each script’s run in this order and stops at the first failure:

Check Rule
Exit code No exit_codes key: any non-zero exit fails. A list: only the listed codes fail. An empty list, []: the exit code is ignored.
error_patterns Any pattern found fails the run.
success_patterns When the list is set and not empty, at least one pattern must be found.

Patterns are plain text, not regular expressions. Matching is case-insensitive and covers stdout and stderr together, which is why a marker printed to stderr still counts. Keep error patterns specific: ERROR: is safe, a bare error can match a line of real config.


Several scripts on one device

A device using a script template runs every command in its command group as a script, one after the other. A script template can’t be mixed with ordinary SSH commands on the same device.

  • One template, every script. The same timeouts and failure criteria apply to each script on the device. Success patterns work as OR, so list one marker per script, or have every script print the same SIE-OK: prefix.
  • Each script is checked on its own output. One script’s success marker doesn’t rescue another script that printed nothing.
  • One failure fails the device. If any script fails, the whole download for that device fails: nothing from that run is stored, the device shows as config failed, and the failure notification is sent. Keep scripts that can fail independently on separate devices if you would rather keep the partial result.

Timeouts

Setting Meaning Default
timeout Total seconds one script may run. 30
idletimeout Seconds one script may go without printing anything, on either stream. 30

Both apply to each script separately. A slow job, such as an export that a device takes two minutes to build, needs a longer timeout, and it should print a progress line to stderr while it waits so the idle timeout doesn’t stop it. A run that times out stores nothing and fails like any other.

Earlier rConfig releases read only the lowercase idletimeout and ignored idleTimeout, so the repository templates set both. Do the same.


Type to search.