biz.neustar.wpm.api
Interface Net

public interface Net

Network monitoring APIs

To include in a script add the following to the top of the script file.

 var net = require('net');
 

The following functionality is provided:

• Direct TCP and UDP communication
• Direct SSL socket communication
• ICMP Ping
• Traceroute
• SMTP
• POP3
• SNTP

Nested Class Summary

static interface	Net.PingResult The result of a ping request.
static interface	Net.TraceRouteResult The result of a traceroute request.

Method Summary

TcpSocket	newSocket() Creates a new TCP socket.
TcpSocket	newSslSocket() Creates a new SSL socket.
UdpSocket	newUdpSocket() Creates a new UDP socket.
Net.PingResult	ping(java.lang.String hostName) Tests whether a network ip or hostname is reachable.
Net.PingResult	ping(java.lang.String hostName, long timeoutMS) Tests whether a network ip or hostname is reachable.
Net.PingResult	ping(java.lang.String hostName, long timeoutMS, int numPingPackets) Tests whether a network ip or hostname is reachable.
Net.TraceRouteResult	traceroute(java.lang.String hostName) Performs a traceroute.
Net.TraceRouteResult	traceroute(java.lang.String hostName, long timeoutMS) Performs a traceroute.
Net.TraceRouteResult	traceroute(java.lang.String hostName, long timeoutMS, int packetsPerHop) Performs a traceroute.
boolean	verifyCertificateOCSP(java.lang.String certFilePath, java.lang.String issuerCertFilePath, java.lang.String responderURI, java.lang.String responderCertFilePath, java.lang.String dateString) Verify certificate validity.
long	verifyPop(java.lang.String hostname) Verify a POP3 server is alive and working correctly.
long	verifyPop(java.lang.String hostname, int port) Verify a POP3 server is alive and working correctly.
long	verifyPop(java.lang.String hostname, java.lang.String username, java.lang.String password) Verify a POP3 server is alive and working correctly.
long	verifyPop(java.lang.String hostname, java.lang.String username, java.lang.String password, int port) Verify a POP3 server is alive and working correctly.
long	verifySmtp(java.lang.String hostname) Verify a SMTP server is alive, and functioning correctly.
long	verifySmtp(java.lang.String hostname, java.lang.String emailAddress) Verify a SMTP server is alive, and functioning correctly.
long	verifySmtp(java.lang.String hostname, java.lang.String emailAddress, int port) Verify a SMTP server is alive and functioning correctly.
long	verifySntp(java.lang.String hostname, int port, int ntpVersion, int timeoutMS) Verify an SNTP server is alive and working correctly.

Method Detail

newSocket

TcpSocket newSocket()

Creates a new TCP socket. The socket is not connected yet.

Returns:

a new TCP socket.

See Also:

TcpSocket

newSslSocket

TcpSocket newSslSocket()

Creates a new SSL socket.

Returns:

a new SSL socket.

See Also:

TcpSocket

newUdpSocket

UdpSocket newUdpSocket()

Creates a new UDP socket.

Returns:

a new UDP socket.

See Also:

UdpSocket

ping

Net.PingResult ping(java.lang.String hostName)
                    throws java.lang.Exception

Tests whether a network ip or hostname is reachable.

Firewalls and server configuration may block requests resulting in a unreachable status while some specific ports may be accessible.

By default 4 ping attempts are made to the host.

By default there is a timeout of 1 second per attempt.

Parameters:

hostName - the hostname to ping

Returns:

the length of time in milliseconds to make the round trip to the server

Throws:

java.lang.Exception - when the server is unreachable

java.lang.Exception - when the server doesn't respond within the timeout

ping

Net.PingResult ping(java.lang.String hostName,
                    long timeoutMS)
                    throws java.lang.Exception

Tests whether a network ip or hostname is reachable.

Firewalls and server configuration may block requests resulting in a unreachable status while some specific ports may be accessible.

The timeout value, in milliseconds, indicates the maximum amount of time the try should take. If the operation times out before getting an answer, the host is deemed unreachable. A negative value will result in an IllegalArgumentException being thrown.

By default 4 ping attempts are made to the host.

Parameters:

hostName - the hostname to ping

timeoutMS - The time, in milliseconds, before the call aborts

Returns:

the length of time in milliseconds to make the round trip to the server

Throws:

java.lang.Exception - when the server is unreachable

java.lang.Exception - when the server doesn't respond within the timeout

ping

Net.PingResult ping(java.lang.String hostName,
                    long timeoutMS,
                    int numPingPackets)
                    throws java.lang.Exception

Tests whether a network ip or hostname is reachable.

The timeout value, in milliseconds, indicates the maximum amount of time the try should take. If the operation times out before getting an answer, the host is deemed unreachable. A negative value will result in an IllegalArgumentException being thrown.

The number of ping packets to send can be specified. A negative value will result in an IllegalArgumentException being thrown.

Parameters:

hostName - the hostname to ping

timeoutMS - The time, in milliseconds, before the call aborts

numPingPackets - The number of pings to send in total.

Returns:

the length of time in milliseconds to make the round trip to the server.

Throws:

java.lang.Exception - when the server is unreachable

java.lang.Exception - when the server doesn't respond within the timeout

traceroute

Net.TraceRouteResult traceroute(java.lang.String hostName)

Performs a traceroute.

Tracks the route of packets follow to a given hostname or ip address. traceroute() utilizes the IP protocol `time to live' field to probe the route to the host, one gateway after another. The probe datagram length on Windows agents is 32 bytes. On Linux this is 40 bytes.

Waits for 30 seconds by default, before timing out.

Default number of packets per hop is 2.

Parameters:

hostName - the hostname or IP address to find the route to.

Returns:

The trace route data for each hop along the way.

traceroute

Net.TraceRouteResult traceroute(java.lang.String hostName,
                                long timeoutMS)

Performs a traceroute.

Tracks the route of packets follow to a given hostname or ip address. traceroute() utilizes the IP protocol `time to live' field to probe the route to the host, one gateway after another. The probe datagram length on Windows agents is 32 bytes. On Linux this is 40 bytes.

Default number of packets per hop is 2.

Parameters:

hostName - the hostname or IP address to find the route to.

timeoutMS - The time, in milliseconds, before the call aborts.

Returns:

The trace route data for each hop along the way.

traceroute

Net.TraceRouteResult traceroute(java.lang.String hostName,
                                long timeoutMS,
                                int packetsPerHop)

Performs a traceroute.

Tracks the route of packets follow to a given hostname or ip address. traceroute() utilizes the IP protocol `time to live' field to probe the route to the host, one gateway after another. The probe datagram length on Windows agents is 32 bytes. On Linux this is 40 bytes.

Parameters:

hostName - the hostname or IP address to find the route to.

timeoutMS - The time, in milliseconds, before the call aborts.

packetsPerHop - the max number of hops to try.

Returns:

the trace route data for each hop along the way.

verifySmtp

long verifySmtp(java.lang.String hostname)

Verify a SMTP server is alive, and functioning correctly. Connects on port 25 by default.

Parameters:

hostname - hostname of SMTP server to query

Returns:

the time taken in milliseconds to connect and login

verifySmtp

long verifySmtp(java.lang.String hostname,
                java.lang.String emailAddress)

Verify a SMTP server is alive, and functioning correctly.

A "MAIL" and "RECP TO" command are sent with the email address given.

Connects on port 25 by default.

Parameters:

hostname - hostname of SMTP server to query

emailAddress - the email address to verify

Returns:

the time taken in milliseconds to connect and login

verifySmtp

long verifySmtp(java.lang.String hostname,
                java.lang.String emailAddress,
                int port)

Verify a SMTP server is alive and functioning correctly.

A "MAIL" and "RECP TO" command are sent with the email address given.

Parameters:

hostname - hostname of SMTP server to query

emailAddress - the email address to verify

port - port to connect to

Returns:

the time taken in milliseconds to connect and login

verifyPop

long verifyPop(java.lang.String hostname)

Verify a POP3 server is alive and working correctly.

Parameters:

hostname - the POP3 server to query

Returns:

the time taken in milliseconds to connect and login

verifyPop

long verifyPop(java.lang.String hostname,
               int port)

Verify a POP3 server is alive and working correctly.

Parameters:

hostname - the POP3 server to query

port - specify a port

Returns:

the time taken in milliseconds to connect and login

verifyPop

long verifyPop(java.lang.String hostname,
               java.lang.String username,
               java.lang.String password)

Verify a POP3 server is alive and working correctly.

Parameters:

hostname - the POP3 server to query

username - account username to use

password - account password to use

Returns:

the time taken in milliseconds to connect and login

verifyPop

long verifyPop(java.lang.String hostname,
               java.lang.String username,
               java.lang.String password,
               int port)

Verify a POP3 server is alive and working correctly.

Parameters:

hostname - the POP3 server to query

username - account username to use

password - account password to use

port - specify a port

Returns:

the time taken in milliseconds to connect and login

verifySntp

long verifySntp(java.lang.String hostname,
                int port,
                int ntpVersion,
                int timeoutMS)

Verify an SNTP server is alive and working correctly.

An exception is thrown if the request times out or if the hostname does not resolve.

Another API, Sntp, can be used for more control over the request and access to the response structure use.

Parameters:

hostname - the NTP server hostname to query

port - the server port to send the query to

ntpVersion - the ntp version, can be set to either 3 or 4

timeoutMS - timeout in milliseconds

Returns:

the time taken in milliseconds

verifyCertificateOCSP

boolean verifyCertificateOCSP(java.lang.String certFilePath,
                              java.lang.String issuerCertFilePath,
                              java.lang.String responderURI,
                              java.lang.String responderCertFilePath,
                              java.lang.String dateString)
                              throws java.lang.Exception

Verify certificate validity.

An exception is thrown if the certificate is not valid.

Parameters:

certFilePath - path to the file containing the certificate to be verified

issuerCertFilePath - path to the file containing the certificate of the issuer of the certificate to be verified

responderURI - URI of the OCSP server to be queried

responderCertFilePath - path to the file containing the OCSP server certificate

dateString - date the certificate is to be validated for, in the form "MM/dd/yyyy"

Returns:

returns true on success

Throws:

java.lang.Exception - describes reason certificate check failed