BBN-Vax-TCP/doc/NetInstall.P
Installing and Operating the BBN Networking
Software
Beta-Test Distribution
Robert F. Gurwitz
Computer Systems Division
Bolt Beranek and Newman, Inc.
50 Moulton Street
Cambridge, Massachusetts 02238
_A_B_S_T_R_A_C_T
This document contains instructions for
installing and operating the BBN networking
software. The package includes modifications to
the 4.1bsd release of the VAX* UNIX** operating
system, as distributed by the University of Cali-
fornia, Berkeley, to support the DoD Standard
Transmission Control and Internet Protocols
(TCP/IP). In addition, user level commands are
included, which implement the TELNET Virtual Ter-
minal Protocol, the File Transfer Protocol (FTP),
and the Mail Transfer Protocol (MTP), as well as
utilities which aid in operating the network and
debugging programs which use the network.
_1. _I_n_t_r_o_d_u_c_t_i_o_n
This document explains how to install the BBN network
software package, which runs under the 4.1bsd release of the
Berkeley version of UNIX for the VAX. The distribution con-
sists of two parts: a set of modifications to the 4.1bsd
kernel which supports the lower level network protocols,
TCP, IP, and the local network interface; and a suite of
user level software (commands and libraries), which includes
both higher level network protocols (TELNET, FTP, and MTP)
and utilities for writing and debugging programs which use
the lower level network protocols.
__________________________
*VAX is a trademark of Digital Equipment Corporation.
**UNIX is a trademark of Bell Laboratories.
October 26, 1981
- 2 -
_1._1. _P_r_e_r_e_q_u_i_s_i_t_e_s
It is assumed that the user is already running 4.1bsd
on a VAX 11/780 or VAX 11/750. The current release of the
system can handle multiple network interfaces on one or more
nets. The system has been developed on the ARPANET, using
the Associated Computer Consultants (ACC) LH/DH-11 IMP
interface. A driver for the LH/DH-11 on the UNIBUS is
included with the software, and the ARPANET 1822 protocol is
supported as the local network access protocol. Currently,
this is the only hardware interface and local network proto-
col supported. It is expected that software will be
developed to handle other hardware interfaces and local net-
work protocols (such as for the ETHERNET) by sites
interested in using this software over networks other than
the ARPANET.
_1._2. _D_i_s_t_r_i_b_u_t_i_o_n _F_o_r_m_a_t
The software is distributed on a 1600bpi 600' magnetic
tape. The tape contains two files. The first is a tape
archive image (see _t_a_r(_1)) of the sources for the 4.1bsd
kernel with the network modifications (in the standard
directory hierarchy /usr/src/sys). The second file is a tar
of a directory hierarchy that includes the sources and
libraries for the user level commands. This hierarchy is
designed to be self-contained, and includes src, lib, bin,
include, and doc directories.
_2. _I_n_s_t_a_l_l_i_n_g _t_h_e _K_e_r_n_e_l _M_o_d_i_f_i_c_a_t_i_o_n_s
There are two paths for integrating the network
software into your system. The kernel contained on the dis-
tribution tape is a complete version of the 4.1bsd system.
If there are few local modifications to your kernel, you may
want to use the distributed system as a base for your pro-
duction system and merge local changes into it. Otherwise,
if there are extensive local changes to your kernel, you can
merge the network additions and modifications into your
existing kernel sources. In either case, you will want to
modify you system configuration files (in /usr/src/sys/conf)
to include the network. You should be familiar with the
instructions for creating system configuration files and
making changes to the kernel as described in sections
3.2.3-4 of "Installing and Operating 4.1bsd," by Bill Joy.
_2._1. _R_e_a_d_i_n_g _t_h_e _D_i_s_t_r_i_b_u_t_i_o_n _T_a_p_e
For either method of installing the kernel modifica-
tions, you should create a directory in /usr/src and read in
the first file from the tape:
cd /usr/src
mkdir netsys
October 26, 1981
- 3 -
cd netsys
tar xpb 20
The kernel sources should now be read in. The network addi-
tions (source and header files) are contained in the bbnnet
subdirectory. In addition, there are modifications to the
following files:
fio.c, ioctl.c, locore.s, machdep.c, main.c, param.c,
sys2.c, sys3.c in sys
file.h, map.h in h
conf.c in dev
These modifications are delimited by:
#ifdef BBNNET
#endif BBNNET
Also, there is a device driver, acc.c, in the dev subdirec-
tory, and its header file, accreg.h, in the h subdirectory.
If you wish to merge the network software with your
current system, the bbnnet subdirectory must be created and
copied in your /usr/src/sys, the BBNNET modifications must
be made to the files in sys and h, and the driver code must
be put in dev and h.
Otherwise, just make your local modifications in the
files of /usr/src/netsys, and make that your /usr/src/sys
hierarchy.
_2._2. _C_o_n_f_i_g_u_r_i_n_g _t_h_e _N_e_t_w_o_r_k _S_o_f_t_w_a_r_e
Once the sources have been properly installed in
/usr/src/sys, you must modify files in the conf subdirectory
to include the network additions. You can use the files in
the distributed conf directory as a guide (i.e., conf/BBNSYS
and conf/files).
You must add the following entries to your system con-
figuration file:
options BBNNET
pseudo-device bbnnet
pseudo-device pty
device acc0 at uba_x csr _y_y_y vector acc_iint acc_oint
The _u_b_a and _c_s_r fields of the acc device entry should be
modified to the appropriate values for your system.
You must add the following to the file conf/files:
October 26, 1981
- 4 -
optional acc.c device-driver
optional pty.c
optional bbnnet _x_x_x
...
where the last entries correspond to an entry for each file
in the bbnnet subdirectory (take these lines from the dis-
tribution conf/files file).
Make sure that dev/conf.c has been set up properly for
the acc device. Use the distributed dev/conf.c as a guide.
In addition to the files in the conf directory, you
must also modify the file netconf.c in bbnnet directory to
reflect you host's interface(s) to the network(s). The
first structure in the file, _s_t_r_u_c_t _i_f_c_b, contains one entry
for each physical network interface device. It need only be
modified if you are attached to a network other than the
ARPANET or have more than one network interface. The impor-
tant line in this structure is the second. On it you must
include the device number of your interface (ACC's are
currently the only interface supported: major device number
is ACCDEV), the maximum packet size of the network you are
interfaced to (1018 for the ARPANET), and its network number
(ARPANET is net 10). The second structure in the file,
_s_t_r_u_c_t _i_f__l_o_c_a_l_x, contains at least one entry for each phy-
sical interface. It gives the network address of the
corresponding interface. The address is in internet inter-
nal format, and is specified in the ipaddr macro as four
decimal digits corresponding to the four bytes of the inter-
net address. (Thus, the address of BBN-VAX, host 1/82 on
the ARPANET would be specified as:
ipaddr(10,1,0,82).
Note that an interface may have more than one address. Nor-
mally, you should just be able to insert your host's address
in the macro and leave it at that. (Ultimately, this file
will be generated by _c_o_n_f_i_g(_8), as part of the compile time
configuration process.)
You should now be able to compile the kernel with
_m_a_k_e(_1) and produce a running version of vmunix.
_3. _I_n_s_t_a_l_l_i_n_g _t_h_e _U_s_e_r _S_o_f_t_w_a_r_e
The remaining file on the distribution tape consists of
the user level commands and libraries that make up the rest
of the network software package. This file is also in
_t_a_r(_1) format, and consists of a standalone hierarchy of
everything you will need to make the commands and libraries.
In addition, you will probably have to modify your mail pro-
grams to operate with the network mailer and mail server.
The necessary modifications are described in the next
October 26, 1981
- 5 -
section.
To read the remaining files off the tape, make a direc-
tory in the appropriate place and read the tape file:
mkdir netuser
cd netuser
tar xpb 20 [the second file on the distribution tape]
(N.B. All further relative pathnames will start here.) The
file Contents contains a description of the various sub-
directories.
Note: some programs reference the include files "con.h"
and "net.h" which are part of the kernel distribution. You
should make sure that these files have been installed in
/usr/include/sys.
Edit the file include/netfiles.h to your taste, if the
filenames contained therein are undesirable.
You are now ready to build executables for the commands
and the network library. Change to the src directory and
issue the _M_a_k_e_i_t command. This will construct libraries in
lib and then build the executables in bin.
Now install the resulting files in the appropriate
places. If the network library is to be made public (so
that other programs may use it) the file include/netlib.h
should be installed in /usr/include, and the archive
lib/libnet.a should be moved to /lib or /usr/lib. Likewise
the executables in bin should be placed in suitable direc-
tories:
host, net, netstat, ftp, telnet in /bin or /usr/bin
mkgate, mkhost, prhost, netser, ftpsrv, srvrftp,
mtpsrv, srvrmtp, mailer in /etc/net
In addition, you should install the gateway source table in
/etc/net. This file, _g_a_t_e_w_a_y._b_i_n, is generated from an
ASCII source file, _g_a_t_e_w_a_y, by the _m_k_g_a_t_e(_1) command, and is
read by the kernel at boot time to initialize the internal
gateway table.
Before anything useful can be done, the network device
should be created in /dev/net:
mknod /dev/net/tcp c 255 0
You should edit the MAKE shell script in /dev to include
this.
Also, the network information files must be set up
October 26, 1981
- 6 -
correctly. (The names of these files are contained in the
include file _i_n_c_l_u_d_e/_n_e_t_f_i_l_e_s._h) The file /_e_t_c/_T_H_I_S_H_O_S_T
should contain the name of the local host. The file
/_e_t_c/_N_E_T_W_O_R_K_S should contain the host address and network
number of local system (e.g., 5/82,10 -- host 5 on imp 82 on
network 10). The ASCII version of the host map should be
revised slightly (see doc/host_map.5.P) to account for the
requirement of network capabilities. A sample host map is
provided in the directory, etc. Finally, the command
_m_k_h_o_s_t(_1), must be used to create a binary host name/address
map from the ASCII, by
mkhost -o tmpfile
prhost -i tmpfile
and inspecting the output of prhost. If it is acceptable,
running _m_k_h_o_s_t with no arguments will build a binary map in
the correct place for use by the library and other software.
In order to run the TELNET server (netser), you must
configure pseudo-teletype (pty) devices, which allow network
users to appear to be logging in on ttys. The distributed
kernel is configured for 16 ptys. To change the number of
possible ptys, modify NPTY in dev/pty.c. For each pty you
plan to use, create corresponding special files. Two spe-
cial files are required for each available pty, created by:
mknod /dev/pty_x c 21 _y
mknod /dev/tty_x c 20 _y
where _x should be a single capital letter, and _y the
corresponding origin 0 number (e.g., the first pty would
have two files, /dev/ptyA and /dev/ttyA, with device numbers
(21,0) and (20,0), respectively). You should modify
/dev/MAKE to create as many of these files as you require.
Both special files are required: /dev/ptyx is the actual pty
device, and the corresponding /dev/ttyx is a slave that
makes programs like _g_e_t_t_y and _w_h_o happy. You must also
include entries in /etc/ttys for each /dev/ttyx, so that
logins can occur.
You should now be able to run the supplied network com-
mands. Add lines to your /etc/rc file to invoke the TELNET
(netser), FTP (ftpsrv), and MTP (mtpsrv) servers, and the
mail daemon (mailer). (Be sure to set up the mail server
and mailer to work with your mail programs, see below.)
These commands, and their output logfiles, should be run out
of /etc/net.
_3._1. _S_e_t_t_i_n_g _u_p _t_h_e _M_a_i_l _S_o_f_t_w_a_r_e
The mail software uses MTP (the Mail Transfer Protocol)
to send and receive mail over the network. The mail
receiver (srvrmtp) gathers up the incoming mail in a file,
October 26, 1981
- 7 -
and then invokes a mail sending program to deliver the con-
tents of the file to a local user's mailbox. Two versions
of srvrmtp are provided in this distribution. One calls
upon the BBN mail program _s_n_d_m_s_g (not included in this dis-
tribution) to deliver mail locally. The other uses the
Berkeley _d_e_l_i_v_e_r_m_a_i_l program to perform this task. The
relevant code is #ifdef'd on "DELIVERMAIL", and the binary
versions are _s_r_v_r_m_t_p and _s_r_v_r_m_t_p._d.
If your site uses neither of these programs, you will
have to modify the routine "sndmsg" in srvrmtp.c to invoke
your mail program. Your mail program must be able to read a
complete message (containing an RFC733 header plus text)
from a file and deposit it into a mailbox. If it is not
possible to specify an input file as a command line argu-
ment, srvrmtp can usually achieve the same effect by closing
the standard input and opening the file just before execut-
ing the mail sending program. See the code in "sndmsg"
which invokes _d_e_l_i_v_e_r_m_a_i_l.
Mail going out to the network is queued in the direc-
tory /_u_s_r/_s_p_o_o_l/_n_e_t_m_a_i_l. A mailer daemon scans this direc-
tory every few minutes looking for work to do. There is one
file for each piece of outgoing mail. The first line of
every file contains information for the use of the mailer,
and the rest of the file is the message to be sent. The
format of the information line is as follows:
host:user:return:
with no blanks. _H_o_s_t is the name of the destination host,
_u_s_e_r is the name of the intended recipient at that host, and
_r_e_t_u_r_n is the return address for the mail, usually the ori-
ginator of the message. You will have to see to it that the
program that queues network mail on your system places mes-
sages in /_u_s_r/_s_p_o_o_l/_n_e_t_m_a_i_l in this format.
Any questions regarding the mail software should be
directed to Eric Shienbrood (shienbrood@bbn-unix).
_4. _O_p_e_r_a_t_i_n_g _t_h_e _N_e_t_w_o_r_k _S_o_f_t_w_a_r_e
The software should need little attention once it is
running. There are no procedures for bringing the network
up or down. The software works if the network is available,
and re-initializes itself when the network goes down and
comes back up. The _n_e_t_s_t_a_t(_1) command can be used to deter-
mine the status of network connections and the condition of
the software (number of buffers in use, etc.). If any
errant connections are found hanging around, they can be
cleared with the _n_e_t_r_e_s_e_t(_1) command (its argument is the
TCB address taken from netstat). The other network utili-
ties, netdebug, trpt, and tcptest, can all be used to test
the network software and debug programs written to use the
October 26, 1981
- 8 -
net.
_5. _F_u_t_u_r_e _M_o_d_i_f_i_c_a_t_i_o_n_s
The software package now being distributed is a prelim-
inary test version. Work is currently underway at BBN and
Berkeley on performance evaluation and improvement. The
user interface will be modified to operate with whatever IPC
mechanisms ultimately adopted by the ARPA Berkeley Steering
Committee. In addition, the raw IP and local network inter-
faces will be undergoing substantial modification to
increase their utility. The raw interfaces provided in this
release have not been extensively tested.
In the meantime, I'd appreciate your comments. Good
luck!
Rob Gurwitz
gurwitz@bbn-unix
617-497-3041
October 26, 1981