Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Référence

Chaque nom intégré avec sa signature et son texte, produit à partir du code.

Toutes les pages de documentation

Tous les noms qu'un programme Bogolang peut utiliser sans import. Cette page est produite à partir du code par tools/make_reference.py : ne la modifiez pas à la main. bogo doc NAME affiche une entrée dans le terminal.

acl

Test de liste d'accès (DESIGN.md 21.5) : cette liste laisserait-elle passer ce trafic, et quelle ligne décide ?

Acl

class Acl(name: str, kind: str, lines: list[str])

An IPv4 access list, read from a configuration by acl().

name: its name or number
kind: "standard" or "extended"
lines: the permit and deny lines in order, without sequence numbers

  .permits(src: IP, dst: IP, port: int = 0, protocol: str = 'ip', src_port: int = 0) -> Verdict
      Would this list let the traffic pass? port and src_port of 0 mean "not said".

      Raises AclError when the list cannot be read with certainty, or when the answer
      depends on a protocol or a port that was not given.

acl

acl(cfg: Config, name: str) -> Acl

The access list of that name or number in a configuration.

AclError

class AclError(...)

The test cannot answer without guessing.

Verdict

class Verdict(permitted: bool, line: str, number: int)

True when the traffic passes. .line is the line that decides, .number its place in the list.

audit

Règles d'audit (DESIGN.md 21.2).

audit

audit(devices: list[Device], configs: str = '', parallel: int = 10) -> AuditResult

Run every rule on every device it is for. With configs="folder", read FOLDER/<name>.cfg
and contact no device.

AuditResult

class AuditResult(rows: list[AuditRow])

What audit() gives: one AuditRow per rule and device in .rows. bool(result) is True when
nothing failed. print() shows it as a table; table() and export() take it as it is.

  .failed
      The rows that did not pass, in order.
  .passed
      True when no row failed. Also True when no rule was run.

AuditRow

class AuditRow(device: str, rule: str, passed: bool, detail: str)

The result of one rule on one device.

device: the device name
rule: the rule name
passed: True when the rule held
detail: the first test that was false, or the error; empty when passed

capture

Fichiers de capture (DESIGN.md 29.9) : les paquets d'un fichier .pcap ou .pcapng, en-têtes seulement.

each_packet

each_packet(path: str) -> Iterator[Packet]

The packets of a .pcap or .pcapng file one by one, read as they come.

Packet

class Packet(time: Moment, length: Size)

One packet of a capture file. Values the packet does not carry are None or empty.

read_capture

read_capture(path: str, limit: int = 0) -> list[Packet]

The packets of a .pcap or .pcapng file: all of them, or the first `limit`.

change

Le côté exécution du bloc change (DESIGN.md 6.2).

ChangeError

class ChangeError(message: str, device: str, rolled_back: bool)

A change did not go through. rolled_back says whether the rollback lines were sent.

checks

Vérifications de services (DESIGN.md 29.10 et 29.11) : certificat, web, DNS, NTP et SIP.

cert_check

cert_check(host: Host, port: int = 443, timeout: Duration = 5s) -> CertCheck

Read the certificate of a TLS service, even one this computer does not trust.

CertCheck

class CertCheck(error: str, seconds: float, expires: Moment | None = None, subject: str = '', issuer: str = '', names: list[str] | None = None, trusted: bool = False, self_signed: bool = False)

The certificate of a TLS service. .ok: one was read and it has not expired.

dns_check

dns_check(name: str, server: Host | None = None, kind: str = 'A', timeout: Duration = 2s) -> DnsCheck

Ask a DNS server for a name. For PTR, name may be an address.

DnsCheck

class DnsCheck(error: str, seconds: float, answers: list[str] | None = None)

A DNS question. .answers holds the records as text.

http_check

http_check(url: str, timeout: Duration = 10s, verify: bool = True) -> HttpCheck

Read a web address. .ok for a status below 400. Sends no token.

HttpCheck

class HttpCheck(error: str, seconds: float, status: int = 0)

A web address. .ok: the status is below 400.

ntp_check

ntp_check(server: Host, timeout: Duration = 2s) -> NtpCheck

Ask an NTP server for the time. .offset is this computer's clock against it.

NtpCheck

class NtpCheck(error: str, seconds: float, offset: float = 0.0, delay: float = 0.0, stratum: int = 0)

An NTP server. .offset is this computer's clock against the server.

sip_check

sip_check(host: Host, port: int = 5060, transport: str = 'udp', timeout: Duration = 2s) -> SipCheck

Send one SIP OPTIONS. Any SIP answer makes .ok true: the status says the rest.

SipCheck

class SipCheck(error: str, seconds: float, status: int = 0, reason: str = '', server: str = '')

A SIP device asked with OPTIONS. .ok: it answered in SIP, whatever the status.

confobj

La configuration comme objet (DESIGN.md 21.1) : des blocs repérés par l'indentation.

InterfaceConfig

class InterfaceConfig(node: _Node)

An 'interface' block, read once when it is made. A line it cannot read leaves its field empty.

name: the interface, as an Intf
description: the description text, or empty
shutdown: True when the block holds "shutdown"
address: the primary IPv4 address as an IfAddr, or None
mode: "access", "trunk", "routed" or empty
access_vlan: the access VLAN number, or None
trunk_vlans: the allowed VLANs of a trunk as a VlanSet, or None when not written

  .find(start: str) -> list[str]
      Every line under the first one, at any depth, that starts with this text, without its indentation.
  .has(start: str) -> bool
      True when find() finds at least one line.
  .line
      The first line of the block, without its indentation.
  .lines
      The lines under the first one, the block's own indentation removed.
  .section(start: str) -> list[Section]
      Every block inside this one, at any depth, whose first line starts with this text.

load_config

load_config(path: str, platform: str = 'ios') -> Config

A saved configuration, such as a nightly backup. Reads no device.

Section

class Section(node: _Node)

One block: its first line and the lines under it.

  .find(start: str) -> list[str]
      Every line under the first one, at any depth, that starts with this text, without its indentation.
  .has(start: str) -> bool
      True when find() finds at least one line.
  .line
      The first line of the block, without its indentation.
  .lines
      The lines under the first one, the block's own indentation removed.
  .section(start: str) -> list[Section]
      Every block inside this one, at any depth, whose first line starts with this text.

device

Commandes d'équipement : inventaire, sessions SSH en lecture seule, tables, sauvegarde, diff, le journal d'exécution.

backup

backup(d: Device) -> Config

Read the running configuration of d over a read-only SSH session. Nothing is written on the device.
With BOGO_REPLAY set, the saved output is read. Use .save(path) to keep it in a file.

Config

class Config(device: Device, text: str, taken: str)

A device configuration, from backup() or load_config(). On Junos the searches see only the
statements in effect.

device: the device it belongs to
text: the configuration as it was read
taken: when it was read, in UTC, as ISO text (for a file: the time the file was last written)

  .find(start: str) -> list[str]
      Every line, at any depth, that starts with this text, without its indentation. On Junos: every
      statement in effect whose path holds these words side by side, as one line.
  .has(start: str) -> bool
      True when find() finds at least one line.
  .hostname
      The name in the hostname line (system host-name on Junos). Empty text when there is none.
  .inactive
      Junos only: the paths marked inactive, such as "interfaces ge-0/0/1". ValueError on another platform.
  .interfaces
      Every interface block, read into fields. On Junos one entry per interface, then one per unit.
      An interface whose name cannot be read is left out.
  .lines
      The text cut into lines, as it is.
  .save(path: str) -> None
      Write the text to a file in UTF-8. load_config() reads it back.
  .section(start: str) -> list[Section]
      Every block, at any depth, whose first line starts with this text: c.section("router ospf").
  .set_lines
      Junos only: the whole configuration as set lines, with a deactivate line after what it
      switches off. ValueError on another platform.
  .warnings
      What a reader of this configuration must know. Empty on most configurations.

ConfigDiff

class ConfigDiff(added: list[str], removed: list[str])

What diff() found. bool(d) is True when there is a difference. print() shows - and + lines.

added: the lines only in b, each with its section lines in front (on Junos: set lines)
removed: the lines only in a, written the same way

Device

class Device(*, name: str, ip: IP, platform: str = 'ios', role: str = '', site: str = '', extra: dict[str, str] | None = None)

One network device, usually read from inventory(). Two devices with the same name are equal.

name: its name, used in messages, the run record and the replay folders
ip: the address Bogolang connects to
platform: "ios" by default; see the platform table for the others (junos, asa, nxos, ...)
role, site: free text, for the engineer's own sorting
extra: every other column of the device list, as text

diff

diff(a: Config, b: Config) -> ConfigDiff

Section by section. A section that only moved is not reported.

inventory

inventory(path: str) -> list[Device]

Read a device list from a .csv, .xlsx (first sheet), .yaml or .yml file (DESIGN.md 26.7).
name and ip are required; unknown columns go to .extra.

Output

class Output(text: str, command: str, device: Device)

The answer of one command. str() gives the text; "word" in output looks for a text in it.

text: the whole output as the device sent it
command: the command as it was sent
device: the device that answered

  .lines
      The text cut into lines.
  .table() -> list[Row]
      The output read into rows with the ntc-templates layouts. ValueError when no layout is known
      for this command on this platform; .text and .lines still hold the output.

Row

class Row(data: Mapping[str, object])

One line of a table. row.status and row["status"] give the same text.

  .columns
      The column names, in small letters, in their order.

serial

serial(port_name: str, speed: int = 9600, platform: str = 'ios', login: str = 'default') -> Session

A read-only session over a console port (DESIGN.md 26.5), the same as an SSH one. The device is
named after the port. A console that asks for no login works: with no login stored for the
profile, the user and the password are empty. With BOGO_REPLAY set, nothing is opened.

Session

class Session(device: Device, transport: _Transport)

A read-only session to one device, made by ssh() or serial(). Use it in a `with` block so it
is closed at the end. .device is the device it talks to.

  .close() -> None
      Close the session. A `with` block does it for you.
  .run(command: str) -> Output
      Send one read-only command and return its output. Each command goes in the run record.

      Accepted first words: show, ping, traceroute, dir, more (on Junos: show, ping, traceroute,
      file list, file show). Anything else, a line break or a pipe that writes a file raises
      PermissionError. On Junos a ping with no count gets count 5.
  .show(command: str) -> Output
      run() with "show " put in front when the command does not start with it: s.show("version").

ssh

ssh(d: Device, via: Device | None = None) -> Session

A read-only session, through the jump host `via` when one is given.
With BOGO_REPLAY set, saved outputs are read and nothing connects.

flow

Le côté exécution des instructions que Bogolang ajoute (DESIGN.md 6.1 et 6.5).

Alert

class Alert(raised: bool, since: Moment, lasted: Duration)

What an alert block is told: whether it runs for the raise or for the clear.

  .cleared
      True when the block runs because the condition is no longer true. The opposite of .raised.

BogoTimeout

class BogoTimeout(...)

A `wait until` did not come true in time.

BogoWindowError

class BogoWindowError(...)

An `only between` block was reached outside its hours.

confirm

confirm(question: str) -> bool

Ask yes or no at the keyboard. No keyboard means no. BOGO_YES=1 (bogo run --yes) means yes.

dry_run

dry_run() -> bool

True when this run sends nothing: bogo run --dry, bogo test, a packed program started with --dry.
A program asks it to say "would add" and not "added".

Failure

class Failure(item: object, error: str, kind: str)

One item of a parallel loop whose run ended with an error.

last_failures

last_failures() -> list[Failure]

The items of the latest parallel loop that ended with an error.

listen

Écoute du syslog, des traps SNMP et de NetFlow (DESIGN.md 29.5 à 29.8 et 29.11).

listen

listen(duration: Duration | None = None) -> list[ListenCount]

Wait here while the listeners work: for that long, or until Ctrl+C or stop_listening().
Then the listeners are closed, what already waits is handled, and the counts are given.
In a replay it returns when every saved event has been handled.

ListenCount

class ListenCount(kind: str, port: int)

What one listener did. Every packet and event is in exactly one count besides .received.

stop_listening

stop_listening() -> None

Close every listener. May be called from inside a block. Events that still wait are not handled.

logs

Événements de journal (DESIGN.md 21.6) : messages Cisco issus de show logging ou d'un fichier syslog, et Junos

LogEvent

class LogEvent(time: Moment | None, device: str, facility: str, severity: int | None, mnemonic: str, message: str, raw: str)

One log message, from logs() or read_logs().

time: when it happened, as a Moment; None when the line carries no date (an uptime stamp)
device: the device name; from a file, the name a syslog server wrote, or empty
facility: LINK in %LINK-3-UPDOWN; on Junos the program that wrote the line, such as rpd
severity: 0 (emergency) to 7 (debug); None when the line does not say, never a guess
mnemonic: UPDOWN in %LINK-3-UPDOWN; empty when there is none
code: the code as written, such as LINK-3-UPDOWN, or UI_COMMIT on Junos
message: the text after the code
raw: the whole line as read

logs

logs(d: Device, zone: str = 'local') -> list[LogEvent]

The log events of d, from `show logging` (on Junos `show log messages`), over a read-only session.
zone is the zone of stamps that name none. A line that is not an event is skipped.
With BOGO_REPLAY set, the saved output is read.

read_logs

read_logs(path: str, zone: str = 'local') -> list[LogEvent]

Cisco lines and Junos lines, from a file saved from a device or a syslog server.

SyslogEvent

class SyslogEvent(time: Moment | None, device: str, facility: str, severity: int, mnemonic: str, message: str, raw: str, source: IP, received: Moment)

A LogEvent that arrived in a syslog packet (DESIGN.md 29.6): its sender and its arrival time
are always known. It is what the block of `on syslog` is given. A LogEvent read from a file or
from `show logging` has neither value, so a table of such events keeps its eight columns.

mail

mail() : envoie un courriel par le serveur enregistré avec bogo login --mail (DESIGN.md 24.6).

mail

mail(to: str, subject: str, body: str, attach: list[str] | None = None) -> None

Send a mail. It leaves the computer and cannot be taken back: ask with confirm() first.

marking

Noms de marquage : les valeurs DSCP par leur nom, et l'inverse (DESIGN.md 24.3).

dscp

dscp(name: str) -> int

The DSCP value of a name: dscp("EF") gives 46. Any case.

dscp_name

dscp_name(value: int) -> str

The name of a DSCP value: dscp_name(46) gives "EF". A value with no name gives its number.

meraki

Lecture de l'API Meraki Dashboard (DESIGN.md 26.3). Repose sur web.request : rejeu, enregistrement, journal d'exécution.

meraki

meraki(org: str = '', token: str = 'meraki') -> MerakiSession

A read-only Meraki Dashboard session. org is the name or the number of the organisation;
it may be left out when the key sees only one. token is the NAME of the stored API key.

MerakiSession

class MerakiSession(org: str, token: str)

A read-only view of one Meraki organisation.

  .devices() -> list[Row]
      The devices of the organisation, one row each, all pages read.
  .get(path: str, **params: str) -> Reply
      Any other read of the Dashboard API: one request, no paging. path starts with /
  .networks() -> list[Row]
      The networks of the organisation, one row each, all pages read.
  .org_id
      The organisation's number. Looked up on first use; ValueError when org matches none or several.
  .org_name
      The organisation's name, looked up as for .org_id.
  .organizations() -> list[Row]
      Every organisation the API key sees, one row each, all pages read.
  .uplinks() -> list[Row]
      One row per uplink of each appliance, with the appliance's values beside it.

net

Types d'adresses : IP, Net, IfAddr, MAC, Intf, VlanSet et summarize (DESIGN.md 4.4).

free_nets

free_nets(block: Net, used: list[Net]) -> list[Net]

The free space of the block as the fewest subnets, in address order.

IfAddr

class IfAddr(text: str)

An address with its prefix, as on an interface, such as 10.20.30.101/24.

  .ip
      The address alone: 192.0.2.10 for 192.0.2.10/24.
  .net
      The subnet it is in: 192.0.2.0/24 for 192.0.2.10/24.
  .prefix
      The prefix length: 24 for 192.0.2.10/24.

Intf

class Intf(text: str)

An interface name. Gi1/0/24 and GigabitEthernet1/0/24 are the same interface.

  .exact(text: str) -> Intf
      A name kept exactly as written, with no IOS reading of its kind (DESIGN.md 30.3).
      For Junos names: ge-0/0/0, et-0/0/48:1, ae0, lo0, irb.100, ge-0/0/0.100.
  .kind
      The long kind, such as GigabitEthernet. A kind Bogolang does not know is kept as written.
  .long
      The long name, such as GigabitEthernet1/0/24.
  .numbers
      The numbers of the name: (1, 0, 24) for Gi1/0/24.
  .short
      The short name, such as Gi1/0/24. str() gives the same.

IP

class IP(text: str)

One IPv4 or IPv6 address, such as 10.20.30.101 or 2001:db8::1.

  .is_private
      True for an address of a private range, as Python's ipaddress says: RFC 1918, loopback,
      link-local, documentation, fc00::/7 and others. 100.64.0.0/10 (carrier NAT) is not private.
  .to_python() -> _Addr
      The same address as a Python ipaddress object, for a package that wants one.
  .version
      4 or 6.

MAC

class MAC(text: str)

A MAC address: 00:1a:2b:3c:4d:5e, 00-1A-2B-3C-4D-5E or 001a.2b3c.4d5e.

  .cisco
      The address in the Cisco form, 001a.2b3c.4d5e. str() gives 00:1a:2b:3c:4d:5e.
  .oui
      The maker's part, the first three bytes, as 00:1a:2b. vendor() gives the maker's name.

Net

class Net(text: str)

A subnet such as 10.20.30.0/24 or 2001:db8::/32. The host part must be zero.

  .address
      The network address, the first of the subnet.
  .broadcast
      The last address of the subnet.
  .hosts
      The usable addresses one by one, without the network and broadcast addresses (on IPv6, without
      the first address). A /31 or /32 (/127 or /128) gives all its addresses. Made as they are read.
  .mask
      The subnet mask, such as 255.255.255.0.
  .overlaps(other: Net) -> bool
      True when the two subnets share at least one address. An IPv4 and an IPv6 subnet never overlap.
  .prefix
      The prefix length: 24 for 192.0.2.0/24.
  .size
      How many addresses the subnet holds, network and broadcast included: 256 for a /24.
  .split(prefix: int) -> list[Net]
      The subnets of that longer prefix, in order: Net("192.0.2.0/24").split(26) gives four /26.
      ValueError for a prefix not longer than this one, or for more than 65536 pieces.
  .to_python() -> _Network
      The same subnet as a Python ipaddress object, for a package that wants one.
  .version
      4 or 6.
  .wildcard
      The wildcard mask of access lists and OSPF, such as 0.0.0.255.

net_of

net_of(address: IP, mask: IP) -> Net

The network that holds the address, from a subnet mask (255.255.255.0) or a wildcard (0.0.0.255).

next_free

next_free(block: Net, prefix: int, used: list[Net]) -> Net

The first subnet of that prefix length in the block that overlaps no used subnet.

summarize

summarize(nets: list[Net]) -> list[Net]

The shortest list of subnets that covers the same addresses.

VlanSet

class VlanSet(text: str)

A set of VLAN numbers written as a list, such as 10-20,30.

netflow

NetFlow 5, NetFlow 9 (RFC 3954) et IPFIX (RFC 7011) : les enregistrements de flux d'un paquet UDP

Flow

class Flow(exporter: IP, src: IP | None, dst: IP | None, src_port: int, dst_port: int, protocol: str, size: Size, packets: int, start: Moment | None, end: Moment | None, in_if: int, out_if: int, tos: int, next_hop: IP | None, received: Moment)

One flow record. A value the exporter did not send is None, 0 or an empty text.

optics

Mesures optiques issues de show interfaces transceiver detail (DESIGN.md 24.2), et sur Junos issues de

OpticReading

class OpticReading(port: Intf, tx: Power | None, rx: Power | None, temperature: float | None, rx_low: Power | None, rx_high: Power | None, tx_low: Power | None, tx_high: Power | None, status: str, lane: int | None = None)

The optical reading of one port, from optics(). A value the device does not give is None.

tx, rx: transmit and receive levels in dBm
temperature: the module temperature in degrees Celsius
rx_low, rx_high, tx_low, tx_high: the device's low and high alarm thresholds
status: from rx against its thresholds: "ok", "low", "high", "no light" (-40 dBm or less), or
"unknown" when rx or a threshold is missing
lane: the lane of a multi-lane optic (Junos), else None

optics

optics(d: Device) -> list[OpticReading]

The optical readings of d, one per port with a transmit or receive reading, sorted by port.

output

table() et export() : des lignes à l'écran, dans un .csv ou dans un .xlsx (DESIGN.md 5.4).

export

export(rows: Sequence[object] | AuditResult, path: str, columns: list[str] | None = None) -> None

Write the rows to a .csv (UTF-8 with a byte order mark, for Excel) or a .xlsx, by the file ending.

table

table(rows: Sequence[object] | AuditResult, columns: list[str] | None = None) -> None

Print the rows as a table: numbers on the right, text on the left. Long lines are not cut.

radio

Estimations radio (DESIGN.md 24.4) : l'affaiblissement que la pluie ajoute sur un bond.

rain_availability

rain_availability(margin: Gain, distance: Distance, freq: Frequency, rain_rate: float, polarization: str = 'horizontal', *, latitude: float) -> Percent

Share of an average year the hop stays up against rain, given its
fade margin.

From ITU-R P.530-12: Ap = A0.01 * 0.12 p^-(0.546 + 0.043 log10 p) at
latitudes of 30 degrees or more (north or south), and
Ap = A0.01 * 0.07 p^-(0.855 + 0.139 log10 p) below 30 degrees, for p
from 0.001 to 1 percent. latitude is the latitude of the hop in degrees,
north or south. It must be given: the two forms differ, and no place
on Earth is a fair default for every engineer. The p where Ap equals the margin is found by
bisection and the result is 100 - p.

The method cannot promise more than 99.999 percent: a larger margin
gives 99.999. A margin below the fade at p = 1 gives 99.0, which means
99 percent or less.

This is an estimate. It counts rain only, not multipath fading,
obstruction or equipment failure.

rain_fade

rain_fade(distance: Distance, freq: Frequency, rain_rate: float, polarization: str = 'horizontal') -> Gain

Loss that rain adds on a line-of-sight hop, exceeded for 0.01 percent
of an average year, as a positive Gain in dB.

rain_rate is R0.01 in mm/h: the rain rate passed for 0.01 percent of the
year at the site, from the ITU-R P.837 maps or local records.

Loss per km: gamma = k * R^alpha, k and alpha from ITU-R P.838-3.
Effective length, ITU-R P.530-12 section 2.4.1: r = 1 / (1 + d / d0),
d0 = 35 exp(-0.015 R0.01) km (R0.01 capped at 100 mm/h in d0), and
A0.01 = gamma * d * r. P.530-12 says the method holds at least up to
40 GHz and 60 km; Bogolang accepts 1 to 100 GHz and up to 60 km.

This is an estimate. It counts rain only, not multipath fading,
obstruction or equipment failure.

reach

Commandes de joignabilité et de recherche : ping, tcping, trace, resolve, scan, vendor, now (DESIGN.md 5.1).

Hop

class Hop(number: int, ip: IP | None, rtt: Duration | None, sent: int = 1, received: int | None = None, min: Duration | None = None, max: Duration | None = None, ips: list[IP] | None = None)

One step of a trace. ip and rtt are None for a hop that did not answer.

Moment

class Moment(t: datetime)

A date and time that knows its zone.

  .clock
      The time of day as text, such as 14:05, in the moment's own zone.
  .date
      The date as text, such as 2026-03-01, in the moment's own zone.
  .hour
      The hour, 0 to 23, in the moment's own zone.
  .in_zone(zone: str) -> Moment
      The same moment as the clock of another zone shows it. zone as in now().
  .minute
      The minute, 0 to 59.
  .to_python() -> datetime
      The same moment as a Python datetime with its zone.
  .utc
      The same moment in UTC.

now

now(zone: str = 'local') -> Moment

The current time in a zone: "local", a short name such as "WAT", or a full name such as "Africa/Douala".

ping

ping(host: Host, count: int = 5, timeout: Duration = 2s, size: Size = 56B, interval: Duration = 1s, ttl: int = 64, source: IP | None = None, dont_fragment: bool = False, dscp: int = 0) -> PingResult

Ping a host with Bogolang's own packets. A host that does not answer gives ok False.
size is the data in each packet; with dont_fragment a packet too large for the path is not split
and counts as lost, and .reason says why.

ping_all

ping_all(hosts: Sequence[Host], count: int = 3, timeout: Duration = 2s, size: Size = 56B, interval: Duration = 200ms, ttl: int = 64, source: IP | None = None, dont_fragment: bool = False, dscp: int = 0) -> list[PingResult]

Ping many hosts at the same time, from one process. The results come in the order of hosts.

PingResult

class PingResult(sent: int, received: int, loss: Percent, min: Duration | None, avg: Duration | None, max: Duration | None, host: IP | None = None, jitter: Duration | None = None, times: list[Duration] | None = None, reason: str = '')

What came back from a ping. bool(result) is True when at least one reply came back.

  .ok
      True when at least one reply came back.

resolve

resolve(target: str | IP) -> list[IP] | str

A name gives its addresses (empty list when it does not exist). An IP gives its name (empty text when none).

scan

scan(net: Net, allow_large: bool = False, port: int | None = None) -> list[IP]

The addresses of a subnet that answer, in order. With port, a TCP check instead of ping.

tcping

tcping(host: Host, port: int, timeout: Duration = 2s) -> bool

True when a TCP connection to the port opens. Works where ICMP is blocked.

trace

trace(host: Host, max_hops: int = 30, probes: int = 3, timeout: Duration = 2s, dscp: int = 0) -> list[Hop]

The path to a host, hop by hop, with Bogolang's own probes. It stops where the host answers.

vendor

vendor(mac: MAC) -> str

The maker of a MAC address, from the vendor list shipped with Bogolang. Empty text when unknown.

report

Rapports : un modèle dont les trous {name} sont remplis dans un fichier .html, .docx ou .pdf, et des graphiques (DESIGN.md 24.5).

chart

chart(rows: Sequence[object], x: str, y: str, path: str, kind: str = 'line', title: str = '') -> Picture

Draw column y against column x as a .png and return it as a Picture for report().

Picture

class Picture(path: str)

A picture file to put in a report.

picture

picture(path: str) -> Picture

A picture file to put in a report() hole. FileNotFoundError when the file does not exist.

report

report(template: str, path: str, **values: object) -> None

Fill the template's holes and write path. Its ending (.html, .docx or .pdf) chooses the kind.

restconf

Lecture d'un équipement par RESTCONF (DESIGN.md 26.4). Repose sur web.request : rejeu, enregistrement, journal d'exécution.

restconf

restconf(d: Device, verify: bool = True) -> RestSession

A read-only RESTCONF session to a device, with its stored login. Nothing is sent yet.

RestSession

class RestSession(d: Device, verify: bool)

A read-only RESTCONF view of one device.

  .get(path: str) -> Reply
      One GET of https://<device>/restconf/data/<path>, path as in the data model,
      for example "ietf-interfaces:interfaces".

routes

Recherche de route (DESIGN.md 21.4) : la table de routage d'un équipement ou d'un instantané, et sa correspondance la plus longue.

Route

class Route(net: Net, protocol: str, next_hop: IP | None = None, interface: str = '', distance: int = 0, metric: int = 0)

One route of a routing table.

net: the destination subnet
protocol: the device's code, such as C, S, O or "O E2"
next_hop: the next-hop address; None for a connected route or one with no next hop
interface: the outgoing interface as the device wrote it, or empty
distance: the administrative distance; 1 for a static the device shows none for, else 0 when not shown
metric: the metric, 0 when not shown

routes

routes(source: Device | Snapshot, vrf: str = '') -> RouteTable

The routing table of a device, read over a read-only session, or of a saved snapshot (no device
is contacted). vrf names a VRF; on Junos the table NAME.inet.0. An ASA takes no vrf.
With BOGO_REPLAY set, the saved output is read.

RouteTable

class RouteTable(routes: list[Route])

The routes of one table, from routes(). .routes is the list; len() and a for loop work on it.
The lookup says what the table says: it does not follow a recursive next hop.

  .lookup(ip: IP) -> Route | None
      The longest match for ip (the first one when there are several), or None when no route matches.
  .lookup_all(ip: IP) -> list[Route]
      Every route of the longest match for ip, such as the equal-cost paths. Empty when none matches.

runtime

Ce dont un programme Bogolang en cours d'exécution a besoin de la part de Bogolang lui-même.

Untyped

class Untyped(o: object)

An object from a package with no types (DESIGN.md 15.3). It may be called and read
from, and every result is Untyped again until a line gives it a type. The checker knows
nothing about what is inside: a wrong name is found when the program runs.

secret

Secret : un texte qui ne doit pas fuiter (DESIGN.md 4.5). .reveal() est le seul moyen d'en sortir.

Secret

class Secret(text: str)

A text that must not leak, such as a password. print(), str() and f-strings show <secret>.
It cannot be pickled or copied. .reveal() is the only way to the text.

  .reveal() -> str
      The text itself. Give it only to what needs it; never print it or write it to a file.

snapshot

Snapshot : routes, voisins, interfaces et configuration d'un équipement, lus en une seule session.

compare

compare(a: Snapshot, b: Snapshot) -> SnapshotDiff

a is before, b is after. Uptimes, hold times and metrics are not compared.

load_snapshot

load_snapshot(path: str) -> Snapshot

A snapshot saved with .save(path). Contacts no device. ValueError when the file is not a
snapshot, is damaged, or was written by another snapshot version.

Snapshot

class Snapshot(device: str, platform: str, taken: Moment, routes: list[Row], neighbors: list[Row], interfaces: list[Row], config: Config)

The state of one device at one time, from snapshot() or load_snapshot(). Give two to compare().

device, platform: the device name and its platform
taken: when the snapshot was taken, as a Moment
routes, neighbors, interfaces: the parsed tables, as rows (neighbours from CDP, LLDP on Junos)
config: the running configuration, as a Config

  .save(path: str) -> None
      Write it to a JSON file that load_snapshot() reads back.

snapshot

snapshot(d: Device) -> Snapshot

The commands come from the platform table. A thing the platform has not (routes on AireOS,
neighbours on an ASA) is an empty list.

SnapshotDiff

class SnapshotDiff(routes_added: list[Row], routes_removed: list[Row], neighbors_added: list[Row], neighbors_removed: list[Row], interfaces_added: list[Row], interfaces_removed: list[Row], interfaces_changed: list[tuple[Row, Row]], config: ConfigDiff)

What compare(before, after) found. bool(d) is True when anything differs; print() shows + - ~ lines.

routes_added, routes_removed, neighbors_added, neighbors_removed, interfaces_added,
interfaces_removed: the rows only in after, or only in before
interfaces_changed: (before, after) pairs of an interface whose address, status or protocol changed
config: the ConfigDiff of the two configurations

snmp

Lectures SNMP : snmp_get et snmp_walk, en lecture seule.

snmp_get

snmp_get(d: Device, oid: str, timeout: Duration = 2s) -> SnmpValue

One value. LookupError when the device has nothing at that OID.

snmp_walk

snmp_walk(d: Device, oid: str, timeout: Duration = 2s) -> list[SnmpValue]

Every value under the OID, in the device's order. Empty when there is none.

SnmpValue

class SnmpValue(oid: str, kind: str, text: str)

One SNMP value. str() gives its text.

oid: the OID in numbers, such as 1.3.6.1.2.1.1.5.0
kind: integer, counter, gauge, timeticks, ip, oid, text or bytes
text: the value as text; bytes are written in hex as 0a:1b:2c, timeticks in hundredths of a second

  .number
      The value as a whole number, for integer, counter, gauge and timeticks. ValueError for any other kind.

sources

Inventaire à partir d'une API web (DESIGN.md 26.7). Les sources sous forme de fichier (.csv, .xlsx, .yaml) sont dans device.inventory.

inventory_api

inventory_api(url: str, token: str = '', fields: dict[str, str] | None = None, verify: bool = True) -> list[Device]

Read the device list from a web API that answers a JSON list of objects.

token is the NAME of a token stored with `bogo login --api NAME`. fields maps a Bogolang field
(name, ip, platform, site, role) to the API's name for it. Every other value goes to .extra.
A platform Bogolang does not know does not stop the list: that device gets the platform ios and
the API's word in .extra["api_platform"]. Check a device's platform before running commands on it.

telecom

Calculs télécoms (DESIGN.md 5.3) : radio, fibre, trafic, voix et ports.

Budget

class Budget(rx: Power, margin: Gain)

Result of link_budget(): received level and margin over the sensitivity.

  .ok
      True when the link closes: the margin is 0 dB or more.

codec_bandwidth

codec_bandwidth(codec: str, layer: str = 'ip') -> Rate

Bandwidth of one call in one direction: (payload + headers) * 8 * packets per second.

Headers: 40 bytes IP + UDP + RTP for "ip", plus 18 bytes Ethernet (14 + FCS 4)
for "ethernet". 20 ms packets, 30 ms for G.723.1 (Cisco "Voice Over IP: Per
Call Bandwidth Consumption"). G.711: 80 kbps IP, 87.2 kbps Ethernet.

eirp

eirp(tx: Power, antenna: Gain, cable_loss: Gain) -> Power

EIRP = tx - cable loss + antenna gain (ITU-R definition, in dBm).

erlang_b

erlang_b(traffic: Traffic, lines: int) -> Percent

Blocking probability of offered traffic A on N lines (Erlang B).

Stable recurrence (ITU-T E.520 / Teletraffic Engineering Handbook, ITU-D):
B(0) = 1, B(n) = A * B(n-1) / (n + A * B(n-1)). No factorials.

erlang_c

erlang_c(traffic: Traffic, agents: int) -> Percent

Probability that a call waits (Erlang C), from Erlang B:
C = N * B / (N - A * (1 - B)) (Teletraffic Engineering Handbook, ITU-D).
When A >= N the queue never empties: 100 percent.

fibre_loss

fibre_loss(distance: Distance, wavelength: Wavelength, connectors: int, splices: int, *, per_km: Gain | None = None, per_connector: Gain = 0.5dB, per_splice: Gain = 0.1dB) -> Gain

Planned loss of a fibre run: km * per_km + connectors * per_connector
+ splices * per_splice (the TIA-568 / IEC 61280-4 loss budget method).

Without per_km the attenuation comes from the wavelength (15 nm either
side): 850 nm 3.0 dB/km, 1300 nm 1.0 dB/km (multimode), 1310 nm 0.35,
1550 nm 0.22, 1625 nm 0.25 dB/km (single-mode). 1300 and 1310 overlap:
the nearest nominal wins, and 1305 nm counts as 1300 (multimode).
These are planning values. The real loss of a fibre is what a
measurement (light source and power meter, or OTDR) says.

fresnel

fresnel(distance: Distance, freq: Frequency, zone: int = 1) -> Distance

Radius of Fresnel zone n at the middle of the hop.

r = sqrt(n * wavelength * d1 * d2 / d), which at the middle (d1 = d2 = d/2)
is sqrt(n * wavelength * d / 4) (ITU-R P.530, P.526).

fspl

fspl(distance: Distance, freq: Frequency) -> Gain

Free-space path loss, as a positive loss in dB.

FSPL = 20 log10(d) + 20 log10(f) + 20 log10(4 pi / c), d in m, f in Hz
(ITU-R P.525: L = 32.44 + 20 log10(f MHz) + 20 log10(d km)).
link_budget(tx: Power, gains: list[Gain], losses: list[Gain], sensitivity: Power) -> Budget

rx = tx + sum(gains) - sum(losses); margin = rx - sensitivity.

Losses are given as positive numbers. A gain may be negative.

mos

mos(loss: Percent, delay: Duration, jitter: Duration, codec: str) -> float

Estimated call quality (MOS, 1.0 to 4.5). It is an estimate, not a measurement.

ITU-T G.107 E-model, simplified form (Cole and Rosenbluth, 2001):
d = one-way delay + 2 * jitter (jitter buffer) + codec delay, in ms;
Id = 0.024 d + 0.11 (d - 177.3) when d > 177.3;
Ie_eff = Ie + (95 - Ie) * Ppl / (Ppl + Bpl), Ie and Bpl from ITU-T G.113 Appendix I;
R = 93.2 - Id - Ie_eff; MOS = 1 + 0.035 R + 7e-6 R (R - 60)(100 - R) (G.107 Annex B).
G.711 uses Bpl 25.1 (with packet-loss concealment). G.722 is treated as G.711.
G.726 has no Bpl in G.113, so it uses G.711's value with concealment.

port_of

port_of(name: str) -> int

Well-known port of a service name, in any case (IANA registry).

service_of

service_of(port: int) -> str

Main service name of a well-known port (IANA registry).

template

Modèles : fichiers texte de lignes d'équipement avec des trous {name} (DESIGN.md 21.3).

Template

class Template(path: str, text: str)

Device lines with holes, read from a file by template(path).

  .fill(d: Device, **values: Insertable) -> str
      The lines for device d, every hole filled. A hole takes its value from values first, then from
      d (name, ip, site, role, platform), then from d.extra. ValueError when a hole has no value or an
      empty one; TypeError for a Secret, as device text never holds a secret.

template

template(path: str) -> Template

Read a template file. Mistakes in its braces or holes are found here.

topology

Voisins issus de CDP et LLDP, et la topologie qu'ils dessinent (DESIGN.md 21.7).

class Link(a: str, a_port: str, b: str, b_port: str)

One cable of a Topology: device a, its port a_port, device b, its port b_port.

Neighbor

class Neighbor(device: str, local_port: Intf, name: str, port: str, platform: str, ip: IP | None, source: str)

One neighbour seen by CDP or LLDP, from neighbors().

device: the device that sees it; local_port: its own port
name: the neighbour's name; port: the neighbour's port as it announces it
platform: the neighbour's model or software as announced, or empty
ip: its management address, or None
source: "cdp", "lldp" or "cdp+lldp" (CDP values first, gaps filled from LLDP)

neighbors

neighbors(d: Device) -> list[Neighbor]

The neighbours CDP and LLDP see on d, one entry per neighbour and local port, sorted by local port.

Topology

class Topology(nodes: list[str], links: list[Link], failed: list[tuple[str, str]])

The devices and cables CDP and LLDP see. Built by topology().

  .neighbors_of(name: str) -> list[str]
      The names linked to this node, sorted. ValueError when name is not a node.
  .path(a: str, b: str) -> list[str]
      The names from a to b with the fewest hops, both ends included. [] when there is no way.

      Hops are counted in what CDP and LLDP see: cables, not routing. It is not the path a packet takes.
  .save(path: str) -> None
      Write .json, .csv or .dot, chosen by the file ending.

topology

topology(devices: list[Device], parallel: int = 10) -> Topology

Read the neighbours of every device, `parallel` at a time. A device that fails goes to .failed.

traps

Traps SNMP : le décodage d'un paquet (version 1 ou 2c) en un Trap.

Trap

class Trap(source: IP, device: str, oid: str, uptime: Duration | None, values: list[SnmpValue], received: Moment)

One SNMP trap or inform (version 1 or 2c), as the block of `on trap` is given it. The community
is never kept.

source: the address that sent it
device: the name of the device of the `from` list with that address, or empty
oid: which trap it is; a version 1 generic trap is given its version 2c OID
uptime: the sender's uptime as a Duration, or None when the trap does not carry it
values: the other values, as SnmpValue
received: when it arrived, as a Moment

units

Grandeurs avec unités (DESIGN.md 3.1, 4.3).

ClockTime

class ClockTime(text: str)

A time of day, "HH:MM" from 00:00 to 23:59. str() gives 02:00.

combine

combine(a: Power, b: Power) -> Power

Sum of two powers, added in milliwatts.

Distance

class Distance(value: float, unit: str)

Length. Base unit m. Shown in m or km. Feet (ft) and miles (mi) can be written and asked for.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Duration

class Duration(value: float, unit: str)

Time span. Base unit s. Shown in ms, s, min, h or d (90s shows as 1.5min).

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Frequency

class Frequency(value: float, unit: str)

Frequency. Base unit Hz. Shown in Hz, kHz, MHz or GHz.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.
  .wavelength
      The wavelength of this frequency in nm, from the speed of light in a vacuum.

Gain

class Gain(value: float, unit: str)

A gain or loss. Base unit dB; dBi is the same number. Shown in dB.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

PacketRate

class PacketRate(value: float, unit: str)

Packets per second. Base unit pps.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Percent

class Percent(value: float, unit: str)

Percentage. Base unit pct. Values below 0 or above 100 are allowed.

  .fraction
      The value as a fraction: 25 percent gives 0.25.
  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Power

class Power(value: float, unit: str)

A power level. Base unit dBm. dBW is dBm - 30. mW and W must be above
zero. Shown in dBm. Power + Power is refused: use combine().

  .to(unit: str) -> float
      The level as a plain number in dBm, dBW, mW or W: Power(0, "dBm").to("mW") gives 1.0.

Rate

class Rate(value: float, unit: str)

Bit rate. Base unit bps. Shown in bps, kbps, Mbps or Gbps.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Size

class Size(value: float, unit: str)

Amount of data. Base unit B (bytes). kB, MB, GB are powers of 1000,
KiB, MiB, GiB powers of 1024. Shown in B, kB, MB or GB only.

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Traffic

class Traffic(value: float, unit: str)

Telephone traffic. Base unit erl (erlangs).

  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

Wavelength

class Wavelength(value: float, unit: str)

Wavelength of light. Base unit nm, shown in nm.

  .frequency
      The frequency of this wavelength, from the speed of light in a vacuum.
  .to(unit: str) -> float
      The value as a plain number in that unit: Rate(1.5, "Gbps").to("Mbps") gives 1500.0.
      ValueError for a unit this kind does not have.

web

Lecture d'une API web (DESIGN.md 26.1 et 26.2). Meraki, RESTCONF et l'inventaire par API reposent dessus.

http_get

http_get(url: str, token: str = '', params: dict[str, str] | None = None, verify: bool = True, timeout: Duration = 10s) -> Reply

Read a web address. token is the NAME of a token stored with `bogo login --api NAME`.

Reply

class Reply(status: int, text: str, url: str, headers: dict[str, str] | None = None)

What a server answered. .rows() and .value() read it as JSON.

  .data() -> object
      The answer read as JSON: a dict, a list or a plain value. ValueError when it is not JSON.
  .rows(key: str = '') -> list[Row]
      The answer as rows, when it is a JSON list of objects. key names the list when it sits
      inside an object, as in .rows("items").
  .value(path: str) -> str
      One value of the JSON answer, as text. The path is written a.b.0.c

webhook

webhook(name: str, text: str) -> None

Post one text to the webhook stored with `bogo login --webhook NAME`. It leaves the computer
and cannot be taken back. With `bogo run --dry` it is shown and not sent.