%$Id: HEL91009.tex,v 1.1 1992/01/24 16:43:51 doc Exp $
%CURRENT VERSION OF THE ETHERNET GUIDE, PRINTED MARCH 1991.
\chapter{About this guide}

The {\it Ethernet I Guide} describes the basic Helios network support 
package, {\bf Ethernet I}. This package provides the Helios user 
with a gateway from Helios to other networks. With it
the user can run well known programs to login 
to remote systems and to transfer files quickly between different machines.
To enable the user to do this, the Ethernet I package
conforms to the standard protocols for Ethernet, 
includes a TCP/IP server and features many of the commonly associated tools.
\par
This guide is a systems administrators guide to setting up Ethernet I 
under Helios 1.2.1, 
or under any subsequent release of Helios. It covers how to install 
and customise the software for your own
particular hardware configuration. It 
provides an overview of how Ethernet I deals with incoming and
outgoing services on the network, and indicates
the interaction of the various support programs. 
Because Ethernet I conforms to the BSD standard, the reference section
simply consists of a quick summary of each of the commands provided. A full
description of these commands can be found in any standard BSD documentation.
\par
The {\it Ethernet I Guide}, however, does not attempt to 
be a detailed introduction to interprocess communication on Ethernet.
This means that to get the best out of this guide, 
you should have some experience of interprocess communication, and a
general understanding of the principles of TCP/IP. Readers without such a
background should first consult the glossary and bibliography for further information.
\par
There should be no need to read through this guide from cover to cover, 
although the order of topics is such that it takes you from 
setting up the software to testing and running it; all the reference material
is at the back of the guide. 
\begin{itemize}
\item{\bf Checking things out}
covers how to check out what is in your Ethernet I package.
\item{\bf Overview}
gives an
overview of the software and includes diagrams which summarise
the information provided.
\item{\bf Installing Ethernet I} 
explains how to load the software
described in the previous section, how to
customise it for your network environment and then how test that the installed
network interface is working correctly.
\item{\bf Examples}
contains example code to help illustrate the use of Ethernet I.
\item{\bf User's reference} 
comprises a summary of
each of the commands, arranged in alphabetical order.
\item{\bf Glossary} 
contains a useful alphabetical listing 
of common interprocess \newline
communication terms and concepts, together
with a brief description of their use or meaning. 
\item{\bf Bibliography}
lists essential works of reference for background reading. 
\end{itemize}



\chapter{Checking things out}

First of all, before you do anything else, 
check that you are not running an early version
of Helios. Ethernet I will not run on any version earlier than Helios 1.2.1.
If you do not have the right version of Helios, contact your 
Helios distributor at
once to arrange for an upgrade; without it you will not be able to
to continue.
\par
Check that you have sufficient memory available to run Ethernet I. To
run the TCP/IP server, you should have a system processor with at least
1Mbyte of memory. The internet daemon also needs a lot of memory; you should
allow a minimum of 1Mbyte for a single user and 2Mbytes or more for multi-user
use. The internet daemon needs the extra memory because it creates daemons on
the same processor and therefore it must have sufficient room to do so.
\par
If you have a PC, you can use Ethernet I with a 
Western Digital EtherCard Plus WDLAN-EPR(F001) or a DLINK card. 
Instructions on how to set up and install the hardware
are given in the section entitled {\bf Installing the hardware}. 
\par
Now check your Ethernet I package;
it should include the following:
\begin{itemize}
\item
Two floppy discs (part number: M5110038)
\item
An {\it Ethernet I Guide} (part number: DM5042)
\end{itemize}
\par
Notice that the package contains a choice of two PC-format floppy discs,
3.5 inch 720 Kbyte and 5.25 inch 1.2 Mbyte.
Examine the contents of the disc that suits your system. 
Apart from the BSD documentation sources, it should contain the following files:

\footnotesize
\begin{tabular}{ll}
\\
   {\tt /helios/lib/tcpip  }     & The TCP/IP server \\
   {\tt /helios/lib/ttyserv}     & The PTY server \\
\\
   {\tt /helios/lib/pc-ether.d}  & The PC Ethernet driver \\
   {\tt /helios/lib/sq-ether.d}  & The Parsytec Ethernet driver \\
   {\tt /helios/lib/in-ether.d}  & The Inmos Ethernet driver \\
   {\tt /helios/lib/b407.b2h}    & The Inmos B407 firmware\\
   {\tt /helios/lib/tpseudo.d}   & The pseudo terminal (PTY) driver \\
   {\tt /helios/lib/tserial.d}   & The serial line driver \\
\\
   {\tt /helios/lib/inetd  }     & The Internet services daemon \\
   {\tt /helios/lib/ftpd   }     & The file transfer protocol daemon \\
   {\tt /helios/lib/telnetd}     & TCP/IP TELNET protocol daemon \\
   {\tt /helios/lib/rlogind}     & The remote login daemon \\
   {\tt /helios/lib/rshd }       & The remote shell daemon \\
   {\tt /helios/lib/rexecd}      & The remote execution daemon \\
\\
   {\tt /helios/bin/ftp}         & The file transfer program \\
   {\tt /helios/bin/telnet}      & Remote system access \\
   {\tt /helios/bin/rcp}         & Remote copy\\
   {\tt /helios/bin/rlogin}      & Remote login \\
   {\tt /helios/bin/rsh }        & Remote shell \\
   {\tt /helios/bin/ping}        & Network maintenance tool \\
   {\tt /helios/bin/setterm}     & Terminal type control \\
\\
   {\tt /helios/etc/hosts}       & Database files \\
   {\tt /helios/etc/services }\\
   {\tt /helios/etc/networks} \\
   {\tt /helios/etc/protocol} \\
   {\tt /helios/etc/termcap} \\
   {\tt /helios/etc/hosts.equiv} \\ 
   {\tt /helios/etc/inetd.conf}  & Network configuration files \\
   {\tt /helios/etc/socket.conf} \\
   {\tt /helios/etc/devinfo.net} \\
\\
   {\tt /helios/include/netdb.h} & Include file \\
   {\tt /helios/include/net/*}    & Include directories \\
   {\tt /helios/include/netinet/*} \\
   {\tt /helios/include/arpa/*} \\
%\\
%   {\tt /helios/lib/bsd.lib}     & Support library \\
\\
%  {\tt \~/.rhosts}         & User file used by rlogin \\
%  {\tt \~/.netrc}          & Information for auto-login 

\end{tabular}

\begin{tabular}{ll}
   {\tt helios/local/tcpip/pc-ether/netdev.c}  & Driver sources:\\
   {\tt helios/local/tcpip/pc-ether/devs.a}    & example code to\\
   {\tt helios/local/tcpip/pc-ether/modend.a}  & help you write your\\
   {\tt helios/local/tcpip/pc-ether/makedfile} & own hardware driver.\\
   {\tt helios/local/tcpip/pc-ether/example.c} & Example socket\\
                                               & program.

\end{tabular}
\normalsize

\chapter{Overview}

This section gives an overview of Ethernet I and  shows
how its constituent programs fit together. Because it is sometimes easier
to understand things when they are displayed diagrammatically, a series of
diagrams illustrating the following descriptions is included at the
end of the section.

\section{Helios /ether server}

The Helios IO Server contains code for a server called {\tt /ether}.
This server allows Helios programs to access your PC's ethernet card
in the same way as the {\tt /serial} device allows Helios programs to access
the PC's serial ports. 
\par
The {\tt /ether} server provides low-level access to the actual
ethernet hardware in the form: read a packet, write a packet, get an
ethernet address. The transport medium at the {\tt /ether} level is
unreliable (that is, a packet that is written in {\em not} guaranteed
to reach its destination).
\par
The recommended way to use Ethernet I to communicate between machines
is not at this low level. You should use the higher level commands, such
as {\tt ftp} (see below under {\bf Commands}), which communicates with
the TCP/IP server to call functions in the {\tt ether.d} driver device (see
below under {\bf Drivers}. This device then communicates directly with the
{\tt /ether} server in the IO Server, which in turn interacts with the hardware
of the ethernet card.
\par
{\bf Warning:} Do not attempt to access the {\tt /ether} server
while the TCP/IP software is running as the results are undefined.

\section{Servers}

Each of these programs provide a given service: {\tt tcpip} runs the
TCP/IP server, which provides the controlling interface for
communication between hosts on the network;
{\tt ttyserv} controls the pseudo terminal driver. The {\tt tcpip} service 
must be active in order for you to access the network; the
{\tt ttyserv} service is started on demand. 
\par
{\tt ttyserv} is responsible for translating the Helios screen control escape
sequences to whatever is needed for your hardware. For example, if 
{\tt telnet} is used to login to a Helios machine from a VT100 then 
{\tt ttyserv}
will translate the Helios escape sequences into their VT100 equivalents.
Furthermore, the ttyserver provides multiple windows with a hotkey-switching
mechanism, like the PC I/O server.

\section{Drivers}

Drivers provide an interface between the Ethernet software and the
hardware: they take ethernet 
packets from the physical network cable and interpret
them for the host, and the other way about. 
On your distribution disc you will find a
number of possible drivers: {\tt pc-ether.d}, {\tt sq-ether.d}, 
and {\tt in-ether.d}. The TCP/IP server selects its driver according to an
entry in the 
\begin{verbatim}
/helios/etc/devinfo
\end{verbatim}
file. This is described in detail
in the installation section, later in this guide.
If your hardware is not represented by any of the above, 
you will need to write your own driver. Should this be the case, 
turn to the {\bf Examples} section for further advice.
\par
The drivers {\tt tpseudo.d} and {\tt tserial.d} are for the pseudo terminal
server {\tt ttyserv}. The driver {\tt tpseudo.d} implements a pseudo-tty
interface, which is functionally equivalent to that provided by Unix.
The ttyserver is used by \newline {\tt telnetd} and {\tt rlogind} in this 
package
and by {\tt xterm} in the Helios {\it X Window} package. The driver 
{\tt tserial.d} allows the ttyserver to use a serial line for directly
attached terminals.

\section{Daemons}

\subsection{Standard daemons}

The application layer TCP/IP protocols include a support daemon on the
remote receiving host for each Ethernet I command that can be invoked from
the local source host. These support daemons do all
the background work. The standard naming convention is {\it command name}
followed by the letter {\em d}; for example, the daemon for {\tt ftp} 
is called {\tt ftpd}. The Ethernet I package supports the following
standard TCP/IP daemons: {\tt ftpd}, {\tt rexecd}, {\tt rlogind}, {\tt rshd},
and {\tt telnetd}. (See {\bf Commands} for further information.)

\subsection{inetd}

The daemon known as {\tt inetd} must be
active for a remote host to access your local host. This daemon, which
is actually a special sort of server, controls
all the other daemons. It consults its supporting
configuration file {\tt inetd.conf} to establish which daemons are required.
For example, it will only run {\tt rshd} if a remote user requests a shell on
the local machine; similarly, it will only run {\tt rlogind} if a remote user
attempts to login to the local host, and so on. The system can get clogged
if too many daemons are run unnecessarily.

\section{Commands}

These are the standard
tools that enable the user to login to a remote host, run a remote
session, transfer a file from one host to another one,
and so on.  

\subsection{ftp}

The application layer 
File Transfer Protocol comprises the {\tt ftp} program, which runs on the
local host machine (source), 
and the {\tt ftpd} daemon, which runs on the remote host
machine (destination). 
(Notice that, for remote hosts to access the local host, a
corresponding fptd should also be available to run on the local host.) 
The remote {\tt ftpd} handles any requests from the local {\tt ftp}. 

\subsection{telnet}

The Telnet protocol allows terminals to communicate over a network supporting
TCP/IP. This application layer
protocol consists of the {\tt telnet} program, which runs on
the local machine (source), and {\tt telnetd}, a daemon which runs on the remote
machine (destination). 
(Again, for remote terminals to communicate with the local one,
a corresponding telnetd should be available to run locally.) 
On running {\tt telnet}, you can invoke a number of commands, 
a quick description of these commands
can be found in the summary for {\tt telnet} in the reference
section, a fuller description can be found in the BSD reference documentation 
on disc. 

\subsection{rlogin}

The rlogin protocol is an application layer protocol for 
handling remote login. It consists
of a local {\tt rlogin} program (source) and a remote {\tt rlogind} daemon
(destination). 

\subsection{rsh}

The rsh protocol is an application layer protocol
which is concerned with starting up a shell on a
remote machine. It consists
of a local {\tt rsh} program (source) and a remote {\tt rshd} daemon 
(destination).
\subsection{rcp}

{\tt rcp} is an application layer protocol. It
copies files over the network: from local machine to remote host, from
remote host to local machine, and from remote host to remote host. Given
the optional flag {\tt -r}, it allows
files and subdirectories to be copied recursively from a given root. Multiple
copies in this way must go to a directory. 
This feature makes {\tt rcp} particularly useful for backing up over the
network, faithfully copying your file hierarchy from one machine to your
filespace on another one. 
{\tt rcp} will always assume the remote userid
to be the same as the current local userid, unless you give a remote username
with the remote hostname as part of the complete remote file identification.

\subsection{setterm}

{\tt setterm}, if run from a window supported by the ttyserver, alters the
termcap file entry the server is using for translating ANSI escape codes.

\section{Database and configuration files}

These files include the communication configuration files and the
database files, which are administrative files
used by each host and service to
keep track of what machines, subnetworks, protocols or 
services are available. The ones supplied
with Ethernet I are summarised briefly below. Notice that other 
database and configuration files used by the package will already have been 
supplied with the operating system, 
such as the password database
{\tt /helios/etc/passwd} and the configuration file {\tt host.con}.
The files outlined here should be treated in the following order:
\begin{enumerate}
\item
If a file pre-exists your purchase of Ethernet I, use that
file in preference to the one supplied.
\item
If you do not have these files already, take the ones supplied and adapt them
to suit your network.
\end{enumerate}
You should not need to write any of these files from scratch. In some
cases a database file may be copied directly from an existing Unix system.


\subsection{hosts}

{\tt hosts} is a simple database file containing the names of all the hosts
known to the network. There should be a separate {\tt hosts} database file on
every host machine on your network. This file is 
used by programs such as {\tt ftp}, {\tt telnet}, {\tt rlogin} etc
and their respective daemons to find a given host. 
\par
The file should contain several one-line entries,
one for each known host, and 
must include a one-line entry for the machine on which it resides
as well as an entry for {\tt localhost}, which must not be removed.
The {\tt localhost} entry is used by programs to locate and use 
services on the same local host as the one from which they were initiated.
\par
The host names and their corresponding network
numbers should be copied by the network
administrator from an existing {\tt hosts} file if at all possible
to tie in with the rest of the network.
Host names should be unique to the network on which
they reside. One or more aliases are allowed for each host. 
These aliases should follow immediately after the official host name 
to which they refer. Each entry starts with the
host's network number. This number should comprise
the standard four 8-bit octets of an IP address number (see Glossary).
Each octet contains
a decimal number in the range 0-255 and is separated from the next
by a decimal point. The entire address must be unique in order to locate
the correct machine over the network. 

\subsection{services }
 
This file consists of a simple database containing the names of 
the services that the network knows about. Each entry in this file
consists of a line containing the official name of the service,
its port number and protocol name (divided by a forward slash), optionally
followed by any aliases the service may have.
Standard services in Ethernet I include ftp and telnet. 
The network administrator can alter
this file to add additional services (for further details, 
see {Configuring the files} in the section on installing the 
Ethernet I software).

\subsection{networks}

This database file contains information on known networks or subnetworks
in your TCP/IP network. It matches names or aliases to network numbers.
Each one-line entry is of the form: 
{\it network name}, {\it network number}, optionally
followed by one or more aliases. Any text after a
{\tt \#} symbol up to the end-of-line is treated as a comment. 
You may make local changes to this file
to add unofficial aliases or unknown subnetworks 
(see {\bf Configuring the files}).

\subsection{protocols}

This database
file contains information on the known TCP/IP protocols used in the DARPA
Internet. For instance, this file is one of the files consulted by the
{\tt ping} program.
The form for each one-line entry in this file is as follows: official
protocol name, protocol number, alias(es). For example:
\begin{verbatim}
tcp 6 TCP  # transmission control protocol
\end{verbatim}

You do not have to maintain this file.

\subsection{termcap}

This file contains a database of terminal capabilities.
It is used by the pseudo terminal server. The format
is compatible with that used by BSD. 

\subsection{hosts.equiv}

Each host on the network will have its own {\tt hosts.equiv} file.
On PCs, the filename of this file is truncated to {\tt hosts.equ}.
This file is used by {\tt rlogind}.
It gives permission for given certain remote hosts and their
users to access the local host machine on which it resides
without a password, by indicating which hosts and users can be trusted 
to access the local machine over the network. 
You
can rlogin even if you are not
in {\tt hosts.equiv}, but you will have to type in your password again.
\par
The single-line file entries can contain the following:
just the name of a network host, in which case 
any user of that host can be trusted to access the local machine; or
the name of the host and that
of a known user (separated by a space), 
in which case that host can only be trusted if that user 
is attempting to access the local machine.  If a remote user or host is not 
listed as trusted in the {\tt hosts.equiv} file of the local machine then they
will not be allowed to access that machine.  See also {\tt .rhosts} in
{\bf User files}.

\subsection{inetd.conf}

This configuration support file is used by the inet daemon, {\tt inetd}.
The entries in this file specify the incoming communication requirements for 
the File Transport Protocol and the TELNET protocol: program
name (for example, {\tt ftp}),
stream or datagram, transport layer protocol (for instance, {\tt tcp}), 
{\tt wait} or {\tt nowait}, local host name, full pathname for the relevant
daemon, and daemon
name. The comments appear after the usual hash {\tt \#} symbol.
On PCs, the filename is truncated to {\tt inetd.con}.

\subsection{socket.conf}

This is the socket configuration file. 
It is used to translate the arguments to the {\tt socket()} call into
an appropriate server name.
The entries in this file are of the form: domain, type, protocol and server. 
On PCs, the filename is truncated to 
{\tt socket.con}.

\subsection{devinfo}

This is a device information database. It is compiled from a text source
file by the {\tt gdi} program. A {\tt devinfo} and {\tt devinfo.src} file are
distributed with the Helios file server, a {\tt devinfo.net} file is
distributed with the Ethernet I product. See the section on
configuring for further information on merging these files.

\subsection{Include files}

These are the files you need to include if you wish to port your own
programs.

\subsection{Library support}

All the necessary library support required for the Ethernet I package
is included in the BSD compatibility library \footnotesize
{\tt /helios/lib/bsd.lib},\normalsize
distributed with with Helios version 1.2.1. The following routines are
defined:

\begin{verbatim}
inet_netof  inet_lnaof    inet_makeaddr  inet_addr
inet_ntoa   inet_network  rcmd rexec     ruserpass

\end{verbatim} 

In addition, all the appropriate {\tt ioctl} operations are implemented,
with the exception of {\tt SIOCGIFCONF}.

\subsection{User files}

There are two user files that should be kept in each network user's own 
home directory: {\tt .rhosts} and {\tt .netrc}.

\subsubsection{.rhosts}

This file is similar to the {\tt hosts.equiv} file in the
{\tt /etc} directory of the local host machine, except that it represents
hosts and users which are considered to be trusted by the local user, and not
just by the local host machine. It is consulted after 
{\tt hosts.equiv}
to further weed out untrusted hosts and users before granting them access
to the local machine. It is up to each individual to ensure that this
file represents their own wishes.
The entries in the {\tt .rhosts} file of the local user of the local machine 
have precedence over the entries in the {\tt hosts.equiv} file of the same
machine.

\subsubsection{.netrc}

This file provides information for auto-login. It is used, in particular,
by {\tt ftp}, and may contain one or more of the following, which may
be separated by spaces, newlines, or tabs:

\begin{description}
\item {\tt machine} {\it name}

This represents a machine with which a connection can be opened. 
All further entries in the file refer
to this machine until end-of-file, or until
another {\tt machine} or a {\tt default} is encountered.
\item {\tt default}

This is like {\tt machine} {\it name}, except that it matches any 
name.

\item {\tt login} {\it name}

Where {\it name} is the userid to be used on login if the remote 
destination server requires a userid.

\item {\tt password} {\it string}

Where {\it string} is the password to be used for login. This
string is supplied automatically if the remote destination
server requires a password for login.
\item{\tt macdef} {\it name}

Enables macros to be defined. All subsequent lines are included in
the macro until a blank line is given.
\end{description}



\chapter{Installing the hardware}

This section makes reference to the installation of a Western Digital EtherCard Plus,
WDLAN-EPR(F001), or a DLINK card in a PC-based system.
If you have an Inmos B407 or B431 ethernet TRAM or a Parsytec ETN card,
refer to the manufacturers' documentation for hardware installation.
Before installing your network card, check
that it does not conflict with any other boards in the PC. Please see
your manufacturer's installation guide for details. 

\section{Configuring the host.con file}

As the IO Server needs to know where to find the board,
you must set the following values in the {\tt host.con} file.

\begin{description}
\item {\tt ethernet}

Tells the IO Server to provide a {\tt /ether} server.

\item {\tt ethertype}

Set to WD8003E or DLINK, depending on which card is provided.

\item {\tt ethermem}

Set to the base memory address in hexadecimal: \footnotesize 0xNNNNNNNN.
\normalsize

\item {\tt etherbase}

Set to the base I/O address in hexadecimal: 0xNNN.

\item {\tt etherrcr}

Sets the receive configuration register on the network card to accept 
broad\-cast
packets. If it is set to any value other than 4 then the action of the
TCP software will be undefined. The default is 0x04. 
{\em You are strongly advised not to alter this setting.}
\end{description}

\subsection{EtherCard Plus}

These are the important items to consider:
 
\begin{itemize}
\item
Base I/O address
\item
Base memory address
\end{itemize}

So, if the base I/O address is 0x280 and you want the memory at 0xD0000000,
add the following lines to the {\tt host.con} file:
\begin{verbatim}

   ethernet
   ethertype = WD8003E
   etherbase = 0x280
   ethermem  = 0xD0000000

\end{verbatim}
{\tt etherrcr} should be left with its default setting. 

{\bf Note:} There is no jumper on this Western Digital card to set the
base memory address as it is set by software.

\subsection{DLINK}

These are the important items to consider:
 
\begin{itemize}
\item
Base I/O address
\item
Base memory address
\end{itemize}

So, if the base I/O address is 0x280 and you want the memory at 0xD0000000,
add the following lines to the {\tt host.con} file:
\begin{verbatim}

   ethernet
   ethertype = DLINK
   ethermem  = 0xD0000000

\end{verbatim}
You do not have to set the
{\tt etherbase} base address here as the software can calculate it by 
looking at the base memory of the board. Again,
{\tt etherrcr} should be left with the default setting. 

{\bf Note:} For a base address of 0xD0000000, you would need to set the
jumpers on the board for the D0000h setting.

\section{Booting Helios}

Having included the correct entries in the {\tt host.con} file, you can
go on to boot Helios. If you have made any mistakes in setting up the
board or in configuring {\tt host.con}, you may get one of the following
error messages from the IO Server:

\begin{tabular}{lll}
\\
I/O Server & : & unknown ethernet board {\it ABCDE}\\
           & : & supported boards are WD8003E and DLINK\\

\end{tabular}

You might get this if you have got the {\tt ethertype} entry incorrect in
the {\tt host.con} file. The next error message indicates that the IO Server
could not find the ethernet board check that the base address and memory
address correspond with the jumpers set on the board:

\begin{tabular}{lll}
\\
I/O Server & : & /ether device not found \\
I/O Server & : & base 280, mem D0000000, etherrcr 4, level 1, type 1\\

\end{tabular}
\par
If you get any error messages, you should check the board and {\tt host.con}
file and then reboot Helios.

\section{Finding out if /ether exists}

To find out if {\tt /ether} exists, type 
\begin{quote}
\begin{verbatim}
ls /ether
\end{verbatim}
\end{quote}
to the shell. This should locate the device. If you fail to locate
it, check the following:
\begin{itemize}
\item
Have you have mistyped the word {\tt ethernet} in the {\tt host.con}
entry?
\item
Are there any error messages from the I/O Server? Check by swapping to the
Error Window with the ALT-F1 key combination.
\item
Have you connected your Helios system to a busy ethernet site? You should 
still be
able to check that your system is working by typing {\tt dump /ether} to
read any broadcast packets from your ethernet and 
then display them to the screen.
Notice that this will only work if you have other machines on the network
sending broadcast ethernet packets.
\end{itemize}
\par
Now follow the instructions in the next section of this manual to
install the rest of the software. %Note that although it is essential that
%you use the correct ethernet driver device, you do not have to worry about
%setting it as it is set up automatically when you load the package.
 
\chapter{Installing Ethernet I}

Installation can be broken down into the following steps:

\begin{enumerate}
\item 
Backing up the original distribution disc
\item
Loading the package
\item
Configuring the distribution files
\item
Setting up subnetworks (this is optional and is not covered here)
\item
Starting up
\item
Checking the network
\end{enumerate}

\section{Backing up the distribution disc}

Do not forget to back up the original distribution disc. 
Copy the contents of the disc to a
safe storage device, preferably to another floppy
disc, which should then be write disabled. This simple precaution should
not be overlooked.

\section{Loading the distribution files}

To install Ethernet I, insert the distribution 
disc in your host machine and type:
\begin{quote}

{\tt loadpac}

\end{quote}

The {\tt loadpac} program prompts you for the required information
as it runs.

\begin{enumerate}
\item
It will ask you to indicate which disc drive contains the package you
wish to load. The default is {\tt /a}. If you wish to select another drive,
type {\tt 1}. {\tt loadpac} will then display a new screen, giving you
instructions on how to continue.
\item
Once {\tt loadpac} knows which drive to use, you can proceed with
the installation. Select menu item 4 to install new software.
\item
{\tt loadpac} will now display a menu screen
containing a range of packages that can be
loaded. Select {\bf Ethernet} by typing {\tt 5}.
\item
All the standard files will now be copied from the distribution disc 
on the selected drive to the
correct directories on your machine's hard disc. If you have inserted the
wrong disc, or selected the wrong drive by mistake, {\tt loadpac} will
inform you that this has happened and will allow you to quit or amend
your mistake. To quit {\tt loadpac}, type {\tt q}.
\item
It will ask you if you wish to use the database and configuration files
provided, or
if you wish to retain previous versions. See {\it Configuring the files}
below for further details.
\end{enumerate}

Once you have loaded the package, you can proceed to configuring the files
to reflect your own network environment.

\section{Configuring the files}

This section is about taking the default files provided 
on the distribution disc and amending them where necessary
to reflect your network. For example, 
all the database files must contain
entries that correspond to the hosts, services, and so on that are present
on your network. Note that these files should normally be copied directly
from existing machines. The network administrator for the whole site
should be responsible for doing this.

\subsection{services}

You should only alter this database file if you have any
additional services available on your network. Each 
service should have a one-line entry, consisting of
the official name of the service,
its port number and protocol name (divided by a forward slash), optionally
followed by any alias the service may have.
The first item may not have any leading blanks before it;
otherwise, there may be any number of blank spaces in between each item.
The port number and protocol name are treated together, hence they are
simply divided by an intervening slash. The {\tt \# } 
symbol introduces a comment;
routines calling this file will ignore
all subsequent characters up to the end of the line. 

\subsection{hosts}

The {\tt hosts} database file 
contains the names of all the hosts known to the network.
If you already have other Unix 5.4, BSD or SUNOS-based hosts, you may
already have access to a standard /etc/hosts file. In which case, 
copy that file and adapt it according to your present requirements. 
Otherwise, take the
{\tt hosts} file provided and adapt that one instead.
\par
For your Helios system to become part of your local network it must
have both a unique name and a unique internet address. In most networks
these are allocated by some central authority. This may be as
informal as saying that the {\tt hosts} database on a particular machine
is the master copy. %(usually the YellowPages/NIS master server).
% DO NOT FORGET TO ENTER THESE TM IN COPYRIGHT FILE!!!!
Alternatively, in very large systems, you may have to apply to a particular
person who ensures that names and addresses are unique, the network
administrator. Either way, the name and address of your machine must be
installed both in the local {\tt hosts} file and in the {\tt hosts} files
of all machines with which you wish to communicate.
{\tt hosts} is regularly consulted by {\tt ftp}, {\tt telnet}, etc and
their respective daemons, to find a given host.
There should therefore be a {\tt hosts} database file on
every host machine on the network to provide an index to the others. 
Each one-line entry in the file refers to a single 
host. The format is as follows:
\begin{quote}

{\it inetaddr}  {\it name   [alias] [} {\tt \#}{\it comment ]}
 
\end{quote}

The names and aliases must be unique to the network on which
they reside. The {\it inetaddr} is a
number allocated to the host which acts as its address on the
network. It should follow the standard four 8-bit
octets of an IP address number (see Glossary).
Each octet contains a decimal number in the range 0-255.
The first three octets represent the network 
and indicate its classification. The last octet indicates the host.
\par
{\bf Warning:}
Do not remove the existing
entry for {\tt localhost} in the {\tt hosts} database:
\begin{quote}
\begin{verbatim}

127.0.0.1   localhost

\end{verbatim}
\end{quote}
This entry must be present for programs to find 
services on the same local host as the one from which they were initiated.
To add another host to {\tt hosts}, follow these steps:

\begin{enumerate}
\item
Unless the host is new to the whole network, insert into the file
the existing address for that host, 
which you can find elsewhere (in another {\tt hosts}
database on another host machine, for instance). 
Otherwise, if the host is completely new to the network, 
take the entry with the highest {\tt inetaddr}, 
copy it and increase the last octet (the host number)
in the copied entry by 1. 
Remember that the maximum number is 255.
\item
Alter the host {\it name} of the copied entry
to match the name of the host to be added. The maximum length for a
host name is 32 printable ASCII characters. 
Host names may not include the characters
newline, hash ({\tt \#}) or slash (/).
\item
Add or alter the {\it alias}; this may not be necessary because aliases are
optional and are not always present. The same alias should not be used for
two hosts on the same network as aliases and names should be unique, 
but two or more aliases can be used for the same host. Maximum length 
and character rules for aliases are the same as for {\it names}.
\item
Insert a new comment after the {\tt \#} symbol. For example:
\begin{verbatim}

            # This is Bill's PC
\end{verbatim}
\end{enumerate} 

\subsection{networks}

The {\tt networks} 
database file contains information on known networks or 
sub\-networks
in your TCP/IP network. 
This file is used to match names or aliases to network numbers.
You should only need to make local changes to this file
to add unofficial aliases or unknown subnetworks. (Official network
names are ones known externally to all internet networks; these names
are maintained by the {\em Network Information Service}. If you reuse
an official name, you may find a few interesting problems arise from
the confusion.)
Each one-line entry in this file is of the form: 
\begin{quote}

{\it name number [alias][comment]}

\end{quote}
where {\it name} is the name by which the network is known, 
{\it number} is the IP network number, the optional 
{\it alias} refers to
one or more extra unofficial names by which the network may be known, and
the {\it comment}, which is also optional, is any supplementary
text starting with a {\tt \#} symbol through to end-of-line. 
Entries may not start with any blank spaces; 
otherwise there may be any number of blank spaces or tab characters
between each item. Lines starting with a
{\tt \#} symbol will be treated as comments (that is,
routines calling this file will ignore
all subsequent characters up to the end of the line). 
To add new entry for each additional network or subnetwork, follow
these steps:
\begin{enumerate}
\item
Take the entry with the highest network number, copy it and increase the
last digit of the last octet in the copy by 1.
Network numbers should be specified with the usual
octet and `.' notation used for IP network numbers.
\item
Alter the network name and alias (if one exists) to match the name of
the network or subnetwork you are adding. The names 
in this file may include
any printable ASCII character except slash (/), newline, and hash ({\tt \#}),
and may have a maximum length of 32 characters.
\item
Add a comment to indicate to others what you have done.
\end{enumerate}

\subsection{devinfo}

The TCP/IP server selects the ethernet device driver it is to use by consulting
this file. The {\tt devinfo} file is compiled by the {\tt gdi} program
that is distributed with Helios 1.2.1.
\par
If you have the Helios File Server then you should already have {\tt devinfo},
{\tt devinfo.src} and {\tt gdi}. You must use the new version of {\tt gdi}
distributed with Helios V1.2.1 and not that distributed with the
File Server. This new version announces itself as Version 1.2 and is
backwards compatible with the older version.
To merge the existing devinfo files, simply concatenate the file
{\tt devinfo.net} onto the end of {\tt devinfo.src} and proceed to edit
it as described later.

If you do not have the Helios File Server, simply rename {\tt devinfo.net} as
{\tt devinfo.src}. If you subsequently install the File Server, ensure that
you rename this file back to {\tt devinfo.net} beforehand and proceed
as described above to merge the files.

If you are using the Inmos B407 or B431 ethernet TRAM you will need to edit the
{\tt devinfo.src} file to set up the link number and ethernet address.
The link number is indicated by the {\tt controller} field of the 
{\tt netdevice in\_ether} entry. This must be the link of the processor
running the TCP/IP server to which the B407 or B431 is attached. This type
of ethernet controller also needs to be told what its ethernet address
is, valid values for this should be included with the hardware documentation.

The TCP/IP server takes a command line option to define the {\tt netdevice}
entry it will use. If no option is given then the name `ether' is looked
for. You may either change the name of the {\tt netdevice} entry you want
to use to `ether' or supply it name to the server. 
Once the {\tt devinfo.src} file has been edited to your satisfaction, save it
and compile it with the following command line:
\begin{verbatim}	
gdi /helios/etc/devinfo.src /helios/etc/devinfo
\end{verbatim}

The file is now ready for use.

\section{Starting up}

Having configured all the files, the ethernet software is started up by
invoking the TCP/IP server. The command line syntax for this is:
\begin{verbatim}
/helios/lib/tcpip name inetaddr [-s mask] [-e device]
\end{verbatim}

The {\em name} and {\em inetaddr} must be the name and address allocated
to your machine and should match the entries in all the {\tt hosts} databases
in the network. The {\em -s} option introduces a subnet mask in normal
`dot' notation. You will be informed by your network administrator whether
you need to supply this, and what value should be given. The {\em -e}
option introduces the name of the {\tt netdevice} entry in the {\tt devinfo}
file which should be used. If no {\em -e} option is given the entry name
`ether' is used.
If you wish other users to access the services supplied by your machine
you will also need to run the internet daemon.
As an example, a shell script to start the ethernet software would look
something like this:
%\begin{quote}
\begin{verbatim}
/helios/lib/tcpip Zaphod 42.0.0.42 -e in_ether &
/helios/lib/inetd &
\end{verbatim}
%\end{quote}

Alternatively you can add the following lines to your {\tt initrc} file:
\small
%\begin{quote}
\begin{verbatim}
run -e /helios/lib/tcpip tcpip Zaphod 42.0.0.42 -e in_ether
run -e /helios/lib/inetd inetd
\end{verbatim}
%\end{quote}
\normalsize

If the processor to which your ethernet hardware is attached is not your
root processor, you can use {\tt remote} from the shell or {\tt initrc}.
Alternatively, you can run tcpip and inetd from the resource map (see the
chapter on Networks in the latest {\em Helios Operating System} manual).

\section{Checking the network}

Once you have loaded Ethernet I and configured it for your own
network, you may wish to check that the network interface 
is up and running correctly. 
To help you do this, Ethernet I includes the {\tt ping} command.
{\tt ping} sends an echo request
between two hosts on the network and watches for a response. Using it,
you can isolate any inter-network problems that may occur. 
Because of the wide range of network hardware and the possible
complexity of gateway interconnections, pinpointing a problem in
the hardware or software can sometimes be a problem in itself. 
\par
{\tt ping} acts by sending an ICMP/IP echo request datagram (a {\it ping})
to other network hosts to provoke an echo response from a host or gateway.
Each of the ECHO\_REQUEST datagrams has an IP and ICMP header,
a \footnotesize {\tt timeval} \normalsize
datastructure, and lastly a number of bytes of padding 
to fill out the rest of the packet. (The
default length for a datagram is 64 bytes, but you may wish to change this
with the {\it packetsize} option; see below.)
The format for {\tt ping} is as follows:
\begin{quote}
{\tt ping} {\it [}{\tt -r}{\it ] [} {\tt -v} {\it ] host [ packetsize] [count]}
\end{quote}

The {\tt -r} option causes the usual routing tables to be bypassed,
so that the {\it ping} is sent directly to a host on an attached network.
If the target host is not on a network that is attached
directly to the originating host's network, an error occurs.
The {\tt -v} option causes any output to be
{\it verbose}: it lists any ICMP packets other than ECHO\_RESPONSE that 
it receives.
{\it host} represents the target host. It
can consist of an Internet address or a character-string that matches 
one of the known host names listed in the {\tt hosts} file.
{\it packetsize}, as mentioned earlier, allows you to specify a different
byte size for the datagram packet (the default is 64). {\it count} 
is optional, it represents the number of times you wish the request to
be sent.
\par
{\tt ping} sends one echo request datagram per second, and then
returns one line of output for each corresponding response it receives.
You can specify {\it count} number of requests.  In which case, as
{\tt ping} only produces output if it gets a response from a request, 
you should get exactly
{\it count} number of responses and {\it count} number of lines of
output if all is going well.
{\tt ping} continues until it has 
\begin{itemize}
\item Received all the responses it expects
\item Timed out
\item Terminated after receiving an interrupt signal
\end{itemize}
\par
Each successful
response provokes one line of output: for example,
%\begin{quote}
\begin{verbatim}
64 bytes from 89.0.0.0 icmp_seq=0.time=12.ms
\end{verbatim}
%\end{quote}

{\tt ping} also works out the
round-trip times for each {\it ping}, plus any packet loss statistics, 
and displays a brief summary.
If a {\it ping} fails, one of the following error messages may be displayed:
\begin{quote}
\begin{verbatim}

Host unreachable
Network unreachable
Bad response from server
Timeout
Out of resources
The intial echo request packet could not be sent

\end{verbatim}
\end{quote}
\par
To isolate a fault:
\begin{enumerate}
\item First run {\tt ping} on your local host.
This way you can check that the local network software is up and
running correctly.
\item Next, in turn, {\it ping} each successive host or gateway 
away from your local host. Continue until you locate the problem.
\end{enumerate}

If a remote host fails to respond to a network request, it means that 
there is 
a cable break at some point between your local host and the remote
host, the host is down, or that host does not support the service you require.
The purpose of {\tt ping} is to help you work out which of these has
caused the failure. If you can {\it ping} other remote hosts on the same network
successfully, then it is likely that the original target host is down or
not listening to the network. If you cannot {\it ping} any host on the same
network successfully, then it is likely that the trouble is somewhere en route
between your local host and the target remote host. You
should then work along the route from your local host
until you stop getting the expected response.
\par
Datagrams are by definition unreliable: their delivery cannot be guaranteed.
It is therefore quite possible for an echo request to be lost if, for example,
the network is overloaded. This means that you should not assume that there
is a problem on the network unless your {\it pings} consistently fail.
Nevertheless,
if most {\it pings} succeed up to a certain point on the network and then
consistently fail beyond that point, you have cause to be suspicious.
\par
{\bf Note:} Overuse of {\tt ping} places a great load on the network. 

\chapter{Examples}


\section{Communication via sockets}


While this document is not intended to be an introduction to the use
of sockets for inter-process communication, a simple example program
of using Internet sockets is included on the disc in 
\begin{verbatim}
/helios/local/tcpip/example/socket.c. 
\end{verbatim}

Read the comments in this file for further information. For more information
on the use of sockets, read the document available with any Unix system
which supports it. The documentation supplied with SunOs is particularly
recommended.

\section{Writing a new driver}


This can be found in the directory {\tt /helios/local/tcpip/pc-ether} together
with a makefile. The comments in the sources should be sufficient for you
to be able to write a functionally equivalent driver.
Note that in order to make drivers you need the latest release of the
AMPP assembler macro pre-processor.
\newpage

\vspace*{18cm}
\chapter{User's reference}

This section contains a quick summary of each of the commands.
For a fuller description, see the 4BSD documentation sources 
on the distribution disc.
\vfill
\newpage

\begin{center}
{\Large{\bf ftp}}
\end{center}
\vspace{2cm}

\noindent {\large{\bf Purpose:}}\hspace{0.5cm} Enables users to transfer files between 
network hosts.
\vspace{1cm}

\noindent {\large{\bf Format:}}\hspace{0.6cm} {\it ftp [\--v] [\--d] [\--i] [\--n] [\--g] 
[host]}
\vspace{1cm}

\noindent {\large{\bf Description:}}
\vspace{0.5cm}

\noindent {\tt ftp} is the user interface to the ARPANET standard File Transfer Protocol.
\vspace{0.25cm}

\noindent {\it host} is the name of the client host. If specified, {\tt ftp} will
open a connection to the corresponding {\tt ftpd} on that machine.
If you omit {\it host}, {\tt ftp} will start up the command interpreter
to handle commands locally. 
You can find out what commands are available by giving the command
{\tt help} or by typing a question mark on a line by itself. Here is
a quick list, similar to what would be displayed if you requested such
general assistance.

\begin{tabular}{lllll}
\\
{\tt !} & {\tt \$} & {\tt ?} & {\tt account} & {\tt append} \\
{\tt ascii} & {\tt bell} & {\tt binary} & {\tt bye} & {\tt case} \\
{\tt cd } & {\tt cdup} & {\tt close} & {\tt cr} & {\tt delete}  \\
{\tt debug} & {\tt dir} & {\tt disconnect} & {\tt form} & {\tt get} \\ 
{\tt glob } & {\tt hash} & {\tt help } & {\tt image} & {\tt lcd } \\
{\tt ls } & {\tt macdef} & {\tt mdelete} & {\tt mdir} & {\tt mget}  \\ 
{\tt mkdir} & {\tt mls}  & {\tt mode}  & {\tt modtime } & {\tt mput } \\ 
{\tt nlist} & {\tt nmap}  & {\tt ntrans}  & {\tt open }  & {\tt prompt} \\ 
{\tt proxy} & {\tt put }  & {\tt pwd} & {\tt quit} & {\tt quote}  \\ 
{\tt recv } & {\tt remotehelp}  & {\tt rename} & {\tt reset} & {\tt rmdir}  \\ 
{\tt rstatus} & {\tt runique} & {\tt send}  & {\tt sendport} & {\tt size} \\
{\tt status} & {\tt struct}  & {\tt sunique} & {\tt system} & {\tt tenex}\\
{\tt trace} & {\tt type}  & {\tt user } & {\tt verbose}
\\
\end{tabular}
\vspace{0.25cm}

To find out specific details about a particular command, specify the
command's name as an argument to {\tt help}. 
Most commands affect files or directories on the remote machine. For example,
{\tt cd} changes your directory to a directory on the remote machine
to which you are connected. To change directory to a directory on your
local machine, use {\tt lcd}. 
\par
To terminate {\tt ftp}, type {\tt quit} or {\tt bye}. To close
a connection without terminating the session, use {\tt close} or
{\tt disconnect}.
\par
To abort a file transfer, press CTRL-C (terminal interrupt). If {\tt ftp}
is waiting for a remote reply, it will ignore the interrupt until it is
ready. You may find in some circumstances, however, that
you have to kill {\tt ftp} instead.
\par
To retrieve remote files, use {\tt recv}, {\tt get} or {\tt mget}. 
To send a local file to a remote machine, use {\tt send}, 
{\tt put} or {\tt mput}. 
\par
Notice that the {\tt m} before the {\tt put} or {\tt get} 
commands in {\tt mput} and {\tt mget}
means that {\tt ftp} should expect multiple file transfers.
Most commands expect to affect a single file; this may be confusing
with familiar commands such as {\tt rm}, which under {\tt ftp} will
only remove one remote file given as argument.
\par
{\tt ftp} processes filename arguments according to the following rules:
\begin{enumerate}
\item If you specify -- in place of a filename, {\tt ftp} takes input from 
{\it stdin} or sends output to
{\it stdout}, depending on context.
\item If the first character of the filename is $|$, {\tt ftp} interprets the
remainder of the argument as a shell command to which the output is piped.
\item If `globbing' is enabled, it expands
local filenames according to {\tt glob} shell command rules.
\item If the {\tt recv}, {\tt mget} and {\tt get} commands are not given
local filenames, the local filename is considered to be the same as
the remote filename.
\item If the {\tt send}, {\tt mput} and {\tt put} commands are not
given remote filenames, the remote filename is considered to be the same as
the local filename.
\end{enumerate}
\par
Parameters that affect file transfer are as follows:
\begin{description} 
\item[{\it type}]
This may be ascii or image (binary).
Ascii is the default type.
\item[{\it mode}, {\it form}, {\rm and} {\it struct}]
These take default values only: {\it stream} mode, 
{\it stream} \newline structure and {\it file} format. 
\end{description} 
\par
You may specify the following
options at the command line, or to the 
command interpreter:
\begin{description}
\item[{\bf --v}]
Turns verbose mode on. 
All responses from the remote server will be shown and data transfer statistics
will be reported in full.
\item[{\bf --n}]
Stops auto-login on connection.
If auto-login is enabled, {\tt ftp}
consults the user's {\tt .netrc} for an entry for the remote machine.
If it cannot find such an entry, it will prompt the user for a login id and,
if necessary, for a password as well.
\item[{\bf --i}]
Stops interactive prompting.
\item[{\bf --d}]
Enables debugging.
\item[{\bf --g}]
Disables filename globbing.
\end{description}


\begin{function}{ping}
\fpurpose{A diagnostic tool that sends echo requests over the network.}
\fformat{ping [--r] [--v] host [packetsize] [count]} 
\begin{fdescription}
{\tt ping} is a network maintenance tool that can be used to isolate
inter-network problems. A full description of its use can be found
earlier in this guide, under the heading {\it Checking the network}.
\par
{\tt ping} acts by sending an ICMP/IP echo request datagram (a {\it ping})
to other network hosts to provoke an echo response from a host or gateway.
Each \footnotesize ECHO\_REQUEST \normalsize  datagram has an IP and 
ICMP header,
a \footnotesize {\tt timeval} \normalsize datastructure, and lastly a number 
of bytes of padding 
to fill out the rest of the packet. (The
default length for a datagram is 64 bytes, but it can be changed 
using the {\it packetsize} option.)
\par
The arguments are as follows:
\begin{description}
\item[{\tt -r}]
Bypasses the usual {\it routing} tables, sending
the {\it ping} directly to a host on an attached network. An error occurs
if the target host is not on a network that is attached
directly to the originating host's network.
\item[{\tt -v}] 
Provokes {\it verbose} output; that is, it lists any ICMP packets other than
\newline ECHO\_RESPONSE that 
it receives.
\item[{\it host}] 
Represents the target host (IP address or host name string). The identification
must match a known host in the {\tt hosts} file.
\item[{\it packetsize}]
Allows you to specify a different
byte size for the datagram packet (the default is 64). 
\item[{\it count}]
Represents the number of times the request is to
be sent (optional).
\end{description}
\par
{\tt ping} sends one echo request datagram per second, and then
returns one line of output for each corresponding response it receives.
You can specify {\it count} number of requests.  In which case, as
{\tt ping} only produces output if it gets a response from a request, 
you should get exactly
{\it count} number of responses and {\it count} number of lines of
output if all is going well.
\par
{\tt ping} continues until it has 
\begin{itemize}
\item Received all the responses it expects
\item Timed out
\item Terminated after receiving an interrupt signal
\end{itemize}
\par
Each successful
response provokes one line of output.
\end{fdescription}
\end{function}
\begin{function}{rcp}
\fpurpose{Copies files between machines}
\fformat{rcp filename1 filename2} or
\fformat{rcp [--r] filename \ldots dirname}
\begin{fdescription}
{\tt rcp} stands for remote copy. It carries out remote file copying over
the network in the same way that {\tt cp} does within one machine. 
The arguments {\it filename}, {\it filename1}, {\it filename2} 
and {\it dirname} refer to remote
or local filenames or directory names. 
Remote names are given as 
\begin{verbatim}
hostname:pathname
\end{verbatim}

or 
\begin{verbatim}
hostname.remoteusername:pathname.
\end{verbatim}

Local names are as usual, although they must
not include a colon character so as not to be confused with a remote file
description.
\par
The optional flag {\tt -r} indicates that the copying should be recursive,
repeatedly copying the contents of any subdirectories below {\it filename}.
If more than one file is being copied, its destination name must be that
of a directory.
\par
Within a remote filename description,
{\it pathname} is usually assumed to be relative to your home login directory
on the remote host {\it hostname}. Your local user id must match exactly
with one on remote host {\it hostname} for the remote copy to take place,
unless you specify {\it remoteusername} as being the name of the
file owner on remote host {\it hostname}.
\end{fdescription}
\end{function}
\begin{function}{rlogin}
\fpurpose{Attempts to login on a remote host.}
\fformat{rlogin rhost [--ec ] [--l user] [--8] [--L]}
\begin{fdescription}
{\it rlogin} connects your terminal to remote host {\it rhost}.
\par
Each host has a file {\tt /helios/etc/hosts.equiv} which contains a list of 
the names of trusted remote hosts and users. If you are listed as
being trusted on the {\tt hosts.equiv} file on the remote machine, you
will not need to give your password in order to login. The
{\tt .rhosts} file is a private version of {\tt hosts.equiv} and can
override the entries given there to effect automatic login.
If your username or {\it user} is not listed as being trusted, {\tt rlogin}
will send the login prompt and request a password.
\par
The options accepted by {\tt rlogin} are as follows:
\begin{description}
\item[{\tt -8}]
Allows an eight-bit input data path.
\item[{\tt -L}]
{\em litout} mode (provided for compatibility with 4BSD).
\item[{\tt -e}{\it c}] Sets up escape character {\it c}. There should be
no space between option flag {\tt -e} and character {\it c}.
\end{description}
\end{fdescription}
\end{function}
\begin{function}{rsh}
\fpurpose{Runs a command in a remote shell.}
\fformat{rsh host [-l user] [[-n] command] }
\begin{fdescription}
{\tt rsh} opens a connection to {\it host},
and executes {\it command}.  
The local stdin will then go directly
to the remote command, the remote commands's
stdout will go to the local stdout, and the
stderr of the remote command will go to the local stderr. Any
interrupts generated locally will go automatically to the remote shell.
\begin{description}
\item[{\it host}] 
This argument must match a name given in {\tt helios/etc/hosts}.  
\item[{\it user}] 
This is only necessary if the name is different from
the local username. Notice that, unlike {\tt rlogin}, {\tt rsh} will not check passwords.
\item[{\it command}]
If you run {\tt rsh} without giving {\it command}, {\tt rsh} 
will act like {\tt rlogin}.
\end{description}
Any quoted shell metacharacters are interpreted on the remote machine; unquoted
shell metacharacters are interpreted on the local machine.
If a link is made to {\tt rsh} using the name of a machine, then
the program will detect this and use this as the destination host name.
On files systems which cannot support links, this can be simulated by copying
{\tt rsh} to files of the appropriate name at the expense of extra disc usage.
Additionally if no command is given then {\tt rsh} executes {\tt rlogin}. 
These features may be combined to make remote execution a little more natural.
For example, suppose you have a remote machine {\tt sparky} which you use
frequently. Put a link to, or copy of, {\tt rsh}, called {\tt sparky},
into one of your command directories. Now, commands can be executed on
{\tt sparky} by: \verb+% sparky <command>+
and you can log into {\em sparky} with the simple command \verb+% sparky+
\end{fdescription}
\end{function}
\begin{function}{setterm}
\fpurpose{Sets the tty server terminal type.}
\fformat{setterm ttytype}
\begin{fdescription}
This program tells the ttyserver to change to a new terminal type.
The single argument must be a terminal name which will match an entry in
the termcap file. The program must be run in a window supported by the
tty server.
\par
Under Helios all programs use ANSI standard escape
sequences to interact with terminals. The IO server implements these 
codes directly, but serial lines and remote sessions may have some other
form of terminal attached to them. In order for the tty server to present
the effect of any ANSI sequence it must be informed what kind of terminal
it is dealing with and translate the codes accordingly. In the case of
remote sessions the tty type will by set automatically, but in the case
of serial line sessions, the type must be set by the user.
\end{fdescription}
\end{function}
\begin{function}{telnet}
\fpurpose{Provides a user interface to the TELNET protocol.}
\fformat{telnet [host [port]]}
\begin{fdescription}
{\tt telnet} is used to communicate with another host using the TELNET
protocol. If it is invoked without any arguments, {\tt telnet}
enters command mode and displays the prompt {\tt telnet$>$}. If invoked
with arguments it opens a connection to the given host in exactly the
same way as it would if the internal command {\tt open} 
(given below) was invoked.
\par
Once a connection has been opened {\tt telnet} enters input mode, which
can be line by line or character by character, depending on what the
remote host requires. 
\par
The internal commands are as follows:

\begin{tabular}{llll}
{\tt ?} & {\tt close} & {\tt display} & {\tt mode} \\
{\tt open} & {\tt quit} & {\tt send} & {\tt set} \\
{\tt status} & {\tt toggle} & {\tt z} 
\end{tabular}
\begin{description}
\item[{\tt ?} {\it [command]}] 
Displays a summary of available commands. 
\item[{\tt close}] 
Closes a {\tt telnet} session. 
\item[{\tt display} {\it [arg\ldots]}] 
Displays {\it set} or {\it toggle} values. 
\item[{\tt mode} {\tt line} $|$ {\tt character}] 
Sets the mode type to line-by-line or characters. 
\item[{\tt open} {\it host [port]}]
Opens a connection to a named host via either a named port or the default
one. 
\item[{\tt quit}] 
Closes a session and exits. 
\item[{\tt send} {\it arg\ldots}] 
Sends one or more special character sequences to the remote host. 
A full description of all the accepted
arguments to {\tt send}
can be found in the summary for {\tt telnet} in the reference
section or in the BSD reference documentation or that of SUNOS or Unix 5.4.
However, they include: 
\begin{description}
\item[{\tt escape}] 
Sends the current Escape character
\item[{\tt synch}] 
Sends the SYNCH sequence
\item[{\tt brk}] 
Sends the Break sequence
\item[{\tt ip}]
Sends the Interrupt Process sequence
\item[{\tt ao}] 
Sends the Abort Output sequence
\item[{\tt ayt}]
Sends the Are You There sequence
\item[{\tt ec}]
Sends the Erase Character sequence
\item[{\tt el}]
Sends the Erase Line sequence
\item[{\tt ga}]
Sends the Go Ahead sequence
\item[{\tt nop}]
Sends the No OPeration sequence
\end{description}
\item[{\tt set} {\it arg value}]
Sets a telnet variable to the given value. A full description can be
found in the full formal documentation of {\tt telnet}.  Here is a 
quick list of the possible variables: {\tt echo}, {\tt eof}, {\tt erase},
{\tt escape}, {\tt flush\-output}, {\tt interrupt}, {\tt kill} and {\tt quit}.




\item[{\tt status}] 
Shows the current status of {\tt telnet}. 
\item[{\tt toggle} {\it arg\ldots}]
Toggles between \footnotesize TRUE \normalsize and \footnotesize FALSE
\normalsize
for the various arguments to control telnet's
response to events. Here is a quick list of the possible arguments:
\begin{description}
\item[{\tt localchars}] 
Initially TRUE for line-by-line and FALSE for character at a time mode.
\item[{\tt autoflush}] 
Initially TRUE. 
\item[{\tt autosynch}]  
Initially FALSE.
\item[{\tt crmod}] 
(Carriage return mode) 
Initially FALSE.
\item[{\tt debug}] 
Initially FALSE.
\item[{\tt options}] 
Initially FALSE.
\item[{\tt netdata}]
Initially FALSE.
\end{description}
\item[{\tt z}] 
Suspends {\tt telnet} from the shell. 
\end{description}
\end{fdescription}
\end{function}

\begin{function}{ttyserv}
\fpurpose{To provide terminal functions on a stream}
\fformat{/helios/lib/ttyserv [-i path] [-o path] [-l path] [-n name] 	

[-d device] [-w] [-s] [-p] [-u]}	 
\begin{fdescription}
This is a server which provides terminal emulation, including line
editing, ANSI escape sequence interpretation and multiple full screen
windows. The exact form of the supporting device is determined by the
driver loaded into the tty server. Two drivers are currently supplied:
{\tt tpseudo.d} which emulates Unix pseudo terminals, and {\tt tserial.d}
which uses a serial stream.

The options are as follows:

\begin{description}

\item {\tt -i} {\em path}	

Use the stream {\em path} for keyboard input.

\item {\tt -o} {\em path}	

Use the stream {\em path} for screen output.

\item {\tt -l} {\em path}

Use the stream {\em path} for input and output.

\item {\tt -n} {\em name}	

Use {\em name} as the server name, if this option is absent
the name used will be {\tt tty.N} where {\tt N} is the lowest
integer not already in use. If the pseudo-tty device is being
used, it will use the same server name with the first character
changed to a `p' (e.g. {\tt pty.0} for {\tt tty.0}).

\item {\tt -t} {\em type}

Initialise the ttyserver to use the {\em type} entry from the
{\tt termcap} file. If this is not present then it will
attempt to use the termcap entry defined by the TERMCAP
environment variable.
		
\item {\tt -d} {\em device}	

Use device {\em device}.

\item {\tt -w}		

Write the server pathname onto the output at startup. This is
used by some pseudo-terminal clients.

\item {\tt -s}		

Equivalent to {\tt -d tserial.d}.

\item {\tt -p}		

Equivalent to {\tt -d tpseudo.d -w}.

\item {\tt -u}		

Print a usage message.

\end{description}

When the pseudo-tty driver is used, the tty server needs to be started from
a program, this is what {\tt rlogind} and {\tt telnetd} do. A serial
line server can be created from the command line by the following:
\begin{verbatim}
/helios/lib/ttyserv -l /rs232/default -s -t vt100 &
\end{verbatim}

A shell, or any other command can now be run with:
\begin{verbatim}
shell </tty.0/Shell >&/tty.0/Shell &
\end{verbatim}

To add an extra login terminal you can add the following lines to your
initrc file:
\footnotesize
\begin{verbatim}
run -e /helios/lib/ttyserv ttyserv -l /rs232/default -s -t vt100
waitfor /tty.0
console /tty.0 User1
run -e /helios/bin/newuser newuser
\end{verbatim}
\normalsize

Any program which may be run on the IO server windows may be run in a tty
server window. New full screen windows may be created in exactly the same
way with {\tt wsh} or {\tt run}. For this to be useable the termcap file
entry must contain definitions of the screen switching keys 
\verb+%5+ and \verb+%8+.
\end{fdescription}
\end{function}

\vfill
\newpage

\vspace*{18cm}
