.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 2024-03-07 "perl v5.38.2" "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.10 2022/03/08 00:01:04 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 \&\fINETMATCH\fR and \fIHOSTNAME_REGEX\fR are not exported by default. .SH "IMPORT LISTS" .IX Header "IMPORT LISTS" This module exports the following symbols by default: .PP .Vb 1 \& ipInNetworks hostInDomains extractIPs netIntersect .Ve .PP The following specialized import lists also exist: .PP .Vb 3 \& List Members \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& all @defaults NETMATCH HOSTNAME_REGEX .Ve .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 IP (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 IP address or network addresses in CIDR 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 IP being tested will be ignored. .PP \&\fBNOTE:\fR IPv4 addresses encoded as IPv6 addresses, e.g.: .PP .Vb 1 \& ::ffff:192.168.0.5 .Ve .PP are supported, however an IP address submitted in this format as the IP 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 \fBIP\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 NETMATCH .IX Subsection "NETMATCH" .Vb 1 \& $cidr = Paranoid::Network::NETMATCH(); .Ve .PP This stores the IP, 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 HOSTNAME_REGEX .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 IP addresses, not network addresses in CIDR or dotted octet notation. In the case of the latter the netmask will be extracted as an additional address. .PP \&\fBNOTE:\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 \&\fBNOTE:\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 free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either: .PP .Vb 7 \& a) the GNU General Public License \& as published by the \& Free Software Foundation ; either version 1 \& , or any later version \& , or \& b) the Artistic License 2.0 \& , .Ve .PP subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark. .PP (c) 2005 \- 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 \- 2020, Paranoid Inc. (www.paranoid.com)