0

Copy Image

Published today

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.

Script arista_eos Verified

The script

Submitted by hugo989 Python3
Verified 1 day ago
1
# py312
2
# requirements:
3
# paramiko==5.1.0
4
# pyeapi==1.0.4
5

6
import base64
7
import hashlib
8
import json
9
import logging
10
import re
11
import socket
12
import ssl
13
import time
14
import urllib.error
15
import urllib.request
16
from typing import TypedDict
17
from urllib.parse import urlsplit
18

19
import paramiko
20
import pyeapi
21

22

23
class arista_eos(TypedDict):
24
    host: str
25
    username: str
26
    password: str
27
    port: int
28
    verify_tls: bool
29
    allow_http: bool
30

31

32
class CopyFailed(Exception):
33
    pass
34

35

36
def main(
37
    auth: arista_eos,
38
    image_url: str,
39
    host: str = "",
40
    sha512: str = "",
41
    vrf: str = "",
42
    dest_name: str = "",
43
):
44
    """
45
    Copy Image
46
    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.
47
    """
48
    auth = with_host(auth, host)
49
    try:
50
        url = checked_url(image_url)
51
        name = flash_name(dest_name or urlsplit(url).path.rsplit("/", 1)[-1])
52
        if vrf and not re.fullmatch(r"[\w.-]+", vrf):
53
            raise ValueError(f"vrf may only contain A-Z a-z 0-9 _ . -: got {vrf!r}")
54
        expected = digest(sha512) if sha512 else expected_digest(url)
55
        if not expected:
56
            raise CopyFailed("sha512 must be the 128-hex digest of the image" if sha512 else f"no sha512 hash in {url}.sha512")
57
        eos = node(auth)
58

59
        def copy():
60
            # The copy runs on the switch and can take minutes for a ~1 GB image.
61
            node(auth, 3600).run_commands([*([f"cli vrf {vrf}"] if vrf else []), f"copy {url} flash:{name}"])
62

63
        def verify():
64
            [v] = eos.run_commands([f"verify /sha512 flash:{name}"])
65
            return digest((v.get("messages") or [""])[0])
66

67
        copied = name not in flash_dir(auth)["entries"]
68
        if copied:
69
            copy()
70
        actual = verify()
71
        if actual != expected and not copied:
72
            # A partial copy left by a killed run, or another file of that name: replace it once.
73
            eos.run_commands([f"delete flash:{name}"])
74
            copy()
75
            copied = True
76
            actual = verify()
77
        if actual != expected:
78
            eos.run_commands([f"delete flash:{name}"])
79
            raise CopyFailed(f"sha512 mismatch for {name} (switch {actual or 'none'}, expected {expected}), deleted it")
80
        size = flash_dir(auth)["entries"][name]["size"]
81
    except (DeviceUnreachable, AuthFailure, CopyFailed):
82
        raise
83
    except Exception as e:
84
        raise CopyFailed(f"{auth['host']}: {e}")
85
    return {"image": f"flash:/{name}", "sha512": expected, "size": size, "copied": copied}
86

87

88
# The URL goes into the switch's copy command, so it is an allowlist: http(s), a host, then only
89
# A-Z a-z 0-9 . _ ~ : / % + - (no query, no user:password@, nothing the CLI reads as a separator).
90
def checked_url(url):
91
    url = (url or "").strip()
92
    if "@" in url:
93
        raise ValueError("the image URL must not contain @ (no user:password@ in it)")
94
    if not re.match(r"https?://", url) or not urlsplit(url).hostname:
95
        raise ValueError(f"the image URL must be http:// or https:// with a host: got {url!r}")
96
    bad = sorted(set(re.sub(r"[A-Za-z0-9._~:/%+-]", "", url.split("://", 1)[1])))
97
    if bad:
98
        raise ValueError(f"the image URL may only contain A-Z a-z 0-9 . _ ~ : / % + -, not {' '.join(map(repr, bad))}: got {url!r}")
99
    return url
100

101

102
# The digest is what the copy is trusted on, so this fetch checks the image server's certificate.
103
def expected_digest(url):
104
    try:
105
        with urllib.request.urlopen(f"{url}.sha512", timeout=60) as r:
106
            return digest(r.read().decode(errors="replace"))
107
    except urllib.error.HTTPError as e:
108
        raise CopyFailed(f"cannot read {url}.sha512 ({e.code}): pass sha512")
109
    except OSError as e:
110
        raise CopyFailed(f"cannot read {url}.sha512 ({getattr(e, 'reason', e)}): pass sha512")
111

112

113
# The 128-hex digest in a sha512sum line, a BSD "SHA512 (f) = <hash>" line or verify /sha512 output.
114
def digest(text):
115
    m = re.search(r"\b[0-9a-fA-F]{128}\b", text or "")
116
    return m.group(0).lower() if m else ""
117

118

119
# 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
120
# goes into a CLI command). Returns NAME.
121
def flash_name(path: str):
122
    name = re.sub(r"^flash:/?", "", (path or "").strip())
123
    if not re.fullmatch(r"[\w.+-]+", name) or name in (".", ".."):
124
        raise ValueError(f"expected a file at the root of flash (flash:/NAME, NAME of A-Z a-z 0-9 _ . + -): got {path!r}")
125
    return name
126

127

128
def flash_dir(auth):
129
    [d] = node(auth).run_commands([{"cmd": "dir flash:/", "revision": 2}])
130
    return d["urls"]["flash:/"]
131

132

133
# One resource can serve every switch that shares a login: the host input, when set, overrides the resource's host.
134
def with_host(auth: arista_eos, host: str):
135
    host = (host or "").strip() or (auth.get("host") or "").strip()
136
    if not host:
137
        raise ValueError("host is required: set it on the resource or pass host")
138
    return {**auth, "host": host}
139

140

141
# SSH transport (transport: ssh): the EOS CLI over an SSH shell, behind the part of pyeapi's Node the scripts use
142
# (run_commands, connection.socket_error, connection.transport.connect), raising pyeapi's own CommandError and
143
# ConnectionError, so the checks and the error mapping are the same for both transports. Show commands in json get
144
# "| json", which prints the eAPI JSON; other commands give { messages: [output] } like eAPI, or {} when silent.
145
# A line starting with "% " is an error, raised as eAPI's CommandError. The host key is checked when the resource
146
# has ssh_host_key (SHA256:... as ssh-keygen -lf prints it).
147
class Ssh:
148
    def __init__(self, auth: arista_eos, timeout: float):
149
        self.auth, self.timeout = auth, timeout
150
        self.connection = self.transport = self
151
        self.socket_error = self.sock = self.chan = None
152

153
    # The TCP connection only, like eAPI's transport.connect(): if it fails, nothing was sent.
154
    def connect(self):
155
        self.sock = socket.create_connection(ssh_addr(self.auth), self.timeout)
156

157
    def lost(self, e):
158
        self.socket_error = e
159
        return pyeapi.eapilib.ConnectionError("ssh", f"SSH connection failed ({e})")
160

161
    def open(self):
162
        auth = self.auth
163
        try:
164
            if not self.sock:
165
                self.connect()
166
            t = paramiko.Transport(self.sock)
167
            t.start_client(timeout=self.timeout)
168
            key = t.get_remote_server_key()
169
        except (OSError, EOFError, paramiko.SSHException) as e:
170
            raise self.lost(e)
171
        fp = "SHA256:" + base64.b64encode(hashlib.sha256(key.asbytes()).digest()).decode().rstrip("=")
172
        if auth.get("ssh_host_key") and auth["ssh_host_key"].strip() != fp:
173
            t.close()
174
            raise RuntimeError(f"{auth['host']}: the SSH host key is {fp}, not the resource's ssh_host_key")
175
        try:
176
            try:
177
                t.auth_password(auth["username"], auth["password"])
178
            except paramiko.BadAuthenticationType:
179
                t.auth_interactive(
180
                    auth["username"], lambda _t, _i, prompts: [auth["password"]] * len(prompts)
181
                )
182
        except paramiko.AuthenticationException as e:
183
            t.close()
184
            raise pyeapi.eapilib.ConnectionError("ssh", str(e))
185
        except (OSError, EOFError, paramiko.SSHException) as e:
186
            raise self.lost(e)
187
        try:
188
            self.chan = t.open_session()
189
            self.chan.get_pty(width=4000)
190
            self.chan.invoke_shell()
191
            self.prompt = None
192
            out = self.read()
193
            self.prompt = re.escape(re.split(r"[(>#]", out.splitlines()[-1].strip())[0])
194
            if out.rstrip().endswith(">"):
195
                self.cli("enable")
196
            self.cli("terminal length 0")
197
            self.cli("terminal width 32767")
198
        except (OSError, EOFError, paramiko.SSHException) as e:
199
            raise self.lost(e)
200

201
    # Reads until the prompt. Questions eAPI never asks are answered as eAPI behaves: confirm, don't save.
202
    def read(self):
203
        buf, end = "", time.monotonic() + self.timeout
204
        prompt = (self.prompt or r"[\w.\-]+") + r"(\([^)\r\n]*\))?[>#] ?$"
205
        while True:
206
            self.chan.settimeout(max(end - time.monotonic(), 0.01))
207
            chunk = self.chan.recv(65536)
208
            if not chunk:
209
                raise self.lost("connection closed")
210
            buf += chunk.decode(errors="replace")
211
            tail = buf[-300:]
212
            if re.search(r"(^|\n)" + prompt, tail):
213
                return buf
214
            for question, answer in (
215
                # enable asks for a password on switches that land the user unprivileged: the login password.
216
                (r"(^|\n)Password:\s*$", self.auth["password"]),
217
                (r"\[confirm\]\s*$", ""),
218
                (r"Save\?.*\[yes/no[^\]]*\]:?\s*$", "no"),
219
                (r"\[(y|yes)/(n|no)\][:?]?\s*$", "y"),
220
            ):
221
                if re.search(question, tail, re.I):
222
                    self.chan.send(answer + "\r")
223
                    buf += "\n"
224

225
    # One command: its output without the echoed command and the prompt; progress lines keep their last state.
226
    def cli(self, cmd):
227
        try:
228
            self.chan.send(cmd + "\r")
229
            out = self.read()
230
        except (OSError, EOFError, paramiko.SSHException) as e:
231
            raise self.lost(e)
232
        self.mode = out.rstrip().splitlines()[-1]
233
        lines = [l.rstrip("\r").split("\r")[-1] for l in out.split("\n")]
234
        return "\n".join(lines[1:-1]).strip("\n")
235

236
    def run_commands(self, cmds, encoding="json", **_):
237
        try:
238
            if not self.chan:
239
                self.open()
240
            if "(config" in self.mode:
241
                self.cli("end")
242
            results = []
243
            for i, c in enumerate(cmds):
244
                # eAPI's { cmd, revision } form is the CLI's "| json revision N".
245
                cmd, rev = (c["cmd"], c.get("revision")) if isinstance(c, dict) else (c, None)
246
                show = encoding == "json" and (rev or re.match(r"\s*sh(ow)?\s", cmd)) and not re.search(r"\|\s*json", cmd)
247
                # pyeapi sends "<cmd> MULTILINE: <text>" (banners) as cmd + input; the CLI reads the text up to EOF.
248
                head, multi, text = cmd.partition("MULTILINE:")
249
                # The shell would run what follows a line break as another command; eAPI refuses it too.
250
                if re.search(r"[\r\n]", head):
251
                    raise ValueError(f"a command may not contain a line break: {head!r}")
252
                line = "\r".join([head.strip(), *text.strip().splitlines(), "EOF"]) if multi else cmd
253
                out = self.cli(f"{cmd} | json{f' revision {rev}' if rev else ''}" if show else line)
254
                errors = [l[2:] for l in out.splitlines() if l.startswith("% ")]
255
                code, kind = 1002, "invalid command"
256
                if show and not errors:
257
                    code, kind = 1000, "could not run command"
258
                    try:
259
                        result = json.loads(out)
260
                    except ValueError:
261
                        errors = [out[:200]]
262
                    else:
263
                        errors = result.get("errors") or []
264
                if errors:
265
                    raise pyeapi.eapilib.CommandError(
266
                        code,
267
                        f"CLI command {i + 2} of {len(cmds) + 1} '{cmd}' failed: {kind}",
268
                        command_error="; ".join(errors),
269
                        commands=cmds,
270
                        output=results,
271
                    )
272
                if encoding != "json":
273
                    result = {"output": out + "\n" if out else ""}
274
                elif not show:
275
                    # The CLI prints eAPI's warnings as "! " notices.
276
                    notices = [l[2:].strip() for l in out.splitlines() if l.startswith("! ")]
277
                    out = "\n".join(l for l in out.splitlines() if not l.startswith("! ")).strip()
278
                    result = {"messages": [out]} if out and not multi else {}
279
                    if notices:
280
                        result["warnings"] = notices
281
                results.append(result)
282
            return results
283
        except pyeapi.eapilib.ConnectionError:
284
            if self.chan:
285
                self.chan.close()
286
            self.sock = self.chan = None
287
            raise
288

289

290
# paramiko logs a traceback when a rebooting switch drops the session.
291
logging.getLogger("paramiko").addHandler(logging.NullHandler())
292

293

294
# host, or host:port ([v6]:port), else port, else 22.
295
def ssh_addr(auth: arista_eos):
296
    h = auth["host"]
297
    if "://" in h:
298
        raise ValueError(f"with transport ssh, host is an address or a hostname (with :port), not a URL: {h}")
299
    url = urlsplit(f"ssh://{h}" if h.count(":") <= 1 or h.startswith("[") else f"ssh://[{h}]")
300
    return url.hostname, url.port or int(auth.get("port") or 22)
301

302

303
# Every action raises DeviceUnreachable when the switch can't be reached and AuthFailure when it refuses the
304
# credential, so a flow can retry on result.error.name. Command errors stay pyeapi's CommandError.
305
def node(auth: arista_eos, timeout: float = 60):
306
    eos = open_node(auth, timeout)
307
    run = eos.run_commands
308

309
    def run_commands(*args, **kwargs):
310
        try:
311
            return run(*args, **kwargs)
312
        except pyeapi.eapilib.ConnectionError as e:
313
            raise connection_error(auth, eos, e)
314

315
    eos.run_commands = run_commands
316
    return eos
317

318

319
# pyeapi 1.0.4 raises ConnectionError for a socket error (kept in socket_error), an answer that isn't JSON (eAPI
320
# still starting, 5xx) and a 401, the only one with neither.
321
def connection_error(auth, eos, e):
322
    # A certificate the resource does not trust is a setting to fix (verify_tls, ca_certificate), not worth a retry.
323
    if isinstance(eos.connection.socket_error, ssl.SSLCertVerificationError):
324
        return RuntimeError(f"{auth['host']}: {eos.connection.socket_error}")
325
    if eos.connection.socket_error is None and e.message != "unable to connect to eAPI":
326
        return AuthFailure(f"{auth['host']}: {'SSH' if auth.get('transport') == 'ssh' else 'eAPI'} refused the credential ({e.message})")
327
    return DeviceUnreachable(f"{auth['host']}: {e.message}")
328

329

330
class DeviceUnreachable(Exception):
331
    pass
332

333

334
class AuthFailure(Exception):
335
    pass
336

337

338
# pyeapi logs a traceback for every socket error.
339
logging.getLogger("pyeapi").addHandler(logging.NullHandler())
340

341

342
# 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
343
# resource ticks allow_http (Basic auth then crosses the network in cleartext). pyeapi skips certificate checks unless it
344
# is given a context, so one is always passed: verifying, or not when the resource unticks verify_tls (EOS ships a
345
# self-signed cert).
346
def open_node(auth: arista_eos, timeout: float = 60):
347
    if auth.get("transport") == "ssh":
348
        return Ssh(auth, timeout)
349
    host = auth["host"]
350
    if "://" not in host:
351
        host = f"https://[{host}]" if host.count(":") > 1 and "[" not in host else f"https://{host}"
352
    url = urlsplit(host)
353
    if not url.hostname or (url.scheme != "https" and not (url.scheme == "http" and auth.get("allow_http"))):
354
        raise ValueError(f"host must be an address or an https:// URL (http:// needs allow_http on the resource): {auth['host']}")
355
    # ca_certificate: the PEM of a private CA, trusted instead of the system's CAs.
356
    context = ssl.create_default_context(cadata=(auth.get("ca_certificate") or "").strip() or None)
357
    if auth.get("verify_tls") is False:
358
        context.check_hostname = False
359
        context.verify_mode = ssl.CERT_NONE
360
    return pyeapi.connect(
361
        transport=url.scheme,
362
        host=url.hostname,
363
        port=url.port or auth.get("port") or None,
364
        username=auth["username"],
365
        password=auth["password"],
366
        context=context,
367
        timeout=timeout,
368
        return_node=True,
369
    )
370