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() : envoie un courriel par le serveur enregistré avec bogo login --mail (DESIGN.md 24.6).
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
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).
Link
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.