1Data::Validate::Domain(U3s)er Contributed Perl DocumentatDiaotna::Validate::Domain(3)
2
6 Data::Validate::Domain - Domain and host name validation
7
9 version 0.15
10
12 use Data::Validate::Domain qw(is_domain);
13 # as a function
15 my $test = is_domain($suspect);
16 die "$test is not a domain" unless $test;
17 # or
19 die "$test is not a domain" unless is_domain($suspect, \%options);
21 # or as an object
23 my $v = Data::Validate::Domain->new(%options);
24 die "$test is not a domain" unless $v->is_domain($suspect);
26
28 This module offers a few subroutines for validating domain and host
29 names.
30
32 All of the functions below are exported by default.
33 All of the functions return an untainted value on success and a false
35 value ("undef" or an empty list) on failure. In scalar context, you
36 should check that the return value is defined, because something like
37 "is_domain_label('0')" will return a defined but false value.
38 The value to test is always the first (and often only) argument.
40 Note that none of these functions test whether a domain or hostname is
42 actually resolvable or reachable.
43 Data::Validate::Domain->new()
45 This method constructs a validation object. It accepts the following
46 arguments:
47 • domain_allow_underscore
49 According to RFC underscores are forbidden in hostnames but not
51 domain names. By default "is_domain()", "is_domain_label()", and
52 "is_hostname()" will fail if the value to be checked includes
53 underscores. Setting this to a true value will allow the use of
54 underscores in all functions.
55 • domain_allow_single_label
57 By default "is_domain()" will fail if you ask it to verify a domain
59 that only has a single label i.e. "neely.cx" is good, but "com"
60 would fail. If you set this option to a true value then
61 "is_domain()" will allow single label domains through. This is most
62 likely to be useful in combination with the "domain_private_tld"
63 argument.
64 • domain_disable_tld_validation
66 Disables TLD validation for "is_domain()". This may be useful if
68 you need to check domains with new gTLDs that have not yet been
69 added to Net::Domain::TLD.
70 • domain_private_tld
72 By default "is_domain()" requires all domains to have a valid
74 public TLD (i.e. com, net, org, uk, etc). This is verified using
75 the Net::Domain::TLD module. This behavior can be extended in two
76 different ways. You can provide either a hash reference where
77 additional TLDs are keys or you can supply a regular expression.
78 NOTE: The TLD is normalized to the lower case form prior to the
80 check being done. This is done only for the TLD check, and does not
81 alter the output in any way.
82 Hashref example:
84 domain_private_tld => {
86 privatetld1 => 1,
87 privatetld2 => 1,
88 }
89 Regular expression example:
91 domain_private_tld => qr /^(?:privatetld1|privatetld2)$/,
93 is_domain($domain, \%options)
95 This can be called as either a subroutine or a method. If called as a
96 sub, you can pass any of the arguments accepted by the constructor as
97 options. If called as a method, any additional options are ignored.
98 This returns the untainted domain name if the given $domain is a valid
100 domain.
101 A dotted quad (such as 127.0.0.1) is not considered a domain and will
103 return false. See Data::Validate::IP for IP Validation.
104 Per RFC 1035, this sub does accept a value ending in a single period
106 (i.e. "domain.com.") to be a valid domain. This is called an absolute
107 domain name, and should be properly resolved by any DNS tool (tested
108 with "dig", "ssh", and Net::DNS).
109 From RFC 952
111 A "name" (Net, Host, Gateway, or Domain name) is a text string up
112 to 24 characters drawn from the alphabet (A-Z), digits (0-9), minus
113 sign (-), and period (.). Note that periods are only allowed when
114 they serve to delimit components of "domain style names".
115 No blank or space characters are permitted as part of a
117 name. No distinction is made between upper and lower case. The first
118 character must be an alpha character [Relaxed in RFC 1123] . The last
119 character must not be a minus sign or period.
120 From RFC 1035
122 labels 63 octets or less
123 names 255 octets or less
124 [snip] limit the label to 63 octets or less.
126 To simplify implementations, the total length of a domain name (i.e.,
128 label octets and label length octets) is restricted to 255 octets or
129 less.
130 From RFC 1123
132 One aspect of host name syntax is hereby changed: the
133 restriction on the first character is relaxed to allow either a
134 letter or a digit. Host software MUST support this more liberal
135 syntax.
136 Host software MUST handle host names of up to 63 characters and
138 SHOULD handle host names of up to 255 characters.
139 is_hostname($hostname, \%options)
141 This can be called as either a subroutine or a method. If called as a
142 sub, you can pass any of the arguments accepted by the constructor as
143 options. If called as a method, any additional options are ignored.
144 This returns the untainted hostname if the given $hostname is a valid
146 hostname.
147 Hostnames are not required to end in a valid TLD.
149 is_domain_label($label, \%options)
151 This can be called as either a subroutine or a method. If called as a
152 sub, you can pass any of the arguments accepted by the constructor as
153 options. If called as a method, any additional options are ignored.
154 This returns the untainted label if the given $label is a valid label.
156 A domain label is simply a single piece of a domain or hostname. For
158 example, the "www.foo.com" hostname contains the labels "www", "foo",
159 and "com".
160
162 [RFC 1034] [RFC 1035] [RFC 2181] [RFC 1123]
163 Data::Validate
165 Data::Validate::IP
166
168 Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
169 Data::Validate module.
170 Thanks to Len Reed <lreed@levanta.com> for helping develop the options
172 mechanism for Data::Validate modules.
173
175 Bugs may be submitted at
176 <https://github.com/houseabsolute/Data-Validate-Domain/issues>.
177 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
179
181 The source code repository for Data-Validate-Domain can be found at
182 <https://github.com/houseabsolute/Data-Validate-Domain>.
183
185 • Neil Neely <neil@neely.cx>
186 • Dave Rolsky <autarch@urth.org>
188
190 • Anirvan Chatterjee <anirvan@users.noreply.github.com>
191 • David Steinbrunner <dsteinbrunner@pobox.com>
193 • Felipe Gasper <felipe@felipegasper.com>
195 • Gregory Oschwald <goschwald@maxmind.com>
197
199 This software is copyright (c) 2021 by Neil Neely.
200 This is free software; you can redistribute it and/or modify it under
202 the same terms as the Perl 5 programming language system itself.
203 The full text of the license can be found in the LICENSE file included
205 with this distribution.
206perl v5.36.0 2022-07-22 Data::Validate::Domain(3)