This application is the client binary distributed for use with imUp.io's connectivity and speed testing platform
It continuously checks for connectivity and periodically runs speed tests in accordance with the ndt7-protocol
The client is also enabled with imUp real-time features including on-demand speed tests, liveness check-ins as well as remote configuration
-
Connection Health: Collects latency, RTT, and packet loss. If you're experiencing connectivity issues while working from home or gaming, this data will help you pinpoint if the issue is on your end or not.
-
Speed Tests: Using the ndt7 protocol collects speed tests data at semi random intervals or on-demand.
-
Real-time Monitoring: With imUp.io you have access to on-demand speed tests as well as real-time altering via email or twitter.
Download the client
go install github.com/imup-io/client@latestRun the client specifying an email address you want to associate the data with
client --email email@example.comSee the contribution guide for details on how to contribute.
If either allowlisted IPs or blocklisted IPs are configured (CIDR notation), imUp will ask ipify.org for the public IP address is of the host it's running on every 60 seconds and pause execution of monitoring if the IP fails to meet the configured criteria.
The CIDR notation for a single IP address to be added to either list is <ip-address>/32. As an example, Cloudflare's DNS server in CIDR notation is 1.1.1.1/32. If an IP address is passed in without CIDR notation, a warning log will print and the address will be assumed to be /32.
A use case for individuals is to only monitor their internet while at home (allowlist) and stop monitoring if they take their computer to a coffee shop.
A use case for businesses is to only monitor their employees' internet while not in the office (blocklist), which might be appropriate for a remote worker who sometimes brings their computer to the office.
Unless the --no-speed-test flag is set, a speed test will be run approximately every four hours. The frequency of the of the test is constrained in part by the ndt7 protocol as well as the imUps teams desire not to excessively run tests, or potentially saturate a network where multiple clients could be running. A poisson distribution is being used to guarantee a consistent number of speed tests every day.
Logs are generally sent to stdout and stderr, but imUp can be configured to write to a log file instead.
To enable logging to a file, set the LOG_TO_FILE environment variable to "true", and be sure to set up imUp's environment to make it's log file path a writeable location.
The following table describes where logs will (by default) be written to:
| Operating System | File Path |
|---|---|
| Unix systems | $XDG_CACHE_HOME/imup/logs/imup.log if XDG_CACHE_HOME is non-empty, else $HOME/.cache/imup/logs/imup.log |
| Darwin | $HOME/Library/Caches/imup/logs/imup.log |
| Windows | %LocalAppData%\imup\logs\imup.log |
To change the default log file path, set the LOG_FILE_PATH environment variable to an alternative writeable location. Note that setting this environment variable overrides LOG_TO_FILE
To configure log verbosity, set the VERBOSITY environment variable to one of the following common log levels:
debuginfo(default value)warnerror
| Name | Description | Default |
|---|---|---|
ALLOWLISTED_IPS |
configures the host IPs allowed to be monitored (CIDR) | "" |
API_KEY |
api key for imup orgs | "" |
BLOCKLISTED_IPS |
configures host IPs that cannot be monitored (CIDR) | "" |
CONN_DELAY |
time between dials in milliseconds | "200" |
CONN_INTERVAL |
dialer interval in seconds | "60" |
CONN_REQUESTS |
number of requests each test | "300" |
EMAIL |
email address associated with imup data | "" |
GROUP_ID |
id associated with an imup org group | "" |
HOST_ID |
id associated with host being monitored | the host name reported by the kernel |
LOG_FILE |
log all output to this file | the default behavior is described in the table above |
LOG_TO_FILE |
log output to a file in the default cache dir | "false" |
IMUP_ADDRESS |
imup API address for connectivity data | "https://api.imup.io/v1/data/connectivity" |
IMUP_ADDRESS_SPEEDTEST |
imup API address for speedtest | "https://api.imup.io/v1/data/speedtest" |
IMUP_LIVENESS_CHECKIN_ADDRESS |
imup API address for liveness checkin | "https://api.imup.io/v1/realtime/livenesscheckin" |
IMUP_SHOULD_RUN_SPEEDTEST_ADDRESS |
imup API address for on-demand speedtests | "https://api.imup.io/v1/realtime/shouldClientRunSpeedTest" |
IMUP_SPEED_TEST_RESULTS_ADDRESS |
imup API address for speed test results | "https://api.imup.io/v1/realtime/speedTestResults" |
IMUP_SPEED_TEST_STATUS_ADDRESS |
imup API address for speed tests running | "https://api.imup.io/v1/realtime/speedTestStatusUpdate" |
IMUP_REALTIME_AUTHORIZED |
imup API address for real-time authorized | "https://api.imup.io/v1/auth/real-timeAuthorized" |
IMUP_REALTIME_CONFIG |
imup API address for reloadable config | "https://api.imup.io/v1/realtime/config" |
IMUP_DATA_LENGTH |
imup data length per interval | "15" |
INSECURE_SPEED_TEST |
runs speed test over ws:// instead of wss:// |
"false" |
NO_GATEWAY_DISCOVERY |
disables autodiscovery of gateway IP address | "false" |
NO_SPEED_TEST |
disable speed tests | "false" |
NONVOLATILE |
use disk to store collected data between tests | "false" |
PING_ADDRESS |
address to ping | "1.1.1.1,1.0.0.1,8.8.8.8,8.8.4.4" (CloudFlare /Google DNS) |
PING_ADDRESS_INTERNAL |
configurable gateway address | discovered/configurable (disabled with --no-discover-gateway) |
PING_DELAY |
time between pings in milliseconds | "100" |
PING_ENABLED |
whether to use ICMP ping or net dials for connectivity tests | "true" |
PING_INTERVAL |
ping interval in seconds | "60" |
PING_REQUESTS |
number of requests each test | "600" |
REALTIME |
enable real-time features if on paid plan | "true" |
VERBOSITY |
controls log level. must be one of debug, info, warn, error |
"info" |
Usage: imup
-allowlisted-ips string
comma separated list of CIDR strings to match against host IP that determines whether speed and connectivity testing will be run, default is allow all
-anonymize.ip value
Valid values are "none" and "netblock". (default none)
-api-post-connection-data string
api endpoint for connectivity data ingestion, default is https://api.imup.io/v1/data/connectivity
-api-post-speed-test-data string
api endpoint for speed data ingestion, default is https://api.imup.io/v1/data/speedtest
-blocklisted-ips string
comma separated list of CIDR strings to match against host IP that determines whether speed and connectivity testing will be paused, default is block none
-conn-delay string
the delay between connectivity tests with a net dialer (milliseconds), default is 200
-conn-interval string
how often a dial test is run (seconds), default is 60
-conn-requests string
the number of dials executed during a connectivity test, default is 300
-email string
email address associated with the gathered connectivity and speed data
-group-id string
an imup org users group id
-host-id string
the host id associated with the gathered connectivity and speed data
-imup-data-length string
the number of data points collected before sending data to the api, default is 15 data points
-insecure
run insecure speed tests (ws:// and not wss://), default is false
-key string
an api key associated with an imup organization
-liveness-check-in-address string
api endpoint for liveness checkins default is https://api.imup.io/v1/realtime/livenesscheckin
-locate.url value
The base url for the Locate API (default https://locate.measurementlab.net/v2/nearest/)
-log-file string
writes a log file this file, default is unset
-log-to-file
if enabled, will log to the default root directory to use for user-specified cached data, default is false
-no-gateway-discovery
do not attempt to discover a default gateway, default is true
-no-speed-test
do not run speed tests, default is false
-nonvolatile
use disk to store collected data between tests to ensure no lost data, default is false to be minimally invasive
-ping
use ICMP ping for connectivity tests, default is true (default true)
-ping-address-internal string
an internal gateway to differentiate between local networking issues and internet connectivity, by default imup attempts to discover your gateway
-ping-addresses-external string
external IP addresses imup will use to validate connectivity, defaults are 1.1.1.1,1.0.0.1,8.8.8.8,8.8.4.4
-ping-delay string
the delay between connectivity tests with ping (milliseconds), default is 100
-ping-interval string
how often a ping test is run (seconds), default is 60
-ping-requests string
the number of icmp echos executed during a ping test, default is 600
-realtime
enable realtime features, default is true (default true)
-realtime-authorized string
api endpoint for imup real-time features, default is https://api.imup.io/v1/auth/realtimeAuthorized
-realtime-config string
api endpoint for imup realtime reloadable configuration, default is https://api.imup.io/v1/realtime/config
-should-run-speed-test-address string
api endpoint for imup realtime speed tests, default is https://api.imup.io/v1/realtime/shouldClientRunSpeedTest
-speed-test-results-address string
api endpoint for imup realtime speed test results, default is https://api.imup.io/v1/realtime/speedTestResults
-speed-test-status-update-address string
api endpoint for imup real-time speed test status updates, default is https://api.imup.io/v1/realtime/speedTestStatusUpdate
-verbosity string
verbosity for log output [debug, info, warn, error], default is info