uftp(1) uftp(1) NAME uftp - Encrypted UDP based ftp with multicast - server SYNOPSIS uftp [ -U ] [ -R txrate ] [ -W txweight ] [ -m min_time ] [ -n ] [ -L logfile ] [ -B udp_buf_size ] [ -Y keytype ] [ -h hashtype ] [ -w sigtype ] [ -c ] [ -k key_file ] [ -K new_key_length ] [ -l ] [ -T ] [ -A announce_time ] [ -S status_time ] [ -a announce_interval ] [ -s status_interval ] [ -r register_interval ] [ -d done_interval ] [ -b mtu ] [ -t ttl ] [ -Q dscp ] [ -z | -Z ] [ -I interface ] [ -p port ] [ -j proxylist_file ] [ -q ] [ -f ] [ -y ] [ -x log_level ] [ -H host[,host...] | -H @hostlist_file | -F restart_file ] [ -X exclude_file ] [ -M pub_multicast_addr ] [ -P priv_multicast_addr ] [ -C cc_config_file ] [ -o ] [ -D dest_name ] [ -E base_dir[,base_dir... ] ] { -i list_file | file [ file... ] } DESCRIPTION uftp is the server process of the UFTP suite. It sends one or more files to one or more receivers via multicast with optional encryption. OPTIONS The following options are supported: -U Send in unicast mode to a single host. This requires the -H option with a single host specified. The -t, -M, and -P options are ignored as they are all related to multicast. -R txrate The transmission speed in Kbps. Specifying -1 for this value results in data being sent as fast as the network interface will allow, and is not compatible with -C. Using a value of -1 is recommended only if the network path between the server and all clients is as fast as the server's local interface, and works best in a gigabit environment. Default is 1000 Kbps. -W txweight Sets the maximum file transfer time, expressed as a percentage of the optimal time. If a value of -1 is given for the -R option, a speed of 100Mpbs is used for the purpose of calculat- ing the max time. Valid values are 110%-10000%. Default value is 300%. When a congestion control file is in use, the transmission speed may change. In this situation, the maximum time is cal- culated based on the current transmission speed at the time a given file in a session is started, which may vary from one file to the next. -m min_time Specifies the minimum file transfer time. This value takes precedence over the maximum time, if it is greater. Valid val- ues are 0-3600 seconds. Default value is 10 seconds. -n Prevents name lookups of clients and proxies under open group membership. Useful if name resolution takes a long time and delays receiving of the registration messages. Names are still looked up under closed group membership, as this happens before any data starts moving. -L logfile Specifies the log file. Default is to write to stderr. -B buf_size The size in bytes of the UDP send buffer and receive buffer to use. Valid values are 65536-104857600 (64KB-100MB). Defaults to 262144. -Y keytype The symmetric encryption algorithm to use. All algorithms are used in cipher block chaining (CBC) mode. Valid values are "des" for DES, "3des" for three key Triple DES, "aes128" for AES-128, "aes256" for AES-256, or "none" to not set up encryp- tion at all. Default is "none". Not all installations may support all of these algorithms. -h hashtype The hashing algorithm to use for key derivation and HMAC signa- tures. Valid values are "sha1" for SHA-1, and "sha256" for SHA-256. Defaults to "sha1". Ignored if -Y is "none". Not all installations may support all of these algorithms. -w sigtype Specifies the type of signature to be applied to encrypted mes- sages. Valid values are "hmac" to apply an HMAC to the encrypted message, and "rsa" to apply an RSA signature. HMAC signatures are based off the group master key and ensure the sender of a message is a valid member of the group, but does not guarantee that the message came from a specific group mem- ber. RSA signatures ensure that messages come from a particu- lar member, but is much much slower to calculate than HMAC and creates a larger per-packet overhead. Default is "hmac". Ignored if -Y is "none". -c If specified, forces clients to authenticate by sending their RSA public key in a CLIENT_KEY message. Client key finger- prints and proxy key fingerprints specified by -H and -j respectively will NOT be checked unless -c is specified. Ignored if -Y is "none". -k key_file -K new_key_length These two options are used to read and/or write the server's RSA private key. Both are ignored if -Y is "none". If neither -k nor -K are specified, an RSA private key 512 bytes in length is generated. If -k is specified but not -K, the RSA private key is read from key_file. If -k is not specified but -K is, an RSA private key new_key_length bytes in length is generated. If both -k and -K are specified, an RSA private key new_key_length bytes in length is generated and stored in key_file. The definition of key_file is dependent on the crypto library UFTP is compiled to use. On Windows systems using the native crypto library (CryptoAPI), all RSA private keys must be stored in a key container (technically only keys used to sign data, but for UFTP's pur- poses this is the case). Key containers are internal to Win- dows, and each user (and the system) has its own set of key containers. In this case, key_file is actually the name of the key container. When -k is not specified, the generated key is stored in a default key container. Note that if more than one server, client, and/or proxy use this default key container on the same machine, they will interfere with each other and the results are undefined. All other systems use OpenSSL for the crypto library (although under Windows UFTP can be also be built to use it). In this case, key_file specifies a file name where the RSA private key is stored unencrypted in PEM format (the OS is expected to pro- tect this file). When both -k and -K are specified, the file is only written to if it does not currently exist. If the file does exist, an error message will be returned and the server will exit. When -k is not specified, the generated key is not persisted. Unlike CryptoAPI, servers, clients, and proxies will not step on each other in this case. These PEM files may also be manipulated via the openssl(1) command line tool. Keys can also be generated and viewed via the uftp_keymgt(1) utility. -l Follow symbolic links. By default, if the server encounters a symbolic link, it will send the link itself instead of the file it points to. Specifying this flag causes the server to send the file the link points to. -T Print the timestamp on each line of output. If -L is speci- fied, this option is implied. -A announce_time The maximum time in seconds that the server and client will spend in the Announce/Register phase or the File Info phase for each file. Under open group membership, the server will always wait for this length of time during the Announce/Register phase to allow as many clients as possible to register. Valid values are 1-240. Default is 10 seconds. -S status_time The maximum time in seconds that the server will wait for a client to respond to a DONE message before declaring the client dropped. Also the maximum time a client will wait for the server to send a DONE_CONF in response to a COMPLETE at the end of a session. Valid values are 1-240. Default is 12 seconds. -a announce_interval The time in milliseconds that the server will idle waiting for REGISTER/CLIENT_KEY or INFO_ACK messages before resending an ANNOUNCE, REG_CONF, KEYINFO, or FILEINFO. Valid values are 500-20000. Defaults to 2500 milliseconds. -s status_interval The time in milliseconds that the server will idle waiting for STATUS or COMPLETE messages before resending a DONE or DONE_CONF. Valid values are 500-20000. Defaults to 4000 mil- liseconds. -r register_interval The time in milliseconds that a client will idle waiting for a REG_CONF or KEYINFO before resending a REGISTER. Valid values are 500-60000, and must be greater than announce_interval. Defaults to 4000 milliseconds. The value specified for register_interval compared to announce_interval depends on network conditions and the number of expected clients. Under high latency or with a large number (100s) of clients, it may take longer for a server to respond. If register_interval is too low, clients could end up retrans- mitting more often than necessary and overwhelm the server. -d done_interval The time in milliseconds that a client will idle waiting for a DONE_CONF before resending a COMPLETE. Valid values are 500-60000, and must be greater than status_interval. Defaults to 4000 milliseconds. The value specified for done_interval compared to status_inter- val depends on network conditions and the number of expected clients. Under high latency or with a large number (100s) of clients, it may take longer for a server to respond. If done_interval is too low, clients could end up retransmitting more often than necessary and overwhelm the server. -b mtu Specifies the expected path MTU. The UFTP packet will be packed to fit into this size. Note that this also includes the IP and UDP headers, and assumes that no IP header options are present. If IP options are present, this value should be low- ered slightly to prevent fragmenting IP datagrams. Default is 1500, which is the maximum MTU for 100Mbps Ethernet. -t ttl Specifies the time-to-live for multicast packets. Default is 1. -Q dscp Specifies the Differentiated Services Code Point (DSCP), for- merly Type of Service (TOS), in the IP header for all outgoing packets. Valid values are 0-63 and may be specified in either decimal or hexadecimal. Default is 0. On Windows XP systems, the OS doesn't allow this parameter to be changed by default. To change this, add/modify the follow- ing DWORD registry value, set to 0, and reboot: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Ser- vices\Tcpip\Parameters\DisableUserTOSSetting Not currently supported on Windows Vista or later. -z Enables sync mode. Clients will check if an incoming file exists. If so, the client will decline the incoming file if it either older than the existing file or the same age and the same size as the existing file. The status messages at the end of each file are modified in this mode into a parsable format. The following is printed for each client after all have regis- tered: CONNECT;status;target Where "status" is either "success" or "failed", and "target" is the name of the client. The following is printed after each file: RESULT;target;filename;size;status;speed Where "target" is the name of the client, "file" is the name of the current file, "size" is the size of the file in kilobytes (i.e. 1234KB), "speed" is the transmission speed for that file in KB/s, and status is: copy: The file was sent overwrite: The file was sent, and overwrote an existing file skipped: The file was declined by the client because it is older that the existing file rejected: The file was rejected, because the file was sent with an absolute pathname and either the client is using a temp directory or the filename doesn't match one of the client's destination directories. The following is printed at the end of the session: STATS;target;num_copy;num_over- write;num_skip;total_size;time;speed Where "target" is the name of the client, "num_copy" is the number of files sentwith "copy" status, "num_overwrite" is the number of files sent with "overwrite" status, "num_skip" is the number of files sent with "skipped" status, "total_size" is the total size of all files sent in kilobytes, "time" is the total transmission time for all files, and "speed" is the overall transmission speed for all files. Also, the following line is printed verbatim prior to the STATS lines for ease of reading: HSTATS;target;copy;overwrite;skip;totalKB;time;speedKB/s -Z Sync preview mode. Works like sync mode, except no files are actually transmitted, and the RESULT and STATS lines reflect the status of each file had they actually been sent. The "time" and "speed" datapoints are approximated based on the transmission speed. -I interface The interface to send the data from. Can be specified either by interface name, by hostname, or by IP. If not specified, the default system interface is used. -p port The UDP port number to send to. Default is 1044. -j proxylist_file A file containing a list of proxies the server is expecting to hear from. The file should contain the name/IP of a proxy optionally followed by the proxy's public key fingerprint, with one on each line. If a key fingerprint is given, the key spec- ified by the proxy must match the fingerprint. This option should not be used without -H. If -H is specified, -j must also be specified if proxies are expected to respond, otherwise the server will reject the proxies. Example contents: 192.168.1.101 66:1E:C9:1D:FC:99:DB:60:B0:1A:F0:8F:CA:F4:28:27:A6:BE:94:BC 192.168.1.201 -q Quit-on-error flag. Normally, the server will continue with a session as long as at least one client is still active. With this flag, the server will quit if any client aborts, drops out, or never responds. Most useful in conjunction with clients using the temp directory option (-T) so that clients that successfully receive at least one file before being told to abort don't have files from an aborted session in the desti- nation directory. -f Restartable flag. If specified, and at least one client fails to receive all files, the server will write a restart file named "_group_{group ID}_restart in the current directory to save the current state, which includes the group ID, list of files, and list of failed clients. This file can then be passed to -F to restart the failed transfer. -y For Windows systems using CryptoAPI, private keys are normally stored in the key container of the running user. Specifying this option stores keys in the system key container. On non- Windows systems, this option has no effect. -x log_level Specifies current logging level. Valid values are 0-5, with 0 being the least verbose and 5 being the most verbose. Default is 2, which is consistent with logging prior to version 3.5. -H { host[,host...] | @hostlist_file } Specifies the clients for closed group membership. Can be specified as either a comma separated list of names/addresses, or can be read from hostlist_file. This file is in the same format as proxylist_file. Note that key fingerprints cannot be specified using the comma separated syntax. Clients that are behind a proxy do not need key fingerprints specified, since the proxy's key fingerprint will be checked instead. If unspecified, open group membership is used, and any client may register. Besides name/IP, clients may also be specified by unique ID. This ID may be specified either as a 6 digit hexadecimal number (0xnnnnnn) or as an IP address of the form 0.n.n.n. -F restart_file Specifies the name of a restart file to use to resume a failed transfer. If specified, -H may not be specified and all files listed to send will be ignored, since the restart file contains both of these. All other command line options specified on the first attempt are not automatically applied, so you can alter then for the next attempt if need be. -X exclude_file A file containing the names of files/paths to be excluded from the session, one per line. For example, if you send a direc- tory called d1 containing subdirectories d2, d3, and d4, and you don't want to send the contents of d4, the exclude_file should contain a line reading "d1/d4". -M pub_multicast_addr The public multicast address to announce on. Default is 230.4.4.1. -P priv_multicast_addr The private multicast address that the data is transferred to. Any combination of the second, third, and fourth octets may be replaced with the letter 'x', resulting in a random number being chosen for that octet. Default value is 230.5.5.x. If clients are using source specific multicast (SSM), this and -M must specify valid SSM addresses, which fall in the range 232.0.0.0-232.255.255.255. -C cc_config Specifies a congestion control config file. Normally, the server always transmits at the speed specified by -R. With this option, the speed can be adjusted each time the server makes a request for NAKs from the clients based on the percent- age of NAKs received to data packets sent. The file consists of one or more of the following lines: percentage;scaling_factor Where "percentage" is a whole number from 0-100 specifying a percentage of NAKs, and scaling_factor is a positive decimal number that the current sending rate is multiplied by for the given percentage. Entries must be listed in ascending order by percentage. If there is no entry for "100", the scaling factor for the last entry becomes the scaling factor for "100". When the server collects NAKs from the clients, it calculates the NAK percentage, then searches the congestion control entries in order for a percengage greater than or equal to the current NAK percentage, and adjusts the rate by the correspond- ing scaling factor. There may also be a single line specifying the maximum trans- mission speed: max;speed Where "speed" is the transmission speed in Kbps. If this entry is not specified, the maximum speed is the initial speed speci- fied by -R. The congestion control config file is reread each time just before adjusting the rate. This allows environments which externally monitor the network to adjust the configuration on the fly. In the event of a failure to read the file, the last configuration successfully read is used. Here is a sample cc_config file: max;10000 0;1.3 5;1.1 10;0.9 25;0.7 50;0.5 100;0.4 -o -D dest_name These options specify the name given to the sent file(s) on the client side. If only one file/directory is specified to send and -o is not specified, the name spcified by -D is given to that file/directory, and the effects of -E are ignored. If more than one file/directory is specified to send, or if -o is specified, they are placed in a subdirectory with the name spcified by -D. This option may also specify an absolute path name. If so, clients must be either all Windows or all UNIX-like, since they have differing filesystem structures, otherwise the behavior is undefined. The server, however, need not be the same OS as the clients. When specifying an absolute path name, the path must be contained in one of a client's destination directories, oth- erwise the client will reject the file. When sending to Win- dows clients, an absolute path may be either local (drive:\path\to\file) or remote (\\host\share\path\to\file). -E base_dir[,base_dir...] Specifies one or more "base" directories for files. Normally, for any file/directory specified, any leading path elements are stripped from the name before sending. If the specified file/directory name matches one of the base directories, only the path elements of the base directory are stripped, and the remainder is sent as the file name. Any specified file/direc- tory that does not match a base directory is skipped. For example, without -E, if you pass /path/to/file to send, the transmitted filename is file. If you pass in -E /path, the transmitted file name is to/file. -i list_file Name of a file containing a list of files to send, one per line. Empty lines are ignored. Passing in '-' for list_file reads files from stdin. Other files specified on the command line are ignored if -i is given. file [ file...] The file(s) or directory(ies) to send. Any special files (block/character devices, pipes, sockets, etc.) are skipped. By default, any symbolic links are sent as links (see -l). Any Windows client will silently refuse to create them. If -F or -i is specified, any files listed will be ignored. EXAMPLES Starting with the default options: uftp the_file The server sends the_file with no encryption at 1000 Kbps, sending announcements over 230.4.4.1 and later messages over 230.5.5.x (x is randomly selected). Any client that responds to the announcement will be accepted. The default delays and timeouts should be OK for sending over satellite with a small number of receivers. Packets (including IP and UDP) will be 1500 bytes. If you were sending a file over a local LAN instead of satellite, you might call the server like this: uftp -R 50000 -A 3 -S 3 -a 500 -s 500 -r 1000 -d 1000 the_file This shortens the timeouts for each message type and cuts down the time the server waits during each phase, and sends the file at 50000 Kbps (~50 Mbps). If you have a large number of clients you might need to specify larger values for -A and -S to ensure the server has time to handle them all. As a general rule, if you need to specify any one of -A, -S, -a, -s, -r, or -d, it's probably a good idea to specify them all. To send multiple files: uftp file_1 file_2 file_3 or: uftp dir_1 dir_2 file_3 To send multiple files that all land in a certain subdirectory on each client: uftp -D dest_dir file_1 file_2 To send announcements over multicast address 224.1.2.3 and later mes- sages over 224.4.5.6: uftp -M 224.1.2.3 -P 224.4.5.6 file To send only to certain hosts: uftp -H host_name_1,host_ip_2,host_name_3 file_to_send or: uftp -H @file_containing_list_of_hosts file_to_send If you want to use jumbo ethernet frames of 8800 bytes: uftp -b 8800 file_to_send To send /path/to/file1 and /path/to/file2, and have them appear on clients as /remote/dir/to/file1 and /remote/dir/to/file2: uftp -E /path -D /remote/dir /path/to/file1 /path/to/file2 To send a file encrypted with AES-256 and SHA-1 hashing, using an autogenerated 512-bit RSA key to negotiate the session: uftp -Y AES256 -h SHA1 file_to_send To do the above with a previously generated RSA key stored in key_file_or_container (under Windows, the name of an internal key con- tainer, otherwise the name of a file containing the key in PEM for- mat): uftp -Y AES256 -h SHA1 -k key_file_or_container file_to_send SEE ALSO uftpd(1), uftpproxyd(1), uftp_keymgt(1) NOTES The latest version of UFTP can be found at http://www.tcnj.edu/~bush/uftp.html. UFTP is covered by the GNU Gen- eral Public License. Commercial licenses and support are available from Dennis Bush (bush@tcnj.edu). UFTP 3.6 3 December 2011 uftp(1)