.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Paranoid::Network 3pm" .TH Paranoid::Network 3pm "2018-11-09" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Paranoid::Network \- Network functions for paranoid programs .SH "VERSION" .IX Header "VERSION" \&\f(CW$Id:\fR lib/Paranoid/Network.pm, 2.06 2018/08/05 01:21:48 acorliss Exp $ .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Paranoid::Network; \& \& $rv = ipInNetworks($ip, @networks); \& $rv = hostInDomains($host, @domains); \& $cidr = Paranoid::Network::NETMATCH(); \& @ips = extractIPs($string1); \& @ips = extractIPs(@lines); \& $rv = netIntersect( $cidr1, $cidr2 ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This modules contains functions that may be useful for working with network data. It attempts to be IPv4/IPv6 agnostic, assuming IPv6 support is present. Due to the gradual introduction of IPv6 support into Perl there may be caveats. Please consult Paranoid::Network::Socket for more details. .PP \&\fI\s-1NETMATCH\s0\fR and \fI\s-1HOSTNAME_REGEX\s0\fR are not exported by default. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .SS "ipInNetworks" .IX Subsection "ipInNetworks" .Vb 1 \& $rv = ipInNetworks($ip, @networks); .Ve .PP This function checks the passed \s-1IP\s0 (in string format) against each of the networks or IPs in the list and returns true if there's a match. The list of networks can be either individual \s-1IP\s0 address or network addresses in \s-1CIDR\s0 notation or with full netmasks: .PP .Vb 3 \& @networks = qw(127.0.0.1 \& 192.168.0.0/24 \& 172.16.12.0/255.255.240.0); .Ve .PP You can safely comingle IPv4 & IPv6 addresses in the list to check against. Addresses not belonging to the same address family as the \s-1IP\s0 being tested will be ignored. .PP \&\fB\s-1NOTE:\s0\fR IPv4 addresses encoded as IPv6 addresses, e.g.: .PP .Vb 1 \& ::ffff:192.168.0.5 .Ve .PP are supported, however an \s-1IP\s0 address submitted in this format as the \s-1IP\s0 to test for will be converted to a pure IPv4 address and compared only against the IPv4 networks. This is meant as a convenience to the developer supporting dual-stack systems to avoid having to list IPv4 networks in the array twice like so: .PP .Vb 1 \& ::ffff:192.168.0.0/120, 192.168.0.0/24 .Ve .PP Just list IPv4 as IPv4, IPv6 as IPv6, and this routine will convert IPv6\-encoded IPv4 addresses automatically. This would make the following test return a true value: .PP .Vb 1 \& ipInNetworks( \*(Aq::ffff:192.168.0.5\*(Aq, \*(Aq192.168.0.0/24\*(Aq ); .Ve .PP but .PP .Vb 1 \& ipInNetworks( \*(Aq::ffff:192.168.0.5\*(Aq, \*(Aq::ffff:192.168.0.0/120\*(Aq ); .Ve .PP return a false value. This may seem counter intuitive, but it simplifies things in (my alternate) reality. .PP Please note that this automatic conversion only applies to the \fB\s-1IP\s0\fR argument, not to any member of the network array. .SS "hostInDomains" .IX Subsection "hostInDomains" .Vb 1 \& $rv = hostInDomains($host, @domains); .Ve .PP This function checks the passed hostname (fully qualified) against each of the domains in the list and returns true if there's a match. None of the domains should have the preceding '.' (i.e., 'foo.com' rather than \&'.foo.com'). .SS "\s-1NETMATCH\s0" .IX Subsection "NETMATCH" .Vb 1 \& $cidr = Paranoid::Network::NETMATCH(); .Ve .PP This stores the \s-1IP,\s0 network address, or domain that matched in \&\fIipInNetworks\fR or \fIhostInDomains\fR. This returns \fBundef\fR if any function call fails to make a match. .SS "\s-1HOSTNAME_REGEX\s0" .IX Subsection "HOSTNAME_REGEX" .Vb 1 \& $rv = $hostname =~ /^@{[ HOSTNAME_REGEX ]}$/so; .Ve .PP This constant is just a regex meant to be a basic sanity check for appropriate hostnames. It is probably overly strict in accordance with outdated RFCs. .SS "extractIPs" .IX Subsection "extractIPs" .Vb 2 \& @ips = extractIPs($string1); \& @ips = extractIPs(@lines); .Ve .PP This function extracts IPv4/IPv6 addresses from arbitrary text. IPv6 support is contingent upon the presence of proper support (please see Paranoid::Network::Socket for more details). .PP This extracts only \s-1IP\s0 addresses, not network addresses in \s-1CIDR\s0 or dotted octet notation. In the case of the latter the netmask will be extracted as an additional address. .PP \&\fB\s-1NOTE:\s0\fR in the interest of performance this function does only rough regex extraction of IP-looking candidates, then runs them through \fBinet_aton\fR (for IPv4) and \fBinet_pton\fR (for IPv6) to see if they successfully convert. Even with the overhead of \fBParanoid\fR (with debugging and \fIloadModule\fR calls for Socket6 and what-not) it seems that this is an order of a magnitude faster than doing a pure regex extraction & validation of IPv6 addresses. .PP \&\fB\s-1NOTE:\s0\fR Like the \fBipInNetworks\fR function we filter out IPv4 addresses encoded as IPv6 addresses since that address is already returned as a pure IPv4 address. .SS "netIntersect" .IX Subsection "netIntersect" .Vb 1 \& $rv = netIntersect( $cidr1, $cidr2 ); .Ve .PP This function is an IPv4/IPv6 agnostic wrapper for the \fBipv{4,6}NetIntersect\fR functions provided by Paranoid::Network::IPv{4,6} modules. The return value from which ever function called is passed on directly. Passing this function non-IP or undefined values simply returns a zero. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" .IP "o" 4 .IX Item "o" Paranoid .IP "o" 4 .IX Item "o" Paranoid::Debug .IP "o" 4 .IX Item "o" Paranoid::Network::Socket .IP "o" 4 .IX Item "o" Paranoid::Network::IPv4 .IP "o" 4 .IX Item "o" Paranoid::Network::IPv6 .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" .SH "AUTHOR" .IX Header "AUTHOR" Arthur Corliss (corliss@digitalmages.com) .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" This software is licensed under the same terms as Perl, itself. Please see http://dev.perl.org/licenses/ for more information. .PP (c) 2005 \- 2017, Arthur Corliss (corliss@digitalmages.com)