Skip to content
Guides & References

Back up a device that builds its export first

An SIE recipe for devices that build a config export as a job: start it, wait until it is ready, then download it, with a bounded wait.

Script Integration EngineUpdated
On this page

Back up a device that builds its export first

Some systems can’t hand over their configuration straight away. You ask for an export, the system builds it in the background, and you come back for the file when it’s ready. Firewall managers, backup appliances and orchestration platforms often work like this. This recipe does all three steps (start the job, wait for it, download the result) inside one script run, with a limit on how long it will wait.


When to use it

  • The platform’s API or CLI returns a job ID or a “pending” status instead of the configuration.
  • A single request can’t get the configuration, so API Collections can’t either.

How it fits the time limits

The export can take minutes. Two template settings matter:

  • timeout must cover the whole run: starting the job, the longest wait you will accept, and the download.
  • idletimeout stops a script that goes quiet. The script prints a progress line to stderr on every check, so a long wait doesn’t look like a hung script.

The script’s own wait limit (MAX_WAIT below) should be shorter than timeout, so the script fails with a clear message before rConfig stops it.


The template

sie-export-job-template.yml
main:
name: "SIE - Export job backup"
desc: "Starts an export job, waits for it and stores the result"
connect:
timeout: 660 # MAX_WAIT (600) plus time to start and download
idletimeout: 60 # the script reports progress every POLL_EVERY seconds
idleTimeout: 60
protocol: script
# exit_codes is deliberately left out: any non-zero exit fails the run.
failure_criteria:
error_patterns:
- "ERROR:"
success_patterns:
- "SIE-OK: export"

The command

/usr/bin/python3 {script_path}export-job-backup.py {device_ip} {device_username} {device_password}

The script

Save it as export-job-backup.py in the scripts folder. The settings at the top describe your platform’s API.

export-job-backup.py
#!/usr/bin/env python3
"""Start a config export job, wait for it and download the result, for the
rConfig Script Integration Engine.
Usage:
export-job-backup.py <host> <username> <password>
The exported config goes to stdout. Progress, errors and the success marker go
to stderr. Exit code 0 on success, 1 on any failure. Standard library only.
"""
import base64
import json
import sys
import time
import urllib.error
import urllib.request
# ---- Settings to adapt for your platform -------------------------------------
START_URL = "https://{host}/api/v1/config/export" # POST: starts the job
STATUS_URL = "https://{host}/api/v1/jobs/{job}" # GET: job status
RESULT_URL = "https://{host}/api/v1/jobs/{job}/download" # GET: the export
JOB_ID_FIELD = "id" # field in the START response holding the job ID
STATUS_FIELD = "status" # field in the STATUS response
DONE = {"completed", "finished", "success"}
FAILED = {"failed", "error", "cancelled"}
POLL_EVERY = 10 # seconds between status checks
MAX_WAIT = 600 # give up after this many seconds
# ----------------------------------------------------------------------------
def note(message):
print(message, file=sys.stderr)
def fail(message):
print(f"ERROR: {message}", file=sys.stderr)
sys.exit(1)
def call(url, auth, method="GET", raw=False):
request = urllib.request.Request(url, method=method, headers={
"Authorization": f"Basic {auth}",
"Accept": "*/*" if raw else "application/json",
"User-Agent": "rconfig-sie-recipe/1.0",
})
if method == "POST":
request.data = b"{}"
request.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(request, timeout=60) as response:
body = response.read()
except urllib.error.HTTPError as e:
fail(f"HTTP {e.code} for {method} {url}")
except urllib.error.URLError as e:
fail(f"cannot reach {url}: {e.reason}")
if raw:
return body
try:
return json.loads(body.decode("utf-8"))
except json.JSONDecodeError:
fail(f"the response for {method} {url} was not valid JSON")
def main():
if len(sys.argv) < 4:
fail("usage: export-job-backup.py <host> <username> <password>")
host, user, password = sys.argv[1:4]
auth = base64.b64encode(f"{user}:{password}".encode()).decode()
# 1. Start the export.
started = call(START_URL.format(host=host), auth, method="POST")
job = started.get(JOB_ID_FIELD)
if not job:
fail(f"the export request returned no '{JOB_ID_FIELD}'")
note(f"export job {job} started on {host}")
# 2. Wait for it, a bounded number of times.
waited = 0
while True:
status = str(call(STATUS_URL.format(host=host, job=job), auth).get(STATUS_FIELD, "")).lower()
if status in DONE:
break
if status in FAILED:
fail(f"export job {job} ended with status '{status}'")
if waited >= MAX_WAIT:
fail(f"export job {job} not ready after {MAX_WAIT}s (last status '{status}')")
note(f"job {job} is '{status}', waited {waited}s")
time.sleep(POLL_EVERY)
waited += POLL_EVERY
# 3. Download the result.
export = call(RESULT_URL.format(host=host, job=job), auth, raw=True)
try:
text = export.decode("utf-8")
except UnicodeDecodeError:
fail("the export is not text; see the config file recipe for archives and binary files")
if not text.strip():
fail("the export is empty, refusing to store it")
sys.stdout.write(text if text.endswith("\n") else text + "\n")
note(f"SIE-OK: export job {job}, {len(text.splitlines())} lines from {host}")
return 0
if __name__ == "__main__":
sys.exit(main())

What gets stored

Exactly what the export contains. For a text export, that’s the configuration as the platform writes it:

config system global
set hostname "fw-mgr-01"
set timezone "Europe/Dublin"
end
config system interface
edit "mgmt"
set ip 192.0.2.50 255.255.255.0

Adapting it

  • A CLI instead of an API. The same three steps work in Expect: send the export command, loop on a status command with a bounded count, then show the file. Keep the progress lines on stderr.
  • Token login. If the platform wants you to log in for a session token first, add that call before step 1 and send the token instead of Basic authentication.
  • Exports with a timestamp in them. Remove the line with drop_lines from the cleaning output recipe, or every run shows a change.
  • Archives or binary exports. See the config file download recipe.

Type to search.