scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

+ Describe rr-data-X 

+ Some general remarks
This commit is contained in:
mainzelm 2003-01-21 14:38:01 +00:00
parent 0c0c27dcb5
commit 7e45f51298
1 changed files with 302 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

350
doc/latex/dns.tex
View File

@ -1,5 +1,11 @@
\chapter{DNS Client Library}\label{cha:dns} \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. The \ex{dns} structure contains a library for querying DNS servers.
Features: 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. Returns a string with the description of the condition.
\end{desc} \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-server-failure} {condition}
\defvarx {dns-name-error} {condition} \defvarx {dns-name-error} {condition}
\defvarx {dns-not-implemented} {condition} \defvarx {dns-not-implemented} {condition}
\defvarx {dns-refused} {condition} \defvarx {dns-refused} {condition}
\begin{desc}
These conditons correspond to errors returned by the DNS server. They These conditons correspond to errors returned by the DNS server.
are all subtypes of the \exi{dns-server-error} condition which in They are all subtypes of the \exi{dns-server-error} condition which
turn is a subtype of \ex{dns-error}. in turn is a subtype of \ex{dns-error}.
\end{desc}
\defun{dns-server-error?}{thing}{\boolean} \defun{dns-server-error?}{thing}{\boolean}
\begin{desc} \begin{desc}
The predicate for \ex{dns-server-error} conditions. The predicate for \ex{dns-server-error} conditions.
\end{desc} \end{desc}
\defun {dns-format-error?} {thing} {\boolean} \defun{parse-error?}{thing} {\boolean}
\defunx {dns-server-failure?} {thing} {\boolean} \defunx{unexpected-eof-from-server?}{thing} {\boolean}
\defunx {dns-name-error?} {thing} {\boolean} \defunx{bad-address?}{thing} {\boolean}
\defunx {dns-not-implemented?} {thing} {\boolean} \defunx{no-nameservers?}{thing} {\boolean}
\defunx {dns-refused?} {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} \begin{desc}
The type predicates for the conditions above. The type predicates for the conditions above.
\end{desc} \end{desc}
@ -49,80 +73,281 @@ turn is a subtype of \ex{dns-error}.
\def\ipaddr{\textnormal{IP-address\xspace}} \def\ipaddr{\textnormal{IP-address\xspace}}
\def\fqdn{\textnormal{FQDN\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} \begin{desc}
Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address. Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address.
The optional argument specifes the nameservers to query, it defaults The optional argument specifes the name servers to query, it defaults
to the ones found in \texttt{/etc/resolv.conf}. \textbf{always uses to the ones found in \texttt{/etc/resolv.conf}.
the cache}
\end{desc} \end{desc}
\defun{dns-lookup-ip}{\ipaddr [nameserver list]}{\fqdn} \defun{dns-lookup-ip}{\ipaddr [nameserver list][use-cache?]}{\fqdn}
\begin{desc} \begin{desc}
Looks up the FQDN for the given IP address. The optional argument Looks up the FQDN for the given IP address. The optional argument
specifes the nameservers to query, it defaults to the ones found in specifes the name servers to query, it defaults to the ones found in
\texttt{/etc/resolv.conf}. \textbf{always uses the cache} \texttt{/etc/resolv.conf}. \oops{use-cache? is not implemented yet}
\end{desc} \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} \begin{desc}
Looks up an authoritative nameserver for a hostname, returns a list Looks up an authoritative name server for a hostname, returns a list
of nameservers. The optional argument specifes the nameservers to of name servers. The optional argument specifes the name servers to
query, it defaults to the ones found in query, it defaults to the ones found in
\texttt{/etc/resolv.conf}\textbf{Why a list if there is only one and \texttt{/etc/resolv.conf}\oops{use-cache? is not implemented yet}
why is there only one for wsi hosts?}\textbf{always uses the cache}
\end{desc} \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} \begin{desc}
Looks up mail-exchangers for a hostname und returns them in a list Looks up mail-exchangers for a hostname und returns them in a list
sorted by preference. \textbf{Always uses the cache}\textbf{why is sorted by preference. \oops{use-cache? is not implemented yet}
there only one MX for wsi?}
\end{desc} \end{desc}
\defun{socket-address->fqdn}{socket-address cache?}{\fqdn} \defun{socket-address->fqdn}{socket-address [use-cache?]}{\fqdn}
\begin{desc} \begin{desc}
Returns the FQDN for of the address bound to argument. The argument Returns the FQDN for of the address bound to argument. The argument
\var{cache?} indicates whether the internal cache may be queried to \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} \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} \defunx{maybe-dns-lookup-ip}{\ipaddr}{\fqdn{} or \sharpf}
\begin{desc} \begin{desc}
These procedures provide the same functionality as These procedures provide the same functionality as
\ex{dns-lookup-name} and \ex{dns-lookup-ip} but return \sharpf{} in \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} \end{desc}
\defun{host-fqdn} {name/socket-address}{\fqdn} \defun{host-fqdn} {name/socket-address [nameserver list][use-cache?]}{\fqdn}
\defunx{system-fqdn}{}{\fqdn} \defunx{system-fqdn}{[nameserver list][use-cache?]}{\fqdn}
\begin{desc} \begin{desc}
\ex{host-fqdn} returns the fully qualified domain name (FQDN) for its \ex{host-fqdn} returns the fully qualified domain name (FQDN) for its
argument which can be either a unqualified host name or a socket argument which can be either a unqualified host name or a socket
address. The procedure \ex{system-fqdn} returns the FQDN of the address. The procedure \ex{system-fqdn} returns the FQDN of the
current host. current host.\oops{optional arguments not implemented yet}
\end{desc} \end{desc}
\section{Low-level Interface} \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} \begin{desc}
This is the most general way to submit a DNS query. The return value 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} \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} \begin{desc}
Pretty prints a DNS message to standard output. A \var{dns-message} records the query sent to the server and the
\textbf{Better return a string} 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{pretty-print-dns-message}{dns-message [output-port]}{\undefined}
\begin{desc}
Pretty prints a DNS message to \var{out-port} which defaults to the
current output port.
\end{desc} \end{desc}
\defun{domains-for-search}{}{\str list} \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} \begin{desc}
Parses \texttt{/etc/resolv.conf} and extracts the domains specified A \ex{message} represents the data sent to the DNS server or
by the \texttt{search} keyword. 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} \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} \section{Host Names}
\defun{is-fqdn?}{\str}{\boolean} \defun{is-fqdn?}{\str}{\boolean}
\begin{desc} \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} \oops{The current implementation simply searches for a dot in the name}
\end{desc} \end{desc}
\defun{unqualified-hostname}{\str}{\boolean} \defun{unqualified-hostname?}{\str}{\boolean}
\begin{desc} \begin{desc}
Returns true if the argument matches the grammar for a unqualified Returns true if the argument matches the grammar for a unqualified
host name host name.
\oops{This procedure isn't implemented yet} \oops{This procedure isn't implemented yet}
\end{desc} \end{desc}
\section{Parsing \texttt{/etc/resolv.conf}} \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} \begin{desc}
Returns the contents of \texttt{/etc/resolv.conv} as an alist with Returns the contents of \texttt{/etc/resolv.conv} as an alist with
the possible keys \texttt{nameserver}, \texttt{domain}, 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 Note that the library caches the contents of
\texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the \texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the
file if its modification time is more recent than the creation time file if its modification time is more recent than the modification
of the cache. time of the cache.
\end{desc} \end{desc}
\defun{parse-resolv.conf!}{}{\undefined} \defun{parse-resolv.conf!}{}{\undefined}
\begin{desc} \begin{desc}
@ -157,17 +395,33 @@ turn is a subtype of \ex{dns-error}.
\end{desc} \end{desc}
\defun{dns-find-nameserver-list}{}{\fqdn list} \defun{dns-find-nameserver-list}{}{\fqdn list}
\begin{desc} \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} \end{desc}
\defun{dns-find-nameserver}{}{\fqdn} \defun{dns-find-nameserver}{}{\fqdn}
\begin{desc} \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 \ex{dns-find-nameserver} raises \ex{no-nameservers} if
\texttt{/etc/resolv.conf} does not contain a \texttt{nameserver} \texttt{/etc/resolv.conf} does not contain a \texttt{nameserver}
entry. entry.
\end{desc} \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: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: "man" %%% TeX-master: "man"