.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 "Net::Subnet 3pm" .TH Net::Subnet 3pm "2021-01-06" "perl v5.32.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" Net::Subnet \- Fast IP\-in\-subnet matcher for IPv4 and IPv6, CIDR or mask. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::Subnet; \& \& # CIDR notation \& my $is_rfc1918 = subnet_matcher qw( \& 10.0.0.0/8 \& 172.16.0.0/12 \& 192.168.0.0/16 \& ); \& \& # Subnet mask notation \& my $is_rfc1918 = subnet_matcher qw( \& 10.0.0.0/255.0.0.0 \& 172.16.0.0/255.240.0.0 \& 192.168.0.0/255.255.0.0 \& ); \& \& print $is_rfc1918\->(\*(Aq192.168.1.1\*(Aq) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq; # prints "yes" \& print $is_rfc1918\->(\*(Aq8.8.8.8\*(Aq) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq; # prints "no" \& \& # Mixed IPv4 and IPv6 \& my $in_office_network = subnet_matcher qw( \& 192.168.1.0/24 \& 2001:db8:1337::/48 \& ); \& \& $x = $in_office_network\->(\*(Aq192.168.1.1\*(Aq); # $x is true \& $x = $in_office_network\->(\*(Aq2001:db8:dead:beef::5\*(Aq); # $x is false \& \& my $classifier = subnet_classifier qw( \& 192.168.1.0/24 \& 2001:db8:1337::/48 \& 10.0.0.0/255.0.0.0 \& ); \& \& $x = $classifier\->(\*(Aq192.168.1.250\*(Aq); # $x is \*(Aq192.168.1.0/24\*(Aq \& $x = $classifier\->(\*(Aq2001:db8:1337::babe\*(Aq); # $x is \*(Aq2001:db8:1337::/48\*(Aq \& $x = $classifier\->(\*(Aq10.2.127.1\*(Aq); # $x is \*(Aq10.0.0.0/255.0.0.0\*(Aq \& $x = $classifier\->(\*(Aq8.8.8.8\*(Aq); # $x is undef \& \& # More specific subnets (smaller subnets) must be listed first \& my @subnets = sort_subnets( \& \*(Aq192.168.0.0/24\*(Aq, # second \& \*(Aq192.168.0.1/32\*(Aq, # first \& \*(Aq192.168.0.0/16\*(Aq, # third \& ); \& my $classifier = subnet_classifier @subnets; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a simple but fast pure Perl module for determining whether a given \s-1IP\s0 address is in a given set of \s-1IP\s0 subnets. It's iterative, and it doesn't use any fancy tries, but because it uses simple bitwise operations on strings it's still very fast. .PP All documented functions are exported by default. .PP Subnets have to be given in \*(L"address/mask\*(R" or \*(L"address/length\*(R" (\s-1CIDR\s0) format. The Socket and Socket6 modules are used to normalise addresses, which means that any of the address formats supported by inet_aton and inet_pton can be used with Net::Subnet. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "subnet_matcher(@subnets)" .IX Subsection "subnet_matcher(@subnets)" Returns a reference to a function that returns true if the given \s-1IP\s0 address is in \f(CW@subnets\fR, false it it's not. .SS "subnet_classifier(@subnets)" .IX Subsection "subnet_classifier(@subnets)" Returns a reference to a function that returns the element from \f(CW@subnets\fR that matches the given \s-1IP\s0 address, or undef if none matched. .SS "sort_subnets(@subnets)" .IX Subsection "sort_subnets(@subnets)" Returns \f(CW@subnets\fR in reverse order of prefix length and prefix; use this with subnet_matcher or subnet_classifier if your subnet list has overlapping ranges and it's not already sorted most-specific-first. .SH "TRICKS" .IX Header "TRICKS" .SS "Generating \s-1PTR\s0 records for IPv6" .IX Subsection "Generating PTR records for IPv6" If you need to classify an \s-1IP\s0 address, but want some other value than the original subnet string, just use a hash. You could even use code references; here's an example of how to generate dynamic reverse \s-1DNS\s0 records for IPv6 addresses: .PP .Vb 10 \& my %ptr = ( \& \*(Aq2001:db8:1337:d00d::/64\*(Aq => sub { \& my $hostname = get_machine_name(shift); \& return $hostname =~ /\e.$/ ? $hostname : "$hostname.example.org."; \& }, \& \*(Aq2001:db8:1337:babe::/64\*(Aq => sub { \& my $hostname = get_machine_name(shift); \& return $hostname =~ /\e.$/ ? $hostname : "$hostname.example.net."; \& }, \& \*(Aq::/0\*(Aq => sub { \& (my $ip = shift) =~ s/:/x/g; \& return "$ip.unknown.example.com."; \& }, \& ); \& my $classifier = subnet_classifier sort_subnets keys %ptr; \& \& while (my $ip = readline) { \& # We get IP addresses from STDIN and return the hostnames on STDOUT \& \& print $ptr{ $classifier\->($ip) }\->($ip), "\en"; \& } .Ve .SS "Matching ::ffff:192.168.1.200" .IX Subsection "Matching ::ffff:192.168.1.200" IPv4 subnets only match IPv4 addresses. If you need to match IPv4\-mapped IPv6 addresses, i.e. IPv4 addresses with \f(CW\*(C`::ffff:\*(C'\fR stuck in front of them, simply remove that part before matching: .PP .Vb 3 \& my $matcher = subnet_matcher qw(192.168.1.0/22); \& $ip =~ s/^::ffff://; \& my $boolean = $matcher\->($ip); .Ve .PP Alternatively, translate the subnet definition to IPv6 notation: \f(CW\*(C`1.2.3.0/24\*(C'\fR becomes \f(CW\*(C`::ffff:1.2.3.0/120\*(C'\fR. If you do this, hexadecimal addresses such as \&\f(CW\*(C`::ffff:102:304\*(C'\fR will also match, but IPv4 addresses without \f(CW\*(C`::ffff:\*(C'\fR will no longer match unless you include \f(CW\*(C`1.2.3.0/24\*(C'\fR as well. .PP .Vb 2 \& my $matcher = subnet_matcher qw(::ffff:192.168.1.0/118 192.168.1.0/22); \& my $boolean = $matcher\->($ip); .Ve .SH "CAVEATS" .IX Header "CAVEATS" No argument verification is done; garbage in, garbage out. If you give it hostnames, \s-1DNS\s0 may be used to resolve them, courtesy of the Socket and Socket6 modules. .SH "AUTHOR" .IX Header "AUTHOR" Juerd Waalboer .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.