======                                              DISview [601]
domain
======


The 'domain' commands control the nodename-to-Internet-address
mapping software.

NET translates Internet nodenames (e.g. "dowrmain.demon.co.uk")
to corresponding IP addresses (e.g. "158.152.123.251") through
the use of an Internet Domain Name resolver and a local "cache" 
file, ~/domain.txt.

Whenever the user specifies a nodename, the local cache is
searched for the desired entry.  If it is present, it is used; if
not, and if domain name server(s) have been configured, a query
is sent over the network to the server(s).

If a server responds with the required information, the answer
is added to the ~/domain.txt file for future use.  If the server 
does not respond, any additional servers on the list are tried 
in a round-robin fashion until one responds, or the retry limit
is reached (see the 'domain retry' command).

If ~/domain.txt does not contain the desired entry and there are
no configured domain name servers (unlikely in a Demon dial-up
scenario), then the request immediately fails.

If a domain name server is available, and if all references to
hosts in ~/autoexec.net are in IP address format, then it is
possible to start with a completely empty ~/domain.txt file and
have YAN build it for you. This is the usual mechanism when
using Demon.

However, you may wish to add your own entries to ~/domain.txt,
either because you prefer to use symbolic domain names in your
~/autoexec.net file or you don't have access to a domain server
and you need to create entries for all of the hosts you may wish
to access.

It is also useful to put your own IP address and MX record in 
~/domain.txt, as in the example below. This is handy for testing
your own system off-line. N.B. All names in ~/domain.txt are
Fully-Qualified-Domain-Names -- they _MUST_ end with a dot.



>> Example of ~/domain.txt:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
dowrmain.demon.co.uk.          IN A     158.152.123.251
dowrmain.demon.co.uk.          IN MX 0  dowrmain.demon.co.uk.
disabuse.demon.co.uk.  601191  IN A     158.152.1.44
ftp.demon.co.uk.       82791   IN CNAME disabuse.demon.co.uk.
demon.co.uk.           601191  IN NS    gate.demon.co.uk.
demon.co.uk.           601191  IN NS    ns2.demon.net.
demon.co.uk.           601191  IN NS    ns.demon.co.uk.
demon.co.uk.           82791   IN NS    dns0.britain.eu.net.
gate.demon.co.uk.      601191  IN A     158.152.1.65
ns2.demon.net.         82791   IN A     192.68.174.95
ns.demon.co.uk.        601191  IN A     158.152.1.193
dns0.britain.eu.net.   107386  IN A     192.91.199.4
post.demon.co.uk.      32841   IN A     158.152.1.72

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


----------------
Resource Records
----------------
Each entry in ~/domain.txt is known as a Resource Record (RR). 
The fields are separated by any combination of tabs or spaces. 

The first field usually contains either a domain name or a host's
Fully-Qualified-Domain-Name (FQDN). The FQDN is the nodename 
terminated with a trailing dot.

The next field may contain a (usually large) decimal number. This
is a Time-to-Live (TTL) number in seconds. When this number falls
to zero the record is deleted (if the "clean" flag is on -- see
the 'domain cache clean' command).

If there is no TTL value in the record, this is a permanent 
record and is never deleted.

The next field contains the letters "IN", indicating that this is
an INternet record.

The next field specifies the record type. The most common types
are:
   A        Address
   CNAME    Canonical name (alias)
   HINFO    Host Information
   MB       Mail Box
   MG       Mail Group
   MINFO    Mail Information
   MR       Mail Rename
   MX       Mail Exchanger
   NS       Name Server
   PTR      Domain Name Pointer (reverse lookup)
   SOA      Start of Authority
   TXT      Text
   WKS      Well-known Services

The final field contains data which corresponds to the record 
type.

[See the book "DNS and BIND" by Paul Albitz and Cricket Liu,
published by O'Reilly & Associates Inc, for much more detail].


The 'domain' commands are now described:
_________________________________________________________________
domain addserver <ip_address|nodename>
_________________________________________________________________
Add a DNS server to the list of name servers.

>> Examples: domain addserver 158.152.1.43
             domain addserver 158.152.1.58


_________________________________________________________________
domain cache clean [off|on]                          Default: off
_________________________________________________________________
Display or set the discarding of expired resource records.
Expired records have their timeout value decremented to zero.

Normally resource records get a default timeout value of 1800
seconds.  After this time they are considered "old" and if
referenced again the domain name resolver should be enquired
again.

When 'clean' is off, expired records will be retained; if no
replacement can be obtained from another domain name server,
these records will continue to be used.

When 'clean' is on, expired records will be removed from the file
whenever any new record is added to the file.

>> Example:  domain cache clean on


_________________________________________________________________
domain cache list
_________________________________________________________________
List the current contents of the local in-memory cache.

>> Example:  domain cache list


_________________________________________________________________
domain cache size [<entries>]                         Default: 20
_________________________________________________________________
Display or set the nominal maximum size of the local memory
cache.

Note: The cache may be temporarily larger when waiting for new
records to be written to ~/domain.txt.

>> Example:  domain cache size 100


_________________________________________________________________
domain cache wait <seconds>                          Default: 300
_________________________________________________________________
Display or set the interval to wait for additional activity
before updating ~/domain.txt.

>> Example:  domain cache wait 600


_________________________________________________________________
domain dropserver <ip_address|nodename>
_________________________________________________________________
Remove a DNS server from the list of name servers. You are warned
when you delete the last name server.

>> Example:  domain dropserver 158.152.1.65


_________________________________________________________________
domain list
_________________________________________________________________
List the currently configured domain name servers, along with
statistics on how many queries and replies have been exchanged
with each one, response times, etc.

DNS servers are queried in the order shown in the list. The most-
recently added server is at the top of the list -- thus the 
server which is most likely to provide an answer should be added
last.

The output from this command also states whether or not the 
built-in DNS server is running, and lists the domain(s) which the
built-in server is primary for (see the 'domain startdns'
command).

>> Example:  domain list


_________________________________________________________________
domain maxwait <seconds>                              Default: 60
_________________________________________________________________
This sets a timeout value (1 to 255 seconds) to a query or domain
name server.  This is not set for an already defined server, but
will be used for a newly defined name server.  Also the value is
used for domain nslookups. 

>> Example:  domain maxwait 120


_________________________________________________________________
domain query <ip_address|nodename> [</logfile>]
_________________________________________________________________
Send a query to a domain server asking for all resource records
associated with this <nodename>, and list the records.
If the logfile parm is included, the output is automatically
logged into the specified file.

>> Example:  domain query dowrmain.demon.co.uk


_________________________________________________________________
domain qtype <type|TYPE>                             Default: 255
_________________________________________________________________
Display or set the type of domain query. 

TYPE    <type>                     Meaning
----    ------ -------------------------------------------------- 
A          1   a host address
NS         2   an authoritative name server
MD         3   a mail destination (Obsolete - use MX)
MF         4   a mail forwarder (Obsolete - use MX)
CNAME      5   the canonical name for an alias
SOA        6   marks the start of a zone of authority
MB         7   a mailbox domain name (EXPERIMENTAL)
MG         8   a mail group member (EXPERIMENTAL)
MR         9   a mail rename domain name (EXPERIMENTAL)
NULL      10   a null RR (EXPERIMENTAL)
WKS       11   a well known service description
PTR       12   a domain name pointer
HINFO     13   host information
MINFO     14   mailbox or mail list information
MX        15   mail exchange
TXT       16   text strings
NSAP      22   Network Service Access Protocol
NSAP-PTR  23   Network Service Access Protocol PTR
AXFR     252   a request for a transfer of an entire zone
MAILB    253   a request for mbox-related records (MB, MG or MR)
MAILA    254   a request for mail agent RRs (Obsolete - see MX)
*        255   a request for all records


>> Examples:  domain qtype 1    (for host address records)
              domain qtype mx   (for MX records)
              domain qtype 255  (for all records)

_________________________________________________________________
domain retry [<n>]                                     Default: 2
_________________________________________________________________
Display or set the number of attempts to reach each server on the
list during one call to the resolver.  If this count is exceeded,
a failure indication is returned.

If set to 0, the list will cycle forever; this may be useful for
unattended operation.

>> Example:  domain retry 10


_________________________________________________________________
domain startdns
_________________________________________________________________
Start the built-in DNS server. This gives YAN the ability to act 
as a nameserver for local domains. It works in a similar way to 
the Unix 'named'. The addition of the built-in nameserver enables
a machine running YAN to be used as the gateway between DIS and a
DIS mail-forwarding or commercial IP site.

>> Example:  domain startdns

The configuration file ~/named.boo defines the domain(s) for 
which the server is authoritative.

>> Example of ~/named.boo:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
primary    fred.org    fred.zon

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


The zone file(s) live in directory ~/spool/zones.

>> Example of ~/spool/zones/fred.zon:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@         IN SOA fred.org. hostmaster.fred.org. (
                    920911001   ; Serial
                    86400       ; Refresh 24 hours
                    1800        ; Retry 1/2 hour
                    360000      ; Expire 100 hours (about 4 days)
                    86400 )     ; Minimum 24 Hours

localhost IN A      127.0.0.1

fred      IN A      192.168.0.14

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note that the mail system uses any information available from the
local nameserver and will respect any MX records it finds. This 
means that if you decide to be primary for your own domain you 
must include the relevant MX records for any machines that will 
be receiving mail.


_________________________________________________________________
domain stopdns
_________________________________________________________________
Stop the built-in DNS server.

>> Example:  domain stopdns


_________________________________________________________________
domain suffix [<domain_name>]
_________________________________________________________________
Display or specify the default domain name suffix to be appended
to a host name when it contains no dots.

For example, if the suffix is set to 'demon.co.uk' and the user
enters 'telnet dowrmain', the domain resolver will attempt to 
find 'dowrmain.demon.co.uk'.

If the host name being sought contains one or more dots, however,
the default suffix is _not_ applied (e.g. 'telnet foo.bar' would
_not_ be turned into 'telnet foo.bar.demon.co.uk').

If the suffix is an empty string, with no dot, the current suffix
is cleared.

>> Example:  domain suffix demon.co.uk


_________________________________________________________________
domain trace [on|off]                                Default: off
_________________________________________________________________
Display or set the flag controlling the tracing of domain server
requests and responses.  Trace messages will be seen only if a
domain name being sought is not found in the local cache file,
~/domain.txt.

>> Example:  domain trace on
