a ping wrapper for nodejs
@last-modified: 2019-06-07
(C) Daniel Zelisko
http://github.com/danielzzz/node-ping
node-ping is a simple wrapper for the system ping utility
npm install ping
Below are examples extracted from examples
var ping = require('ping');
var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
hosts.forEach(function(host){
ping.sys.probe(host, function(isAlive){
var msg = isAlive ? 'host ' + host + ' is alive' : 'host ' + host + ' is dead';
console.log(msg);
});
});
var cfg = {
timeout: 10,
// WARNING: -i 2 may not work in other platform like window
extra: ['-i', '2'],
};
hosts.forEach(function(host){
ping.sys.probe(host, function(isAlive){
var msg = isAlive ? 'host ' + host + ' is alive' : 'host ' + host + ' is dead';
console.log(msg);
}, cfg);
});
var ping = require('ping');
var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
hosts.forEach(function (host) {
ping.promise.probe(host)
.then(function (res) {
console.log(res);
});
});
hosts.forEach(function (host) {
// WARNING: -i 2 argument may not work in other platform like window
ping.promise.probe(host, {
timeout: 10,
extra: ['-i', '2'],
}).then(function (res) {
console.log(res);
});
});
var ping = require('ping');
var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
for(let host of hosts){
let res = await ping.promise.probe(host);
console.log(res);
}
});
var ping = require('ping');
var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
for(let host of hosts){
// WARNING: -i 2 argument may not work in other platform like window
let res = await ping.promise.probe(host, {
timeout: 10,
extra: ['-i', '2'],
});
console.log(res);
}
});
Below is the possible configuration
/**
* Cross platform config representation
* @typedef {Object} PingConfig
* @property {boolean} numeric - Map IP address to hostname or not
* @property {number} timeout - Timeout in seconds for each ping request.
* Behaviour varies between platforms. Check platform ping documentation for more information.
* @property {number} deadline - Specify a timeout, in seconds, before ping exits regardless of
how many packets have been sent or received. In this case ping
does not stop after count packet are sent, it waits either for
deadline expire or until count probes are answered or for some
error notification from network. This option is only available on linux and mac.
* @property {number} min_reply - Exit after sending number of ECHO_REQUEST
* @property {boolean} v6 - Ping via ipv6 or not. Default is false
* @property {string} sourceAddr - source address for sending the ping
* @property {string[]} extra - Optional options does not provided
*/
- For callback based implementation:
/**
* Callback after probing given host
* @callback probeCallback
* @param {boolean} isAlive - Whether target is alive or not
* @param {Object} error - Null if no error occurs
*/
- For promise based implementation
/**
* Parsed response
* @typedef {object} PingResponse
* @param {string} host - The input IP address or HOST
* @param {string} numeric_host - Target IP address
* @param {boolean} alive - True for existed host
* @param {string} output - Raw stdout from system ping
* @param {number} time - Time (float) in ms for first successful ping response
* @param {Array} times - Array of Time (float) in ms for each ping response
* @param {string} min - Minimum time for collection records
* @param {string} max - Maximum time for collection records
* @param {string} avg - Average time for collection records
* @param {string} stddev - Standard deviation time for collected records
*/
-
Since
ping
in this module relies on theping
from underlying platform, arguments inPingConfig.extra
will definitely be varied across different platforms. -
However,
numeric
,timeout
andmin_reply
have been abstracted. Values for them are expected to be cross platform. -
By setting
numeric
,timeout
ormin_reply
to false, you can runping
without corresponding arguments. -
For LINUX users, since we have enable
shell
option in child_process.spawn, make sure arguments you are passing in into this library are sanitized. Otherwise, any input containing shell metacharacters may be used to trigger arbitrary command
- It does not work with busybox's ping implemetation #89
Try to install package iputils
. For example, running apk add iputils
- For questions regarding to the implementation of
timeout
, anddeadline
, please checkout discussions in #101
Before opening a pull request please make sure your changes follow the contribution guidelines.