Hey Emacs, this is -*- text -*-.


README for Socket-1.5.

For version 1.5, Boris Nikolaus has added three enhancements which
are described in short here:

1. Half-close support:

   Half-close is a term from the TCP protocol which means that only
   one direction of a TCP connection is closed. E. g., one side of the
   communication can send a request and close its "write" side of the
   socket immediately while the other side can still send data on the
   socket until it closes its side, too.

   Example:
   (Output from the socket program is prefixed by ">", ^D means that
   an EOF has been produced, most often by typing CTRL-D).

   Server:                                  Client:
   -------------------------------------------------------------------
   socket -Hsv 12345
   >Listening on port 12345
                                            socket -Hv localhost 12345
   >connection from ...			    >connected to 127.0.0.1...
   Hello
                                            >Hello
   ^D                                       
   >end of input on stdin                   >connection closed by peer
                                            This direction is alive.
   >This direction is alive.
                                            ^D
   >connection closed by peer               >end of input on stdin
   (program terminated)                     (program terminated)

2. Support for connection reset:

   Beside of orderly closing a connection, TCP supports an ungraceful
   abortion of a connection. In this case, TCP does not perform the
   half-close for both directions but sends a "RESET" indication to
   the remote side. The advantage of support for connection reset is
   that the other side can know if the transmission has been aborted.

   Example:
   (Output from the socket program is prefixed by ">", ^C means that
   a SIGINT has been produced, most often be typing CTRL-C).

   Server:                                  Client:
   -------------------------------------------------------------------
   socket -Hsv 12345
   >Listening on port 12345
                                            socket -Hv localhost 12345
   >connection from ...			    >connected to 127.0.0.1...
   Hello
                                            >Hello
   ^C                                       
   >caught signal, resetting connection     >socket: read: Connection
                                            >reset by peer
   (program terminated with                 (program terminated with
   exit code 4)                             exit code 4)

3. Support for IPv6:

   Full support for IPv6 has been integrated into the socket program:
   Connections are now set up either using IPv6 or IPv4, depending on
   the address (or address resolution). If the address resolution
   results in both IPv4 and IPv6 addresses, the protocol version can
   be manually selected by the "-4" or "-6" command line options.

Boris Nikolaus [socket at boris.nikolaus.name 2006-05-08]

======================================================================
README for Socket-1.4.

See BLURB for a short description of the program. A longer
descriptions follows below.

======================================================================
README for Socket-1.3.

Known bugs:
  - putenv() needs strdup() with Solaris.
  - Does not compile with gcc on Solaris.

Version 1.3 features mainly an option to suppress reverse lookups
(-n), an option to bind the socket to a specific local address (-a),
and environment variables to pass the local and remote socket IP
address and port number to the child program. The state of the
program stays as it is: Currently not well tested, but believed to
work (mostly).

Since version 1.2 the Socket program is distributed under a
BSD-style license, but I forgot to mention that earlier.

Juergen Nickelsen [ni@jnickelsen.de 2000-09-27]

======================================================================

Socket 1.2p1 corrects a major bug (the SIGCHLD handler wasn't
correctly initialized, which would result in crashes or hangs in
server mode as soon a a subprocess terminates) and has a few
stylistic fixes. It is no longer tested on Solaris and Linux, but
since the changes are very small, it should still work on these
platforms.

Juergen Nickelsen [ni@jnickelsen.de 1999-09-19]

======================================================================
README for Socket-1.2.

This release Socket-1.2 is an interim release. Some time ago I
actually began working on Socket version 2, but I don't find very
often the time to continue the work. In the meantime, I want to
release a version that runs on Linux, Solaris, and FreeBSD (in
increasing importance :-). The changes to Socket-1.1 are minor and
next to none in terms of features.

This release is also not very well tested. I appreciate any bug
reports you may have.

Juergen Nickelsen [ni@jnickelsen.de 1999-08-06]

======================================================================
This is the README file for Socket-1.1.  

For information on how to build and install Socket, read the file
INSTALL.  Please read the file LICENSE about the terms under which
this program is licensed to you.


What is it?

The program Socket implements access to TCP sockets from shell level.
First written for the need to open a server socket and read and write
to the socket interactively for testing purposes, it quickly evolved
into a generic tool providing the socket interface for shell script
and interactive use.


Client mode

In client mode (which is the default) it connects to a given port at a
given host.  Data read from the socket is written to stdout, data read
from stdin is written to the socket.  When the peer closes the
connection or a signal is received, the program terminates.  An
example for this is the following command:

	% socket coma.cs.tu-berlin.de nntp

This connects to the host coma.cs.tu-berlin.de at the nntp port
(provided these two names can be resolved through gethostbyname(3) and
getservbyname(3)).  The user can now issue commands to the NNTP
server, any output from the server is written to the user's terminal.


Server mode

In server mode (indicated by the "-s" command line switch) it binds a
server socket to the given port on the local host and accepts a
connection.  When a client connects to this socket, all data read from
the socket is written to stdout, data read from stdin is written to
the socket.  For example, the command

	% socket -s 3917

accepts a connection on port 3917.  


Restricting data flow

It is not always desirable to have data flow in both directions, e.g.
when the program is running in the background, it would be stopped if
it tried to read from the terminal.  So the user can advise the program
only to read from the socket ("-r") or only to write to the socket
("-w").  Especially when Socket executes a program (see below), it is
important *not* to write to the program's stdin if the program doesn't
read it.  This is the main reason why I added this option.


Closing connection on EOF

For non-interactive use it is not always clear when to close the
network connection; this is still an unsolved problem.  But often it
will be enough to close the connection when some data has been written
to the socket.  In this case the "quit" switch ("-q") can be used:
when an end-of-file condition on stdin occurs, Socket closes the
connection.


Executing a program

An interesting use of a server socket is to execute a program when a
client connects to it.  This done with the "-p" switch.  Stdin,
stdout, and stderr of the program are read from resp. written to the
socket.  Since the server is usually expected to accept another
connection after a connection has been closed, the "loop" switch
("-l") makes it do exactly that.


CRLF conversion

The Internet protocols specify a CRLF sequence (Carriage Return
Linefeed) to terminate a line, whereas UNIX uses only a single LF.  If
the user specifies the "crlf" switch ("-c"), all CRLF sequences that
are read from the socket are converted to a single LF on output.  All
single LFs on input are converted to a CRLF sequence when written to
the socket.


Background mode

It may be desirable for a server program to run in background. For
that purpose the "background" switch ("-b") is provided.  If it is
set, Socket runs in background, detaches itself from the controlling
tty, closes the file descriptors associated with the tty, and changes
it current directory to the root directory.  It is still possible to
redirect the standard file descriptors to a file.


Forking child to handle connection

Often one wants the server to be able to respond to another client
immediately, even before the connection to the previous client has
been closed.  For this case, Socket can fork a client to handle a
connection while the father process already accepts the next
connection.  To get this behaviour, specify the "-f" option.


With all these options, a typical server call would look like

	% socket -bcfslqp program port

Gee, I know that's a lot of options for the standard case, but I
really want to make all these things *optional*.


Verbose

At last, there is also a "verbose" option ("-v"). If this option is
specified, a message is given for each opening and closing of a
connection.  This is convenient especially in interactive use, but can
also provide some kind of logging.  See fingerd.sh for an example.


WARNING

Nothing prevents you from using Socket like this:

	% socket -slqp sh 5678

THIS IS DANGEROUS! If your machine is connected to the Internet,
*anyone* on the Internet can connect to this server and issue shell
commands to your shell.  These commands are executed with your user
ID.  Some people may think of this program as a BAD THING, because it
allows its user to open his machine for world-wide access to all kinds
of malicious crackers, crashers, etc.  I don't know if I should
consider this as a real security risk or not.  Anyway, it is not my
program which is so dangerous -- anyone with moderate programming
skill can write a something like this.

Another problem is that any server program that uses Socket may not be
secure.  I tried to avoid any holes -- especially that one that made
fingerd vulnerable to the attack of Morris' Internet Worm, but I don't
give any warranty.  Also the program run by Socket may have security
holes.

I would like to hear your opinion about this topic.  Do you consider it
a security risk to have a program like Socket around?


Sample programs

I included two sample programs, which mimic the behavior of finger(1)
and fingerd(8), implemented as shell scripts using Socket.  rfinger.sh
can only finger remote hosts.  fingerd.sh is RFC 1288 compliant and
can be used independently of inetd(8).

[EOB]

