Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Reach: ping, trace, scan and lookups

ping, ping_all, trace, tcping, resolve, scan.

All documentation pages

This page covers the commands that test whether hosts answer: ping, ping_all, tcping, trace, resolve, scan and vendor, with their results PingResult and Hop. It also says what works on Windows and on Linux, and how to run these commands on saved answers with no network.

The example reach_hosts uses most of them.

Where a command can send to

Every command here takes a host in one of three forms:

  • an address: 192.0.2.1 or 2001:db8::1
  • a text: "192.0.2.1" (read as an address, no lookup) or "core-sw1.example.net" (a name, looked up first with resolve)
  • anything with an .ip, such as a Device from the inventory (see devices.md)

A name that does not resolve stops the command with a ValueError that says so.

ping

ping(host, count=5, timeout=2s, size=56B, interval=1s, ttl=64, source=None,
     dont_fragment=False, dscp=0) -> PingResult

ping sends Bogolang's own echo packets. It does not start the ping program of the system (with one exception on Linux, below). A host that does not answer is not an error: the result says ok is false.

Bogolang
r: PingResult = ping(192.0.2.1)
if r.ok:
    print(f"192.0.2.1 answers in {r.avg}, loss {r.loss}")
else:
    print(f"192.0.2.1 does not answer: {r.reason or 'no reply'}")
Option Accepted Default Meaning
count 1 or more 5 Packets sent
timeout more than zero 2s Wait for each answer
size whole bytes, 0 to 65500 56B Bytes of data in each packet. size=112B and size=1472B are written as they are
interval 10ms or more 1s Gap between two packets
ttl 1 to 255 64 Hop limit of the packets
source an address of this machine None Send from this address. None lets the system choose
dont_fragment True or False False A packet too large for the path is not split. It counts as lost, and .reason says why
dscp 0 to 63 0 The DSCP mark on each packet. See the limits on Windows below

A wrong value is refused with a ValueError before anything is sent, and the sentence names the option:

ValueError: size must be a whole number of bytes from 0 to 65500, got 70000 B.

Some calls with options:

Bogolang
big: PingResult = ping(192.0.2.1, count=4, size=1472B, dont_fragment=True)
if not big.ok:
    print(big.reason)
voice: PingResult = ping(192.0.2.1, count=20, interval=200ms, dscp=46)
near: PingResult = ping(203.0.113.20, count=2, ttl=2, source=192.0.2.250)
print(voice.jitter, near.reason)

PingResult

Field Type Meaning
.ok bool At least one answer came back. bool(r) is the same
.sent, .received int Packets sent and answers received
.loss Percent Loss, rounded to one decimal. A loss that is not zero is never shown as zero
.min, .avg, .max Duration or None Answer times. None when nothing came back
.jitter Duration or None The average change between one answer time and the next. Answers of 1, 3 and 1 ms give 2 ms. None with fewer than two answers
.times list[Duration] The time of each answer, in the order sent. A lost packet has no entry
.host IP or None The address that was pinged
.reason str Empty, or why packets were lost when something said why

Printed, a result is one line:

3 sent, 2 received, 33.3% loss, min/avg/max 2.1ms/2.35ms/2.6ms, jitter 0.5ms
3 sent, 0 received, 100% loss

When there is a reason, it is added at the end in brackets.

The reasons a ping gives

.reason is filled when the network or the system said why packets were lost. The first that applies is given:

Reason When
the packet is too large for the path and may not be split. dont_fragment=True and the packet does not fit. The path takes N bytes. follows when the system or a router gave the limit
the system refused to send: ... The operating system refused the packet, with its own words
ROUTER answered that the host cannot be reached A router sent "unreachable"
the hop limit ended at ROUTER The ttl ran out on the way

With no answer and no reason, .reason is empty. The run record then says no reply.

ping_all

ping_all(hosts, count=3, timeout=2s, size=56B, interval=200ms, ttl=64, source=None,
         dont_fragment=False, dscp=0) -> list[PingResult]

ping_all pings every host at the same time, from one process, and gives one result per host in the order of the list. Each result carries its .host. The same host written twice is pinged once and gives two equal results. The options are those of ping; only count and interval have other defaults.

Bogolang
hosts: list[IP] = [192.0.2.1, 192.0.2.10, 198.51.100.7]
for r in ping_all(hosts, count=3, timeout=1s):
    print(f"{r.host}: {r}")

A list of devices works too: ping_all(inventory("devices.csv")).

Where hosts do not answer, ping_all waits about once for all of them, not once per host. Hosts are sent to in groups of at most 1024.

tcping

tcping(host, port, timeout=2s) -> bool

True when a TCP connection to the port opens. It works where ICMP is blocked. The port must be 1 to 65535.

Bogolang
if not tcping(192.0.2.1, 22, timeout=1s):
    print("SSH does not open on 192.0.2.1")

trace

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

The path to a host, hop by hop. max_hops is 1 to 255 and probes (probes per hop) is 1 to 10. The trace stops at the hop where the host answers, or at a hop where a router answers that the host cannot be reached.

Bogolang
for hop in trace(203.0.113.20, max_hops=10, probes=2):
    print(hop)

Hop

Field Type Meaning
.number int The hop, from 1
.ip IP or None The first router that answered at this hop. None when none did
.ips list[IP] Every router that answered at this hop, each once
.rtt, .avg Duration or None The average time of the answers
.min, .max Duration or None The shortest and longest answer
.sent, .received int Probes sent and answered
.loss Percent Lost probes at this hop

Printed, a hop is one line, with * for what is missing. The loss is shown when more than one probe was sent:

3  *  *  100% loss
4  198.51.100.65  40.95ms  0% loss

resolve

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

A name gives its addresses, an empty list when the name does not exist. An address gives its name, an empty text when it has none. The checker knows which one you get.

Bogolang
addresses: list[IP] = resolve("core-sw1.example.net")
name: str = resolve(192.0.2.1)
print(addresses, name or "no name")

scan

scan(net, allow_large=False, port=None) -> list[IP]

The addresses of a subnet that answer, in order. Without port, each address gets one ping with a wait of 2 seconds, all at the same time. With port, each address gets a TCP check of that port instead.

Bogolang
up: list[IP] = scan(192.0.2.0/28)
ssh_up: list[IP] = scan(192.0.2.0/28, port=22)
print(f"{len(up)} answer, {len(ssh_up)} open SSH")

A subnet of more than 1024 addresses (larger than a /22) is refused unless you write allow_large=True:

ValueError: 10.0.0.0/16 is larger than a /22. A wide scan can trip security monitoring. If you mean it, write scan(net, allow_large=True).

vendor

vendor(mac) -> str

The maker of a MAC address, from the public IEEE list carried inside Bogolang. Empty text when the prefix is not in the list. It reads no network.

Bogolang
maker: str = vendor(00:1a:2b:3c:4d:5e)
print(maker or "unknown maker")

Windows and Linux

Windows Linux
ping, ping_all, scan The ICMP interface of Windows, the one its own ping uses. No administrator right needed The ICMP socket for ordinary users. No administrator right needed
trace The same interface, with a rising hop limit. IPv6 too Echo probes on the same socket as ping, with a rising hop limit
A DSCP mark on ping, ping_all IPv4 only, sent through a raw socket IPv4 and IPv6
A DSCP mark on trace Refused Works

Refused on Windows

Each of these is refused with one sentence, before anything is sent, also under --replay:

  • trace(..., dscp=N) with N other than 0: the ICMP interface of Windows drops the mark.
ValueError: On Windows, trace cannot put a DSCP mark on its probes: the ICMP interface of Windows drops the mark. Leave dscp out here, or run this on Linux.
  • A ping with a DSCP mark to an IPv6 address.
  • A ping with a DSCP mark on a PC where Windows refuses a raw socket to the user. Run it as an administrator, or leave dscp out.

With dont_fragment=True Windows refuses a packet that is too large, but does not say the limit of the path. Linux gives it when a router does.

A Linux that refuses the ICMP socket

Some Linux systems keep the ICMP socket from ordinary users, by the setting net.ipv4.ping_group_range. The Linux installer offers to open it once, with the administrator password (see install.md). When it stays closed:

  • ping, ping_all and scan use the ping command of the system, and print this note once per run, with the command that opens the setting:
bogo: this system does not allow Bogolang's own ping to this user, so the ping command of the system is used.
      To allow it, an administrator runs once: sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
  • On that way, size, interval, ttl, source, dont_fragment and dscp have no effect.
  • trace sends UDP probes instead, which need no setting. Many hosts and firewalls answer an echo but stay silent to a UDP probe, so such a trace may not reach its end.

Saved answers: --replay and --save-replay

Every command on this page can run with no network. bogo run --save-replay FOLDER keeps each answer in FOLDER/reach, and bogo run --replay FOLDER reads it back and sends nothing. bogo test reads saved answers the same way (see tools.md).

bogo run --replay saved reach_hosts.bogo

Run in the folder of the example, this gives:

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

One file per command and target. The files are plain text, so a test can use a file written by hand:

Call File in FOLDER/reach What it holds
ping(192.0.2.1) ping_192.0.2.1.txt {"sent": 3, "times_ms": [1.2, null, 1.1], "reason": ""}, with null for a lost packet
trace(203.0.113.20) trace_203.0.113.20.txt {"hops": [[["192.0.2.1", 1.1], ["", null]], ...]}: for each hop, for each probe, who answered and in how many milliseconds
tcping(192.0.2.1, 22) tcping_192.0.2.1_port_22.txt open or closed
resolve("core-sw1.example.net") resolve_core-sw1.example.net.txt The addresses, one per line
resolve(192.0.2.1) resolve_192.0.2.1.txt The name
scan(192.0.2.0/29) scan_192.0.2.0_29.txt The addresses that answered, one per line
scan(192.0.2.0/29, port=22) scan_192.0.2.0_29_port_22.txt The same

Rules of the saved answers:

  • One answer per target. The count and the timeout are not in the file name, so a host pinged three times gets the same answer three times. ping_all uses the same files as ping.
  • A host given by name needs its resolve file too.
  • A sign a file name may not hold is written _: the answer of ::1 is ping___1.txt.
  • A ping or trace file in the text of the system's own tool, as older versions saved, is still read.
  • A missing file stops the command and names the file needed:
RuntimeError: Replay mode has no saved answer for tcping 192.0.2.1 port 443. The file needed is ...\saved\reach\tcping_192.0.2.1_port_443.txt.
  • A file that is neither form is refused as damaged, with a sentence that says to save it again.

The run record

Each call writes one line to the run record, which bogo run --record prints at the end (see devices.md).

Call Device column Command column Marked not ok when
ping, ping_all the address ping no reply, or the reason
tcping(h, 22) the address tcping port 22 the port did not open
trace the address trace the command itself failed
resolve the name or address resolve the name does not exist, or the address has no name
scan the subnet scan or scan port N the command itself failed

A ping with no reply is marked not ok, but the program goes on: ping still gives its result. A host given by name writes two lines, the lookup and the ping. A mistake of the program, such as a port out of range, writes no line: nothing was sent.

Not proven

Tried on Windows and Linux to the machine itself, and on one real path to a public address (a trace of 9 hops, a ping with a short hop limit, "do not fragment"). Not tried:

  • a router that says "cannot be reached"
  • answers from another machine through the Windows firewall
  • IPv6 beyond the machine itself (::1)
  • a DSCP-marked ping through a raw socket on a Windows PC other than the one it was built on

See not-proven.md for the whole list.