Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Joignabilité : ping, trace, scan et résolutions

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

Toutes les pages de documentation

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.1 ou 2001: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 avec resolve)
  • tout ce qui a un .ip, comme un Device de 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.

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 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 :

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

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.

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}")

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.

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]

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.

Bogolang
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.

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]

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.

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")

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.

Bogolang
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_all et scan utilisent la commande ping du 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_fragment et dscp n'ont aucun effet.
  • trace envoie à 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_all utilise les mêmes fichiers que ping.
  • 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 ::1 est ping___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.