Shareware Grab Bag/Shareware Grab Bag.iso/007/tcp_ip.arc/USEGUIDE.DOC

Text File | 1987-09-10 | 28.0 KB | 579 lines

          User's Guide for Net 870526.4
        Copyright 1987 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.  The notation "<hostid>" denotes a host
or gateway, which may be specified in one of two ways: as a symbolic name
listed in the file "\hosts.net", or as a numeric IP address in dotted decimal
notation enclosed by brackets, 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,
net remains in command mode.

#
Commands starting with the hash mark (#) are ignored. This is mainly useful
for 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> <mtu> [<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 and a KISS TNC
control header in front of the datagram before SLIP encoding. (This mode is
intended for operation with the KISS TNC code. The KISS control header
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. <mtu> is the Maximum Transmission Unit size, in bytes. Datagrams larger
than this value will be fragmented at the IP layer into smaller pieces. Note:
this parameter also sets the limit on the largest allowable incoming SLIP
frame; frames larger than the limit are discarded. At present the limit is
2 * MTU + 40 bytes; this allows for a link level header plus worst-case
bytestuffing in the SLIP protocol.

H. <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, and outgoing packets larger
# than 1500 bytes will be fragmented
attach 3c500 0x300 3 arpa ec0 5 1500

# 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. Outgoing packets larger
# than 256 bytes are fragmented.
attach asy 0x3f8 4 slip sl0 1024 256 9600

# Attach the secondary PC asynch card ("com2") to operate in AX.25 mode
# with an MTU of 576 bytes at 9600 baud with a KISS TNC, calling it "ax0":
attach asy 0x2f8 3 ax25 ax0 1024 576 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 [<session #>]
Send a FIN (i.e., initiate a close) on the the current or specified 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|refuse]
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 refuse" causes an incoming WILL ECHO
offer to be answered with a DONT ECHO; the client Telnet session remains
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.)

eol [unix|standard]
Displays or changes Telnet's end-of-line behavior when in remote echo mode.
In standard mode, each key is sent as-is. In unix mode, carriage returns
are translated to line feeds.  This command is not necessary with all UNIX
systems; use it    only when you find that a particular system responds to
line feeds but not carriage returns.  Only Sun UNIX release 3.2 seems to
exhibit this behavior.

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 <hostid>
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.

gateway [<hostid>]
Displays or sets the host to be used as a "smart" mail relay. Any mail sent
to a hostid not in the host table will instead be sent to the gateway for
forwarding.

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 [<hostid>]
Displays or sets the local IP address.

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


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.

param <interface> [param ...]

Param invokes a device-specific control routine.  On a KISS TNC
interface, this sends control packets to the TNC.  Data bytes are
treated as hexadecimal.  For example, "param ax0 1 255" will set the
keyup timer (type field = 1) on the KISS TNC configured as ax0 to 2.55
seconds (255 x .01 sec).  On a SLIP interface, the param command allows
the baud rate to be read (without arguments) or set.  The implementation
of this command for the various interface drivers is incomplete and
subject to change.

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 hostid>[/bits]|default <interface> [<gateway hostid> [<metric>]]
route drop <dest hostid>
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 host id 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 host id should also
be specified. (If the interface is a point-to-point link, then <gateway hostid>
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 hostid> is also unnecessary since the destination
address is used to determine the interface link address).

The optional "/bits" suffix to the destination host id specifies how
many leading bits in the host id are to be considered significant in the
routing comparisons.  If not specified, 32 bits (i.e., full significance) is
assumed.  With this option, a single routing table entry may refer to
many hosts all sharing a common bit string prefix in their IP addresses.
For example, ARPA Class A, B and C networks would use suffixes of /8,
/16 and /24 respectively; the command

route add [44]/8 sl0 [44.64.0.2]

causes any IP addresses beginning with "44" in the first 8 bits to be
routed to [44.64.0.2]; the remaining 24 bits are "don't-cares".

When an IP address to be routed matches more than one entry in the routing
table, the entry with largest "bits" parameter (i.e., the "best" match)
is used. This allows individual hosts or blocks of hosts to be exceptions
to a more general rule for a larger block of hosts.

The special destination "default" is used to route datagrams to
addresses not in the routing table; it is equivalent to specifying a
/bits suffix of /0 to any destination hostid.  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]

# The local Ethernet has an ARPA Class-C address assignment; route all IP
# addresses beginning with 192.4.8 to it
route add [192.4.8]/24 ec0

# The station with IP address [44.0.0.10] is on the local AX.25 channel
route add [44.0.0.10] ax0

session [<session #>]
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.

smtp
Run through the outgoing mail queue and attempt to deliver any pending mail.
This command is periodically invoked by a timer whenever net is running;
executing "smtp" allows the user to "kick" the mail system manually.

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|discard|echo
Starts the specified Internet server, allowing remote connection requests.

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

tcpkick [<tcb_addr> [<srtt>]]
If there is data on the send queue of the specified tcb, this command forces
an immediate retransmission.  If no tcb_addr is given, the tcb corresponding
to the current session, if any, is used. If an optional srtt value in
milliseconds is given, it replaces the automatically computed round trip time.
This command is useful to speed up recovery from a series of lost packets
since it provides a manual bypass around the normal exponential backoff
retransmission timing mechanisms.

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 <hostid>
Creates a Telnet session to the specified host and enters converse mode.

trace [<level>]
Controls packet tracing by the interface drivers. Specific bits enable
tracing of the various interfaces and the amount of information produced.
The trace variable is a 32 bit hexadecimal number with the following
interpretation ("0" nybbles are reserved for future use):

       |---- control level of header decoding
000MI0HL
   || |----- controls whether a hex dump is generated
   ||------- controls which interfaces are to be traced
   |---------controls SMTP tracing

AX.25 interface tracing is enabled by setting bit 0x8000, Ethernet tracing by
bit 0x4000, PC-100 by 0x2000 and SLIP by 0x1000.

A "H" value of 1 causes a hex dump to be generated of all packets sent or
received on the physical interfaces being traced; 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.

Setting the M control field to 1 traces outgoing SMTP mail sessions.

ttl [<val>]
Displays or sets the default time-to-live value placed in each outgoing IP
datagram. This limits the number of switch hops the datagram will be allowed to
take. The idea is to bound the lifetime of the packet should it become caught
in a routing loop, so make the value somewhat larger than the diameter of
the network.

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.

5. FTP server configuration

Since MS-DOS was designed as a single-user operating system, it provides
no access control; all files can be read, written or deleted by the
local user.  It is usually undesirable to give such open access to a
system to remote network users.  The FTP server therefore provides its own
access control mechanism.

The file "\ftpusers" is used to control remote FTP access.  The default
is NO access; if this file does not exist, the FTP server will be
unusable.  A remote user must first "log in" to the system with the USER
and PASS commands, giving a valid name and password listed in \ftpusers,
before he or she can transfer files.

Each entry in \ftpusers consists of a single line of the form

username password \path permissions

There must be exactly four fields, and there must be exactly one space
between each field.  Comments may be added after the last field.
Comment lines are begun with "#" in column one.

a. "username" is the user's login name.

b.  "password" is the required password.  Note that this is in
plaintext; therefore it is not a good idea to give general read
permission to the root directory.  A password of "*" (a single asterisk)
means that any password is acceptable.

c.  "\path" is the allowable prefix on accessible files.  Before any
file or directory operation, the current directory and the user-
specified file name are joined to form an absolute path name in
"canonical" form (i.e., a full path name starting at the root, with ".\"
and "..\" references, as well as redundant \'s, recognized and removed).
The result MUST begin with the allowable path prefix; if not, the
operation is denied.  NB! Under MS-DOS, this field must use backslashes
("\"), NOT forward slashes ("/").  This field must always begin with a
"\", i.e., at the root directory.

d.  "permissions" is a decimal number granting permission for read,
create and write operations.  If the low order bit (0x1) is set, the
user is allowed to read a file subject to the pathname prefix
restriction.  If the next bit (0x2) is set, the user is allowed to
create a new file if it does not overwrite an existing file.  If the
third bit (0x4) is set, the user is allowed to write a file even if it
overwrites an existing file, and in addition he may delete files.  Again,
all operations are allowed subject to the path name prefix restrictions.
Permissions may be combined by adding bits, for example, 0x3 (= 0x2 + 0x1)
means that the user is given read and create permission, but not
overwrite/delete permission.

For example, suppose \ftpusers on machine "ka9q-pc" contains the line

friendly test \testdir 7

A session using this account would look like this:

net> ftp ka9q-pc
SYN Sent
Established
250 ka9q-pc.nnj.ampr.us (Fri Jun 12 18:15:20 1987) FTP Ready
user friendly
331 Enter password
pass test
230 Logged in

The user now has read, write, overwrite and delete privileges for any file
under \testdir; he may not access any other files.

Here are some more sample entries in \ftpusers:


karn foobar \ 7        # User "karn" with password "foobar" may read, write,
            # overwrite and delete any file on the system.

guest bletch \g\bogus 3    # User "guest" with password "bletch" may read any
            # file under \g\bogus and its subdirectories, and may
            # create a new file as long as it does not overwrite
            # an existing file. He may NOT delete any files.

anonymous * \public 1    # User "anonymous" (any password) may read files under
            # \public and its subdirectories; he may not create,
            # overwrite or delete any files.

I recommend this last entry as a standard convention for keeping a
repository of downloadable files; in particular, the username
"anonymous" is an established ARPA convention.


10 Sept 1987
Phil Karn, KA9Q