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  calculated
	      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 sup‐
	      port 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  member.
	      RSA  signatures ensure that messages come from a particular mem‐
	      ber, 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 fingerprints
	      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  (techni‐
	      cally  only keys used to sign data, but for UFTP's purposes this
	      is the case).  Key containers are internal to Windows, 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 specified,
	      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 lowered 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  following
	      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 des‐
	      tination 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 num‐
	      ber of files sentwith "copy" status, "num_overwrite" is the num‐
	      ber 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 speci‐
	      fied  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  suc‐
	      cessfully	 receive  at least one file before being told to abort
	      don't have files from an	aborted	 session  in  the  destination
	      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 spec‐
	      ified 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	speci‐
	      fied  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 unspeci‐
	      fied, open group membership is used, and any client  may	regis‐
	      ter.

	      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 directory
	      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	percentage  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 corresponding	 scal‐
	      ing factor.

	      There may also be a single line specifying the maximum transmis‐
	      sion 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 speci‐
	      fied,  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 Windows
	      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 9000 bytes:

	    uftp -b 9000 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 auto‐
       generated 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 format):

	    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.7			 28 June 2012			       uftp(1)
