		     User's Guide for Net 1.0
		Copyright 1986 by Phil Karn, KA9Q

The executable file "net.exe" provides both client and server Internet
facilities.  It includes code that implements the various ARPA protocols as
both a host and gateway (i.e., it acts as an end-user node as well as an IP
packet switch for transit traffic).  The keyboard and display is used by the
local operator to control both host and gateway level functions, for which a
number of commands are provided.

1. Startup

When net.exe is first executed, it attempts to open the file "autoexec.net"
in the root directory of the current drive. If it exists, it is read and
executed as though its contents were typed on the console as commands.  This
feature is useful for setting the local IP address and host name, initializing
the IP routing table, and starting the various Internet services.

2. Console mode

The console may be in one of two modes: command mode and converse mode.
In command mode, the prompt "net>" is displayed and any of the commands
described in the next section may be entered. In converse mode, keyboard
input is processed according to the "current session", which may be
either a Telnet or FTP connection.  In a telnet session, keyboard input
is sent to the remote system and any output from the remote system is
displayed on the console. In an FTP session, keyboard input is first
examined to see if it is a known local command; if so it is executed locally.
If not, it is "passed through" to the remote FTP server. (See the section
titled "FTP Subcommands").

On the IBM-PC, the user may escape back to command mode by hitting the F10 key.
On other systems, the user must enter the "escape" character, which is by
default control-] (hex 1d, ASCII GS). (Note that this is distinct from the
ASCII character of the same name). The escape character can be changed (see
the "escape" command).

3. Commands

This section describes each of the commands recognized while in command mode.
Note that certain FTP subcommands, e.g., put, get, dir, etc, are recognized
only in converse mode with the appropriate FTP session; they are not
recognized while in command mode.  At present, all hosts and gateways must
be specified as numeric IP addresses in dotted decimal notation (e.g.,
44.0.0.1). When domain server support is added, ARPA-style domain names
(e.g., ka9q.ampr.net) will also be accepted if a domain server is available
on the network to resolve them into IP addresses.

<cr>
Entering a carriage return (empty line) while in command mode puts you in
converse mode with the current session. If there is no current session,
nothing happens.

#
Commands starting with the hash mark (#) are ignored. This is mainly useful
for putting comments into the autoexec.net file.

arp
Displays the Address Resolution Protocol table that maps IP addresses
to their subnet (link) addresses on subnetworks capable of broadcasting.
For each IP address entry the subnet type (e.g., Ethernet, AX.25), subnet
address and time to expiration is shown. If the link address is currently
unknown, the number of IP datagrams awaiting resolution is also shown.

attach <hw type> <I/O address> <vector> <mode> <label> <bufsize> [<speed>]

Configure and attach a hardware interface to the system.

A. <hw type> represents the kind of I/O device that is being attached; at
present this may be "3c500" (a 3Com 3c500 Ethernet interface) or "asy" (a
standard PC asynchronous interface using the 8250 chip). "pc100" is for the
PACCOMM PC-100 interface board, but the driver isn't working yet.

B. <I/O address> is the base address of the control registers for the device.

C. <vector> is the interrupt vector number.  Both the address and the vector
must be in hexadecimal. (You may put "0x" in front of these two values if you
wish, but note that they will be interpreted in hex even if you don't use it).

D. <mode> controls how IP datagrams are to be encapsulated in the device's link
level protocol; i.e., it selects among several link protocols that may be
available. The choices here depend on the interface; at present, the 3c500
interface only supports mode "arpa", which uses standard ARPA-style
encapsulation. (In the future, "802" will mean "use 802.3-style
encapsulation").  Two modes for the "asy" device are currently supported:
"slip", which encapsulates IP datagrams directly in SLIP frames without a link
header (for operation on point-to-point lines, compatible with 4.2BSD UNIX
SLIP) and "ax25", which puts an AX.25 UI frame link header in front of the
datagram before SLIP encoding. (This mode is intended for operation with the
KISS TNC code. The very first byte of each packet is a type field that
distinguishes between control and data packets).  The Address Resolution
Protocol (ARP) maps IP to link level addresses on Ethernet controllers and on
"asy" lines operating in "ax25" mode.

E. <label> gives the name by which the interface will be known in "route"
commands and displays.

F. For asynchronous ports, <bufsize> specifies the size of the ring buffer
in bytes to be statically allocated to the receiver; incoming bursts larger
than this may (but not necessarily) cause data to be lost.  For Ethernet,
<bufsize> specifies how many PACKETS may be queued on the receive queue at one
time; if this limit is exceeded, further received packets will be discarded.
This is useful to prevent the system from running out of memory should another
node suddenly develop a case of diarrhea.

G. <speed> is needed only for an "asy" line; the controller will be initialized
to the given speed.

Examples:

# Attach a 3Com Ethernet controller using the standard 3Com address and
# vector (i.e., as it comes out of the box) to use ARPA-standard encapsulation.
# The receive queue is limited to 5 packets
attach 3c500 0x300 3 arpa ec0 5

# Attach the PC asynch card normally known as "com1" (the first controller)
# to operate in point-to-point slip mode at 9600 baud, calling it "sl0".
# A 1024 byte receiver ring buffer is allocated
attach asy 0x3f8 4 slip sl0 1024 9600

# Attach the secondary PC asynch card ("com2") to operate in AX.25 mode
# at 9600 baud with a KISS TNC, calling it "ax0":
attach asy 0x2f8 3 ax25 ax0 1024 9600

(Note that you cannot use the second asynch controller ("com2") and a 3Com
Ethernet card with standard addressing at the same time because they both
use interrupt vector 3).

close
Send a FIN (i.e., initiate a close) on the the current session's TCP
connection (either FTP or Telnet). This is not normally necessary, since the
usual procedure is to ask the remote server to initiate a close ("QUIT" to FTP,
or the logout command appropriate for the remote system in the case of Telnet).
When either FTP or Telnet sees the incoming half of a TCP connection close,
it automatically responds by closing the outgoing half of the connection.
Close is useful in aborting a pending connection to a system that is not
responding, or in closing an open connection to a server that has gone
catatonic. (This is more graceful than the "reset" command, in that it is less
likely to leave the remote TCP in a "half-open" state).

echo [accept|reject]
Displays or changes the flag controlling client Telnet's response to a
remote WILL ECHO offer.

The Telnet presentation protocol specifies that in the absence of a negotiated
agreement to the contrary, neither end echoes data received from the other.
In this mode, a Telnet client session echoes keyboard input locally and nothing
is actually sent until a carriage return is typed. Local line editing is also
performed: backspace deletes the last character typed, while control-U deletes
the entire line.

When communicating from keyboard to keyboard the standard local echo mode is
used, so the setting of this parameter has no effect. However, many
timesharing systems (e.g., UNIX) prefer to do their own echoing of typed input.
(This makes screen editors work right, among other things). Such systems send
a Telnet WILL ECHO offer immediately apon receiving an incoming Telnet
connection request. If "echo accept" is in effect, a client Telnet session will
automatically return a DO ECHO response. In this mode, local echoing and
editing is turned off and each keystroke is sent immediately (subject to the
Nagle tinygram algorithm in TCP).  While this mode is just fine across an
Ethernet, it is clearly inefficient and painful across slow paths like packet
radio channels. Specifying "echo reject" will cause future incoming WILL ECHO
offers to be answered with DONT ECHOes; the client Telnet sessions will remain
in the local echo mode.  Sessions already in the remote echo mode are
unaffected. (Note: Berkeley Unix has a bug in that it will still echo input
even after the client has refused the WILL ECHO offer. To get around this
problem, enter the "stty -echo" command to the shell once you have logged in.)

escape <char>	
Without arguments, displays the current command-mode escape character in hex.
If given an argument, the first character becomes the new escape character.
(This command is not provided on the IBM-PC; on the PC, the escape char is
always F10.)

etherstat
Display 3-Com Ethernet controller statistics (if configured).

exit
Exit the "net" program and return to MS-DOS (or CP/M).

ftp <host>
Open an FTP control channel to the specified remote host and enter converse
mode on the new session.  Responses from the remote server are displayed
directly on the screen.

help
Display a brief summary of top-level commands.

hostname [<name>]
Displays or sets the local host's name (an ASCII string such as "ka9q-pc",
NOT an IP address).  Currently this is used only in the greeting messages
from the SMTP (mail) and FTP (file transfer) servers.

log [stop | <file>]
Without arguments, indicates whether server sessions are being logged. If
"stop" is given as the argument, logging is terminated (the servers themselves
are unaffected). If a file name is given as an argument, server session log
entries will be appended to it.

icmpstat
Displays statistics about the Internet Control Message Protocol (ICMP),
including the number of ICMP messages of each type sent or received.

ipaddr [<addr>]
Displays or sets the local IP address.

ipstat
Displays Internet Protocol (IP) statistics, such as total packet counts and
error counters of various types.

mail
Send Internet Mail using the Simple Mail Transfer Protocol (SMTP). (This
command	is currently under development by N3EUA).

memstat
Displays the internal free memory list in the storage allocator.

mss [<size>]
Display or set the TCP Maximum Segment Size in bytes that will be sent on all
outgoing TCP connect request (SYN segments).  This tells the remote end the
size of the largest segment (packet) it may send. Changing MSS affects
only future connections; existing connections are unaffected.

mycall [<call>]
Display or set the local AX.25 address.  The standard format is used, e.g.,
KA9Q-0 or WB6RQN-5.

reset [<tcb_addr>]
If an argument is given, force a local reset (deletion) of the TCP Control
Block (TCB) at the specified memory address. The argument is first
checked for validity. If no argument is given, the TCB belonging to the
current session, if any, is reset. This command should be used with caution
since it does not inform the remote TCP that the connection no longer exists
(although a TCP reset (RST) message will be automatically generated should the
remote TCP send anything after a local reset has been done). It is used to get
rid of a lingering half-open connection after a remote system has crashed.

route
route add <dest>|default <interface> [<gateway> [<metric>]]
route drop <dest>
With no arguments, "route" displays the IP routing table. "route add" adds
an entry to the routing table, while "route drop" deletes an existing entry.
"route add" requires at least two more arguments, the IP address of the target
destination and the local name of the interface to which its packets should be
sent.  If the destination is not local, the gateway's IP address should also
be specified. (If the interface is a point-to-point link, then <gateway> may
be omitted even if the target is non-local because this field is only used to
determine the gateway's link level address, if any.  If the destination is
directly reachable, <gateway> is also unnecessary since the destination
address is used to determine the interface link address).

The special destination "default" is used to route datagrams to addresses not
in the routing table. Care must be taken with default entries since two nodes
with default entries pointing at each other will route packets to unknown
addresses back and forth in a loop until their time-to-live (TTL) fields
expire. (Routing loops for specific addresses can also be created, but this
is less likely to occur accidentally).

"route drop" deletes an entry from the table. If a packet arrives for the
deleted address and a default route is in effect, it will be used.

Here are some examples of using the route command:

# Route datagrams to IP address 44.0.0.3 to SLIP line #0.
# No gateway is needed because SLIP is point-to point.
route add 44.0.0.3 sl0 

# Route all default traffic to the gateway on the local Ethernet
# with IP address 44.0.0.1
route add default ec0 44.0.0.1

# Assume all traffic is to sites on the local Ethernet */
route add default ec0

# The station with IP address 44.0.0.10 is on the local AX.25 channel
# (Note: the "ax" interface is not yet implemented)
route add 44.0.0.10 ax0

session <s#>
Without arguments, displays the list of current sessions, including session
number, remote TCP address and the address of the TCP control block (TCB).
An asterisk (*) is shown next to the "current" session; entering <cr> at this
point will put you in converse mode with that session. Entering a session
number as an argument to the session command will put you in converse mode
with that session.  If the telnet server is enabled, the user is notified
of an incoming request and a session number is automatically assigned. The
user may then select the session normally to converse with the remote user
as though the session had been locally initiated.

speed [<line num> [<speed>]]
Without arguments, displays the line number and speed of all asynchronous
devices.  The line number corresponds to the order in which the devices were
attached to the system. With arguments, "speed" changes the speed of a
specific interface. Note that on the IBM PC, any speed is accepted and used
directly to compute the baud rate clock divisor. At high speeds, however, the
divisors are small so large truncation errors may result when nonstandard
speeds are used.

start ftp|smtp|telnet|misc
Starts the specified Internet server, allowing remote connection requests.
"start misc" enables the "echo" and "discard" servers on TCP ports 7 and 9
respectively.

stop ftp|smtp|telnet|misc
Stops the specified Internet server, rejecting any further remote connect
requests. Existing connections are allow to complete normally.

tcpstat <tcb_addr>
Without arguments, displays several TCP-level statistics, plus a summary of
all existing TCP connections, including TCB address, send and receive queue
sizes, local and remote sockets, and connection state. If <tcb_addr> is
specified, a more detailed dump of the specified TCB is generated, including
send and receive sequence numbers and timer information.

telnet <host>
Creates a Telnet session to the specified host and enters converse mode.

trace [<level>]
Controls packet tracing by the interface drivers. At present, all drivers
are enabled and disabled by a common trace variable. The trace variable is
a hexadecimal number with the following interpretation:

   |---- control level of header decoding
00HL
  |------ controls whether a hex dump is generated

A "H" value of 1 causes a hex dump to be generated of all packets sent
or received on the physical interfaces; a zero disables the hex dump.
Independent of the hex dump function, the value of "L" controls how many
levels of protocol headers are decoded:
0 - No headers are decoded
1 - The name and device number of the interface, plus "sent" or "recv"
2 - Link level headers (AX.25, Ethernet)
3 - ARP and IP headers
4 - TCP & UDP headers
(Note that these numbers correspond to the approximate ISO levels of the
various protocols). Each higher setting includes all levels below it, e.g.,
setting H to 4 will print the name and number of the interface, its link
header, the IP header and the UDP or TCP header.  Setting "trace" to 0
disables all tracing.  At present there is no tracing on the "local"
interface; i.e., self connections are not traced.

window [<val>]
Displays or sets the default receive window size in bytes to be used by TCP
when creating new connections. Existing connections are unaffected.

?
Same as the "help" command.

4. FTP Subcommands

When in converse mode with an FTP server, everything typed on the console is
first examined to see if it is a locally-known command. If not, the line is
passed intact to the remote server on the control channel. If it is one of
the following commands, however, it is executed locally. (Note that this
generally involves other commands being sent to the remote server on the
control channel.)  When actively transferring a file, the only acceptable
command is "abort"; all other commands will result in an error message.

abort
Aborts a get, put or dir operation in progress. When receiving a file, abort
simply resets the data connection; the next incoming data packet will generate
a TCP RST (reset) in response which will clear the remote server.  When
sending a file, abort sends a premature end-of-file. Note that in both cases
abort will leave a partial copy of the file on the destination machine, which
must be removed manually if it is unwanted. Abort is valid only when a
transfer is in progress.

dir [<file>|<directory> [<local file>]]
Without arguments, "dir" requests that a full directory listing of the remote
server's current directory be sent to the terminal.  If one argument is
given, this is passed along in the LIST command; this can be a specific
file or subdirectory that is meaningful to the remote filesystem. If two
arguments are given, the second is taken as the local file into which the
directory listing should be put (instead of being sent to the console).
The PORT command is used before the LIST command is sent.

get <remote file> [<local file>]
Asks the remote server to send the file specified in the first argument.
The second argument, if given, will be the name of the file on the local
machine; otherwise it will have the same name as on the remote machine.
The PORT and RETR commands are sent on the control channel.

ls [<file>|<directory> [<local file>]]
ls is identical to the "dir" command except that the "NLST" command is
sent to the server instead of the "LIST" command. This results in an
abbreviated directory listing, i.e., one showing only the file names
themselves without any other information.

put <local file> [<remote file>]
Asks the remote server to accept data, creating the file named in the
first argument. The second argument, if given, will be the name of the file
on the remote machine; otherwise it will have the same name as on the local
machine.  The PORT and STOR commands are sent on the control channel.

type [a|i]
Tells both the local client and remote server the type of file that is to be
transferred. The default is 'a', which means ASCII (i.e., a text file). Type
'i' means "image", i.e., binary.  In ASCII mode, files are sent as varying
length lines of text in ASCII separated by cr/lf sequences; in IMAGE mode,
files are sent exactly as they appear in the filesystem. ASCII mode should be
used whenever transferring text between dissimilar systems (e.g., UNIX and
MS-DOS) because of their different end-of-line and/or end-of-file conventions.
When exchanging text files between machines of the same type, either mode will
work but IMAGE mode may be somewhat faster. Naturally, when exchanging raw
binary files (executables, compressed archives, etc) IMAGE mode must be used.
This command generates the TYPE command on the control channel.

4 Nov 1986
Phil Karn, KA9Q
