tcptool(1) - Linux man page

Name

tcptool - Data transfer using the TCP protocol

Synopsys

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

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 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 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 n times when using tcptool instead of 1 time when using multicast.

Options

-s port

(sender only, required) indicates sender mode. The port argument specifies the port number to listen for incoming connection requests.
-c 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.
-a IP/mask: (sender only, optional, can occur multiple times) specifies hosts allowed to connect. Both IP and mask must be specified using 4 decimals separated by dots (i.e. 192.168.101.0/255.255.255.0).
-r host:port: (recipient only, required) indicates recipient mode. The host:port argument specifies the host and port to connect to.
-t (recipient only, optional, use on the last client only) indicates ''all clients ready, start data transfer'' to the sender (server).
-d debuglevel: (sender or recipient, optional) specifies the debug level:; n (or none or any string started by ''n'')

sets the program in silent mode.

e (or error or any string started by ''e'')

prints errors only.

w (or warning or any string started by ''w'')

prints errors and warnings.

i (or info or any string started by ''i'')

prints errors, warnings and informational messages.

p (or progress or any string started by ''p'')

prints errors, warnings, informational messages and progress messages.

d (or debug or any string started by ''d'')

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

Return Value

The program returns 0 on success, 1 on error.

Diagnostics

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.
Problem while writing to output file!: The write() operation failed. Check disk space (disk full?) and availability of file servers (i.e. NFS servers).
Failed to send initialization byte to sender!: The sender probably was terminated (killed).
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.
Sender host IP not found!: You should specify the senders IP address in dotted decimal notation if possible, make sure the information is correct.
Failed to create TCP/IP socket!: This typically indicates resource shortage or problems in the TCP/IP subsystem.
Missing host name!: No host name was specified on the recipient!
Failed to create new process for connection!: This indicates a resource shortage on the sender.
Failed to create pipe for communication with sender process!: This indicates a resource shortage on the sender.
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.
Connection attempt from non-authorized client!: A client not listed in the access rules attempted to connect.
Wrong peer name size!: Internal error: the getpeername() function returned an address not recognized as Internet address ( IP address and port number).
Failed to get peer name!: Internal error: the getpeername() function failed to find the address of the client.
Failed to accept client connection!: Typically this indicates a resource shortage or a problem in the TCP/IP subsystem.
Failed to listen for connection attempts!: Typically this indicates a resource shortage or a problem in the TCP/IP subsystem.
Failed to bind to specified port!: Make sure the port is not used by other applications.
Failed to open input file ''...''!: Make sure the file exists and you have read permissions.
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.
Failed tosend data!: Did the peer close the connection unexpectedly?
Illegal port number: ...!: The port number must be an unsigned numeric value.
Missing port number!: The sender needs a port number to listen for incoming connection requests.
Multiple hosts specified!: A recipient can connect to one sender only.
Not enough memory (RAM/swap space)!: An attempt to allocate memory failed.
Illegal host:port combination ''....''!: Host and port must be separated by a colon.
Host:port ''...'' too long!: The host:port combination is too long.
Too many access rules!: The -a 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.
Invalid IP/mask ''...''!: Something is wrong in the IP/mask argument of a -a option.
Missing IP/mask!: The -a option needs an IP/mask argument.
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.
Illegal option ''...''!: The tcptool program does not accept this option.
Too many file names ''...''!: The tcptool program can use only one file name for input or output file.
Old file name: ''...''.: If there are too many file names the program shows the last file name in use.
No sender/recipient mode was choosen!: How should the program know whether to run as sender or recipient?
Transmission succeeded for ''...''.: Data was transferred successfully to that host.
Transmission failed for ''...''!: Transmission to this host failed.

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.

Caveats

As the sender sends each packet n times it needs a fast network connection.

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.

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.

Author

Dirk Krause

Copyright And License

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 .

History

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

Referenced By

blks(1), blksize(1)