=head1	NAME

tcptool - Data transfer using the TCP protocol

=head1	SYNOPSYS

  tcptool <options> -s <port> [-c <maxclients>] [<inputfile>]
  tcptool <options> -r <host:port> [-t] [<outputfile>]

=head1	DESCRIPTION

The tcptool program transfers data from one sender to one or multiple
recipients using the TCP protocol.

If the program is started in sender mode it listens for incoming connection
requests from recipients. After checking the IP address against a set of
allowed IP address / net mask pairs (see the -a option) tcptool reads
one byte from the connection. This byte contains a flag indicating
``I am the last client, start transmission now'' in the least significant
bit. If this flag is set or the number of clients has reached
I<maxclients> data transfer starts.
The sender transfer the contents of the specified
input file to the receiver(s). If no input file is specified, data from
standard input is transferred.

If the program is started in recipient mode (option -r) the program establishes
a connection to the specified I<host:port>. The byte containing the
``I am the last client, start transmission now'' is sent, the flag value
depends on whether or not the -t option (transfer start) was used.
The program now reads data from the network connection and saves the data
to the specified output file or writes it to standard output if no file name
was specified.

The purpose of the program is to transfer data from one sender to multiple
recipients using the reliability of TCP connections.

On some sites routers are misconfigured, multicast session contents is
transferred using broadcast mechanisms disturbing computers which did not
join the multicast group. If the computers not interested in the multicast
contents are older and have slow network cards only the computers may
become unsable when flooded with the packets from the multicast session.
As a first aid sites can use tcptool instead of multicast mechanisms.
The better solution -- of course -- is to configure the routers correctly
to send multicast packets only to hosts in the multicast group.

If routers are configured correctly you should prefer multicast transfer
mechanisms over tcptool because the tcptool sender sends each packet
I<n> times when using tcptool instead of 1 time when using multicast.

=head1	OPTIONS

=over 6

=item	-s I<port>

(sender only, required) indicates sender mode. The I<port> argument specifies
the port number to listen for incoming connection requests.

=item	-c I<maxclients>

(sender only, optional) specifies the maximum number of clients. The default
1 accepts just one client connection. The special values 0 or unlimited
allow an unspecified number of clients to connect, the last client must
use the -t option to indicate ``all clients ready for start of transfer''.

Practically the number of clients is limited by the value of the
TCPTOOL_MAX_CLIENTS preprocessor definition in tcptool.h. The default
value is 256, this value can be increased at compile time.

=item	-a I<IP/mask>

(sender only, optional, can occur multiple times) specifies hosts allowed
to connect. Both I<IP> and I<mask> must be specified using 4 decimals
separated by dots (i.e. 192.168.101.0/255.255.255.0).

=item	-r I<host:port>

(recipient only, required) indicates recipient mode. The I<host:port> argument
specifies the host and port to connect to.

=item	-t

(recipient only, optional, use on the last client only) indicates
``all clients ready, start data transfer'' to the sender (server).

=item	-d I<debuglevel>

(sender or recipient, optional) specifies the debug level:

=over 12

=item	n (or none or any string started by ``n'')

sets the program in silent mode.

=item	e (or error or any string started by ``e'')

prints errors only.

=item	w (or warning or any string started by ``w'')

prints errors and warnings.

=item	i (or info or any string started by ``i'')

prints errors, warnings and informational messages.

=item	p (or progress or any string started by ``p'')

prints errors, warnings, informational messages and progress messages.

=item	d (or debug or any string started by ``d'')

prints errors, warnings, informational, progress and debug messages.

=back

=back

=head1	RETURN VALUE

The program returns 0 on success, 1 on error.

=head1	DIAGNOSTICS

=over 6

=item	Failed to open output file ``...''!

The recipient failed to open the specified output file for writing.

Check access permissions to the file and make sure all parent directories
exist.

=item	Problem while writing to output file!

The write() operation failed. Check disk space (disk full?) and availability
of file servers (i.e. NFS servers).

=item	Failed to send initialization byte to sender!

The sender probably was terminated (killed).

=item	Failed to connect to sender!

The sender did not accept the connection request. Make sure tcptool is running
on the sender, listens on the port and make sure access permissions to tcptool
on the sender are set properly.

=item	Sender host IP not found!

You should specify the senders IP address in dotted decimal notation if
possible, make sure the information is correct.

=item	Failed to create TCP/IP socket!

This typically indicates resource shortage or problems in the TCP/IP
subsystem.

=item	Missing host name!

No host name was specified on the recipient!

=item	Failed to create new process for connection!

This indicates a resource shortage on the sender.

=item	Failed to create pipe for communication with sender process!

This indicates a resource shortage on the sender.

=item	Failed to obtain initialization byte from recipient!

The recipient did not send an initialization byte. May be a wrong program
has connected to the sender or the recipient tcptool program was terminated.

=item	Connection attempt from non-authorized client!

A client not listed in the access rules attempted to connect.

=item	Wrong peer name size!

Internal error: the getpeername() function returned an address not recognized
as Internet address (IP address and port number).

=item	Failed to get peer name!

Internal error: the getpeername() function failed to find the address
of the client.

=item	Failed to accept client connection!

Typically this indicates a resource shortage or a problem in the TCP/IP
subsystem.

=item	Failed to listen for connection attempts!

Typically this indicates a resource shortage or a problem in the TCP/IP
subsystem.

=item	Failed to bind to specified port!

Make sure the port is not used by other applications.

=item	Failed to open input file ``...''!

Make sure the file exists and you have read permissions.

=item	Failed to transfer data to sender process!

On the sender the master process failed to transfer data to the sender
subprocess. Maybe the subprocess died of resource shortage or gave up as
the peer closed the connection.

=item	Failed tosend data!

Did the peer close the connection unexpectedly?

=item	Illegal port number: ...!

The port number must be an unsigned numeric value.

=item	Missing port number!

The sender needs a port number to listen for incoming connection requests.

=item	Multiple hosts specified!

A recipient can connect to one sender only.

=item	Not enough memory (RAM/swap space)!

An attempt to allocate memory failed.

=item	Illegal host:port combination ``....''!

Host and port must be separated by a colon.

=item	Host:port ``...'' too long!

The I<host:port> combination is too long.

=item	Too many access rules!

The -a I<IP/mask> option can be used only 256 times. The
TCPTOOL_MAX_CLIENTS preprocessor definition can be used to change this
value at compile time.

=item	Invalid IP/mask ``...''!

Something is wrong in the I<IP/mask> argument of a -a option.

=item	Missing IP/mask!

The -a option needs an I<IP/mask> argument.

=item	Number of clients reduced to ``...''!

The number of recipients (network clients) is restricted to
TCPTOOL_MAX_CLIENTS (256 by default). The value specified as argument
to the -c option exceeds the range.

=item	Illegal option ``...''!

The tcptool program does not accept this option.

=item	Too many file names ``...''!

The tcptool program can use only one file name for input or output file.

=item	Old file name: ``...''.

If there are too many file names the program shows the last file name in use.

=item	No sender/recipient mode was choosen!

How should the program know whether to run as sender or recipient?

=item	Transmission succeeded for ``...''.

Data was transferred successfully to that host.

=item	Transmission failed for ``...''!

Transmission to this host failed.

=back

=head1	EXAMPLES

To clone a file system /dev/hda1 between a number of equal computers
(i.e. in a PC lab in a school or university) run

  dd if=/dev/hda1 | tcptool -s 9876 -c unlimited -a 192.168.101.0/255.255.255.0

on the computer containing the file system in the state you want to distribute
(192.168.101.13 in the example).

On all recipients -- except the last -- run

  tcptool -r 192.168.101.13:9876 | blks | dd if=/dev/hda

On the last recipient run

  tcptool -r 192.168.101.13:9876 -t | blks | dd if=/dev/hda

Note 1: You need the blks program, see http://dktools.sourceforge.net for
details.

Note 2: All contents is transferred as clear text. This means everyone can
read the /etc/shadow file in such a file system and run crack on it.
Solution: For image distribution use a different root password, change
the password on the sender and on all recipients immediately after
transferring the file system.

=head1	CAVEATS

=over 6

=item	As the sender sends each packet I<n> times it needs a fast network
connection.

=item	On Linux (and other systems...?) the TCP/IP subsystem seems to buffer
data provided by send() for TCP connections. If the peer has disconnected
sometimes the send() operations return value indicates success even if the
peer closed the connection.

=back


=head1	NOTES

All contents is transferred as clear text. This means everyone can
read the /etc/shadow file and run crack on it if you transfer a file system.
Solution: For image distribution use a different root password, change
the password on the sender and on all recipients immediately after
transferring the file system.

=head1	SEE ALSO

http://dktools.sourceforge.net/tcptool.html

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (C) - 2008, Dirk Krause
All rights resrved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1	HISTORY

2008-07-31: First version finished, tested on Solaris and Linux.

