SOA RRs

From: https://www.zytrax.com/books/dns/ch8/soa.html

Intro
Format
Notes
Examples


Start of Authority Resource Record (SOA RR)
Defined in RFC 1035. The SOA defines the global parameters for the zone
(domain). Only one SOA resource record (RR) is allowed in a zone file and it
must be the first RR in the zone. (Though it may follow $ORIGIN or $TTL
directives.)



Format


owner-name
ttl
class
rr
name-server email-addr (sn ref ret ex min)
example.com. IN SOA ns.example.com. hostmaster.example.com. (
2003080800 ; sn = serial number
172800 ; ref = refresh = 2d
900 ; ret = update retry = 15m
1209600 ; ex = expiry = 2w
3600 ; nx = nxdomain ttl = 1h
)
; the following are also valid using @ and blank 
@  IN SOA ns.example.com. hostmaster.example.com. (
  IN SOA ns.example.com. hostmaster.example.com. (

NOTE: We are reliably informed that while a blank is a perfectly
 valid format certain DNSSEC signing tools may choke on this format.
The most complex and most critical record in the zone file. The following
notes apply:


Field
Description
owner-name 	

Generically this is a normal owner or label field. I is the 'root name' or
the apex of the zone. Most commonly written as @ (which substitutes the
$ORIGIN) but can be the explicit base Domain Name in FQDN format (which is
the same as the $ORIGIN or its synthesized version) as shown above.

ttl 	

Standard TTL values apply (range 0 to 2147483647 clarified by RFC 2181). A
Slave DNS does not use this TTL value but various parameters defined within
the SOA RR - see below. For more information about TTL values.

class 	

Defines the class of record and normally takes the value IN = Internet
(Defaulted ii not present). It may also take the value HS = Hesiod and CH =
Chaos both historic MIT protocols.

name-server 	

Any name server that will respond authoritatively for the domain. Called the
Primary Master in the context of Dynamic DNS (DDNS). If DDNS is not used
this may be any suitable name server either within the zone file (in-zone)
or in an external or foreign zone (also called out-of-zone or even out-of
-bailiwick by those of a more literary bent or with a taste for the exotic).
To mimimise confusion this is most commonly written as a Fully-qualified
Domain Name (FQDN - ends with a dot). If the record points to an EXTERNAL
server (not defined in this zone) it MUST be a FQDN and end with a '.'
(dot), for example, ns1.example.net. If the name server is within this
domain (in this zone file) it can be written as ns1 (without the dot) which
will be expanded to include the $ORIGIN. In the jargon this field is called
MNAME field which is why we called it name-server. When to use the dot.

email-addr 	

Email address of the person responsible for this zone and to which email may
be sent to report errors or problems. In the jargon this is called the RNAME
field which is why we called it email-addr. The email address of a suitable
DNS admin but more commonly the technical contact for the domain. By
convention (in RFC 2142) it is suggested that the reserved mailbox
hostmaster be used for this purpose but any sensible and stable email
address will work. NOTE: Format is mailbox-name.domain.com, for example,
hostmaster.example.com (uses a dot not the more normal @ sign, since @ has
other uses in the zone file) but mail is sent to hostmaster@example.com.
Most commonly ending with a '.' (dot) but if the email address lies within
this domain you can just use hostmaster (see also example below). when to
use the dot.

sn = serial number 	

Unsigned 32 bit value in range 1 to 4294967295 with a maximum increment of
2147483647. In BIND implementations this is defined to be a 10 digit field.
This value MUST increment when any resource record in the zone file is
updated. A slave (Secondary) DNS server will read the master DNS SOA record
periodically, either on expiry of refresh (defined below) or when it
receives a NOTIFY and compares, arithmetically, its current value of sn with
that received from the master. If the sn value from the master is
arithmetically HIGHER than that currently stored by the slave then a zone
transfer (AXFR/IXFR) is initiated by the slave. If the value of sn from the
master DNS SOA is the same or LOWER then no zone transfer is initiated. The
convention is to use a date based sn value to simplify the task of
incrementing the sn - the most popular convention being yyyymmddss where
yyyy = year, mm = month and dd = day ss = a sequence number in case you
update it more than once in the day! Using this date format convention the
value 2005021002 indicates the last update was on the 10th February 2005 and
it was the third update that day. The date format is just a convention, not
a requirement, so BIND (or any other DNS software) will not validate the
contents of this field. It is easy to make mistakes and get serial numbers
out of sequence. Fix Serial Numbers.


Note: the arithmetic used by the serial number is defined in RFC 1982.

refresh 	

Signed 32 bit time value in seconds. Indicates the time when the slave will
try to refresh the zone from the master (by reading the master DNS SOA RR).
RFC 1912 recommends 1200 to 43200 seconds, low (1200) if the data is
volatile or 43200 (12 hours) if it's not. If you are using NOTIFY you can
set it to much higher values, for instance, 1 or more days (> 86400
seconds). BIND Time format.

retry 	

Signed 32 bit value in seconds. Defines the time between retries if the
slave (secondary) fails to contact the master when refresh (above) has
expired or a NOTIFY message is received. Typical values would be 180 (3
minutes) to 900 (15 minutes) or higher. BIND Time format.

expiry 	

Signed 32 bit value in seconds. Indicates when the zone data is no longer
authoritative. Used by Slave (Secondary) servers only. BIND9 slaves stop
responding authoritatively to queries for the zone when this time has
expired and no contact has been made with the master. Thus, every time the
refresh values expires (or a NOTIFY message is received) the slave will
attempt to read the SOA record from the zone master - and initiate a zone
transfer AXFR/IXFR if sn is HIGHER. If contact is made the expiry and
refresh values are reset and the cycle starts again. If the slave fails to
contact the master it will retry every retry period but continue to respond
authoritatively for the zone until the expiry value is reached at which
point it will stop answering authoritatively for the domain. RFC 1912
recommends 1209600 to 2419200 seconds (2-4 weeks) to allow for major outages
of the zone master. BIND Time format.

nx = nxdomain ttl 	

Signed 32 bit value in seconds. RFC 2308 (implemented by BIND 9) redefined
this value to be the negative caching time - the time a NAME ERROR =
NXDOMAIN result may be cached by any resolver. The maximum value allowed by
RFC 2308 for this parameter is 3 hours (10800 seconds). Note: This value was
historically (in BIND 4 and 8) used to hold the default TTL value for any RR
from the zone that did not specify an explicit TTL. RFC 2308 (and BIND 9)
uses the $TTL directive as the zone default TTL. You may find older
documentation or zone file configurations which reflect the old usage. BIND
Time format.




Notes:
BIND and most other DNS software will accept time values in a number of
formats, for example, 1h 3m etc.. Saves all that work with the calculator.
The opening '(' (bracket) MUST appear on the same line as the SOA record.
This is defined in RFC 1035 and BIND will reject the whole zone if this rule
is broken. The terminating ')' (bracket) can appear on any line as shown in
the examples.
The name server defined in the SOA record will ALWAYS have a NS record
(there may be more than one NS record). For the sake of completeness the NS
record is shown in the example fragments.



Examples
; zone file fragment for example.com
; both name servers are out-of-zone (or out-of-bailiwick)
$TTL 2d ; zone TTL default = 2 days or 172800 seconds
$ORIGIN example.com.
@ IN SOA ns.example.net. hostmaster.example.com. (
 2003080800 ; serial number
 1d12h ; refresh = 1 day 12 hours
 15M ; update retry = 15 minutes
 3W12h ; expiry = 3 weeks + 12 hours
 2h20M ; minimum = 2 hours + 20 minutes
 )
 IN NS ns.example.net. ; out-of-zone name server
 IN NS ns.example.org. ; out-of-zone name server
; since both name servers are out-of-zone (or out-of-bailiwick)
; no A RRs are required (and will be rejected if present)

The email address in the SOA lies within the domain and can be written as an
unqualified (no-dot) name:
; zone file fragment for example.com
; both name servers are out-of-zone (or out-of-bailiwick)
$TTL 2d ; zone TTL default = 2 days or 172800 seconds
$ORIGIN example.com.
@ IN SOA ns.example.net. hostmaster (
 2003080800 ; serial number
 1d12h ; refresh = 1 day 12 hours
 15M ; update retry = 15 minutes
 3W12h ; expiry = 3 weeks + 12 hours
 2h20M ; minimum = 2 hours + 20 minutes
 )
 IN NS ns.example.net. ; out-of-zone
 IN NS ns.example.org. ; out-of-zone
; since both name servers are out-of-zone (or out-of-bailiwick)
; no A RRs are required (and will be rejected if present)

The master DNS is within the domain. The second name server is not:
; zone file fragment for example.com 
$TTL 2d ; zone TTL default = 2 days or 172800 seconds
$ORIGIN example.com.
@ IN SOA ns.example.com. hostmaster.example.com. (
 2003080800 ; serial number
 1d12h ; refresh = 1 day 12 hours
 15M ; update retry = 15 minutes
 3W12h ; expiry = 3 weeks + 12 hours
 2h20M ; minimum = 2 hours + 20 minutes
 )
 IN NS ns.example.com.
 IN NS ns.example.net. ; out-of-zone 
...
; A record for ns.example.com. RR above
ns IN A 192.168.2.1
; the above could have been written as
; ns.example.com. IN A 192.168.2.1
; ns.example.net is out-of-zone (or out-of-bailiwick)
; an A RRs is not required (and will be rejected if present)

The above rewritten to use unqualified names:
$TTL 2d ; zone TTL default = 2 days or 172800 seconds
$ORIGIN example.com.
@ IN SOA ns hostmaster (
 2003080800 ; serial number
 1d12h ; refresh = 1 day 12 hours
 15M ; update retry = 15 minutes
 3W12h ; expiry = 3 weeks + 12 hours
 2h20M ; minimum = 2 hours + 20 minutes
 )
 IN NS ns
 IN NS ns.example.net. ; out-of-zone 
...
; A record for the NS RR above
ns IN A 192.168.2.1
; the above could have been written as
; ns.example.com. IN A 192.168.2.1
; ns.example.net is out-of-zone (or out-of-bailiwick)
; an A RRs is not required (and will be rejected if present)

owner-name	class	rr	name-server email-addr (sn ref ret ex min)
example.com.	IN	SOA	ns.example.com. hostmaster.example.com. (
			2003080800 ; sn = serial number
			172800 ; ref = refresh = 2d
			900 ; ret = update retry = 15m
			1209600 ; ex = expiry = 2w
			3600 ; nx = nxdomain ttl = 1h
			)
; the following are also valid using @ and blank
@	IN	SOA	ns.example.com. hostmaster.example.com. (
	IN	SOA	ns.example.com. hostmaster.example.com. (

Field	Description
owner-name	Generically this is a normal owner or label field. I is the 'root name' or the apex of the zone. Most commonly written as @ (which substitutes the $ORIGIN) but can be the explicit base Domain Name in FQDN format (which is the same as the $ORIGIN or its synthesized version) as shown above.
ttl	Standard TTL values apply (range 0 to 2147483647 clarified by RFC 2181). A Slave DNS does not use this TTL value but various parameters defined within the SOA RR - see below. For more information about TTL values.
class	Defines the class of record and normally takes the value IN = Internet (Defaulted ii not present). It may also take the value HS = Hesiod and CH = Chaos both historic MIT protocols.
name-server	Any name server that will respond authoritatively for the domain. Called the Primary Master in the context of Dynamic DNS (DDNS). If DDNS is not used this may be any suitable name server either within the zone file (in-zone) or in an external or foreign zone (also called out-of-zone or even out-of -bailiwick by those of a more literary bent or with a taste for the exotic). To mimimise confusion this is most commonly written as a Fully-qualified Domain Name (FQDN - ends with a dot). If the record points to an EXTERNAL server (not defined in this zone) it MUST be a FQDN and end with a '.' (dot), for example, ns1.example.net. If the name server is within this domain (in this zone file) it can be written as ns1 (without the dot) which will be expanded to include the $ORIGIN. In the jargon this field is called MNAME field which is why we called it name-server. When to use the dot.
email-addr	Email address of the person responsible for this zone and to which email may be sent to report errors or problems. In the jargon this is called the RNAME field which is why we called it email-addr. The email address of a suitable DNS admin but more commonly the technical contact for the domain. By convention (in RFC 2142) it is suggested that the reserved mailbox hostmaster be used for this purpose but any sensible and stable email address will work. NOTE: Format is mailbox-name.domain.com, for example, hostmaster.example.com (uses a dot not the more normal @ sign, since @ has other uses in the zone file) but mail is sent to hostmaster@example.com. Most commonly ending with a '.' (dot) but if the email address lies within this domain you can just use hostmaster (see also example below). when to use the dot.
sn = serial number	Unsigned 32 bit value in range 1 to 4294967295 with a maximum increment of 2147483647. In BIND implementations this is defined to be a 10 digit field. This value MUST increment when any resource record in the zone file is updated. A slave (Secondary) DNS server will read the master DNS SOA record periodically, either on expiry of refresh (defined below) or when it receives a NOTIFY and compares, arithmetically, its current value of sn with that received from the master. If the sn value from the master is arithmetically HIGHER than that currently stored by the slave then a zone transfer (AXFR/IXFR) is initiated by the slave. If the value of sn from the master DNS SOA is the same or LOWER then no zone transfer is initiated. The convention is to use a date based sn value to simplify the task of incrementing the sn - the most popular convention being yyyymmddss where yyyy = year, mm = month and dd = day ss = a sequence number in case you update it more than once in the day! Using this date format convention the value 2005021002 indicates the last update was on the 10th February 2005 and it was the third update that day. The date format is just a convention, not a requirement, so BIND (or any other DNS software) will not validate the contents of this field. It is easy to make mistakes and get serial numbers out of sequence. Fix Serial Numbers. Note: the arithmetic used by the serial number is defined in RFC 1982.
refresh	Signed 32 bit time value in seconds. Indicates the time when the slave will try to refresh the zone from the master (by reading the master DNS SOA RR). RFC 1912 recommends 1200 to 43200 seconds, low (1200) if the data is volatile or 43200 (12 hours) if it's not. If you are using NOTIFY you can set it to much higher values, for instance, 1 or more days (> 86400 seconds). BIND Time format.
retry	Signed 32 bit value in seconds. Defines the time between retries if the slave (secondary) fails to contact the master when refresh (above) has expired or a NOTIFY message is received. Typical values would be 180 (3 minutes) to 900 (15 minutes) or higher. BIND Time format.
expiry	Signed 32 bit value in seconds. Indicates when the zone data is no longer authoritative. Used by Slave (Secondary) servers only. BIND9 slaves stop responding authoritatively to queries for the zone when this time has expired and no contact has been made with the master. Thus, every time the refresh values expires (or a NOTIFY message is received) the slave will attempt to read the SOA record from the zone master - and initiate a zone transfer AXFR/IXFR if sn is HIGHER. If contact is made the expiry and refresh values are reset and the cycle starts again. If the slave fails to contact the master it will retry every retry period but continue to respond authoritatively for the zone until the expiry value is reached at which point it will stop answering authoritatively for the domain. RFC 1912 recommends 1209600 to 2419200 seconds (2-4 weeks) to allow for major outages of the zone master. BIND Time format.
nx = nxdomain ttl	Signed 32 bit value in seconds. RFC 2308 (implemented by BIND 9) redefined this value to be the negative caching time - the time a NAME ERROR = NXDOMAIN result may be cached by any resolver. The maximum value allowed by RFC 2308 for this parameter is 3 hours (10800 seconds). Note: This value was historically (in BIND 4 and 8) used to hold the default TTL value for any RR from the zone that did not specify an explicit TTL. RFC 2308 (and BIND 9) uses the $TTL directive as the zone default TTL. You may find older documentation or zone file configurations which reflect the old usage. BIND Time format.