Uses the connvitals library to continuously poll and record network connectivity statistics.
Project description
Persistently monitors network conditions with respect to a set of specific hosts.
Dependencies
The executable for the connvitals-monitor package (connmonitor) runs on python3 (tested CPython 3.6.3) and requires a python3 interpreter. It also requires `connvitals <https://github.com/comcast/connvitals>`__ to exist as a subdirectory in its directory (or your import path) as it uses that as a library.
Note: Because this package is not in a standard repository (nor is its dependency), dependencies cannot be automatically resolved; you must first install connvitals for this package to work.
Installation
Note: Versions 1.2+ **only* support Linux systems that run systemd. It’s possible that it may install on your system even if you do not run systemd, but it will attempt to install the Unit File under /usr/lib/systemd/system.*
Via pip (Standard)
By far the easiest way to install connvitals-monitor is to simply use pip like so:
pip install connmonitor
Note that you’ll probably need to run this command with sudo or the --user flag.
Via pip (From This Repository)
The easiest way to install is to simply use pip. You can install directly from this repository without needing to manually download it by running
user@hostname ~ $ pip install git+https://github.com/comcast/connvitals-monitor.git#egg=connmonitor
Note that you may need to run this command as root/with sudo or with --user, depending on your pip installation. Also ensure that pip is installing packages for Python 3.x. Typically, if both Python2 and Python3 exist on a system with pip installed for both, the pip to use for Python3 packages is accessible as pip3.
Manually
To install manually, first download or clone this repository. Then, in the directory you downloaded/cloned it into, run the command
user@hostname ~/connvitals-monitor $ python setup.py install
Usage
$ connmonitor [input file]
$ connmonitor [ -v --version ]
As a systemd daemon
Starting with version 1.2.1, connvitals-monitor (unfortunately) comes packaged with a systemd Unit File, and will attempt to install it. To run the daemon, simply run systemctl start connmonitor (as root), and to stop it run systemctl stop connmonitor (also as root). By default, the monitor will log its stdout in JSON format to /var/log/connmonitor.log, and its stderr to /var/log/connmonitor.err. Whenever the monitor is started, it looks for a configuration file at /var/run/connmonitor.conf, and creates it if it does not exist with the following default contents (see ‘Input Format’):
1 1 1 10 41 40 1 500 localhost
The monitor service does not check for filesystem updates to that config file; if you wish to edit it you may safely do so, but should run systemctl reload connmonitor to read in the new configuration.
Input Format
connmonitor expects input formatted like this:
DOPINGS DOTRACE DOPSCAN NUMPINGS PAYLOAD HOPS JSON SLEEP host1 host2 host3 ...
where the fields have the following meanings
DOPINGS is either 0 to indicate that pings should not be sent, or any other integer (typically 1) to indicate that they should be sent.
DOTRACE is either 0 to indicate that route tracing should not be done, or any other integer (typically 1) to indicate they should be done.
DOPSCAN is either 0 to indicate that port scanning should not be done, or any other integer (typically 1) to indicate they should be done.
NUMPINGS is a positive integer indicating the number of pings to be sent. If DOPINGS is 0, this is not used, but must still be specified. Note that - in general - setting NUMPINGS to 0 is less efficient than setting DOPINGS to 0.
PAYLOAD is a positive integer indicating the size of each ping payload. If DOPINGS is 0, this is not used, but must still be specified. It is recommended that this be at least 14.
HOPS is a positive integer that sets the maximum number of network hops to be considered in route tracing. If DOTRACE is 0, this is not used, but must still be specified. It is recommended that this be at least 15 for testing hosts that are not on LAN. Note that - in general - setting HOPS to 0 is less efficient than setting DOTRACE to 0.
JSON is either 0 to indicate that output should not be formatted as JSON, or any other integer (typically 1) to indicate that output should be formatted as JSON.
SLEEP is the amount of time for the process to “sleep” between queries of its hosts (in milliseconds).
Output Format
connmonitor outputs results to stdout and logs errors to stderr. Output (including JSON output) takes the same form as connvitals, and you can read about that format on that project’s README.
Starting with version 3.0, connmonitor will no longer output traces if they are determined to be the same as the most recent route previously recorded for a given host. This is as a result of changes made to connvitals (but only the Python version) which are discussed in greater detail on that project’s page.
Example
Here’s an example of a configuration file that will gather port scans and ping statistics for 10 pings per run each having a payload of 1337B - but not route traces - from google.com, github.com and the address 127.0.0.1 (localhost) every half-second and outputs in connvitals’s standard, plain-text format:
1 0 1 10 1337 100 0 500 google.com github.com 127.0.0.1
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for connmonitor-3.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | aefac1ab5c891bd935a420a0dba78766684cdc2ea0cac290856de9311c79dc7e |
|
MD5 | 65ec7e7a5ac7d20c52e9b07142035ca6 |
|
BLAKE2b-256 | fbbd52eceffa3b53448632b3c28cc2c33401c386d135583f2daf11875617c879 |