@chapter Operating Procedures
@label[chapter-doc-operating]

This chapter documents the functions and variables
that are part of the networking software operating procedures.
The functions include general system management and user procedures.

@section Summary of Networking Functions and Variables

The following table shows the most significant
symbol names which comprise the networking functions and variables.
These items are discussed in detail in the following sections.

@sp 1
@settabs 4 @columns
@< @i(Name) @\ @\ @i(Type) @\ @i(Usage) @cr
@sp 1
@< arp:addr-stat @\ @\ function @\ diagnostic @cr
@< ethernet:exos-stats @\ @\ function @\ diagnostic @cr
@< ethernet:netspy @\ @\ function @\ diagnostic @cr
@< ftp:ftp @\ @\ function @\ interface @cr
@< global:peek @\ @\ function @\ program @cr
@< icmp:ping @\ @\ function @\ diagnostic @cr
@< ip:list-route-table @\ @\ function @\ diagnostic @cr
@< kermit:telnet-h19 @\ @\ function @\ interface @cr
@< net:configure @\ @\ function @\ configuration @cr
@< net:deconfigure @\ @\ function @\ configuration@cr
@< net:*network-protocols* @\ @\ variable @\ configuration @cr
@< net:print-int-pkt-status @\ @\ function @\diagnostic @cr
@< si:dont-use-3com @\ @\ variable @\ configuration @cr
@< si:dont-use-excelan @\ @\ variable @\ configuration @cr
@< si:set-processor-owning-ethernet @\  @\ function @\ configuration @cr
@< tcp:telnet @\ @\ function @\ interface @cr
@< tcpa:*network-services* @\ @\ variable @\ configuration @cr
@< tcpa:disable-all-network-services @\ @\ function @\ configuration @cr
@< tcpa:disable-one-network-service @\ @\ function @\ configuration @cr
@< tcpa:enable-all-network-services @\ @\ function @\ configuration @cr
@< tcpa:enable-one-network-service @\ @\ function @\ configuration @cr
@< tcpa:ruptime @\ @\ function @\ diagnostic @cr
@< tcpa:rwho @\ @\ function @\ diagnostic @cr
@< tcpa:set-imagen-print-options @\ @\ function @\ configuration @cr
@< telnet:telnet-glass-tty @\ @\ function @\ interface @cr
@cleartabs

The major functions that comprise each particular protocol/interface, such as
@l[Telnet], are documented in subsequent chapters.
This chapter documents the most generally useful functions and programs
related to network configuration, diagnostics, and operation.

@ref[appendix-packages] lists the LISP packages that are created and used
by the networking software.

@section Networking Functions
@label[section-functions]

@subsection Networking Configuration Functions

@defun net:configure
@defunx net:deconfigure

Start up (@l(configure)) or shut down (@l(deconfigure)) 
network processes and protocols.
@csubindex[network][start-up]

@end(defun)

@l[configure] tells the local processor
to use the currently available set of network boards
and site information.
Both reset TCP and UDP connections, but not Chaos connections
(use @l(chaos:reset)).

@defun chaos:reset &optional enable-p
Turn off and reinitialize the Chaosnet software.@*
This may unwedge it if it is not working properly.@*
This will cause all of your currently open connections to lose.@*
You must call CHAOS:ENABLE to turn the chaosnet ncp on again
before you can use the chaosnet; but many user-level functions
that use the net will do that for you.@*
Calling this function with ENABLE-P of T will have the same effect.
@end(defun)

The use of @l(chaos:reset) for resetting the network is obsolete for most purposes,
but still available because it resets Chaos connections.

@defun si:set-processor-owning-ethernet &optional (operation :find) (board :all)

Change the processor controlling the ethernet boards.@*
If there is no ethernet board, make sure this machine knows not to use it.@*
If the argument is :FIND (the default) figure out who owns the board so we can
send packets to him.  If no one currently owns it, we allocate it.@*
If the argument is :TAKE or T, then steal it from the owner.@*
If the argument is :GIVE-UP or NIL, then deallocate it so someone else can have it.

This function should be called after deconfiguring and before reconfiguring, as follows:
@lisp
(net:deconfigure)
(si:set-processor-owning-ethernet ...)
(net:configure)
@end(lisp)

If you reassign boards you must perform a @l[(net:configure)] on @i(all)
the processors in the chassis.
@end(defun)

@defun tcpa:disable-all-network-services
@defunx tcpa:disable-one-network-service service
@defunx tcpa:enable-all-network-services &optional also-do-non-auto-enable?
@defunx tcpa:enable-one-network-service service

Disable all, or one specific, network service.@*
(Re)enable all, or one specific, network service.
@csubindex[network services][enabling/disabling]

The variants that take a @l(service) argument expect one of
the variables corresponding to specific services.
@cindex[network services]
These are listed by the variable @see[tcpa:*network-services*][var].
@end(defun)

@defun si:enable-services &rest services
@defunx si:disable-services &rest services

Allow the machine to provide or revoke services; the @i(services) argument
is currently ignored.
They are provided for future enhancements to these functions.

Each function runs a corresponding initialization list and marks all entries
on the complementary list as having not been run.
@end(defun)

@subsection Networking Diagnostic Functions

@defun hostat &rest hosts

Prints out information on the status of the specified Chaosnet HOSTS.
If no HOSTS are specified, all known hosts are polled.

The information printed includes each host's address, pretty name,
and number of packets input and output from/to that host.

A numeric Chaos address may be specified as a host.

Examples:
@lisp
(hostat)
(hostat 'lama 'lamb)
(hostat #o3430)
@end(lisp)

@end(defun)

@defun tcpa:ruptime
@defunx tcpa:rwho

Report back status of any known Internet host supporting the @l[RUPTIME] or @l[RWHO]
service, respectively.

For each host that answers, @l[RUPTIME] lists how long it has been up (``uptime'').
Some @l[RUPTIME] servers report the current number of logged-in users and average
load statistics (e.g., how many ``jobs'' have been eligible to run).

@l[RWHO] lists information on the logged-in user at the remote host,
including what terminal they are using, the time they logged in, and how
long their terminal has been idle.

@end(defun)

@defun icmp:ping host &optional (operation :echo) (data nil)

Do an ICMP Echo, Timestamp, Information Request, or Address Mask.
@end(defun)

The @l[icmp:ping] function passes the specified Internet host an ICMP request
corresponding to @l(OPERATION), passing @l(DATA) if specified.
@cindex[ping]

Valid @l(OPERATION) arguments are
@l(:ECHO), @l(:INFO), @l(:ADDRESS-MASK), and @l(:TIMESTAMP).
@l(PING) returns two values.
If the first value is NIL, the remote host did not answer;
this could mean 1] that the remote host is not accessible
(e.g. not connected to the network), or
2] that it doesn't respond to ``Ping'' requests.

If an answer was received, an integer value is returned
that represents the response time in clock-ticks (1/60'th second).

The second value (possibly NIL) represents any data received from the remote host.

For example:

@lisp
(icmp:ping 'myvax :echo "are you there")
6
("are you there")
@end(lisp)

@defun net:print-int-pkt-status &optional print-all

Print status of packets to be handled at microcode interrupt level.
@end(defun)

A fixed array of packet buffers is configured by the system.
@cindex[packet buffers]
Each packet buffer is either free for use by some protocol,
waiting to be transmitted, or just received.

With no argument, @l(PRINT-INT-PKT-STATUS) lists the number of
free, transmit, and receive packets;
if @l(PRINT-ALL) is non-NIL,
the function displays, for each packet buffer, its associated protocol and status.

@defun ethernet:exos-stats &key reset-p

Print Exos statistics collected by hardware interface.
@csubindex[network][statistics]
Non-NIL @l(RESET-P) resets the collected statistics.

Unfortunately, only the Excelan board supports Exos statistics.
@end(defun)

@defun ethernet:netspy

Look at all ethernet packets seen by the Excelan board.
For documentation, execute @l[(documentation 'ethernet:netspy)].
@end(defun)

@defun ip:list-route-table
Displays IP routing information, including the gateways and interfaces, for the known networks.
@end(defun)

@defun arp:addr-stat
Displays address translations (from Chaosnet or Internet to Ethernet)
for each host.
@end(defun)
 
@section Networking Control Variables
@label[section-variables]

@defvar net:*network-protocols* '(:CHAOS :INTERNET)

This is the list of keywords that correspond to
available network protocols
in the preferred order of usage.
By default, the system will ``prefer'' Chaosnet access over TCP/IP.

In general this variable should not be manipulated.
Not all networking functions respect this priority order,
but it is provided for future enhancements that could be made.
See Section @ref[section-tcp-chaos-priority], @nameref[section-tcp-chaos-priority], 
for further information.

@end(defvar)

@defvar si:dont-use-3com NIL
When non-NIL, calls to @see[si:set-processor-owning-ethernet][fun]
will ignore (or relinquish) the 3COM board.
@end(defvar)

@defvar si:dont-use-excelan NIL
When non-NIL, calls to @l(si:set-processor-owning-ethernet)
will ignore (or relinquish) the Excelan board.
@end(defvar)

@defvar tcpa:*network-services*
A list of names of generic servers to enable.
@end(defvar)

@csubindex[network services][enabling/disabling]

Each of the symbols in the list @l(tcpa:*network-services*)
corresponds to a variable which defines a specific network service.
These are:

@itemize @bullet
@item tcpa:*tcp-finger-service*
@item tcpa:*udp-time-service*
@item tcpa:*tcp-time-service*
@item tcpa:*tcp-disk-service*
@item tcpa:*tcp-smtp-service*
@item ftp:*tcp-ftp-service*
@item telnet:*tcp-telnet-service*
@item udp:*udp-namespace-service*
@end(itemize)

These variable names are used in calls to 
@see[tcpa:enable-one-network-service][fun]
and
@see[tcpa:disable-one-network-service][fun].

@defvar si:enable-services-initialization-list
@defvarx si:disable-services-initialization-list

The associated initialization list is run when Chaosnet services are enabled or disabled.
The function @l(add-initialization) can be used to add other LISP commands to each list.
@end(defvar)

@section Peek Display
@label[section-peek]

Several command modes within the @l(Peek) program pertain to networking status information.

@defun peek &optional initial-mode
@end(defun)

You can invoke @l(Peek) by running the function from LISP, and optionally
include a command mode:
@lisp
(peek :network)
@end(lisp)

Alternatively, invoke @l(Peek) by typing ``@system P'',
then press a key or select the desired option from the Peek command menu.

@subsection Network Display
@csubindex[network][statistics]
@csubindex[Peek][network] 

The @l(Network) command displays status and statistical information
on each network protocol and interface.

The protocols, interfaces, and connections are mouse-selectable.
Options include closing, resetting, inspecting, and describing
the selected item;
this is useful for debugging and/or resetting wedged connections.
Levels of information detail may be set for the statistics displays;
options are @i(Normal), @i(Verbose), and @i(Brief).

There is usually more than one full screen to the display;
position the mouse cursor to the far left of the display and use the scrolling bar
to move up or down within the display.

@sp 1
@textbox
@b(Warning:) do not close the network interfaces, drivers, or transport protocols
through the Peek Network option.
This capability is available for debugging or extreme situations only, and will prevent
remote and external access.
You must use @l(net:configure) to restart the protocols
@csubindex[network][restart]
after closing down through @l(Peek).

The preferred method for disabling specific TCP network services is
@see[tcpa:disable-one-network-service][fun].

@end(textbox)

@subsection Hostat Display
@csubindex[network][Chaosnet host status]
@csubindex[Peek][hostat] 

The @l(Hostat) command displays status and statistical information
on each Chaosnet host that responds when polled.
This is the same information provided by @see[hostat][fun].

@subsection Chaosnet Display
@csubindex[Peek][Chaosnet]

The @l(Chaosnet) command displays the status of opened Chaosnet connections,
plus Chaosnet ``meters'', or statistics, that are not included on the @l(Network) display.

The connections are mouse-sensitive; a particular connection can be described, inspected,
or (most useful) closed.

@section Messages and Errors
@label[section-messages]

The following run-states may be seen on the Who-Line (or reported by Peek):

@description
@item TCP Socket I/O
This run-state appears during socket-level TCP/IP connections.
It will appear during both input (listen, reply) and output.

@item TCP Service Lock
This run-state may appear when a network function enters
a process wait state.
If the function does not return, it means that a lock
has been usurped, and the process locking the service
may be hung.
This may occur if protocols or drivers are closed abnormally. 

@item TCP Server Lock
Similar to ``TCP Service Lock'', this run-state may appear
while running a function that communicates directly
with a network server process.
If such a function does not return, it means that a lock
has been usurped, and the process locking the server
may be hung, or the server itself may be hung.

@item Net Connect
This run-state appears when a Chaosnet function is attempting
to make an initial connection to a particular contact (server)
on a particular host.
Hanging here generally indicates that the physical connection
cannot be established;
e.g., one of the two hosts is not connected to the physical Ethernet.

@item Chaosnet Finish
This run-state appears when a function is waiting for
all terminating packets on a Chaos connection to be transmitted and acknowledged.
Hanging here may indicate that the remote host has dropped
the connection,
or that the local connection was aborted at a delicate time.
Press @ctrl[@abort] to force the connection to terminate.
If no other connections are outstanding, you can use @l(fs:close-all-files)
to force any open streams to this connection to be closed;
alternatively, the specific connection can be closed in @l(Peek).

@item Chaosnet Input, BRD In
Indicates the caller is waiting for an input Chaosnet packet.

@item Chaosnet Wait
Waiting for a Chaos connection to change state; should time out, normally.

@item Poll Hosts, Hostat Reply, Host time, Uptime reply
Waiting for any of a number of hosts to respond to a status poll.

@item Network Buffer
Indicates that the ``int packet'' buffers are all in use.
@cindex[packet buffers]
If functions hang here, it is probably necessary to execute @l(net:configure).
Report persistent problems to Customer Service.

@item Network or Terminal
Displayed during initial connection to remote TCP Telnet.

@end(description)



















@c end oper2