Cette page présente les commandes qui testent si des hôtes répondent : ping, ping_all,
tcping, trace, resolve, scan et vendor, avec leurs résultats PingResult et Hop.
Elle indique aussi ce qui fonctionne sous Windows et sous Linux, et comment exécuter ces
commandes sur des réponses enregistrées, sans réseau.
L'exemple reach_hosts utilise la plupart d'entre elles.
Vers quoi une commande peut envoyer
Chaque commande de cette page accepte un hôte sous l'une de trois formes :
- une adresse :
192.0.2.1ou2001:db8::1 - un texte :
"192.0.2.1"(lu comme une adresse, sans résolution) ou"core-sw1.example.net"(un nom, d'abord résolu avecresolve) - tout ce qui a un
.ip, comme unDevicede l'inventaire (voir devices.md)
Un nom qui ne se résout pas arrête la commande avec une ValueError qui le dit.
ping
ping(host, count=5, timeout=2s, size=56B, interval=1s, ttl=64, source=None,
dont_fragment=False, dscp=0) -> PingResult
ping envoie les propres paquets d'écho de Bogolang. Elle ne lance pas le programme ping du
système (avec une exception sous Linux, voir plus bas). Un hôte qui ne répond pas n'est pas une
erreur : le résultat indique que ok est faux.
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 | Accepté | Par défaut | Signification |
|---|---|---|---|
count |
1 ou plus | 5 | Paquets envoyés |
timeout |
plus de zéro | 2s |
Attente de chaque réponse |
size |
octets entiers, de 0 à 65500 | 56B |
Octets de données dans chaque paquet. size=112B et size=1472B s'écrivent tels quels |
interval |
10ms ou plus |
1s |
Écart entre deux paquets |
ttl |
de 1 à 255 | 64 | Limite de sauts des paquets |
source |
une adresse de cette machine | None |
Envoyer depuis cette adresse. None laisse le système choisir |
dont_fragment |
True ou False |
False |
Un paquet trop grand pour le chemin n'est pas découpé. Il compte comme perdu, et .reason dit pourquoi |
dscp |
de 0 à 63 | 0 | La marque DSCP de chaque paquet. Voir les limites sous Windows plus bas |
Une valeur fausse est refusée avec une ValueError avant tout envoi, et la phrase nomme
l'option :
ValueError: size must be a whole number of bytes from 0 to 65500, got 70000 B.
Quelques appels avec des 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
| Champ | Type | Signification |
|---|---|---|
.ok |
bool |
Au moins une réponse est revenue. bool(r) est équivalent |
.sent, .received |
int |
Paquets envoyés et réponses reçues |
.loss |
Percent |
Perte, arrondie à une décimale. Une perte qui n'est pas nulle n'est jamais affichée comme nulle |
.min, .avg, .max |
Duration ou None |
Temps de réponse. None quand rien n'est revenu |
.jitter |
Duration ou None |
La variation moyenne entre un temps de réponse et le suivant. Des réponses de 1, 3 et 1 ms donnent 2 ms. None avec moins de deux réponses |
.times |
list[Duration] |
Le temps de chaque réponse, dans l'ordre d'envoi. Un paquet perdu n'a pas d'entrée |
.host |
IP ou None |
L'adresse qui a reçu le ping |
.reason |
str |
Vide, ou la raison de la perte des paquets quand quelque chose l'a indiquée |
Affiché, un résultat tient sur une ligne :
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
Quand il y a une raison, elle est ajoutée à la fin entre parenthèses.
Les raisons qu'un ping donne
.reason est rempli quand le réseau ou le système a dit pourquoi des paquets ont été perdus.
La première raison qui s'applique est donnée :
| Raison | Quand |
|---|---|
the packet is too large for the path and may not be split. |
dont_fragment=True et le paquet ne passe pas. The path takes N bytes. suit quand le système ou un routeur a donné la limite |
the system refused to send: ... |
Le système d'exploitation a refusé le paquet, avec ses propres mots |
ROUTER answered that the host cannot be reached |
Un routeur a envoyé « unreachable » |
the hop limit ended at ROUTER |
Le ttl s'est épuisé en chemin |
Sans réponse et sans raison, .reason est vide. Le journal d'exécution indique alors
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 envoie un ping à chaque hôte en même temps, depuis un seul processus, et donne un
résultat par hôte dans l'ordre de la liste. Chaque résultat porte son .host. Le même hôte
écrit deux fois reçoit un seul ping et donne deux résultats égaux. Les options sont celles de
ping ; seuls count et interval ont d'autres valeurs par défaut.
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}")
Une liste d'équipements fonctionne aussi : ping_all(inventory("devices.csv")).
Là où des hôtes ne répondent pas, ping_all attend environ une fois pour tous, et non une fois
par hôte. Les envois se font par groupes de 1024 hôtes au plus.
tcping
tcping(host, port, timeout=2s) -> bool
Vrai quand une connexion TCP vers le port s'ouvre. Fonctionne là où ICMP est bloqué. Le port doit être compris entre 1 et 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]
Le chemin vers un hôte, saut par saut. max_hops va de 1 à 255 et probes (sondes par saut)
de 1 à 10. La trace s'arrête au saut où l'hôte répond, ou à un saut où un routeur répond que
l'hôte ne peut pas être joint.
for hop in trace(203.0.113.20, max_hops=10, probes=2):
print(hop)
Hop
| Champ | Type | Signification |
|---|---|---|
.number |
int |
Le saut, à partir de 1 |
.ip |
IP ou None |
Le premier routeur qui a répondu à ce saut. None quand aucun n'a répondu |
.ips |
list[IP] |
Chaque routeur qui a répondu à ce saut, une fois chacun |
.rtt, .avg |
Duration ou None |
Le temps moyen des réponses |
.min, .max |
Duration ou None |
La réponse la plus courte et la plus longue |
.sent, .received |
int |
Sondes envoyées et sondes ayant reçu une réponse |
.loss |
Percent |
Sondes perdues à ce saut |
Affiché, un saut tient sur une ligne, avec * pour ce qui manque. La perte est affichée quand
plus d'une sonde a été envoyée :
3 * * 100% loss
4 198.51.100.65 40.95ms 0% loss
resolve
resolve(target) -> list[IP] | str
Un nom donne ses adresses, une liste vide quand le nom n'existe pas. Une adresse donne son nom, un texte vide quand elle n'en a pas. Le vérificateur sait lequel des deux vous obtenez.
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]
Les adresses d'un sous-réseau qui répondent, dans l'ordre. Sans port, chaque adresse reçoit un
ping avec une attente de 2 secondes, toutes en même temps. Avec port, chaque adresse reçoit à
la place une vérification TCP de ce port.
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")
Un sous-réseau de plus de 1024 adresses (plus grand qu'un /22) est refusé, sauf si vous écrivez
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
Le fabricant d'une adresse MAC, d'après la liste publique de l'IEEE embarquée dans Bogolang. Texte vide quand le préfixe n'est pas dans la liste. Cette commande ne lit aucun réseau.
maker: str = vendor(00:1a:2b:3c:4d:5e)
print(maker or "unknown maker")
Windows et Linux
| Windows | Linux | |
|---|---|---|
ping, ping_all, scan |
L'interface ICMP de Windows, celle qu'utilise son propre ping. Aucun droit d'administrateur nécessaire |
Le socket ICMP pour les utilisateurs ordinaires. Aucun droit d'administrateur nécessaire |
trace |
La même interface, avec une limite de sauts croissante. IPv6 aussi | Des sondes d'écho sur le même socket que ping, avec une limite de sauts croissante |
Une marque DSCP sur ping, ping_all |
IPv4 seulement, envoyée par un socket brut | IPv4 et IPv6 |
Une marque DSCP sur trace |
Refusée | Fonctionne |
Refusé sous Windows
Chacun de ces cas est refusé avec une phrase, avant tout envoi, également sous --replay :
trace(..., dscp=N)avec N différent de 0 : l'interface ICMP de Windows supprime la marque.
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.
- Un ping avec une marque DSCP vers une adresse IPv6.
- Un ping avec une marque DSCP sur un PC où Windows refuse un socket brut à l'utilisateur.
Exécutez-le en tant qu'administrateur, ou retirez
dscp.
Avec dont_fragment=True, Windows refuse un paquet trop grand, mais n'indique pas la limite du
chemin. Linux la donne quand un routeur la donne.
Un Linux qui refuse le socket ICMP
Certains systèmes Linux interdisent le socket ICMP aux utilisateurs ordinaires, par le réglage
net.ipv4.ping_group_range. L'installateur Linux propose de l'ouvrir une fois, avec le mot de
passe administrateur (voir install.md). Quand il reste fermé :
ping,ping_alletscanutilisent la commandepingdu système, et affichent cette note une fois par exécution, avec la commande qui ouvre le réglage :
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"
- Dans ce mode,
size,interval,ttl,source,dont_fragmentetdscpn'ont aucun effet. traceenvoie à la place des sondes UDP, qui ne demandent aucun réglage. Beaucoup d'hôtes et de pare-feu répondent à un écho mais restent muets face à une sonde UDP, donc une telle trace peut ne pas atteindre sa fin.
Réponses enregistrées : --replay et --save-replay
Chaque commande de cette page peut s'exécuter sans réseau. bogo run --save-replay FOLDER
conserve chaque réponse dans FOLDER/reach, et bogo run --replay FOLDER la relit et n'envoie
rien. bogo test lit les réponses enregistrées de la même façon (voir tools.md).
bogo run --replay saved reach_hosts.bogo
Exécuté dans le dossier de l'exemple, cela donne :
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
Un fichier par commande et par cible. Les fichiers sont en texte brut, donc un test peut utiliser un fichier écrit à la main :
| Appel | Fichier dans FOLDER/reach |
Ce qu'il contient |
|---|---|---|
ping(192.0.2.1) |
ping_192.0.2.1.txt |
{"sent": 3, "times_ms": [1.2, null, 1.1], "reason": ""}, avec null pour un paquet perdu |
trace(203.0.113.20) |
trace_203.0.113.20.txt |
{"hops": [[["192.0.2.1", 1.1], ["", null]], ...]} : pour chaque saut, pour chaque sonde, qui a répondu et en combien de millisecondes |
tcping(192.0.2.1, 22) |
tcping_192.0.2.1_port_22.txt |
open ou closed |
resolve("core-sw1.example.net") |
resolve_core-sw1.example.net.txt |
Les adresses, une par ligne |
resolve(192.0.2.1) |
resolve_192.0.2.1.txt |
Le nom |
scan(192.0.2.0/29) |
scan_192.0.2.0_29.txt |
Les adresses qui ont répondu, une par ligne |
scan(192.0.2.0/29, port=22) |
scan_192.0.2.0_29_port_22.txt |
La même chose |
Règles des réponses enregistrées :
- Une réponse par cible. Le nombre de paquets et le délai d'attente ne figurent pas dans le nom
du fichier, donc un hôte qui reçoit trois pings obtient trois fois la même réponse.
ping_allutilise les mêmes fichiers queping. - Un hôte donné par son nom a aussi besoin de son fichier
resolve. - Un signe qu'un nom de fichier ne peut pas contenir s'écrit
_: la réponse de::1estping___1.txt. - Un fichier de ping ou de trace au format texte de l'outil propre du système, tel que les anciennes versions l'enregistraient, est toujours lu.
- Un fichier manquant arrête la commande et nomme le fichier nécessaire :
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.
- Un fichier qui n'a aucune des deux formes est refusé comme endommagé, avec une phrase qui dit de l'enregistrer à nouveau.
Le journal d'exécution
Chaque appel écrit une ligne dans le journal d'exécution, que bogo run --record affiche à la
fin (voir devices.md).
| Appel | Colonne Device | Colonne Command | Marqué non ok quand |
|---|---|---|---|
ping, ping_all |
l'adresse | ping |
pas de réponse, ou la raison |
tcping(h, 22) |
l'adresse | tcping port 22 |
le port ne s'est pas ouvert |
trace |
l'adresse | trace |
la commande elle-même a échoué |
resolve |
le nom ou l'adresse | resolve |
le nom n'existe pas, ou l'adresse n'a pas de nom |
scan |
le sous-réseau | scan ou scan port N |
la commande elle-même a échoué |
Un ping sans réponse est marqué non ok, mais le programme continue : ping donne quand même son
résultat. Un hôte donné par son nom écrit deux lignes, la résolution et le ping. Une erreur du
programme, comme un port hors plage, n'écrit aucune ligne : rien n'a été envoyé.
Non prouvé
Essayé sous Windows et Linux vers la machine elle-même, et sur un vrai chemin vers une adresse publique (une trace de 9 sauts, un ping avec une limite de sauts courte, « ne pas fragmenter »). Non essayé :
- un routeur qui dit « ne peut pas être joint »
- des réponses d'une autre machine à travers le pare-feu de Windows
- IPv6 au-delà de la machine elle-même (
::1) - un ping marqué DSCP par un socket brut sur un PC Windows autre que celui sur lequel il a été construit
Voir not-proven.md pour la liste complète.