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
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.
#!/usr/bin/env python3"""Download a device's config file and store its text, its unpacked archive orits 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 tostderr. Exit code 0 on success, 1 on any failure. Standard library only."""
import base64import hashlibimport ioimport osimport sslimport sysimport tarfileimport urllib.errorimport urllib.requestimport zipfile
# ---- Settings to adapt for your device ---------------------------------------DOWNLOAD_URL = "https://{host}/cgi-bin/backup/config" # what the backup button fetchesCA_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 defaultsoption 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.cookiejarwithurllib.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.