perldoc > Net::Ping

man perldoc info pydoc3 ri search

📛 NAME

Net::Ping - check a remote host for reachability

🚀 Quick Reference

Use Case	Command	Description
Basic TCP ping	Net::Ping->new()->ping($host)	Default protocol check reachability via TCP echo port
ICMP ping (requires root)	Net::Ping->new("icmp")->ping($host)	Send ICMP echo request (requires root/setuid)
UDP ping	Net::Ping->new("udp")->ping($host)	Send UDP echo packet to host's echo port
SYN ping (parallel)	Net::Ping->new("syn")->ping($host); $p->ack	Send TCP SYN packets to multiple hosts; use ack() to collect responses
High precision ping	Net::Ping->new()->hires()->ping($host, 5.5)	Use Time::HiRes for millisecond precision
Wake-on-LAN	wakeonlan($mac, $host, $port)	Send magic packet to wake a device

📋 SYNOPSIS

        use Net::Ping;

        $p = Net::Ping->new();
        print "$host is alive.\n" if $p->ping($host);
        $p->close();

        $p = Net::Ping->new("icmp");
        $p->bind($my_addr); # Specify source interface of pings
        foreach $host (@host_array)
        {
            print "$host is ";
            print "NOT " unless $p->ping($host, 2);
            print "reachable.\n";
            sleep(1);
        }
        $p->close();

        $p = Net::Ping->new("icmpv6");
        $ip = "[fd00:dead:beef::4e]";
        print "$ip is alive.\n" if $p->ping($ip);

        $p = Net::Ping->new("tcp", 2);
        # Try connecting to the www port instead of the echo port
        $p->port_number(scalar(getservbyname("http", "tcp")));
        while ($stop_time > time())
        {
            print "$host not reachable ", scalar(localtime()), "\n"
                unless $p->ping($host);
            sleep(300);
        }
        undef($p);

        # Like tcp protocol, but with many hosts
        $p = Net::Ping->new("syn");
        $p->port_number(getservbyname("http", "tcp"));
        foreach $host (@host_array) {
          $p->ping($host);
        }
        while (($host,$rtt,$ip) = $p->ack) {
          print "HOST: $host [$ip] ACKed in $rtt seconds.\n";
        }

        # High precision syntax (requires Time::HiRes)
        $p = Net::Ping->new();
        $p->hires();
        ($ret, $duration, $ip) = $p->ping($host, 5.5);
        printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n",
                1000 * $duration)
          if $ret;
        $p->close();

        # For backward compatibility
        print "$host is alive.\n" if pingecho($host);

📝 DESCRIPTION

This module contains methods to test the reachability of remote hosts on a network. A ping object is first created with optional parameters, a variable number of hosts may be pinged multiple times and then the connection is closed.

You may choose one of six different protocols to use for the ping. The "tcp" protocol is the default. Note that a live remote host may still fail to be pingable by one or more of these protocols. For example, www.microsoft.com is generally alive but not "icmp" pingable.

With the "tcp" protocol the ping() method attempts to establish a connection to the remote host's echo port. If the connection is successfully established, the remote host is considered reachable. No data is actually echoed. This protocol does not require any special privileges but has higher overhead than the "udp" and "icmp" protocols.

Specifying the "udp" protocol causes the ping() method to send a udp packet to the remote host's echo port. If the echoed packet is received from the remote host and the received packet contains the same data as the packet that was sent, the remote host is considered reachable. This protocol does not require any special privileges. It should be borne in mind that, for a udp ping, a host will be reported as unreachable if it is not running the appropriate echo service. For Unix-like systems see inetd(8) for more information.

If the "icmp" protocol is specified, the ping() method sends an icmp echo message to the remote host, which is what the UNIX ping program does. If the echoed message is received from the remote host and the echoed information is correct, the remote host is considered reachable. Specifying the "icmp" protocol requires that the program be run as root or that the program be setuid to root.

If the "external" protocol is specified, the ping() method attempts to use the "Net::Ping::External" module to ping the remote host. "Net::Ping::External" interfaces with your system's default "ping" utility to perform the ping, and generally produces relatively accurate results. If "Net::Ping::External" if not installed on your system, specifying the "external" protocol will result in an error.

If the "syn" protocol is specified, the "ping" method will only send a TCP SYN packet to the remote host then immediately return. If the syn packet was sent successfully, it will return a true value, otherwise it will return false. NOTE: Unlike the other protocols, the return value does NOT determine if the remote host is alive or not since the full TCP three-way handshake may not have completed yet. The remote host is only considered reachable if it receives a TCP ACK within the timeout specified. To begin waiting for the ACK packets, use the "ack" method as explained below. Use the "syn" protocol instead the "tcp" protocol to determine reachability of multiple destinations simultaneously by sending parallel TCP SYN packets. It will not block while testing each remote host. This protocol does not require any special privileges.

🔧 Functions

• Net::Ping->new([proto, timeout, bytes, device, tos, ttl, family, host, port, bind, gateway, retrans, pingstring, source_verify econnrefused dontfrag IPV6_USE_MIN_MTU IPV6_RECVPATHMTU]) — Create a new ping object. All of the parameters are optional and can be passed as hash ref. All options besides the first 7 must be passed as hash ref.
  • proto — specifies the protocol to use when doing a ping. The current choices are "tcp", "udp", "icmp", "icmpv6", "stream", "syn", or "external". The default is "tcp".
  • timeout — in seconds, used when a timeout is not given to the ping() method. Must be > 0, default 5 seconds.
  • bytes — number of data bytes included in the ping packet. Ignored for tcp. Minimum 1 for udp, 0 otherwise. Max 65535, but staying below MTU (1472 bytes for ICMP) recommended.
  • device — device to bind source endpoint before sending ping packet. Requires superuser privileges for udp and icmp.
  • tos — ToS value configured into the socket.
  • ttl — set TTL of outgoing packet for icmp.
  • family — IPv4 or IPv6 family. Valid values: 4, v4, ip4, ipv4, AF_INET for IPv4; 6, v6, ip6, ipv6, AF_INET6 for IPv6.
  • host — implicitly specifies the family if family not given.
  • port — only valid for udp, tcp or stream ping. Default is echo port. Note: ping returns true on "Connection refused".
  • bind — local_addr to bind to. Alternative to bind method.
  • gateway — only valid for IPv6, requires IPv6 address.
  • retrans — exponential backoff rate, default 1.2. Matches $def_factor global.
  • dontfrag — sets IP_DONTFRAG bit. Not available on many systems; ignored. On linux also sets IP_MTU_DISCOVER to IP_PMTUDISC_DO but does not chunk oversized packets. Need to set $data_size manually.
• $p->ping($host [, $timeout [, $family]]); — Ping the remote host and wait for a response. $host can be hostname or IP. Optional timeout must be > 0 seconds, defaults to object's timeout. Returns success flag (1 reachable, 0 not, undef on error). In array context, returns elapsed time and string form of IP. Elapsed time is float if hires() called, else integer.
• $p->source_verify( { 0 | 1 } ); — Enable or disable source endpoint verification. Useful for multi-interface destinations where response may not originate from same endpoint. Affects udp and icmp. Enabled by default.
• $p->service_check( { 0 | 1 } ); — Set whether connect behavior should enforce remote service availability as well as reachability. For tcp, full three-way handshake must succeed. For udp, remote must echo back same data. Affects udp, tcp, and syn. Disabled by default.
• $p->tcp_service_check( { 0 | 1 } ); — Deprecated; same as service_check().
• $p->hires( { 0 | 1 } ); — With 1 use Time::HiRes for millisecond precision in subsequent ping() calls.
• $p->time — Current time, hires or not.
• $p->socket_blocking_mode( $fh, $mode ); — Sets or clears O_NONBLOCK flag on a file handle.
• $p->IPV6_USE_MIN_MTU — With argument sets the option. Without returns the option value.
• $p->IPV6_RECVPATHMTU — Notify an according IPv6 MTU. With argument sets the option. Without returns the option value.
• $p->IPV6_HOPLIMIT — With argument sets the option. Without returns the option value.
• $p->IPV6_REACHCONF *NYI* — Sets ipv6 reachability (removed in RFC3542). ping6 -R supports it. Requires root/admin permissions. Not yet implemented.
• $p->bind($local_addr); — Sets the source address from which pings will be sent. Must be an address of a local interface. For tcp can be called multiple times; for icmp/udp must be called at most once before first ping(). Can be omitted via new(bind).
• $p->message_type([$ping_type]); — For icmp protocol, change message type to 'echo' or 'timestamp' (IPv4 only, RFC 792). Without argument returns current type (default 'echo').
• $p->open($host); — For stream protocol, pre-opens the tcp socket. Optional; connection is automatically opened on first ping(). $host can be omitted via new(host).
• $p->ack( [ $host ] ); — For syn protocol, returns the host that came back with TCP ACK as many times as ping() was called. Returns undef if timeout reached or remote not listening. In list context returns host, ack time, dotted ip, and port number. With optional $host returns info for that host only. If new had host option, uses that host.
• $p->nack( $failed_ack_host ); — Reason why host did not receive a valid ACK.
• $p->ack_unfork($host) — Variant called by ack with syn protocol and $syn_forking enabled.
• $p->ping_icmp([$host, $timeout, $family]) — Ping method used with icmp protocol.
• $p->ping_icmpv6([$host, $timeout, $family]) — Ping method used with icmpv6 protocol.
• $p->ping_stream([$host, $timeout, $family]) — Ping method used with stream protocol. Opens tcp connection if not already open, sends data, waits for reply, leaves stream open.
• $p->ping_syn([$host, $ip, $start_time, $stop_time]) — Ping method used with syn protocol. Sends TCP SYN packet to host.
• $p->ping_syn_fork([$host, $timeout, $family]) — Ping method used with forking syn protocol.
• $p->ping_tcp([$host, $timeout, $family]) — Ping method used with tcp protocol.
• $p->ping_udp([$host, $timeout, $family]) — Ping method used with udp protocol. Constructs message with sequence number and data bytes, sends and waits for matching echo reply.
• $p->ping_external([$host, $timeout, $family]) — Ping method used with external protocol. Uses Net::Ping::External.
• $p->tcp_connect([$ip, $timeout]) — Initiates a TCP connection for a tcp ping.
• $p->tcp_echo([$ip, $timeout, $pingstring]) — Performs TCP echo: writes string to socket, reads it back. Returns 1 on success, 0 on failure.
• $p->close(); — Close the network connection for this ping object. Also closed by undef $p or when object goes out of scope.
• $p->port_number([$port_number]) — Set port number to ping (instead of echo port). Also calls service_check(1) so ping returns success only if that port is accessible. Returns the port value.
• $p->mselect — A select() wrapper that compensates for platform peculiarities.
• $p->ntop — Platform abstraction over inet_ntop().
• $p->checksum($msg) — Do a checksum on the message: sum all short words, fold high order bits into low order bits.
• $p->icmp_result — Returns a list of addr, type, subcode.

🔙 pingecho

pingecho($host [, $timeout]); — To provide backward compatibility with the previous version of Net::Ping, a "pingecho()" subroutine is available with the same functionality as before. "pingecho()" uses the tcp protocol. The return values and parameters are the same as described for the "ping" method. This subroutine is obsolete and may be removed in a future version of Net::Ping.

💤 wakeonlan

wakeonlan($mac, [$host, [$port]]) — Emit the popular wake-on-lan magic udp packet to wake up a local device. See also Net::Wake, but this has the mac address as 1st arg. $host should be the local gateway. Without it will broadcast. Default host: '255.255.255.255' Default port: 9

  perl -MNet::Ping=wakeonlan -e'wakeonlan "e0:69:95:35:68:d2"'

📝 NOTES

There will be less network overhead (and some efficiency in your program) if you specify either the udp or the icmp protocol. The tcp protocol will generate 2.5 times or more traffic for each ping than either udp or icmp. If many hosts are pinged frequently, you may wish to implement a small wait (e.g. 25ms or more) between each ping to avoid flooding your network with packets.

The icmp and icmpv6 protocols requires that the program be run as root or that it be setuid to root. The other protocols do not require special privileges, but not all network devices implement tcp or udp echo.

Local hosts should normally respond to pings within milliseconds. However, on a very congested network it may take up to 3 seconds or longer to receive an echo packet from the remote host. If the timeout is set too low under these conditions, it will appear that the remote host is not reachable (which is almost the truth).

Reachability doesn't necessarily mean that the remote host is actually functioning beyond its ability to echo packets. tcp is slightly better at indicating the health of a system than icmp because it uses more of the networking stack to respond.

Because of a lack of anything better, this module uses its own routines to pack and unpack ICMP packets. It would be better for a separate module to be written which understands all of the different kinds of ICMP packets.

📦 INSTALL

The latest source tree is available via git:

git clone https://github.com/rurban/Net-Ping.git
cd Net-Ping

The tarball can be created as follows:

perl Makefile.PL ; make ; make dist

The latest Net::Ping releases are included in cperl and perl5.

🐞 BUGS

For a list of known issues, visit:

• https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping
• https://github.com/rurban/Net-Ping/issues

To report a new bug, visit:

• https://github.com/rurban/Net-Ping/issues

👥 AUTHORS

• Current maintainers: perl11 (for cperl, with IPv6 support and more), p5p (for perl5)
• Previous maintainers: bbb AT cpan.org (Rob Brown), Steve Peters
• External protocol: colinm AT cpan.org (Colin McMillen)
• Stream protocol: bronson AT trestle.com (Scott Bronson)
• Wake-on-lan: 1999-2003 Clinton Wong
• Original pingecho(): karrer AT bernina.ch (Andreas Karrer), pmarquess AT bfsec.uk (Paul Marquess)
• Original Net::Ping author: mose AT ns.edu (Russell Mosemann)

© COPYRIGHT

Copyright (c) 2017-2020, Reini Urban. All rights reserved.

Copyright (c) 2016, cPanel Inc. All rights reserved.

Copyright (c) 2012, Steve Peters. All rights reserved.

Copyright (c) 2002-2003, Rob Brown. All rights reserved.

Copyright (c) 2001, Colin McMillen. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION 📝 NOTES 📦 INSTALL 🐞 BUGS 👥 AUTHORS © COPYRIGHT