mirror of https://github.com/dzavalishin/oskit/
266 lines
8.6 KiB
TeX
Executable File
266 lines
8.6 KiB
TeX
Executable File
%
|
|
% Copyright (c) 1997-1998 University of Utah and the Flux Group.
|
|
% All rights reserved.
|
|
%
|
|
% The University of Utah grants you the right to copy and reproduce this
|
|
% document or portions thereof for academic, research, evaluation, and
|
|
% personal use only, provided that (1) the title page appears prominently,
|
|
% and (2) these copyright and permission notices are retained in all copies.
|
|
% To arrange for alternate terms, contact the University of Utah at
|
|
% csl-dist@cs.utah.edu or +1-801-585-3271.
|
|
%
|
|
\label{bootp}
|
|
|
|
\newcommand{\bootp}{BOOTP}
|
|
|
|
\section{Introduction}
|
|
|
|
The \oskit{} provides a small library that allows \oskit{} clients to
|
|
contact a \bootp{} server to obtain the information necessary to
|
|
configure their network parameters, such as IP address or hostname.
|
|
The implementation is based on RFC 1048/1533.
|
|
|
|
\section{External Dependencies}
|
|
|
|
The current implementation requires the user to provide an
|
|
implementation of the \texttt{oskit_etherdev} interface. Such interfaces
|
|
are supported by the \oskit{}'s device driver components.
|
|
It also requires access to the system clock. The library obtains
|
|
access to the system clock by calling
|
|
\texttt{oskit_clock_init} % name might change
|
|
It releases its reference after the \bootp{} protocol has finished.
|
|
Additionally, \texttt{bootp_dump} uses \texttt{printf}.
|
|
|
|
\section{API reference}
|
|
|
|
The following sections describe the functions exported by the \bootp{}
|
|
library in detail.
|
|
All of these functions, as well as the types necessary to use them,
|
|
are declared in the header file {\tt <oskit/net/bootp.h>}.
|
|
|
|
\api{bootp_net_info}{\bootp{} protocol information structures}
|
|
\begin{apisyn}
|
|
\begin{codefrag}
|
|
\small
|
|
\begin{verbatim}
|
|
struct bootp_addr_array {
|
|
struct in_addr *addr; /* array of addresses */
|
|
int len; /* number of addresses */
|
|
};
|
|
|
|
struct bootp_net_info {
|
|
oskit_u32_t flags; /* which fields are valid */
|
|
struct in_addr ip; /* client IP address */
|
|
struct in_addr netmask; /* subnet mask */
|
|
struct in_addr server; /* server that replied */
|
|
struct bootp_addr_array gateway; /* gateways */
|
|
struct bootp_addr_array dns_server; /* DNS server address */
|
|
struct bootp_addr_array time_server; /* time server address */
|
|
struct bootp_addr_array log_server; /* log server address */
|
|
struct bootp_addr_array lpr_server; /* LPR server address */
|
|
oskit_s32_t time_offset; /* offset from UTC */
|
|
char *hostname; /* client hostname */
|
|
char *server_name; /* name of replying server */
|
|
char *bootfile_name; /* boot file name */
|
|
char *domainname; /* domain name */
|
|
unsigned char server_hwaddr[ETHER_ADDR_SIZE]; /* server address */
|
|
};
|
|
\end{verbatim}
|
|
\end{codefrag}
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
The first field of the \texttt{struct bootp_net_info} structure,
|
|
\emph{flags},
|
|
denotes which of the other fields are valid.
|
|
\emph{flags} is an ORed combination of the flag values below.
|
|
Each flag corresponds to a field in the structure
|
|
with the same name (in lower case).
|
|
|
|
All other fields are of one of three types:
|
|
\begin{enumerate}
|
|
\item An IP address encoded as a
|
|
\texttt{struct in_addr},
|
|
\item A string encoded as a \texttt{char *},
|
|
\item A list of IP addresses encoded in a
|
|
\texttt{struct bootp_addr_array}.
|
|
\end{enumerate}
|
|
|
|
The following table gives an overview of the flags that
|
|
are currently supported and the types of the corresponding
|
|
fields.
|
|
|
|
\begin{tabular}{|l|l|l|}
|
|
\hline
|
|
Field & Type & Function \\
|
|
\hline
|
|
\texttt{BOOTP_NET_IP} & IP address & IP address \\
|
|
\texttt{BOOTP_NET_NETMASK} & IP address & netmask \\
|
|
\texttt{BOOTP_NET_GATEWAY} & IP address & gateway \\
|
|
\texttt{BOOTP_NET_SERVER} & IP address &
|
|
server that answered \bootp{} request \\
|
|
\texttt{BOOTP_NET_DNS_SERVER} & List of IP addrs &
|
|
domain name servers \\
|
|
\texttt{BOOTP_NET_TIME_SERVER} & List of IP addrs &
|
|
time servers \\
|
|
\texttt{BOOTP_NET_LOG_SERVER} & List of IP addrs &
|
|
log servers \\
|
|
\texttt{BOOTP_NET_LPR_SERVER} & List of IP addrs &
|
|
LPR servers \\
|
|
\texttt{BOOTP_NET_TIME_OFFSET} & unsigned int & see below \\
|
|
\texttt{BOOTP_NET_HOSTNAME} & string & hostname \\
|
|
\texttt{BOOTP_NET_SERVER_NAME} & string &
|
|
name of the \bootp{} server \\
|
|
\texttt{BOOTP_NET_BOOTFILE_NAME}& string &
|
|
bootfile name \\
|
|
\texttt{BOOTP_NET_DOMAINNAME} & string &
|
|
DNS domain name \\
|
|
\texttt{BOOTP_NET_SERVER_ADDR} & unsigned char[6] &
|
|
Ethernet MAC address of \bootp{} server \\
|
|
\hline
|
|
\end{tabular}
|
|
|
|
The \emph{time_offset} field
|
|
specifies the time offset of the local subnet in seconds
|
|
from Coordinated Universal Time (UTC).
|
|
It is a signed 32-bit integer,
|
|
positive numbers indicate west of the Prime Meridian.
|
|
% and it even works on our subnet, thanks to Bart!
|
|
\end{apidesc}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%
|
|
% bootp
|
|
%
|
|
\api{bootp_gen}{Generate a \bootp{} protocol request}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/net/bootp.h}
|
|
|
|
\funcproto int bootp_gen(oskit_etherdev_t *dev,
|
|
\inoutparam struct~bootp_net_info *info,
|
|
int retries, int timeout);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This function broadcasts \emph{retries} \bootp{} request packets,
|
|
waiting \emph{timeout} milliseconds for a reply.
|
|
|
|
The only field of \emph{info} that is used as input for the request
|
|
is the \emph{ip} field corresponding to \texttt{BOOTP_NET_IP}.
|
|
See RFC 1048 for more explanation. Users should set this
|
|
field if they know their IP address; \texttt{BOOTP_NET_IP}
|
|
needs to be set in \emph{flags} if this is the case.
|
|
|
|
Lists of IP addresses and strings are dynamically
|
|
allocated as needed, users of \texttt{boopt_gen}
|
|
should pass the \emph{info} struct to
|
|
\texttt{bootp_free} to deallocate them.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[dev]
|
|
A pointer to an \texttt{oskit_etherdev} device interface.
|
|
|
|
\item[info]
|
|
The \bootp{} info to be used.
|
|
|
|
\item[retries]
|
|
Number of \bootp{} request packets that are sent.
|
|
|
|
\item[timeout]
|
|
Timeout in milliseconds.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns zero on success, \texttt{OSKIT_ETIMEDOUT} if the
|
|
operation timed out, or another error code as specified in
|
|
{\tt <oskit/error.h>}
|
|
\end{apiret}
|
|
\begin{apirel}
|
|
\texttt{bootp_net_info}
|
|
\end{apirel}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%
|
|
% bootp
|
|
%
|
|
\api{bootp}{Generate a \bootp{} protocol request (simple interface)}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/net/bootp.h}
|
|
|
|
\funcproto int bootp(oskit_etherdev_t *dev,
|
|
\inoutparam struct~bootp_net_info *info);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This function performs a \bootp{} request with
|
|
a timeout of 200 milliseconds (1/5 of a second) with five retries
|
|
using \texttt{bootp_gen}.
|
|
|
|
The only field of \emph{info} that is used as input for the request
|
|
is the \emph{ip} field corresponding to \texttt{BOOTP_NET_IP}.
|
|
See RFC 1048 for more explanation. Users should set this
|
|
field if they know their IP address; \texttt{BOOTP_NET_IP}
|
|
needs to be set in \emph{flags} if this is the case.
|
|
|
|
Lists of IP addresses and strings are dynamically
|
|
allocated as needed, users of \texttt{boopt_gen}
|
|
should pass the \emph{info} struct to
|
|
\texttt{bootp_free} to deallocate them.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[dev]
|
|
A pointer to an \texttt{oskit_etherdev} device interface.
|
|
\item[info]
|
|
The \bootp{} info to be used.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns zero on success, or an error code specified in
|
|
{\tt <oskit/error.h>} on error.
|
|
\end{apiret}
|
|
\begin{apirel}
|
|
\texttt{bootp_net_info}
|
|
\end{apirel}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%
|
|
% bootp_free
|
|
%
|
|
\api{bootp_free}{Free the result of a \bootp{} request}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/net/bootp.h}
|
|
|
|
\funcproto void bootp_free(\inoutparam struct~bootp_net_info *info);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
The function frees data structures that were allocated
|
|
during a call to \texttt{bootp_gen}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[info]
|
|
The \bootp{} info to be freed.
|
|
\end{apiparm}
|
|
\begin{apirel}
|
|
\texttt{bootp_gen},
|
|
\texttt{bootp_net_info}
|
|
\end{apirel}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%
|
|
% bootp_dump
|
|
%
|
|
\api{bootp_dump}{Dump the result of a \bootp{} via printf}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/net/bootp.h}
|
|
|
|
\funcproto void bootp_dump(struct~bootp_net_info *info);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This function prints the contents stored in a
|
|
\texttt{bootp_net_info} structure to via \texttt{printf}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[info]
|
|
The \bootp{} info to be printed.
|
|
\end{apiparm}
|
|
\begin{apirel}
|
|
\texttt{bootp_net_info},
|
|
\texttt{printf}
|
|
\end{apirel}
|