Package: connvitals
Checks a machine’s connection to a specific host or list of hosts in
terms of packet loss, icmp latency, routing, and anything else that
winds up getting added.Note: Does not recognize duplicate hosts passed on ``argv`` and will
test each as though unique.Note: Under normal execution conditions, requires super-user privileges
to run.DependenciesThe utility runs on Python 3 (tested 3.6.3), but requires no
non-standard external modules.However, in most cases you will needsetuptoolsafter installation,
and if you are using an older version of Python (< 3.5) then you will
need to install the backport oftyping. These should be handled for
you if you are using an.rpmfile orpipto installconnvitals.InstallationBinary packagesBinary packages are offered in.rpmformat for Fedora/CentOS/RHEL
and.whlformat for all other operating systems under
‘Releases’.Viapip(standard)By far the simplest way to install this package is to simply usepiplike so:pip install connvitalsNote that it’s likely you’ll need to either run this command as an
administrator (Windows), withsudo(Everything Else), or with the--useroption (Everything Including Windows).Viapip(From This Repository)If for some reason the standard python package index is unavailable to
you, you can install directly from this repository without needing to
manually download it by runninguser@hostname~$pipinstallgit+https://github.com/connvitals.git#egg=connvitalsNote that you may need to run this command as root/withsudoor with--user, depending on yourpipinstallation. Also ensure thatpipis installing packages for Python 3.x. Typically, if both
Python2 and Python3 exist on a system withpipinstalled for both,
thepipto use for Python3 packages is accessible aspip3.ManuallyTo install manually, first download or clone this repository. Then, in
the directory you downloaded/cloned it into, run the commanduser@hostname~/connvitals$pythonsetup.pyinstallNote that it’s highly likely that you will need to run this command as
root/withsudo. Also ensure that thepythoncommand points to
a valid Python3 interpreter (you can check withpython--version).
On many systems, it is common forpythonto point to a Python2
interpreter. If you have both Python3 and Python2 installed, it’s
common that they be accessible aspython3andpython2,
respectively.Finally, if you are choosing this option because you do not have a
Python3pipinstallation, you may not havesetuptoolsinstalled. On most ‘nix distros, this can be installed without
installingpipby runningsudoapt-getinstallpython3-setuptools(Debian/Ubuntu),sudo pacman-Spython3-setuptools(Arch),sudo yum installpython3-setuptools(RedHat/Fedora/CentOS), orbrew installpython3-setuptools(macOS withbrewinstalled).Usageconnvitals[-h--help][-V--version][-H--hopsHOPS][-p--pingsPINGS][-P--no-ping][-t--trace][--payload-sizePAYLOAD][-s--port-scan]host[hosts...]hosts- The host or hosts to check connection to. May be ipv4
addresses, ipv6 addresses, fqdn’s, or any combination thereof.-hor--help- Prints help text, then exits successfully.-Vor--version- Prints the program’s version information,
then exits successfully.-Hor--hops- Sets max hops for route tracing (default 30).-por--pings- Sets the number of pings to use for aggregate
statistics (default 4).-Por--no-ping- Don’t run ping tests.-tor--trace- Run route tracing.-jor--json- Prints output as one line of JSON-formatted
text.-sor--port-scan- Perform a limited scan on each hosts’
ports.--payload-size- Sets the size (in B) of ping packet payloads
(default 41).Output FormatNormal OutputFor each host tested, results are printed in the newline-separated order
“host->Ping Results->Route Trace Results->Port Scan Results” where
“host” is the name of the host, as passed on argv. If the name passed
for a host onargvis not what ends up being used to test connection
vitals (e.g. the program may translategoogle.cominto216.58.218.206), then the “host” line will containhost-as-typed(host IP used).Ping tests output their results as a tab-separated list containing - in
this order - minimum round-trip time in milliseconds (rtt), mean rtt,
maximum rtt, rtt standard deviation, and packet loss in percent. If all
packets are lost, the min/mean/max/std are all reported as -1.Route traces output their results as a list of network hops, separated
from each other by newlines. Each network hop is itself a tab-separated
list of data containing - in this order - a network address for the
machine this hop ended at, and the rtt of a packet traversing this
route. If the packet was lost, a star (*) is shown instead of an
address and rtt.Port scans check for http(s) servers on ports 80 and 443, and MySQL
servers running on port 3306. It outputs its results as a tab-separated
list containing - in this order - port 80 results, port 443 results,
port 3306 results. Results for ports 80 and 443 consist of sending aHEAD / HTTP/1.1request and recording “rtt (in milliseconds),
response code, server” from the server’s response. “server” will be the
contents of the “Server” header if found within the first kilobyte of
the response, but if it is not found will simply be “Unknown”. Port 3306
results report the version of the MySQL server listening on that port if
one is found (Note that this version number may be mangled if the server
allows unauthenticated connection or supports some other automatic
authentication mechanism for the machine running connvitals). If a
server is not found on a port, its results are reported as “None”,
indicating no listening server. If a server on port 80 expects
encryption or a server on port 443 does not expect encryption, they will
be “erroneously” reported as not existing.Example Output (with localhost running mysql server):root@hostname/# connvitals -stp 100 google.com 2607:f8b0:400f:807::200e localhostgoogle.com(172.217.3.14)3.5434.95511.3681.4420.00010.169.240.13.10810.168.253.82.37310.168.254.2523.65910.168.255.2262.399198.178.8.943.05969.241.22.3351.10468.86.103.1316.47068.86.92.1215.48868.86.86.774.25768.86.83.63.946173.167.58.1425.290*216.239.49.2474.491172.217.3.143.92756.446,200,gws75.599,200,gwsNone2607:f8b0:400f:807::200e3.4464.44012.4221.5260.0002001:558:1418:49::18.8462001:558:3da:74::11.4532001:558:3da:6f::12.9552001:558:3da:1::22.4162001:558:3c2:15::12.6052001:558:fe1c:6::147.5162001:558:1c0:65::145.4422001:558:0:f71e::19.165**2001:559:0:9::63.984*2001:4860:0:1::10ad3.9702607:f8b0:400f:807::200e3.89157.706,200,gws77.736,200,gwsNonelocalhost(127.0.0.1)0.0450.2210.6650.1121.000127.0.0.10.351NoneNone0.165,5.7.2JSON Output FormatThe JSON output format option (-jor--json) will render the
output on one line. Each host is represented as an object, indexed by
itsaddress. This is not necessarily the same as the host as given
on the command line, which may be found as an attribute of the host,
named'name'.Results for ping tests are a dictionary attribute named'ping',
with floating point values labeled as'min','avg','max','std'and'loss'. As with all floating point numbers in json
output, these values arenot rounded or truncatedand are printed
exactly as calculated, to the greatest degree of precision afforded by
the system.Route traces are output as a list attribute, labeled'trace',
where each each step in the route is itself a list. The first element
in each list is either the address of the discovered host at that
point in the route, or the special string'*'which indicates the
packet was lost and no host was discovered at this point. The second
element, if it exists, is a floating point number giving the
round-trip-time of the packet sent at this step, in milliseconds. Once
again, unlike normal output format, these floating point numbersare
not rounded or truncatedand are printed exactly as calculated, to
the greatest degree of precision afforded by the system.Port scans are represented as a dictionary attribute named'scan'.
The label of each element of'scan'is the name of the server
checked for.'http'and'https'results will report a
dictionary of values containing:*'rtt'- the time taken for the server to respond*'response code'- The decimal representation of the server’s
response code to aHEAD / HTML/1.1request.*'server'- the name of the server, if found within the first
kilobyte of the server’s response, otherwise “Unknown”.'mysql'fields will also contain a dictionary of values, and that
dictionary should also contain the'rtt'field with the same
meaning as for'http'and'https', but will replace the other
two fields used by those protocols with'version', which will give
the version number of the MySQL server.If any of these three server types is not detected, the value of its
label will be the string ‘None’, rather than a dictionary of values.Example JSON Output (with localhost running mysql server):root@hostname/# sudo connvitals -j --port-scan -tp 100 google.com 2607:f8b0:400f:807::200e localhost{"addr":"172.217.3.14","name":"google.com","ping":{"min":3.525257110595703,"avg":4.422152042388916,"max":5.756855010986328,"std":0.47761748430602524,"loss":0.0},"trace":[["*"],["10.168.253.8",2.187013626098633],["10.168.254.252",4.266977310180664],["10.168.255.226",3.283977508544922],["198.178.8.94",2.7751922607421875],["69.241.22.33",3.7970542907714844],["68.86.103.13",3.8001537322998047],["68.86.92.121",7.291316986083984],["68.86.86.77",5.874156951904297],["68.86.83.6",4.465818405151367],["173.167.58.142",4.443883895874023],["*"],["216.239.49.231",4.090785980224609],["172.217.3.14",4.895925521850586]],"scan":{"http":{"rtt":59.095,"response code":"200","server":"gws"},"https":{"rtt":98.238,"response code":"200","server":"gws"},"mysql":"None"}}}{"addr":"2607:f8b0:400f:807::200e","name":"2607:f8b0:400f:807::200e","ping":{"min":3.62396240234375,"avg":6.465864181518555,"max":24.2769718170166,"std":5.133322111766303,"loss":0.0},"trace":[["*"],["2001:558:3da:74::1",1.9710063934326172],["2001:558:3da:6f::1",2.904176712036133],["2001:558:3da:1::2",2.5751590728759766],["2001:558:3c2:15::1",2.7141571044921875],["2001:558:fe1c:6::1",4.7512054443359375],["2001:558:1c0:65::1",3.927946090698242],["*"],["*"],["2001:558:0:f8c1::2",3.635406494140625],["2001:559:0:18::2",3.8270950317382812],["*"],["2001:4860:0:1::10ad",4.517078399658203],["2607:f8b0:400f:807::200e",3.91387939453125]],"scan":{"http":{"rtt":51.335,"response code":"200","server":"gws"},"https":{"rtt":70.521,"response code":"200","server":"gws"},"mysql":"None"}}}{"addr":"127.0.0.1","name":"localhost","ping":{"min":0.04792213439941406,"avg":0.29621124267578125,"max":0.5612373352050781,"std":0.0995351687014057,"loss":0.0},"trace":[["127.0.0.1",1.9199848175048828]],"scan":{"http":"None","https":"None","mysql":{"rtt":0.148,"version":"5.7.2"}}}}Error Output FormatWhen an error occurs, it is printed tostderrin the following
format:EE: <Error Type>: <Error Description>:  -   <Timestamp>EE:is prepended for ease of readability in the common case that
stdout and stderr are being read/parsed from the same place.<Error Type>is commonly juststrorException, but can in
some cases represent more specific error types.<Error Description>holds extra information describing why the error occurred. Note that
stack traces are not commonly logged, and only occur when the program
crashes for unforseen reasons.<Timestamp>is the time at which the
error occurred, given in the system’sctimeformat, which will
usually look likeMon Jan 1 12:59:59 2018.Some errors do not affect execution in a large scope, and are printed
largely for debugging purposes. These are printed as warnings tostderrin the following format:WW: <Warning> - <Timestamp>WhereWW:is prepended both for ease of readability and to
differentiate it from an error,<Warning>is the warning message,
and<Timestamp>is the time at which the warning was issued, given
in the system’sctimeformat.In the case thatstderris a tty,connvitalswill attempt to
print errors in red and warnings in yellow, using ANSI control sequences
(supports all VT/100-compatible terminal emulators).