/ 
WebService-NFSN-1.04
River stage zero No dependents
/ WebService::NFSN::DNS

NAME

WebService::NFSN::DNS - Access NFSN DNS information

VERSION

This document describes version 1.04 of WebService::NFSN::DNS, released April 20, 2024 as part of WebService-NFSN version 1.04.

SYNOPSIS

use WebService::NFSN;

my $nfsn = WebService::NFSN->new($USER, $API_KEY);
my $expire = $nfsn->dns($DOMAIN)->expire;

DESCRIPTION

WebService::NFSN::DNS provides access to NearlyFreeSpeech.NET's DNS API. It is only useful to people who have websites hosted at NearlyFreeSpeech.NET.

All times are specified in seconds.

INTERFACE

$dns = $nfsn->dns($DOMAIN)

This constructs a new DNS object for the specified $DOMAIN (like 'example.com'). Equivalent to $dns = WebService::NFSN::DNS->new($nfsn, $DOMAIN).

Properties

$dns->expire( [$NEW_EXPIRE] )

Gets or sets the "expire" value for the domain. To quote RFC1912: "How long a secondary [nameserver] will still treat its copy of the zone data as valid if it can't contact the primary [nameserver]."

The expire value must be:

  • Between 86400 and 2678400, and

  • Greater than or equal to the refresh and retry values.

$dns->minTTL( [$NEW_TTL] )

Gets or sets the DNS minimum TTL (minTTL), the smallest TTL value (in seconds) allowed for any resource record in the zone. If a resource record has a smaller TTL value than minTTL, the server will substitute the minimum value.

The minimum value is 60 (one minute) and the maximum value is 2678400 (31 days).

$dns->refresh( [$NEW_REFRESH] )

Gets or sets the refresh value for the domain. To quote RFC 1912: "How often a secondary [nameserver] will poll the primary [name]server to see if the serial number for the zone has increased (so it knows to request a new copy of the data for the zone). Set this to how long your secondaries can comfortably contain out-of-date data." In other words, set this for the minimum amount of time you're willing to wait for a change you make to the domain's DNS records to propagate.

The refresh value must be:

  • Greater than or equal to the minTTL value, and

  • Less than or equal to the expire value.

$dns->retry( [$NEW_RETRY] )

Gets or sets the retry value for the domain. To quote RFC 1912: "If a secondary was unable to contact the primary at the last refresh, wait the retry value before trying again."

The retry value must be:

  • Greater than or equal to 60, and

  • Less than or equal to the expire value.

$dns->serial()

Returns the current serial value for this domain. To quote RFC 1912: "Each zone has a serial number associated with it. Its use is for keeping track of who has the most current data. If and only if the primary's serial number of the zone is greater will the secondary ask the primary for a copy of the new zone data (see special case below)." In other words, the serial indicates the "version" of the data.

The serial is maintained by the DNS system, and cannot be directly modified. You may, however, update the serial number in order to cause other nameservers to refresh any cached data in it by calling the updateSerial method.

$dns->sync()

Returns the fraction of NFSN's DNS servers that are up-to-date for this domain. This will be 1 if all servers are up-to-date, or 0 if no servers are up-to-date with a change you just made. A number between 0 and 1 (e.g. 0.5) indicates that some but not all servers are up-to-date. After making a DNS change, you may poll this property every few seconds to determine when it is safe to expect that NFSN's DNS responses will include that change. (But this does not consider third-party DNS servers that may have cached the previous record.)

Methods

Most DNS methods take 3 parameters:

name

Name of the resource record. This does not include the $DOMAIN associated with the DNS object; www means www.example.com (if the DNS object is for example.com). The empty string refers to the domain itself.

type

Type of the resource record. Must be one of: A, AAAA, CNAME, MX, NS, PTR, SRV, TXT.

data

Contents of the resource record. Must be in the same format as the "data" field in the member interface.

These are the methods:

$dns->addRR(name => $NAME, type => $TYPE, data => $DATA [,ttl => $TTL])

Adds a new resource record to the domain's DNS. Any record that can be added through the member interface can be added through this method as well, including the SPF Email Protection record.

The optional ttl parameter is the Time To Live value (in seconds) for the new record. It defaults to 3600 (1 hour).

$dns->listRRs([name => $NAME,] [type => $TYPE,] [data => $DATA])

Returns an array reference containing a hash reference for each matching record. All RR's except the SOA RR are eligible to be returned. (The SOA RR is accessed/manipulated directly through object methods.)

Each hash has the following fields: ttl, name, data, type, and scope. (scope is either "system" or "member").

All parameters are optional. If supplied, only records that exactly match the parameter(s) are returned.

$dns->removeRR(name => $NAME, type => $TYPE, data => $DATA)

Removes a resource record from the domain's DNS. Only "member" resource records (as indicated by their scope) and the SPF Email Protection resource record can be removed. The parameters must match an existing record.

$dns->updateSerial()

Updates the serial of this domain. See the serial property for more details.

This method is generally unnecessary. The serial is updated automatically when any change is made to the domain.

SEE ALSO

WebService::NFSN

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-WebService-NFSN AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=WebService-NFSN.

You can follow or contribute to WebService-NFSN's development at https://github.com/madsen/webservice-nfsn.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Christopher J. Madsen.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.