Version 0.1.0 on Python 3.15
A programming language for network and telecommunications engineers.
Bogolang is a language of its own, built on top of Python 3. It has its own literals, statements, rules and tools. It is class based, as Java is: all code stands inside a class, and a program starts in main. Addresses, subnets, interfaces and units are real types. Reaching hosts, reading devices, testing an access list or planning a radio link are built-in commands. A change to a device is refused when it has no rollback. Every Python package keeps working.
- Class based
- Windows and Linux
- No administrator right
- MIT licence
edition 2027
"""Is everything up? Ping a list of hosts at once, trace the path to one, scan a small network."""
class ReachHosts:
"""A morning reach check: a table of ping results, one trace and one scan."""
hosts: list[IP] = [192.0.2.1, 192.0.2.10, 198.51.100.7, 203.0.113.20]
far: IP = 203.0.113.20
lan: Net = 192.0.2.0/29
slow: Duration = 50ms
@staticmethod
def verdict(r: PingResult, slow: Duration) -> str:
"""One word for a ping result: DOWN, LOSS, SLOW or ok."""
if not r.ok:
return "DOWN"
if r.received < r.sent:
return "LOSS"
if r.avg is not None and r.avg > slow:
return "SLOW"
return "ok"
@staticmethod
def main(args: list[str]) -> None:
results: list[PingResult] = ping_all(ReachHosts.hosts, count=3, timeout=1s)
rows: list[dict[str, object]] = []
for r in results:
rows.append(
{
"host": r.host,
"received": f"{r.received}/{r.sent}",
"loss": r.loss,
"avg": r.avg,
"jitter": r.jitter,
"state": ReachHosts.verdict(r, ReachHosts.slow),
}
)
table(rows)
print(f"\nPath to {ReachHosts.far}:")
for hop in trace(ReachHosts.far, max_hops=10, probes=2):
print(f" {hop}")
up: list[IP] = scan(ReachHosts.lan)
print(
f"\n{len(up)} addresses answer in {ReachHosts.lan}: {', '.join(str(ip) for ip in up)}"
)
$ bogo run --replay saved reach_hosts.bogo
host received loss avg jitter state ------------ -------- ------- -------- ------ ----- 192.0.2.1 3/3 0pct 1.233ms 0.25ms ok 192.0.2.10 2/3 33.3pct 2.35ms 0.5ms LOSS 198.51.100.7 0/3 100pct DOWN 203.0.113.20 3/3 0pct 61.767ms 4.1ms SLOW Path to 203.0.113.20: 1 192.0.2.1 1ms 0% loss 2 198.51.100.1 8.65ms 0% loss 3 * * 100% loss 4 198.51.100.65 40.95ms 0% loss 5 203.0.113.20 61.05ms 0% loss 3 addresses answer in 192.0.2.0/29: 192.0.2.1, 192.0.2.2, 192.0.2.5
edition 2027
"""Address plan for new sites, worked out from one block. No device is contacted."""
class AddressPlan:
"""Give each new site a user subnet and a link to the hub, check a few
subnets someone asked for, then show the space that is still free."""
block: Net = 10.40.0.0/16
in_use: list[Net] = [10.40.0.0/22, 10.40.8.0/24, 10.40.64.0/18]
links: Net = 10.40.255.0/24
# site name, and the prefix length its users need
sites: dict[str, int] = {
"north-depot": 22,
"south-depot": 23,
"river-office": 24,
"harbour": 24,
}
# subnets other teams asked for: are they free?
requests: list[Net] = [10.40.12.0/23, 10.40.70.0/24, 10.40.128.0/24]
@staticmethod
def plan(block: Net, used: list[Net], wanted: dict[str, int]) -> dict[str, Net]:
"""The next free subnet of the asked size for each site, in the order given."""
taken: list[Net] = list(used)
out: dict[str, Net] = {}
for site, prefix in wanted.items():
net: Net = next_free(block, prefix, taken)
taken.append(net)
out[site] = net
return out
@staticmethod
def clashes(asked: list[Net], used: list[Net]) -> list[tuple[Net, Net]]:
"""Each asked subnet that overlaps a used one, with the one it hits."""
return [(a, u) for a in asked for u in used if a.overlaps(u)]
@staticmethod
def main(args: list[str]) -> None:
a = AddressPlan
subnets: dict[str, Net] = a.plan(a.block, a.in_use, a.sites)
p2p: list[Net] = a.links.split(30)
rows: list[dict[str, object]] = []
for n, (site, net) in enumerate(subnets.items()):
rows.append(
{
"site": site,
"users": str(net),
"hosts": net.size - 2,
"gateway": str(next(net.hosts)),
"hub link": str(p2p[n]),
}
)
table(rows)
used: list[Net] = a.in_use + list(subnets.values()) + [a.links]
print()
for asked in a.requests:
hits: list[tuple[Net, Net]] = a.clashes([asked], used)
print(
f"{asked}: "
+ (f"no, it overlaps {hits[0][1]}" if hits else "free, it can be given")
)
print()
print(f"Free in {a.block}:")
table([{"subnet": str(f), "addresses": f.size} for f in free_nets(a.block, used)])
$ bogo run address_plan.bogo
site users hosts gateway hub link ------------ ------------- ----- ---------- --------------- north-depot 10.40.4.0/22 1022 10.40.4.1 10.40.255.0/30 south-depot 10.40.10.0/23 510 10.40.10.1 10.40.255.4/30 river-office 10.40.9.0/24 254 10.40.9.1 10.40.255.8/30 harbour 10.40.12.0/24 254 10.40.12.1 10.40.255.12/30 10.40.12.0/23: no, it overlaps 10.40.12.0/24 10.40.70.0/24: no, it overlaps 10.40.64.0/18 10.40.128.0/24: free, it can be given
edition 2027
"""The plan of one microwave hop: free-space loss, link budget, fade margin and rain."""
class RadioLink:
"""Checks one microwave hop against a target availability.
The rain rate and the latitude depend on where the hop is. The values below are
examples only: take the rain rate R0.01 for your site from the ITU-R P.837 maps or
from local records, and the latitude of your own hop.
"""
name = "site-a to site-b"
freq = 18GHz
distance = 12km
tx = 18dBm
antenna_a = 38dBi
antenna_b = 38dBi
feeder_loss = 2dB # waveguide and connectors, both ends together
sensitivity = -70dBm # receiver threshold of the chosen modulation
rain_rate = 42.0 # EXAMPLE: mm/h passed for 0.01 percent of the year
latitude = 45.0 # EXAMPLE: degrees, north or south
polarization = "vertical"
target = 99.99pct
@staticmethod
def budget(distance: Distance, freq: Frequency) -> Budget:
losses: list[Gain] = [fspl(distance, freq), RadioLink.feeder_loss]
gains: list[Gain] = [RadioLink.antenna_a, RadioLink.antenna_b]
return link_budget(RadioLink.tx, gains, losses, RadioLink.sensitivity)
@staticmethod
def verdict(availability: Percent, target: Percent) -> str:
if availability >= target:
return "meets the target"
return "misses the target"
@staticmethod
def downtime_minutes(availability: Percent) -> float:
"""Minutes of rain outage in an average year."""
return (100 - availability.value) / 100 * 365 * 24 * 60
@staticmethod
def main(args: list[str]) -> None:
r = RadioLink
b = r.budget(r.distance, r.freq)
fade = rain_fade(r.distance, r.freq, r.rain_rate, r.polarization)
print(f"Hop {r.name}: {r.distance} at {r.freq}, {r.polarization} polarization")
print(f" Free-space loss {fspl(r.distance, r.freq)}")
print(f" First Fresnel zone {fresnel(r.distance, r.freq)} radius at mid-hop")
print(f" Received level {b.rx}")
print(f" Fade margin {b.margin}")
print(f" Rain fade (0.01%) {fade} at {r.rain_rate} mm/h")
if not b.ok:
print(" The link does not close: no availability to compute.")
return
avail = rain_availability(
b.margin, r.distance, r.freq, r.rain_rate, r.polarization, latitude=r.latitude
)
minutes = r.downtime_minutes(avail)
print(f" Availability (rain) {avail}, about {minutes:.0f} min down a year")
print(f" Target {r.target}: the hop {r.verdict(avail, r.target)}")
$ bogo run radio_link.bogo
Hop site-a to site-b: 12km at 18GHz, vertical polarization Free-space loss 139.137dB First Fresnel zone 7.069m radius at mid-hop Received level -47.137dBm Fade margin 22.863dB Rain fade (0.01%) 23.855dB at 42.0 mm/h Availability (rain) 99.989pct, about 59 min down a year Target 99.99pct: the hop misses the target
edition 2027
"""Would the access list on the internet uplink let these flows in? Reads a saved configuration."""
class AclTest:
"""Ask the list OUTSIDE-IN about a few flows and print each answer with the line
that decided it. When the test cannot be sure, it says so and names the line."""
config_file: str = "edge-rt1.cfg"
list_name: str = "OUTSIDE-IN"
# name, source, destination, protocol, destination port (0 when there is none)
flows: list[tuple[str, IP, IP, str, int]] = [
("web", 203.0.113.50, 198.51.100.10, "tcp", 443),
("dns", 203.0.113.50, 198.51.100.20, "udp", 53),
("sip from a blocked range", 192.0.2.10, 198.51.100.30, "tcp", 5060),
("sip", 203.0.113.60, 198.51.100.30, "tcp", 5061),
("voice media", 203.0.113.60, 198.51.100.30, "udp", 16000),
("ntp", 203.0.113.60, 198.51.100.99, "udp", 123),
("ssh to the web server", 203.0.113.60, 198.51.100.10, "tcp", 22),
("ping the web server", 203.0.113.60, 198.51.100.10, "icmp", 0),
]
@staticmethod
def ask(rules: Acl, src: IP, dst: IP, protocol: str, port: int) -> tuple[str, str]:
"""The answer in one word, and the line that decided or the reason there is no answer."""
try:
v: Verdict = rules.permits(src, dst, port=port, protocol=protocol)
except AclError as e:
return "CANNOT SAY", str(e)
return ("permitted" if v else "denied"), (
f"line {v.number}: {v.line}" if v.number else v.line
)
@staticmethod
def main(args: list[str]) -> None:
cfg: Config = load_config(AclTest.config_file, platform="iosxe")
rules: Acl = acl(cfg, AclTest.list_name)
print(f"{rules.name} on {cfg.hostname}: {len(rules.lines)} lines")
rows: list[dict[str, str]] = []
for name, src, dst, protocol, port in AclTest.flows:
answer, why = AclTest.ask(rules, src, dst, protocol, port)
service: str = f"{protocol}/{port}" if port else protocol
rows.append(
{
"flow": name,
"from": str(src),
"to": str(dst),
"service": service,
"answer": answer,
"why": why,
}
)
table(rows)
$ bogo run acl_test.bogo
OUTSIDE-IN on edge-rt1: 8 lines flow from to service answer why ------------------------ ------------ ------------- --------- ---------- --------------------------------------------------------- web 203.0.113.50 198.51.100.10 tcp/443 permitted line 1: permit tcp any host 198.51.100.10 eq 443 dns 203.0.113.50 198.51.100.20 udp/53 permitted line 3: permit udp any host 198.51.100.20 eq domain sip from a blocked range 192.0.2.10 198.51.100.30 tcp/5060 denied line 4: deny ip 192.0.2.0 0.0.0.255 any log sip 203.0.113.60 198.51.100.30 tcp/5061 permitted line 5: permit tcp any host 198.51.100.30 range 5060 5061 voice media 203.0.113.60 198.51.100.30 udp/16000 permitted line 6: permit udp any host 198.51.100.30 range 10000 20000 ntp 203.0.113.60 198.51.100.99 udp/123 denied implicit deny ssh to the web server 203.0.113.60 198.51.100.10 tcp/22 CANNOT SAY The access-list test does not understand 'established' in this line: permit tcp any any established
Get started
From an empty folder to a program that runs, checks and passes its tests.
OpenDownload
One installer for Windows, one for Linux. No administrator right, no internet.
OpenDocumentation
The language, every built-in command, and the reference of every name.
OpenExamples
Thirteen programs with saved answers. They run with no device and no network.
OpenThe shape of a program
Class based, as in Java
Every Bogolang program has the same shape, so any engineer can open a colleague's file and know where to look.
- All code stands inside a class
- The top of a file holds only the edition line, imports and classes. A function, an assignment or a loose line at the top is refused before the program runs.
- A program starts in main
- The start is the static method main of the class named after the file: link_check.bogo starts in class LinkCheck. The words typed after the file name arrive in args.
- Tests are classes too
- A test is a method whose name starts with test_, in a class whose name starts with Test. A program may carry its own tests, and bogo test runs them.
- Everything Python offers for classes stays
- Inheritance, decorators, @dataclass, Enum, Protocol, properties and class methods work as in Python.
edition 2027
"""Says which routers answer."""
class LinkCheck:
"""Pings each router twice."""
routers: list[IP] = [192.0.2.1, 192.0.2.2]
@staticmethod
def main(args: list[str]) -> None:
for r in LinkCheck.routers:
print(r, ping(r, count=2))
class TestLinkCheck:
def test_there_are_two_routers(self) -> None:
assert len(LinkCheck.routers) == 2
top.bogo:3:1: error: code must be inside a class
x = 1
^
Only imports and classes stand at the top of a file. Put this line in a method of a class.
Built in
The daily work of a network engineer, as commands of the language
No library to find, no wrapper to write. Each card opens the page that explains it.
Reach
Its own ping, ping_all, trace, tcping and scan, with size, "do not fragment" and DSCP.
Devices
Inventories, read-only SSH sessions, show commands as tables, SNMP, backups, snapshots before and after a work.
Changes
The change block: apply, rollback, verify. --dry shows what would be sent and sends nothing.
Configurations
The configuration as an object, audit rules, differences, templates.
Planning
Free subnets, overlaps, route lookup, an access-list test that never guesses.
Telecom
Radio link budgets, rain, fibre loss, Erlang, voice quality, optical readings.
Output
Tables, Excel, charts, Word and HTML reports, mail.
Watching
watch, alert when, and listeners for syslog, SNMP traps and NetFlow.
Other systems
Web APIs, Meraki, RESTCONF, the serial console.
Trying safely
--replay runs a program on saved answers and connects to nothing.
Safe by rule
Careful with the network, because a mistake there is costly
- Read-only by default
- Device sessions are read-only unless a change block says otherwise.
- No change without a rollback
- A change block with no rollback is refused before the program runs.
- No login in a file
- Logins are kept in the protected store of the system, never in a file.
- Try it with no device
- --dry prints each change and sends nothing. --replay answers from saved outputs.
change on d:
apply:
vlan {vid}
name {name}
interface {trunk}
switchport trunk allowed vlan add {vid}
rollback:
interface {trunk}
switchport trunk allowed vlan remove {vid}
no vlan {vid}
verify:
name in show("vlan brief")
str(vid) in show(f"interfaces {trunk} trunk")
$ bogo run --dry --replay saved change_vlan.bogo
DRY RUN: change on core-sw1. Nothing is sent.
apply:
vlan 30
name CAMERAS
interface GigabitEthernet1/0/2
switchport trunk allowed vlan add 30
rollback:
interface GigabitEthernet1/0/2
switchport trunk allowed vlan remove 30
no vlan 30
core-sw1: VLAN 30 would be added, nothing was sent
access-sw3: VLAN 30 is already there, nothing to do
The language
Python underneath, stricter on top
If you read Python, you read Bogolang. The rules it adds catch mistakes before a packet leaves the PC.
-
01
Values with a type
192.0.2.1, 10.40.0.0/16, 50ms and 18GHz are values with a type. Comparing a duration with a rate is a mistake.
-
02
Checked before it runs
A mistake in a type stops the program before it starts, with the line, the column and what to write.
-
03
Editions keep old programs working
An edition fixes the meaning of the language. A newer Bogolang runs every older edition with the meaning it had.
-
04
Every Python package keeps working
The Python 3.15 engine stays inside. Python packages are imported as they are.
- kinds of work built in
- 10
- documentation pages
- 20
- example programs
- 13
- systems: Windows and Linux
- 2
Examples
Programs that run on any PC
Each example comes with saved answers, so it runs with no device and no network.
Pings four hosts at once with ping_all, traces the path to one and scans a small network.
Read the program $ bogo run acl_test.bogoAsks an access list whether flows would pass, with the line that decided; it never guesses.
Read the program $ bogo run radio_link.bogoPlans a microwave hop: free-space loss, Fresnel zone, fade margin, rain and availability.
Read the programFrom an empty folder to a program that runs
Install Bogolang, then follow the first-program page. Its last step runs on saved answers and contacts no host.