mainzelm
parent
0c0c27dcb5
commit
7e45f51298
|
|
@ -1,5 +1,11 @@
|
|||
\chapter{DNS Client Library}\label{cha:dns}
|
||||
|
||||
%
|
||||
\begin{description}
|
||||
\item[Used files:] dns.scm
|
||||
\item[Name of the package:] dns
|
||||
\end{description}
|
||||
%
|
||||
\section{Overview}
|
||||
The \ex{dns} structure contains a library for querying DNS servers.
|
||||
|
||||
Features:
|
||||
|
|
@ -21,26 +27,44 @@ the library. The supertype of these conditions is \exi{dns-error}.
|
|||
Returns a string with the description of the condition.
|
||||
\end{desc}
|
||||
|
||||
\defvar{parse-error}{condition}
|
||||
\defvarx{unexpected-eof-from-server}{condition}
|
||||
\defvarx{bad-address}{condition}
|
||||
\defvarx{no-nameservers}{condition}
|
||||
\defvarx{bad-nameserver}{condition}
|
||||
\defvarx{not-a-hostname}{condition}
|
||||
\defvarx{not-a-ip} {condition}
|
||||
|
||||
\defvarx {dns-format-error} {condition}
|
||||
\begin{desc}
|
||||
|
||||
\end{desc}
|
||||
\defvar {dns-format-error} {condition}
|
||||
\defvarx {dns-server-failure} {condition}
|
||||
\defvarx {dns-name-error} {condition}
|
||||
\defvarx {dns-not-implemented} {condition}
|
||||
\defvarx {dns-refused} {condition}
|
||||
|
||||
These conditons correspond to errors returned by the DNS server. They
|
||||
are all subtypes of the \exi{dns-server-error} condition which in
|
||||
turn is a subtype of \ex{dns-error}.
|
||||
\begin{desc}
|
||||
These conditons correspond to errors returned by the DNS server.
|
||||
They are all subtypes of the \exi{dns-server-error} condition which
|
||||
in turn is a subtype of \ex{dns-error}.
|
||||
\end{desc}
|
||||
\defun{dns-server-error?}{thing}{\boolean}
|
||||
\begin{desc}
|
||||
The predicate for \ex{dns-server-error} conditions.
|
||||
\end{desc}
|
||||
|
||||
\defun {dns-format-error?} {thing} {\boolean}
|
||||
\defunx {dns-server-failure?} {thing} {\boolean}
|
||||
\defunx {dns-name-error?} {thing} {\boolean}
|
||||
\defunx {dns-not-implemented?} {thing} {\boolean}
|
||||
\defunx {dns-refused?} {thing} {\boolean}
|
||||
\defun{parse-error?}{thing} {\boolean}
|
||||
\defunx{unexpected-eof-from-server?}{thing} {\boolean}
|
||||
\defunx{bad-address?}{thing} {\boolean}
|
||||
\defunx{no-nameservers?}{thing} {\boolean}
|
||||
\defunx{bad-nameserver?}{thing} {\boolean}
|
||||
\defunx{not-a-hostname?}{thing} {\boolean}
|
||||
\defunx{not-a-ip?}{thing} {\boolean}
|
||||
\defunx{dns-format-error?} {thing} {\boolean}
|
||||
\defunx{dns-server-failure?} {thing} {\boolean}
|
||||
\defunx{dns-name-error?} {thing} {\boolean}
|
||||
\defunx{dns-not-implemented?} {thing} {\boolean}
|
||||
\defunx{dns-refused?} {thing} {\boolean}
|
||||
\begin{desc}
|
||||
The type predicates for the conditions above.
|
||||
\end{desc}
|
||||
|
|
@ -49,80 +73,281 @@ turn is a subtype of \ex{dns-error}.
|
|||
\def\ipaddr{\textnormal{IP-address\xspace}}
|
||||
\def\fqdn{\textnormal{FQDN\xspace}}
|
||||
|
||||
\defun{dns-lookup-ip}{\fqdn [nameserver list]}{\fqdn}
|
||||
The library uses an internal store to cache data obtained from DNS
|
||||
servers. All procedures take a boolean flag \var{use-cache?} that
|
||||
indicates whether the cache should be used or not. \var{use-cache?}
|
||||
defaults to true.
|
||||
|
||||
\defun{dns-clear-cache!}{}{\undefined}
|
||||
\begin{desc}
|
||||
This procedure erases all information stored in the internal cache.
|
||||
\end{desc}
|
||||
|
||||
The library is further capable of parsing the contents of
|
||||
\texttt{/etc/resolv.conf} (see Section~\ref{sec:dns-rc}). The
|
||||
nameservers listed there are the default value for the optional
|
||||
argument \var{nameserver list} which many procedures of the library
|
||||
possess.
|
||||
|
||||
\defun{dns-lookup-ip}{\fqdn [nameserver list][use-cache?]}{\fqdn}
|
||||
\begin{desc}
|
||||
Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address.
|
||||
The optional argument specifes the nameservers to query, it defaults
|
||||
to the ones found in \texttt{/etc/resolv.conf}. \textbf{always uses
|
||||
the cache}
|
||||
The optional argument specifes the name servers to query, it defaults
|
||||
to the ones found in \texttt{/etc/resolv.conf}.
|
||||
\end{desc}
|
||||
|
||||
\defun{dns-lookup-ip}{\ipaddr [nameserver list]}{\fqdn}
|
||||
\defun{dns-lookup-ip}{\ipaddr [nameserver list][use-cache?]}{\fqdn}
|
||||
\begin{desc}
|
||||
Looks up the FQDN for the given IP address. The optional argument
|
||||
specifes the nameservers to query, it defaults to the ones found in
|
||||
\texttt{/etc/resolv.conf}. \textbf{always uses the cache}
|
||||
specifes the name servers to query, it defaults to the ones found in
|
||||
\texttt{/etc/resolv.conf}. \oops{use-cache? is not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\defun{dns-lookup-nameserver}{name/\ipaddr [nameserver list]}{\ipaddr list}
|
||||
\defun{dns-lookup-nameserver}{name/\ipaddr [nameserver list][use-cache?]}{\ipaddr list}
|
||||
\begin{desc}
|
||||
Looks up an authoritative nameserver for a hostname, returns a list
|
||||
of nameservers. The optional argument specifes the nameservers to
|
||||
Looks up an authoritative name server for a hostname, returns a list
|
||||
of name servers. The optional argument specifes the name servers to
|
||||
query, it defaults to the ones found in
|
||||
\texttt{/etc/resolv.conf}\textbf{Why a list if there is only one and
|
||||
why is there only one for wsi hosts?}\textbf{always uses the cache}
|
||||
\texttt{/etc/resolv.conf}\oops{use-cache? is not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\defun{dns-lookup-mail-exchanger}{name/\ipaddr [nameserver list]}{\fqdn list}
|
||||
\defun{dns-lookup-mail-exchanger}{name/\ipaddr [nameserver list][use-cache?]}{\fqdn list}
|
||||
\begin{desc}
|
||||
Looks up mail-exchangers for a hostname und returns them in a list
|
||||
sorted by preference. \textbf{Always uses the cache}\textbf{why is
|
||||
there only one MX for wsi?}
|
||||
sorted by preference. \oops{use-cache? is not implemented yet}
|
||||
\end{desc}
|
||||
\defun{socket-address->fqdn}{socket-address cache?}{\fqdn}
|
||||
\defun{socket-address->fqdn}{socket-address [use-cache?]}{\fqdn}
|
||||
\begin{desc}
|
||||
Returns the FQDN for of the address bound to argument. The argument
|
||||
\var{cache?} indicates whether the internal cache may be queried to
|
||||
obtain the information.
|
||||
obtain the information.\oops{use-cache? is required by the implmentation}
|
||||
\end{desc}
|
||||
|
||||
\defun{maybe-dns-lookup-name}{name}{\ipaddr or \sharpf}
|
||||
\defun{maybe-dns-lookup-name}{name [nameserver list][use-cache?]}{\ipaddr or \sharpf}
|
||||
\defunx{maybe-dns-lookup-ip}{\ipaddr}{\fqdn{} or \sharpf}
|
||||
\begin{desc}
|
||||
These procedures provide the same functionality as
|
||||
\ex{dns-lookup-name} and \ex{dns-lookup-ip} but return \sharpf{} in
|
||||
case of an \ex{dns-error}.
|
||||
case of an \ex{dns-error}.\oops{optional arguments not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\defun{host-fqdn} {name/socket-address}{\fqdn}
|
||||
\defunx{system-fqdn}{}{\fqdn}
|
||||
\defun{host-fqdn} {name/socket-address [nameserver list][use-cache?]}{\fqdn}
|
||||
\defunx{system-fqdn}{[nameserver list][use-cache?]}{\fqdn}
|
||||
\begin{desc}
|
||||
\ex{host-fqdn} returns the fully qualified domain name (FQDN) for its
|
||||
argument which can be either a unqualified host name or a socket
|
||||
address. The procedure \ex{system-fqdn} returns the FQDN of the
|
||||
current host.
|
||||
current host.\oops{optional arguments not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\section{Low-level Interface}
|
||||
|
||||
\defun{dns-lookup}{\fqdn/\ipaddr type [nameserver list]}{dns-message}
|
||||
\defun{dns-lookup}{\fqdn/\ipaddr type [nameserver list][use-cache?]}{dns-message}
|
||||
\begin{desc}
|
||||
This is the most general way to submit a DNS query. The return value
|
||||
is a DNS message.\textbf{need to explain dns-message}
|
||||
is a \ex{dns-message} structure:\oops{optional arguments not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\defun{show-dns-message}{dns-message}{\undefined}
|
||||
\defun{dns-message?}{thing}{\boolean}
|
||||
\defunx{dns-message-query}{dns-message}{message}
|
||||
\defunx{dns-message-reply}{dns-message}{message}
|
||||
\defunx{dns-message-cache?}{dns-message}{\boolean}
|
||||
\defunx{dns-message-protocol}{dns-message}{'udp or 'tcp}
|
||||
\defunx{dns-message-tried-nameservers}{dns-message}{}
|
||||
\begin{desc}
|
||||
Pretty prints a DNS message to standard output.
|
||||
\textbf{Better return a string}
|
||||
A \var{dns-message} records the query sent to the server and the
|
||||
reply from the server. It also contains information whether the
|
||||
library took the reply from the cache, which protocol was used and
|
||||
to which nameservers the query was sent.
|
||||
\end{desc}
|
||||
|
||||
\defun{domains-for-search}{}{\str list}
|
||||
\defun{pretty-print-dns-message}{dns-message [output-port]}{\undefined}
|
||||
\begin{desc}
|
||||
Parses \texttt{/etc/resolv.conf} and extracts the domains specified
|
||||
by the \texttt{search} keyword.
|
||||
Pretty prints a DNS message to \var{out-port} which defaults to the
|
||||
current output port.
|
||||
\end{desc}
|
||||
|
||||
\defun{message?}{thing}{\boolean}{}
|
||||
\defunx{message-header}{message}{header}
|
||||
\defunx{message-questions}{message}{question list}
|
||||
\defunx{message-answers}{message}{rr list}
|
||||
\defunx{message-nameservers}{message}{rr list}
|
||||
\defunx{message-additionals}{message}{rr list}
|
||||
\defunx{message-source}{message}{char list}
|
||||
\begin{desc}
|
||||
A \ex{message} represents the data sent to the DNS server or
|
||||
received from the DNS server. The DNS protocol uses the same message
|
||||
format for queries and replies. In queries only the header and the
|
||||
questions is present, a reply may contain answers, name servers and
|
||||
and additional informations as resource records. \ex{message-source}
|
||||
returns the actual data sent over the network.
|
||||
\end{desc}
|
||||
|
||||
\defun{header?}{thing}{\boolean}
|
||||
\defunx{header-id}{header}{number}
|
||||
\defunx{header-flags}{header}{flags}
|
||||
\defunx{header-question-count}{header}{number}
|
||||
\defunx{header-answer-count}{header}{number}
|
||||
\defunx{header-nameserver-count}{header}{number}
|
||||
\defunx{header-additional-count}{header}{number}
|
||||
\begin{desc}
|
||||
Every DNS message contains a header which stores information about
|
||||
the data present in the message and contains flags for the query.
|
||||
\end{desc}
|
||||
|
||||
\defun{flags?}{thing}{\boolean}
|
||||
\defunx{flags-query-type}{flags}{'query or 'response}
|
||||
\defunx{flags-opcode}{flags}{number}
|
||||
\defunx{flags-authoritative?}{flags}{\boolean}
|
||||
\defunx{flags-truncated?}{flags}{\boolean}
|
||||
\defunx{flags-recursion-desired?}{flags}{\boolean}
|
||||
\defunx{flags-recursion-available?}{flags}{\boolean}
|
||||
\defunx{flags-z}{flags}{0}
|
||||
\defunx{flags-response-code}{flags}{number}
|
||||
\begin{desc}
|
||||
Flags occur within the header of a DNS message. The boolean value
|
||||
returned from \ex{flags-authoritative} indicates whether the message
|
||||
was sent from a authoritative server, \ex{flags-truncated?} should
|
||||
always be \sharpf as the library automatically uses the TCP protocol
|
||||
is the UDP message size is not sufficied.
|
||||
\end{desc}
|
||||
|
||||
\defun{question?}{thing}{\boolean}
|
||||
\defunx{question-name}{question}{\str}
|
||||
\defunx{question-type}{question}{message-type}
|
||||
\defunx{question-class}{question}{message-class}
|
||||
\begin{desc}
|
||||
A question sent to the DNS server.
|
||||
\end{desc}
|
||||
The type and class of the question and answer are elements of
|
||||
enumerated types: \textbf{class doesn't start at 0}
|
||||
|
||||
\dfn{message-class}{class-name}{message-class}{syntax}
|
||||
\defunx{message-class?}{thing}{\boolean}
|
||||
\defunx{message-class-name}{message-class}{symbol}
|
||||
\defunx{message-class-number}{message-class}{number}
|
||||
\begin{desc}
|
||||
\ex{message-class} constructs a member of the enumeration,
|
||||
\ex{message-class?} is the type predicate, \ex{message-class-name}
|
||||
returns the symbol and \ex{message-class-number} the number used for
|
||||
the class in the DNS protocol.
|
||||
\end{desc}
|
||||
The possible names for the classes are:
|
||||
\begin{description}
|
||||
\item[\ex{in}] The Internet
|
||||
\item[\ex{cs}] obsolete
|
||||
\item[\ex{ch}] the CHAOS class
|
||||
\item[\ex{hs}] Hesoid
|
||||
\end{description}
|
||||
|
||||
\dfn{message-type}{type-name}{message-type}{syntax}
|
||||
\defunx{message-type?}{thing}{\boolean}
|
||||
\defunx{message-type-name}{message-type}{symbol}
|
||||
\defunx{message-type-index}{message-type}{number}
|
||||
\begin{desc}
|
||||
\ex{message-type} constructs a member of the enumeration from name
|
||||
\synvar{type-name} listed in Table~\ref{tab:message-types}.
|
||||
\ex{message-type?} is the type predicate, \ex{message-type-name}
|
||||
returns the name, and \ex{message-type-number} the number used for
|
||||
the class the DNS protocol.
|
||||
|
||||
\end{desc}
|
||||
\begin{table}[htb]
|
||||
\centering
|
||||
\begin{tabular}{|l|l|}
|
||||
\hline
|
||||
\ex{a}& a host address\\\hline
|
||||
\ex{ns}&an authoritative name server\\\hline
|
||||
\ex{md}&(obsolete)\\\hline
|
||||
\ex{mf}&(obsolete)\\\hline
|
||||
\ex{cname}&the canonical name for an alias\\\hline
|
||||
\ex{soa}& marks the start of a zone of authority\\\hline
|
||||
\ex{mb}&(experimental)\\\hline
|
||||
\ex{mg}&(experimental)\\\hline
|
||||
\ex{mr}&(experimental)\\\hline
|
||||
\ex{null}& (experimental)\\\hline
|
||||
\ex{wks}& a well known service description\\\hline
|
||||
\ex{ptr}& a domain name pointer\\\hline
|
||||
\ex{hinfo}& host information\\\hline
|
||||
\ex{minfo}& (experimental)\\\hline
|
||||
\ex{mx}& mail exchange\\\hline
|
||||
\ex{txt}& text strings\\\hline
|
||||
\end{tabular}
|
||||
\caption{Message types}
|
||||
\label{tab:message-types}
|
||||
\end{table}
|
||||
|
||||
\defun{rr?}{thing}{\boolean}
|
||||
\defunx{rr-name}{rr}{\str}
|
||||
\defunx{rr-type}{rr}{message-type}
|
||||
\defunx{rr-class}{rr}{message-class}
|
||||
\defunx{rr-ttl}{rr}{number}
|
||||
\defunx{rr-data}{rr}{rr-data-X}
|
||||
\begin{desc}
|
||||
A resource record as returned from the DNS server. The actual data
|
||||
of the record is stored in the \texttt{rr-data} field.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-a?}{thing}{\boolean}
|
||||
\defunx{rr-data-a-ip}{rr-data-a}{\ipaddr}
|
||||
\begin{desc}
|
||||
An address resource record which holds an internet address.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-ns?}{thing}{\boolean}
|
||||
\defunx{rr-data-ns-name}{rr-data-ns}{\fqdn}
|
||||
\begin{desc}
|
||||
A name server resource record containing the FQDN of the name server.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-cname?}{thing}{\boolean}
|
||||
\defunx{rr-data-cname}{rr-data-cname}{\fqdn}
|
||||
\begin{desc}
|
||||
A canonical name resource record which contains the canonical or
|
||||
primary name of the owner.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-mx?}{thing}{\boolean}
|
||||
\defunx{rr-data-mx-preference}{rr-data-mx}{number}
|
||||
\defunx{rr-data-mx-exchanger}{rr-data-mx}{\fqdn}
|
||||
\begin{desc}
|
||||
A mail exchange resource record with the preference and the FQDN of
|
||||
a host willing to act as a mail exchange.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-ptr?}{thing}{\boolean}
|
||||
\defunx{rr-data-ptr-name}{rr-data-ptr}{\str}
|
||||
\begin{desc}
|
||||
A pointer resource record which points to some other domain name.
|
||||
\end{desc}
|
||||
|
||||
\defun{rr-data-soa?}{thing}{\boolean}
|
||||
\defunx{rr-data-soa-mname}{rr-data-soa}{\fqdn}
|
||||
\defunx{rr-data-soa-rname}{rr-data-soa}{\fqdn}
|
||||
\defunx{rr-data-soa-serial}{rr-data-soa}{number}
|
||||
\defunx{rr-data-soa-refresh}{rr-data-soa}{number}
|
||||
\defunx{rr-data-soa-retry}{rr-data-soa}{number}
|
||||
\defunx{rr-data-soa-expire}{rr-data-soa}{number}
|
||||
\defunx{rr-data-soa-minimum}{rr-data-soa}{number}
|
||||
\begin{desc}
|
||||
A zone of authority resource record.
|
||||
\end{desc}
|
||||
The protocol specifies other possiple values for the \texttt{rr-data}
|
||||
field but we where no able to find test cases for them.
|
||||
|
||||
|
||||
\defun{cache?}{thing}{\boolean}
|
||||
\defunx{cache-answer}{cache}{dns-message}
|
||||
\defunx{cache-ttl}{cache}{number}
|
||||
\defunx{cache-time}{cache}{number}
|
||||
\begin{desc}
|
||||
A cache data structure corresponds to a saved answer to a previous
|
||||
query. \ex{cache-answer} returns the saved message, \ex{cache-ttl}
|
||||
returns the time when the cache entry expires and \ex{cache-time}
|
||||
returns the time the entry was created.
|
||||
\end{desc}
|
||||
|
||||
|
||||
\section{Host Names}
|
||||
\defun{is-fqdn?}{\str}{\boolean}
|
||||
\begin{desc}
|
||||
|
|
@ -131,15 +356,28 @@ turn is a subtype of \ex{dns-error}.
|
|||
\oops{The current implementation simply searches for a dot in the name}
|
||||
\end{desc}
|
||||
|
||||
\defun{unqualified-hostname}{\str}{\boolean}
|
||||
\defun{unqualified-hostname?}{\str}{\boolean}
|
||||
\begin{desc}
|
||||
Returns true if the argument matches the grammar for a unqualified
|
||||
host name
|
||||
host name.
|
||||
\oops{This procedure isn't implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\section{Parsing \texttt{/etc/resolv.conf}}
|
||||
\defun{resolv.conf}{}{symbol$\rightarrow$string alist}
|
||||
\label{sec:dns-rc}
|
||||
|
||||
\defvar{resolv.conf-parse-error} {condition}
|
||||
\defun{resolv.conf-parse-error?}{thing}{\boolean}
|
||||
\begin{desc}
|
||||
The code signals the condition \var{resolv.conf-parse-error} if a
|
||||
parse error occurs while scanning \texttt{/etc/resolv.conf}. It is a
|
||||
subtype of the \var{dns-error} condition.
|
||||
\ex{resolv.conf-parse-error?} is the type predicate for this
|
||||
condition.
|
||||
\oops{this is not implemented yet}
|
||||
\end{desc}
|
||||
|
||||
\defun{resolv.conf}{}{{symbol$\rightarrow$string} alist}
|
||||
\begin{desc}
|
||||
Returns the contents of \texttt{/etc/resolv.conv} as an alist with
|
||||
the possible keys \texttt{nameserver}, \texttt{domain},
|
||||
|
|
@ -147,8 +385,8 @@ turn is a subtype of \ex{dns-error}.
|
|||
|
||||
Note that the library caches the contents of
|
||||
\texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the
|
||||
file if its modification time is more recent than the creation time
|
||||
of the cache.
|
||||
file if its modification time is more recent than the modification
|
||||
time of the cache.
|
||||
\end{desc}
|
||||
\defun{parse-resolv.conf!}{}{\undefined}
|
||||
\begin{desc}
|
||||
|
|
@ -157,17 +395,33 @@ turn is a subtype of \ex{dns-error}.
|
|||
\end{desc}
|
||||
\defun{dns-find-nameserver-list}{}{\fqdn list}
|
||||
\begin{desc}
|
||||
Returns a list of nameservers from \texttt{/etc/resolv.conf}
|
||||
Returns a list of name servers from \texttt{/etc/resolv.conf}
|
||||
\end{desc}
|
||||
\defun{dns-find-nameserver}{}{\fqdn}
|
||||
\begin{desc}
|
||||
Returns the first nameservers found in \texttt{/etc/resolv.conf}.
|
||||
Returns the first name servers found in \texttt{/etc/resolv.conf}.
|
||||
\ex{dns-find-nameserver} raises \ex{no-nameservers} if
|
||||
\texttt{/etc/resolv.conf} does not contain a \texttt{nameserver}
|
||||
entry.
|
||||
\end{desc}
|
||||
\defun{domains-for-search}{}{\str list}
|
||||
\begin{desc}
|
||||
Parses \texttt{/etc/resolv.conf} and extracts the domains specified
|
||||
by the \texttt{search} keyword.
|
||||
\end{desc}
|
||||
|
||||
|
||||
\section{IP Addresses as Dotted Strings}
|
||||
\textbf{Should live in its own package}
|
||||
\defun{address32->ip-string}{\ipaddr}{ip-string}
|
||||
|
||||
\defun{ip-string->address32}{ip-string}{\ipaddr}
|
||||
|
||||
\defun{ip-string?}{string}{\boolean}
|
||||
\begin{desc}
|
||||
Tests whether \var{string} represents a valid IPv4 address.
|
||||
\oops{not yet implemented}
|
||||
\end{desc}
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "man"
|
||||
|
|
|
|||
Loading…
Reference in New Issue