Skip to content
Guides & References

Back up a device that saves its config as a file

An SIE recipe for IoT and OT gateways and appliances that export a config file: text is stored as is, archives are unpacked and binary files get a fingerprint.

Script Integration EngineUpdated
On this page

Back up a device that saves its config as a file

Cellular routers, industrial gateways, PLC communication modules, UPS cards and many other appliances have no CLI worth the name. What they do have is a “download backup” button in their web interface, which hands you a file. That file might be plain text, an archive of several files, or something binary. This recipe downloads it and stores the most useful form rConfig can keep: the text itself, every text file from an archive, or a fingerprint when the file can’t be read.


When to use it

  • The device’s web interface or API offers its configuration as a downloadable file.
  • The device is in an OT or IoT network where you want changes noticed, even if the file can’t be read line by line.

Three kinds of file, three ways to store them

The file is What the script stores What a change looks like in rConfig
Plain text The text The changed lines
An archive (.tar.gz, .tgz, .zip) Every text file inside, in name order, each under a ===== name ===== line The changed lines, under the name of the file they’re in
Binary or encrypted A short summary: size and SHA-256 fingerprint A different fingerprint

A fingerprint can’t tell you what changed, only that something did. That is still worth having: a gateway whose config changed outside a change window is a question someone should answer.


The template

sie-config-file-template.yml
main:
name: "SIE - Config file download"
desc: "Downloads a device's config file and stores its text, its unpacked archive or its fingerprint"
connect:
timeout: 120
idletimeout: 60
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: file"

The command

/usr/bin/python3 {script_path}config-file-download.py {device_ip} {device_username} {device_password}

The script

Save it as config-file-download.py in the scripts folder.

config-file-download.py
#!/usr/bin/env python3
"""Download a device's config file and store its text, its unpacked archive or
its fingerprint, for the rConfig Script Integration Engine.
Usage:
config-file-download.py <host> <username> <password>
What is stored 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 hashlib
import io
import os
import ssl
import sys
import tarfile
import urllib.error
import urllib.request
import zipfile
# ---- Settings to adapt for your device ---------------------------------------
DOWNLOAD_URL = "https://{host}/cgi-bin/backup/config" # what the backup button fetches
CA_FILE = "/var/www/html/rconfig8/current/storage/app/rconfig/scripts/keys/device-ca.pem"
MAX_BYTES = 50 * 1024 * 1024 # refuse anything larger
# ----------------------------------------------------------------------------
def note(message):
print(message, file=sys.stderr)
def fail(message):
print(f"ERROR: {message}", file=sys.stderr)
sys.exit(1)
def download(url, user, password):
auth = base64.b64encode(f"{user}:{password}".encode()).decode()
request = urllib.request.Request(url, headers={
"Authorization": f"Basic {auth}",
"User-Agent": "rconfig-sie-recipe/1.0",
})
context = (ssl.create_default_context(cafile=CA_FILE)
if os.path.exists(CA_FILE) else ssl.create_default_context())
try:
with urllib.request.urlopen(request, timeout=60, context=context) as response:
data = response.read(MAX_BYTES + 1)
except urllib.error.HTTPError as e:
fail(f"HTTP {e.code} downloading {url}")
except urllib.error.URLError as e:
fail(f"cannot reach {url}: {e.reason}")
if len(data) > MAX_BYTES:
fail(f"the file is larger than {MAX_BYTES} bytes")
if not data:
fail("the device returned an empty file")
return data
def as_text(data):
"""Return the data as text, or None if it is not text."""
if b"\x00" in data[:8192]:
return None
try:
return data.decode("utf-8")
except UnicodeDecodeError:
return None
def archive_members(data):
"""Return [(name, bytes)] for an archive, or None if it is not one."""
buffer = io.BytesIO(data)
if zipfile.is_zipfile(buffer):
with zipfile.ZipFile(buffer) as archive:
return [(i.filename, archive.read(i)) for i in archive.infolist() if not i.is_dir()]
buffer.seek(0)
try:
with tarfile.open(fileobj=buffer, mode="r:*") as archive:
return [(m.name, archive.extractfile(m).read()) for m in archive.getmembers() if m.isfile()]
except tarfile.TarError:
return None
def fingerprint(name, data):
return f"{name}: binary, {len(data)} bytes, sha256 {hashlib.sha256(data).hexdigest()}"
def main():
if len(sys.argv) < 4:
fail("usage: config-file-download.py <host> <username> <password>")
host, user, password = sys.argv[1:4]
url = DOWNLOAD_URL.format(host=host)
note(f"downloading {url}")
data = download(url, user, password)
text = as_text(data)
members = None if text is not None else archive_members(data)
if text is not None:
kind = "text"
out = text if text.endswith("\n") else text + "\n"
elif members is not None:
kind = f"archive of {len(members)} files"
parts = []
for name, content in sorted(members):
member_text = as_text(content)
parts.append(f"===== {name} =====")
parts.append(member_text.rstrip("\n") if member_text is not None
else fingerprint(name, content))
out = "\n".join(parts) + "\n"
else:
kind = "binary"
out = fingerprint("config file", data) + "\n"
sys.stdout.write(out)
note(f"SIE-OK: file {kind}, {len(data)} bytes from {host}")
return 0
if __name__ == "__main__":
sys.exit(main())

The script never writes the archive to disk: it reads it in memory and prints what it finds, so there are no files to clean up and nothing in an archive can land on the rConfig server.


What gets stored

For an archive holding two text files and one binary file:

===== etc/config/firewall =====
config defaults
option input 'REJECT'
option forward 'REJECT'
===== etc/config/network =====
config interface 'lan'
option ipaddr '192.0.2.1'
option netmask '255.255.255.0'
===== etc/certs/device.p12 =====
etc/certs/device.p12: binary, 2741 bytes, sha256 4f2a0c6e9b1d...

Adapting it

  • A login page instead of Basic authentication. Many web interfaces want a form login and a session cookie first. Use http.cookiejar with urllib.request.build_opener, post the login form, then download with the same opener.
  • Files with a timestamp or serial counter in them. Strip those lines with the cleaning output recipe helpers, or every run shows a change.
  • Encrypted backups. If the device encrypts its backup with a password you set, the fingerprint changes on every download even with no config change, because encryption usually adds random data. Check two downloads of an unchanged device before relying on it.
  • Reading files over SSH instead. Linux-based gateways often allow ssh user@device cat /etc/config/network. The jump host recipe script shows the SSH side.

Type to search.