# Copyright (c) 2013-2016 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Data::Checker::DNS - check data to see if it is valid in DNS

=head1 SYNOPSIS

   use Data::Checker;
   $obj = new Data::Checker;

   $obj->check($data,"DNS",$check_opts);

=head1 DESCRIPTION

This module is meant to be used by the L<Data::Checker> module.

One set of checks that is often done on sets of hostnames or IPs is to
check that they are defined in DNS.  This module provides several DNS
related checks that can be performed.  It uses the L<Net::DNS> module
to actually do the checks.

=head1 FUNCTIONS

=over 4

=item B<check>

This is the only function provided by this module, and it is
intended to be used by the L<Data::Checker> module.

=back

=head1 CHECKS OPTIONS

The C<$check_opts> hashref defines exactly what DNS checks to perform,
and some options used by those checks.  Known keys that specify the
checks are:

=over 4

=item qualified

If this keys is present, the hostname is tested to see if it
is fully qualified or not.  This check will fail on on IP.

This check does not actually do a DNS lookup.  Instead, it looks at the
hostname to see if is fully qualified or not.

If this is given, the host must be fully qualifed to pass (or
unqualifed if the 'negate' option is given).

=item dns

If this key is present, the hostname or IP is tested to see if it is
in DNS.  If it is defined in DNS, it passes.

This is the default check done, and if C<$check_opts> is not passed
in, this check will be performed.

=item expected_ip, expected_domain, expected_hostname

If any of these keys are present, the information in DNS is tested
to make sure that the values are as expected.

The expected value should be stored in the description passed to the check
function (see Data::Checker for more information), or in the 'value' option
in C<$check_opts>.

If the description is a hashref and there are keys 'ip', 'domain', or
'hostname' respectively, the values are either a string or a listref
of strings, and the value in DNS must match one of those strings.

Alternately, if the description does not exist or does not contain
those keys, the 'value' option in C<$check_opts> will be used.

If the 'negate' option is included, the values are restricted value
which cannot be used in DNS.

=back

The following keys can also be present to specify additional options:

=over 4

=item nameservers

This is a whitespace separated list of nameservers to use.

=back

=head1 EXAMPLES

All examples include the following lines:

   use Data::Checker;
   $obj = new Data::Checker;

   $data = ...
   $opts = ...

   ($pass,$fail,$info,$warn) = $obj->check($data,"DNS",$opts);

The value of C<$data> and C<$opts> is listed below in the examples.

=over 4

=item To check if a hostname is fully qualified

   $data = [ 'foo', 'bar.com' ];
   $opts = { 'qualified'  => undef };

This yields:

   $pass = [ 'bar.com' ]
   $fail = { 'foo' => [ 'Host is not fully qualified' ] }

=item To check if a hostname is NOT fully qualified:

   $data = [ 'foo', 'bar.com' ];
   $opts = { 'qualified' => { 'negate' => 1 } };

This yields:

   $pass = [ 'foo' ]
   $fail = { 'bar.com' => [ 'Host is fully qualified' ] }

=item To check that a host is in DNS:

   $data = [ 'cpan.org', 'aaa.bbb.ccc' ];
   $opts = { 'dns' => undef };

=item To check that a host has the expected IP in DNS

Current DNS shows:

   cpan.org        = 207.171.7.91
   blogs.perl.org  = 188.40.132.3

The test:

   $data = { 'cpan.org'       => { 'ip'  => '207.171.7.91' },
             'blogs.perl.org' => { 'ip'  => '100.101.102.103' }
           };
   $opts = { 'dns' => undef,
             'expected_ip' => undef };

Yields:

   $pass = { 'cpan.org'       => { 'ip'  => '207.171.7.91' } }
   $fail = { 'blogs.perl.org' => [ 'DNS IP value does not match expected value' ] }

=back

=head1 KNOWN BUGS AND LIMITATIONS

None known.

=head1 SEE ALSO

L<Data::Checker>, L<Net::DNS>

=head1 LICENSE

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

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut
