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:
timeoutmust cover the whole run: starting the job, the longest wait you will accept, and the download.idletimeoutstops 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
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.
#!/usr/bin/env python3"""Start a config export job, wait for it and download the result, for therConfig Script Integration Engine.
Usage: export-job-backup.py <host> <username> <password>
The exported config goes to stdout. Progress, errors and the success marker goto stderr. Exit code 0 on success, 1 on any failure. Standard library only."""
import base64import jsonimport sysimport timeimport urllib.errorimport urllib.request
# ---- Settings to adapt for your platform -------------------------------------START_URL = "https://{host}/api/v1/config/export" # POST: starts the jobSTATUS_URL = "https://{host}/api/v1/jobs/{job}" # GET: job statusRESULT_URL = "https://{host}/api/v1/jobs/{job}/download" # GET: the exportJOB_ID_FIELD = "id" # field in the START response holding the job IDSTATUS_FIELD = "status" # field in the STATUS responseDONE = {"completed", "finished", "success"}FAILED = {"failed", "error", "cancelled"}POLL_EVERY = 10 # seconds between status checksMAX_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 globalset hostname "fw-mgr-01"set timezone "Europe/Dublin"endconfig system interfaceedit "mgmt"set ip 192.0.2.50 255.255.255.0Adapting 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
Basicauthentication. - Exports with a timestamp in them. Remove the line with
drop_linesfrom the cleaning output recipe, or every run shows a change. - Archives or binary exports. See the config file download recipe.