pingpath.1

.Dd $Mdocdate$
.Dt PINGPATH 1 URM
.Os
.Sh NAME
.Nm pingpath
.Nd ping wrapper for network diagnostic
.Sh SYNOPSIS
.Nm
.Op Fl AcfgGhiILnpPqrRsStTvVX1246
.Sy [ TARGET ]
.Sh DESCRIPTION
Network diagnostic tool based on parsing iputils
.Sy ping
output with functionality of
.Sy traceroute .
.br
No need set-root-uid or raw-socket-perms itself to run due to being a wrapper for ping.
.br
Inspired by ncurses look of
.Sy mtr
and written in
.Sy GTK4 .
.Pp
What it displays:
.Bl -tag -width Ds
.ad l
- Hop hostnames taken by DNS back resolving (see\~https://docs.gtk.org/gio/class.Resolver.html)
.br
- Whois lookup data received by querying RIPE whois (see\~http://www.ripe.net/ris/riswhois.html)
.br
- Statistics calculated on data from iputils-ping output (see\~ping(8)\~manual)
.br
- Graphs and 3D plots providing visual representation at runtime
.El
.br
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl f, Fl -file Ar FILENAME
Read options from ini file.
.It Fl c, Fl -cycles Ar NUMBER
Run
.Ar number
of cycles per target.
.br
Default
.Ar 100
.It Fl i, Fl -interval Ar SECONDS
Interval in
.Ar seconds
between pings.
.br
Default
.Ar 1
.It Fl n, Fl -numeric
Numeric output (i.e. disable DNS resolving).
.br
Default
.Ar symbolic
.It Fl p, Fl -payload Ar PATTERN
Payload
in hex notation, upto 16 bytes (32 hex characters).
.br
Default
.Ar 00
.It Fl q, Fl -qos Ar BITS
QoS/ToS
.Ar byte
(0..255) in outgoing pings.
.br
Default
.Ar 0
.It Fl s, Fl -size Ar BYTES
Payload
.Ar size ,
minimum is 16 (timestamp size), maximum is 9000-20-8.
.br
Default
.Ar 56
.It Fl t, Fl -ttl Ar MIN,MAX
TTL
.Ar range
to ping, it can be partially set as
.Ar MIN
or
.Ar MIN,MAX
or
.Ar ,MAX
.br
Default
.Ar 1,30
.It Fl I, Fl -info Ar KEYS
Hop info elements which match
.Ar hacdr
pattern.
.br
Keys stand for:
.Bl -tag -offset Ds -compact
.It Cm h
Host
.It Cm a
AS
.It Cm c
CC
.It Cm d
Description
.It Cm r
Route
.El
Default
.Ar hac
.br
Note: duplicates in output are marked with '*'
.El
.Bl -tag -width Ds
.It Fl S, Fl -stat Ar KEYS
Display statistic elements which match
.Ar lsrmbwaj
pattern.
.br
Keys stand for:
.Bl -tag -offset Ds -compact
.It Cm l
Loss
.It Cm s
Sent
.It Cm r
Received
.It Cm m
Last(Msec)
.It Cm b
Best
.It Cm w
Worst
.It Cm a
Average
.It Cm j
Jitter
.El
Default
.Ar lsmbwaj
.El
.Bl -tag -width Ds
.It Fl T, Fl -theme Ar BITS
Toggle dark/light themes according to
.Ar bits :
.Bl -tag -offset Ds -compact
.It Cm 1st
Main theme
.It Cm 2nd
Graph theme
.It Cm 3rd
Graphs with legend
.It Cm 4th
3D-plot theme
.El
Default
.Ar 5
(dark main, light graph, graph legend, light plot)
.br
Note: bit value 1 corresponds to `dark' or `on'
.El
.Bl -tag -width Ds
.It Fl g, Fl -graph Ar TYPE
Draw graphs of
.Ar type :
.Bl -tag -offset Ds -compact
.It Cm 1
Just dots
.It Cm 2
Straight line
.It Cm 3
Curved spline
.El
Default
.Ar 3
.El
.Bl -tag -width Ds
.It Fl G, Fl -extra Ar KEYS
Display extra elements on graphs according to
.Ar keys :
.Bl -tag -offset Ds -compact
.It Cm l
Average line
.It Cm r
Jitter range
.It Cm a
Jitter area
.El
Default
.Ar none
.El
.Bl -tag -width Ds
.It Fl L, Fl -legend Ar KEYS
Display graph legend and its fields according to
.Ar keys :
.Bl -tag -offset Ds -compact
.It Cm d
Field "Average Delay ± Jitter"
.It Cm c
Field "Country Code : AS Number"
.It Cm h
Field "Hopname"
.El
Default
.Ar all
.El
.Bl -tag -width Ds
.It Fl P, Fl -plot Ar KEYS
Which parts of 3D-plot to display
.Bl -tag -offset Ds -compact
.It Cm b
Backside with grid
.It Cm a
Axes with marks
.It Cm g
Grid on surface
.It Cm r
Rotator
.El
Default
.Ar all
.El
.Bl -tag -width Ds
.It Fl X, Fl -extra-params Ar PAIRS
3D-plot extra parameters tagged with characters
.Bl -tag -offset Ds -compact
.It Cm r
Red surface gradient
.It Cm g
Green surface gradient
.It Cm b
Blue surface gradient
.It Cm o
Orientation and rotation
.It Cm f
Field of view
.El
Default
.Ar r=77:77,g=230:77,b=77:230,o=1:0:-20:0:5,f=45
.br
Note: \fBrgb\fR colors are in range from 0 to 255
.br
.in +.6i
r\fBo\fRtation parameters are set with space:xaxis:yaxis:zaxis:step, where
.br
.in
.in +.9i
global space is set with 1, local is 0
.br
orientation angles are from -180 to 180
.br
rotation step is in range from 1 to 180
.in
.br
.in +.6i
\fBf\fRield-of-view in range from 30 to 90 in degrees
.in
.El
.Bl -tag -width Ds
.It Fl r, Fl -recap Ar TYPE
Run non-interactively and print summary at exit:
.Bl -tag -offset Ds -compact
.It Cm t
Simple text
.It Cm c
CSV delimited with a semicolon
.It Cm J
Pretty printed JSON
.It Cm j
More numeric JSON
.El
Default
.Ar none
.El
.Bl -tag -width Ds
.It Fl R, Fl -run
Autostart from CLI (if ping target is set)
.It Fl A, Fl -active-tab
Active tab at start
.Bl -tag -offset Ds -compact
.It Cm 1
Ping
.It Cm 2
Graph
.It Cm 3
Plot
.El
Default
.Ar 1
.El
.Bl -tag -width Ds
.It Fl v, Fl -verbose Ar LEVEL
Print debug messages to stdout according to bits of
.Ar level :
.Bl -tag -offset Ds -compact
.It Cm 1st
(1)  main log
.It Cm 2nd
(2)  common debug
.It Cm 3rd
(4)  dns
.It Cm 4th
(8)  whois
.It Cm 5th
(16) config
.It Cm 6th
(32) reorder and dnd
.El
Default
.Ar none
.El
.Bl -tag -width Ds
.It Fl V, Fl -version
Print app and runtime lib versions
.It Fl 1, Fl -pingtab-only
With ping tab only
.It Fl 2, Fl -without-plot
Without plot tab
.It Fl 4, Fl -ipv4
IPv4 only
.It Fl 6, Fl -ipv6
IPv6 only
.El
.Sh KEYBOARD SHORTCUTS
For common actions:
.Bl -tag -offset Ds -compact
.It Cm Ctrl+S
Start/Stop pings
.It Cm Space
Pause/Resume visual updates
.It Cm Ctrl+R
Reset statistics
.It Cm Ctrl+L
Toggle graph legend on/off
.It Cm Ctrl+H
Display help
.It Cm Ctrl+X
Exit
.It Cm Ctrl+Left, Keypad Left
Axis-Y minus, Yaw Left
.It Cm Ctrl+Right, Keypad Right
Axis-Y plus,  Yaw Right
.It Cm Ctrl+Up, Keypad Up
Axis-X minus, Roll Clockwise (Up)
.It Cm Ctrl+Down, Keypad Down
Axis-X plus,  Roll Contra (Down)
.It Cm Ctrl+PgUp, Keypad Begin/PgUp/PgDn
Axis-Z minus, Pitch Up (Clockwise)
.It Cm Ctrl+PgDn, Keypad Home/End
Axis-Z plus,  Pitch Down (Contra)
.It Cm Ctrl+Home, Keypad Subtract
Scale Down
.It Cm Ctrl+End, Keypad Add
Scale Up
.El
.Sh DRAG-N-DROP
 Items that can be reordered ot relocated:
.Bl -tag -offset Ds -compact
.It Cm Notebook tabs
.It Cm Info fields
.It Cm Stat fields
.It Cm Graph legend
.It Cm Plot rotator
.El
.Bl -tag -width Ds
.Sh KNOWN CAVEATS
RTT for transit hops is calculated from TIMESTAMPS generated by
.Sy ping
for
.Sy no-answer-yet
and
.Sy time-to-live-exceeded
diagnostic messages.
Jitter used here is the simple average difference between two consecutive RTTs for depicting the range in which they vary.
So that use
.Sy traceroute
or
.Sy mtr
for more accurate measures of transit hops and statistics.
.sp 1
On whois data: if there are multiple sources despite -m flag in query, it displays the last tags (marked with '*').
.El
.El
.Sh PROJECT LOCATION
.Lk https://github.com/yvs2014/pingpath
.El
.Sh SEE ALSO
ping(8), traceroute(8), mtr(8)