===============================                                     Written by:
The Dnsfile protocol, version 1                                Meilof Veeningen
===============================                                     August 2003

Introduction
============

The Dnsfile protocol is a protocol for sending files over the Domain Name
System.

Dnsfile file names and domain name representation
=================================================

The Dnsfile file tree is a file tree similar to the Unix file tree, that is,
the directory names and the file name are separated by slashes, where the name
of the file is the right of the file name.

File names are mapped to domain names in a very simple way: the file name is
split at the slashes, and each element becomes a DNS label, the order of the
elements is reversed. For example, the file name /var/posadis/pidfile would
become the domain name "pidfile.posadis.var". If there's a dot in an element
of the file name, it just becomes part of the filename, similar to the way dots
are allowed in the RNAME field of the SOA record. These domain names are
relative to the domain name at which the Dnsfile tree is being exported.

Dnsfile queries and answers
===========================

It is important to note that, while Dnsfile zones can become part of the
internet namespace, client applications using Dnsfile should not send their
queries to a recursive DNS server; queries should be sent to a Dnsfile server
directly. For files, the reason is obvious: we wouldn't want our recursive DNS
servers to store megabytes of files in their cache, now would we (and besides,
recursive DNS servers might rightly decide to refuse to answer these queries).

So, if a Dnsfile client wants to connect to a Dnsfile server, and the user
hasn't given the address of the Dnsfile server, the Dnsfile client should find
out the addresses of the Dnsfile server(s) by doing a NS query for the root of
the Dnsfile tree. To simplify things, all nameserver for the Dnsfile server
_should_ be inside the Dnsfile zone itself, that is, the zone should have glue
delegation. These NS and A records do not interfere with Dnsfile operations
because Dnsfile uses only TXT and NULL records. Apart from these NS and A (or
AAAA, or A6, at your opinion) records, there should be no other records in the
zone, except for an optional SOA record at the zone root.

Dnsfile clients should use TCP for their queries since the answers are very
likely to be too large for UDP packets. The TTL values of all records in the
dnsfile zone have the obvious meaning of how long the data may be considered
current.

Nameserver queries
------------------

Dnsfile clients send a {zone-root,NS} query if they want to find out the Dnsfile
servers for a given zone. The server answers with NS records for the nameservers
in the answer section of the message, and _all_ of their adresses in the
additional section.

File listings
-------------

A client can ask for a directory listing by doing a {domainname,TXT} query. If
the file doesn't exist, the server will answer with a NXDOMAIN. Else, the server
will answer by means of TXT records in the answer section (the server may
optionally include the NS records in the authority section, and the A records in
the additional section).

If the given filename refers to a directory, the answers are all TXT records
connected to the query domain name, containing two text entries in the RR data.
The first is the file name, which will end in a "/" if the file is a directory,
and the file size in bytes (without any thousands separator), or "d" if the file
is a directory.

If the given filename refers to a file, a TXT record is returned, connected to
the query domain name. Similar to the directory listing, the two elements in the
RR data are the filename (only the filename portion, e.g. "posadis.pdf" for
"/home/meilof/posadis.pdf"), and the filesize in bytes.

Downloading files
-----------------

A client can ask for a file download by doing a {domainname,NULL} query. The
client can choose only to download part of the file by adding an optional
TXT record to the answer section of the query, containing two entries in the
RR data: the offset (0 is the first byte of the file), and the number of bytes
to download. If no TXT record is in the answer section, an offset of zero, and
a file length of 65000 is assumed.

If the file doesn't exist, the server returns with an RCODE of NXDOMAIN. If the
file is not a regular file (e.g. a directory), the server returns NOTIMP. If
the file does exist, the server answers with the asked portion of the file as
a NULL record in the answer section. If requested_length + offset is larger
than the file size, the NULL RR should be filled with as much data as fits.

More information
================

For more information on the Dnsfile protocol, visit
  www.posadis.org/projects/dnsfile

If you have any questions, you can always reach the author at
  meilof@users.sourceforge.net