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 ": |
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 |
|