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.1or2001:db8::1 - a text:
"192.0.2.1"(read as an address, no lookup) or"core-sw1.example.net"(a name, looked up first withresolve) - anything with an
.ip, such as aDevicefrom 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.
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:
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.
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.
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.
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.
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.
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.
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
dscpout.
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_allandscanuse thepingcommand 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_fragmentanddscphave no effect. tracesends 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_alluses the same files asping. - A host given by name needs its
resolvefile too. - A sign a file name may not hold is written
_: the answer of::1isping___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.