Edits history of script submission #24234 for ' Copy Image (arista_eos)'

  • python3
    One script reply has been approved by the moderators
    Ap­pro­ved
    # py312
    # requirements:
    # paramiko==5.1.0
    # pyeapi==1.0.4
    
    import base64
    import hashlib
    import json
    import logging
    import re
    import socket
    import ssl
    import time
    import urllib.error
    import urllib.request
    from typing import TypedDict
    from urllib.parse import urlsplit
    
    import paramiko
    import pyeapi
    
    
    class arista_eos(TypedDict):
        host: str
        username: str
        password: str
        port: int
        verify_tls: bool
        allow_http: bool
    
    
    class CopyFailed(Exception):
        pass
    
    
    def main(
        auth: arista_eos,
        image_url: str,
        host: str = "",
        sha512: str = "",
        vrf: str = "",
        dest_name: str = "",
    ):
        """
        Copy Image
        Copy a file from an HTTP(S) URL to the switch's flash and verify its sha512 (the sha512 input, else the <image_url>.sha512 file). Skips the copy when the file is already on flash with that digest; on a mismatch deletes it and raises. Returns { image, sha512, size, copied }. Raises CopyFailed, DeviceUnreachable or AuthFailure. Step 1 of an upgrade, before Set Boot Image.
        """
        auth = with_host(auth, host)
        try:
            url = checked_url(image_url)
            name = flash_name(dest_name or urlsplit(url).path.rsplit("/", 1)[-1])
            if vrf and not re.fullmatch(r"[\w.-]+", vrf):
                raise ValueError(f"vrf may only contain A-Z a-z 0-9 _ . -: got {vrf!r}")
            expected = digest(sha512) if sha512 else expected_digest(url)
            if not expected:
                raise CopyFailed("sha512 must be the 128-hex digest of the image" if sha512 else f"no sha512 hash in {url}.sha512")
            eos = node(auth)
    
            def copy():
                # The copy runs on the switch and can take minutes for a ~1 GB image.
                node(auth, 3600).run_commands([*([f"cli vrf {vrf}"] if vrf else []), f"copy {url} flash:{name}"])
    
            def verify():
                [v] = eos.run_commands([f"verify /sha512 flash:{name}"])
                return digest((v.get("messages") or [""])[0])
    
            copied = name not in flash_dir(auth)["entries"]
            if copied:
                copy()
            actual = verify()
            if actual != expected and not copied:
                # A partial copy left by a killed run, or another file of that name: replace it once.
                eos.run_commands([f"delete flash:{name}"])
                copy()
                copied = True
                actual = verify()
            if actual != expected:
                eos.run_commands([f"delete flash:{name}"])
                raise CopyFailed(f"sha512 mismatch for {name} (switch {actual or 'none'}, expected {expected}), deleted it")
            size = flash_dir(auth)["entries"][name]["size"]
        except (DeviceUnreachable, AuthFailure, CopyFailed):
            raise
        except Exception as e:
            raise CopyFailed(f"{auth['host']}: {e}")
        return {"image": f"flash:/{name}", "sha512": expected, "size": size, "copied": copied}
    
    
    # The URL goes into the switch's copy command, so it is an allowlist: http(s), a host, then only
    # A-Z a-z 0-9 . _ ~ : / % + - (no query, no user:password@, nothing the CLI reads as a separator).
    def checked_url(url):
        url = (url or "").strip()
        if "@" in url:
            raise ValueError("the image URL must not contain @ (no user:password@ in it)")
        if not re.match(r"https?://", url) or not urlsplit(url).hostname:
            raise ValueError(f"the image URL must be http:// or https:// with a host: got {url!r}")
        bad = sorted(set(re.sub(r"[A-Za-z0-9._~:/%+-]", "", url.split("://", 1)[1])))
        if bad:
            raise ValueError(f"the image URL may only contain A-Z a-z 0-9 . _ ~ : / % + -, not {' '.join(map(repr, bad))}: got {url!r}")
        return url
    
    
    # The digest is what the copy is trusted on, so this fetch checks the image server's certificate.
    def expected_digest(url):
        try:
            with urllib.request.urlopen(f"{url}.sha512", timeout=60) as r:
                return digest(r.read().decode(errors="replace"))
        except urllib.error.HTTPError as e:
            raise CopyFailed(f"cannot read {url}.sha512 ({e.code}): pass sha512")
        except OSError as e:
            raise CopyFailed(f"cannot read {url}.sha512 ({getattr(e, 'reason', e)}): pass sha512")
    
    
    # The 128-hex digest in a sha512sum line, a BSD "SHA512 (f) = <hash>" line or verify /sha512 output.
    def digest(text):
        m = re.search(r"\b[0-9a-fA-F]{128}\b", text or "")
        return m.group(0).lower() if m else ""
    
    
    # A file at the root of flash: "flash:/NAME", "flash:NAME" or "NAME", with only A-Z a-z 0-9 _ . + - in NAME (the name
    # goes into a CLI command). Returns NAME.
    def flash_name(path: str):
        name = re.sub(r"^flash:/?", "", (path or "").strip())
        if not re.fullmatch(r"[\w.+-]+", name) or name in (".", ".."):
            raise ValueError(f"expected a file at the root of flash (flash:/NAME, NAME of A-Z a-z 0-9 _ . + -): got {path!r}")
        return name
    
    
    def flash_dir(auth):
        [d] = node(auth).run_commands([{"cmd": "dir flash:/", "revision": 2}])
        return d["urls"]["flash:/"]
    
    
    # One resource can serve every switch that shares a login: the host input, when set, overrides the resource's host.
    def with_host(auth: arista_eos, host: str):
        host = (host or "").strip() or (auth.get("host") or "").strip()
        if not host:
            raise ValueError("host is required: set it on the resource or pass host")
        return {**auth, "host": host}
    
    
    # SSH transport (transport: ssh): the EOS CLI over an SSH shell, behind the part of pyeapi's Node the scripts use
    # (run_commands, connection.socket_error, connection.transport.connect), raising pyeapi's own CommandError and
    # ConnectionError, so the checks and the error mapping are the same for both transports. Show commands in json get
    # "| json", which prints the eAPI JSON; other commands give { messages: [output] } like eAPI, or {} when silent.
    # A line starting with "% " is an error, raised as eAPI's CommandError. The host key is checked when the resource
    # has ssh_host_key (SHA256:... as ssh-keygen -lf prints it).
    class Ssh:
        def __init__(self, auth: arista_eos, timeout: float):
            self.auth, self.timeout = auth, timeout
            self.connection = self.transport = self
            self.socket_error = self.sock = self.chan = None
    
        # The TCP connection only, like eAPI's transport.connect(): if it fails, nothing was sent.
        def connect(self):
            self.sock = socket.create_connection(ssh_addr(self.auth), self.timeout)
    
        def lost(self, e):
            self.socket_error = e
            return pyeapi.eapilib.ConnectionError("ssh", f"SSH connection failed ({e})")
    
        def open(self):
            auth = self.auth
            try:
                if not self.sock:
                    self.connect()
                t = paramiko.Transport(self.sock)
                t.start_client(timeout=self.timeout)
                key = t.get_remote_server_key()
            except (OSError, EOFError, paramiko.SSHException) as e:
                raise self.lost(e)
            fp = "SHA256:" + base64.b64encode(hashlib.sha256(key.asbytes()).digest()).decode().rstrip("=")
            if auth.get("ssh_host_key") and auth["ssh_host_key"].strip() != fp:
                t.close()
                raise RuntimeError(f"{auth['host']}: the SSH host key is {fp}, not the resource's ssh_host_key")
            try:
                try:
                    t.auth_password(auth["username"], auth["password"])
                except paramiko.BadAuthenticationType:
                    t.auth_interactive(
                        auth["username"], lambda _t, _i, prompts: [auth["password"]] * len(prompts)
                    )
            except paramiko.AuthenticationException as e:
                t.close()
                raise pyeapi.eapilib.ConnectionError("ssh", str(e))
            except (OSError, EOFError, paramiko.SSHException) as e:
                raise self.lost(e)
            try:
                self.chan = t.open_session()
                self.chan.get_pty(width=4000)
                self.chan.invoke_shell()
                self.prompt = None
                out = self.read()
                self.prompt = re.escape(re.split(r"[(>#]", out.splitlines()[-1].strip())[0])
                if out.rstrip().endswith(">"):
                    self.cli("enable")
                self.cli("terminal length 0")
                self.cli("terminal width 32767")
            except (OSError, EOFError, paramiko.SSHException) as e:
                raise self.lost(e)
    
        # Reads until the prompt. Questions eAPI never asks are answered as eAPI behaves: confirm, don't save.
        def read(self):
            buf, end = "", time.monotonic() + self.timeout
            prompt = (self.prompt or r"[\w.\-]+") + r"(\([^)\r\n]*\))?[>#] ?$"
            while True:
                self.chan.settimeout(max(end - time.monotonic(), 0.01))
                chunk = self.chan.recv(65536)
                if not chunk:
                    raise self.lost("connection closed")
                buf += chunk.decode(errors="replace")
                tail = buf[-300:]
                if re.search(r"(^|\n)" + prompt, tail):
                    return buf
                for question, answer in (
                    # enable asks for a password on switches that land the user unprivileged: the login password.
                    (r"(^|\n)Password:\s*$", self.auth["password"]),
                    (r"\[confirm\]\s*$", ""),
                    (r"Save\?.*\[yes/no[^\]]*\]:?\s*$", "no"),
                    (r"\[(y|yes)/(n|no)\][:?]?\s*$", "y"),
                ):
                    if re.search(question, tail, re.I):
                        self.chan.send(answer + "\r")
                        buf += "\n"
    
        # One command: its output without the echoed command and the prompt; progress lines keep their last state.
        def cli(self, cmd):
            try:
                self.chan.send(cmd + "\r")
                out = self.read()
            except (OSError, EOFError, paramiko.SSHException) as e:
                raise self.lost(e)
            self.mode = out.rstrip().splitlines()[-1]
            lines = [l.rstrip("\r").split("\r")[-1] for l in out.split("\n")]
            return "\n".join(lines[1:-1]).strip("\n")
    
        def run_commands(self, cmds, encoding="json", **_):
            try:
                if not self.chan:
                    self.open()
                if "(config" in self.mode:
                    self.cli("end")
                results = []
                for i, c in enumerate(cmds):
                    # eAPI's { cmd, revision } form is the CLI's "| json revision N".
                    cmd, rev = (c["cmd"], c.get("revision")) if isinstance(c, dict) else (c, None)
                    show = encoding == "json" and (rev or re.match(r"\s*sh(ow)?\s", cmd)) and not re.search(r"\|\s*json", cmd)
                    # pyeapi sends "<cmd> MULTILINE: <text>" (banners) as cmd + input; the CLI reads the text up to EOF.
                    head, multi, text = cmd.partition("MULTILINE:")
                    # The shell would run what follows a line break as another command; eAPI refuses it too.
                    if re.search(r"[\r\n]", head):
                        raise ValueError(f"a command may not contain a line break: {head!r}")
                    line = "\r".join([head.strip(), *text.strip().splitlines(), "EOF"]) if multi else cmd
                    out = self.cli(f"{cmd} | json{f' revision {rev}' if rev else ''}" if show else line)
                    errors = [l[2:] for l in out.splitlines() if l.startswith("% ")]
                    code, kind = 1002, "invalid command"
                    if show and not errors:
                        code, kind = 1000, "could not run command"
                        try:
                            result = json.loads(out)
                        except ValueError:
                            errors = [out[:200]]
                        else:
                            errors = result.get("errors") or []
                    if errors:
                        raise pyeapi.eapilib.CommandError(
                            code,
                            f"CLI command {i + 2} of {len(cmds) + 1} '{cmd}' failed: {kind}",
                            command_error="; ".join(errors),
                            commands=cmds,
                            output=results,
                        )
                    if encoding != "json":
                        result = {"output": out + "\n" if out else ""}
                    elif not show:
                        # The CLI prints eAPI's warnings as "! " notices.
                        notices = [l[2:].strip() for l in out.splitlines() if l.startswith("! ")]
                        out = "\n".join(l for l in out.splitlines() if not l.startswith("! ")).strip()
                        result = {"messages": [out]} if out and not multi else {}
                        if notices:
                            result["warnings"] = notices
                    results.append(result)
                return results
            except pyeapi.eapilib.ConnectionError:
                if self.chan:
                    self.chan.close()
                self.sock = self.chan = None
                raise
    
    
    # paramiko logs a traceback when a rebooting switch drops the session.
    logging.getLogger("paramiko").addHandler(logging.NullHandler())
    
    
    # host, or host:port ([v6]:port), else port, else 22.
    def ssh_addr(auth: arista_eos):
        h = auth["host"]
        if "://" in h:
            raise ValueError(f"with transport ssh, host is an address or a hostname (with :port), not a URL: {h}")
        url = urlsplit(f"ssh://{h}" if h.count(":") <= 1 or h.startswith("[") else f"ssh://[{h}]")
        return url.hostname, url.port or int(auth.get("port") or 22)
    
    
    # Every action raises DeviceUnreachable when the switch can't be reached and AuthFailure when it refuses the
    # credential, so a flow can retry on result.error.name. Command errors stay pyeapi's CommandError.
    def node(auth: arista_eos, timeout: float = 60):
        eos = open_node(auth, timeout)
        run = eos.run_commands
    
        def run_commands(*args, **kwargs):
            try:
                return run(*args, **kwargs)
            except pyeapi.eapilib.ConnectionError as e:
                raise connection_error(auth, eos, e)
    
        eos.run_commands = run_commands
        return eos
    
    
    # pyeapi 1.0.4 raises ConnectionError for a socket error (kept in socket_error), an answer that isn't JSON (eAPI
    # still starting, 5xx) and a 401, the only one with neither.
    def connection_error(auth, eos, e):
        # A certificate the resource does not trust is a setting to fix (verify_tls, ca_certificate), not worth a retry.
        if isinstance(eos.connection.socket_error, ssl.SSLCertVerificationError):
            return RuntimeError(f"{auth['host']}: {eos.connection.socket_error}")
        if eos.connection.socket_error is None and e.message != "unable to connect to eAPI":
            return AuthFailure(f"{auth['host']}: {'SSH' if auth.get('transport') == 'ssh' else 'eAPI'} refused the credential ({e.message})")
        return DeviceUnreachable(f"{auth['host']}: {e.message}")
    
    
    class DeviceUnreachable(Exception):
        pass
    
    
    class AuthFailure(Exception):
        pass
    
    
    # pyeapi logs a traceback for every socket error.
    logging.getLogger("pyeapi").addHandler(logging.NullHandler())
    
    
    # host is an address or a URL (https://10.0.0.11:8443); a bare IPv6 address is bracketed. Only https, or http when the
    # resource ticks allow_http (Basic auth then crosses the network in cleartext). pyeapi skips certificate checks unless it
    # is given a context, so one is always passed: verifying, or not when the resource unticks verify_tls (EOS ships a
    # self-signed cert).
    def open_node(auth: arista_eos, timeout: float = 60):
        if auth.get("transport") == "ssh":
            return Ssh(auth, timeout)
        host = auth["host"]
        if "://" not in host:
            host = f"https://[{host}]" if host.count(":") > 1 and "[" not in host else f"https://{host}"
        url = urlsplit(host)
        if not url.hostname or (url.scheme != "https" and not (url.scheme == "http" and auth.get("allow_http"))):
            raise ValueError(f"host must be an address or an https:// URL (http:// needs allow_http on the resource): {auth['host']}")
        # ca_certificate: the PEM of a private CA, trusted instead of the system's CAs.
        context = ssl.create_default_context(cadata=(auth.get("ca_certificate") or "").strip() or None)
        if auth.get("verify_tls") is False:
            context.check_hostname = False
            context.verify_mode = ssl.CERT_NONE
        return pyeapi.connect(
            transport=url.scheme,
            host=url.hostname,
            port=url.port or auth.get("port") or None,
            username=auth["username"],
            password=auth["password"],
            context=context,
            timeout=timeout,
            return_node=True,
        )
    

    Submitted by hugo989 1 day ago