sockets.tex

项目描述: slsnif is a serial port logging utility. It listens to the specified serial port and logs all

As indicated in Table~\ref{portmaster}, the PortMaster handles more events than
just the {\small PM\_SERVER} and {\small PM\_CLIENT} events mentioned earlier.
When~a~client opens to the PortMaster, it identifies the type of service it
wishes by sending that PortMaster~a~``message'':  {\small PM\_SERVER}, {\small
PM\_CLIENT}, {\small PM\_CLOSE}, {\small PM\_TABLE}, or {\small PM\_QUIT}.
These messages are discussed below.  Whenever the PortMaster does not
understand the initial message (due to garbling or whatever), the PortMaster
will immediately issue~a~{\small PM\_RESEND} message and then wait for data.
It will continue doing so for up to {\small PM\_MAXTRY} times (in the
\verb`sockets.h` file as sent, {\small PM\_MAXTRY} is defined as $20$).  If the
limit of re-tries is reached, the PortMaster will peremptorily close down the
connection and go back to its usual quiescent state waiting for~a~new
connection.

The PortMaster will wait no more than {\small TIMEOUT} seconds for data, which
is set to 20 seconds in \verb`Spm.c` as delivered.  If that amount of time
elapses, the PortMaster will summarily close down the temporary client and
continue for more business.

\begin{description}

  \item[{\small PM\_CLIENT}] tells the PortMaster that~a~client is attempting
   to open.  The PortMaster normally responds with~a~{\small PM\_OK} and the
   program attempting to open~a~client responds with~a~null-byte terminated
   string (the requested server name).  If the PortMaster finds the requested
   server in its list, then it responds with~a~{\small PM\_OK} and then the
   port number, otherwise it sends~a~{\small PM\_SORRY}.

   If the PortMaster is using~a~firewall, it may respond immediately with
  ~a~{\small PM\_SORRY} if the client is originating from an unapproved
   machine.

  \item[{\small PM\_CLOSE}] tells the PortMaster that~a~server is closing down.
   The PortMaster will normally respond with~a~{\small PM\_OK}; the program
   closing down the server (via {\em Sclose}) will then send the port number.
   The PortMaster will then remove the associated server from its internal
   list of servers and respond with~a~{\small PM\_OK} if the designated
   server was in its list and~a~{\small PM\_SORRY} otherwise.

  \item[{\small PM\_FWINIT}] tells the PortMaster to re-read its firewall
   datafile.  The PortMaster will then respond with~a~{\small PM\_OK} if
   it worked or {\small PM\_RESEND} if something got garbled.

  \item[{\small PM\_QUIT}] tells the PortMaster that~a~shutdown command is
   to be sent.  The PortMaster responds with~a~{\small PM\_OK}, and the program
   shutting down the PortMaster issues~a~null-byte terminated string,
   ``PortMaster'' (just to guarantee that~a~shutdown is really wanted).  The
   PortMaster will then shutdown.  This operation requires some knowledge of
   the protocol as no \SSL\ function is provided to make shutting down the
   PortMaster easy.  However, the \verb`sktdbg` program does provide an easy
   way to shut down the PortMaster.  Concerned system administrators may wish
   to remove the ``shut'' command from \verb`sktdbg`.  Shutting down the
   PortMaster does not affect currently connected Sockets; however, new
   connections between servers and clients cannot be made.  On the other hand,
   starting up~a~new PortMaster is easy and anyone may do so -- the \verb`Spm`
   program itself will refuse to allow two PortMasters to run concurrently (and
   will say so).

  \item[{\small PM\_SERVER}] tells the PortMaster that~a~server has been
   opened.  The PortMaster will normally respond with~a~{\small PM\_OK}
   and then the program opening~a~server will send~a~string giving the
   new server's name and then will send its port.

   The PortMaster will then respond with~a~{\small PM\_OK} upon success or
  ~a~{\small PM\_SORRY} if~a~server by that name already exists.

   If the PortMaster is using~a~firewall, it may respond immediately with a
   {\small PM\_SORRY} if the server is originating from an unapproved machine.
   When PortMaster sharing is not operating, this event should never occur, as
   servers can then only be legally generated on the same machine that the
   PortMaster resides upon.  The PortMaster enters its own host onto its
   internal firewall table whenever use of~a~firewall is enabled.

  \item[{\small PM\_TABLE}] tells the PortMaster to give out~a~list of the
   servers it currently knows about.  Normally the PortMaster will respond with
  ~a~{\small PM\_OK},~a~count of servers (in network standard 2-byte format,
   see the Berkeley ``ntohs'' function for details), and~a~sequence of strings
   giving the server name and associated port number.  The \verb`spmtable`
   program and \verb`sktdbg`'s ``table'' function use this facility.

\end{description}

\subsubsection{The PortMaster Firewall}

The PortMaster supports~a~{\em firewall} to keep out socket requests from
unapproved machines.  The firewall consists of~a~list of machines' internet
addresses in~a~file.  One specifies the file by one of two methods:

 \begin{enumerate}
  \item Startup with \verb# Spm -f#{\em full-path-to-filename}
  \item Initialization of an environment variable, {\small SPMFIREWALL},
        to the {\em full-path-to-filename}.
 \end{enumerate}

The {\em full-path-to-filename} file contains records of the form:
\begin{verbatim}
  * * number number number number
\end{verbatim}

where the four \verb`number`s are the internet addresses of the machines
permitted to talk to the PortMaster.  The \verb`*` indicates accept any number
in that field.  The firewall function examines incoming internet addresses by
use of the {\em getpeername} function.

The firewall file, often called {\em spmfirewall.dat}, may contain blank
lines.  The \verb`#` is assumed to begin~a~comment and is stripped off.


\newpage
\section{The Utilities}

There are several utilities provided with the \SSL, and they are explained
below.  These are all complete programs in themselves, and can serve as
lessons on how to use the \SSL.

\begin{description}

  \item[sktdbg] \verb`server-name {s|c}` \\
    {\em sktdbg} is the \SSL's testing program.  One may open server Sockets,
    accept Sockets, and client Sockets, test out how other program's Sockets
    are communicating, etc.  See the subsection on {\em sktdbg} below.  The
    ``server-name'' may take two forms: \verb`servername` or
    \verb`servername@machine-name`.  The latter form may be used when
    attempting to open clients to servers residing on machines other than the
    one the user is currently running \verb`sktdbg` on.

  \item[spmchk] \verb`[machine]` \\
    This program tests the current machine by default, the named machine
    otherwise, for the presence of~a~PortMaster.  It will return~a~0 if
    the PortMaster is present, or~a~1 otherwise, and is useful in scripts:

      \begin{center}
       spmchk \verb`||` (nohup Spm \verb`>` /dev/null \&) \\
      \end{center}

    Translated for non-csh/ksh users: if spmchk finds no PortMaster on the
    current machine, start one up in the background in ``no hangup on user
    exit'' mode, with output headed to the bit bucket. {\small (thanks go
    to Marty Olevitch for this program)}.

    For {\small VMS} users:

      \begin{center}
       \begin{minipage}[h]{5in}
        \begin{verbatim}
spmchk:= [fullpath]spmchk.exe
set noon
spmchk
if '$SEVERITY' .ne. 1 then run/detach [fullpath]Spm.exe
set on
        \end{verbatim}
       \end{minipage}
      \end{center}

  \item[spmtable] \verb`[machine [machine [machine ...]]]` \\
    This program lists the servers and port numbers on the requested machines.
    If no machine is listed, then the current machine will be used.

  \item[srmsrvr] \verb`[server-name [server-name [server-name ...]]]` \\
    Sometimes the all-knowledgeable and omnipotent programmer finds~a~need to
    hit the control-c key or otherwise kill~a~running program with~a~server
    Socket.  In such cases, the PortMaster does not get informed that the
    server has gone down.  This utility will tell the PortMaster to forcibly
    remove the named server(s) from its list.

\end{description}

Except when using \verb`sktdbg` to open~a~server with \verb`sktdbg`, the server
names above can also have the form \verb`srvr@machine-name`.  This name
specifies~a~server on~a~specific machine.  Note that the machine-name is its
normal abbreviation (ie.~gryphon) or its full name
(ie.~gryphon.gsfc.nasa.gov).


\subsection{The \protect\verb`sktdbg` Program}

The \verb`sktdbg` program was originally~a~testing facility to debug the \SSL\ 
itself, but has proven exceptionally useful in debugging programs which use the
\SSL.  Consequently, it is provided as part of the package.

To start up \verb`sktdbg`, one must choose between starting up~a~server or
attempting to open~a~client Socket.

\begin{example} Starting up~a~sktdbg Server \\ \label{sktdbg-srvr}
sktdbg servername s
\end{example}

\begin{example} Starting up~a~sktdbg Client \\ \label{sktdbg-client}
sktdbg servername c
\end{example}

One may also ask sktdbg to explain itself.

\begin{example} sktdbg Explanation \\ \label{sktdbg-explain}
sktdbg "?"
\end{example}

When the \verb`sktdbg` program is started, the first thing it does is attempt
to create the requested type of Socket.  Typically, attempts to make~a~server
will succeed; if it doesn't, it will report~a~warning, apply Srmsrvr(), and try
a~second time to open the server again.  If it fails twice, then usually the
PortMaster is not running on your machine.

Attempts to open~a~client to~a~non-existent server also yields an error
message: ``unable to Sopen(srvrname,c)''.  If the server is up and running,
then~a~client Socket will be set up.

The \verb`sktdbg` program then prints out~a~little menu of actions that the
user can take with it.

\begin{table}[thb]
  \begin{center}
  \caption{sktdbg Help Menu}
  \label{sktdbg-help}
  \begin{verbatim}
Socket Test Commands
  accept
  close
  fwinit
  fput
  get
  menu
  peek
  printf
  put
  q
  quit
  read
  rmsrvr
  scanf
  shutdown
  table
  test
  wait
  write
  ?
(   0 bytes) Enter: 
  \end{verbatim}
  \end{center}
\end{table}

The ``Enter'' prompt now also shows the number of bytes waiting on the queue
for reading.  This number is updated only when the prompt is generated; ie. it
is not~a~dynamic value, but is often useful.

In Table~\ref{sktdbg-help}, there are 20 commands available, and are
described below.

\begin{description}

  \item[accept] \ \\
  Used by~a~server Socket to accept clients.  Note that one
  may first do {\em test} to determine if~a~client is waiting.

  \item[close] \ \\
  Used by~a~server Socket to close do