Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
uftp(1)			    General Commands Manual		       uftp(1)

       uftp - Encrypted	UDP based ftp with multicast - server

       uftp [ -R txrate	] [ -L logfile ] [ -B udp_buf_size ]
	   [ -g	max_log_size ] [ -n max_log_count ]
	   [ -Y	keytype	] [ -h hashtype	]
	   [ -k	key_file ] [ -K	key_length | curve ] [ -l ] [ -T ]
	   [ -b	block_size ] [ -t ttl ]	[ -Q dscp ] [ -z | -Z ]
	   [ -I	interface ] [ -p port ]	[ -u source_port ]
	   [ -j	proxylist_file ] [ -q ]	[ -f ] [ -y ] [	-U UID ]
	   [ -a	max_passes ] [ -x log_level ] [	-W txweight ]
	   [ -H	host[,host...] | -H @hostlist_file
	   | -F	restart_file ] [ -X exclude_file ]
	   [ -M	pub_multicast_addr ] [ -P priv_multicast_addr ]
	   [ -N	max_nak_pct ] [	-C cc_type ] [ -o ][ -D	dest_name ]
	   [ -E	base_dir[,base_dir... ]	] [ -S status_file ]
	   [ -r	init_grtt[:min_grtt:max_grtt] ]	[ -s robust ]
	   { -i	list_file | file [ file... ] }

       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.

       The following options are supported:

       -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.  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  environ-
	      ment.   Default  is 1000 Kbps.  Ignored if -C is given any value
	      other than "none".

       -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.

       -g max_log_size
	      Specifies	the maximum log	file size in MB.  Once	the  log  file
	      reaches this size, the file is renamed with a .1 extension and a
	      new log file is  opened.	 For  example,	if  the	 log  file  is
	      /tmp/uftp.log,  it  will	be  renamed  /tmp/uftp.log.1 and a new
	      /tmp/uftp.log will be created.  Ignored if -L is not  specified.
	      Valid values are 1-1024.	Default	is no log rolling.

       -n max_log_count
	      Specifies	 the  maximum number of	archive	log files to keep when
	      log rolling is active.  When the log file	 rolls,	 archive  logs
	      are  renamed  with an incrementing numerical extension until the
	      max is reached.	Archive	 log  files  beyond  the  maximum  are
	      deleted.	 Ignored if -L and -g are not specified.  Valid	values
	      are 1-1000.  Default is 5.

       -Y keytype
	      The symmetric encryption algorithm to  use.   Valid  values  are
	      "aes128-gcm",   "aes256-gcm",   "aes128-ccm",  "aes256-ccm",  or
	      "none"  to  not  set  up	encryption   at	  all.	  Default   is

       -h hashtype
	      The  hashing  algorithm to use for key derivation.  Valid	values
	      are "sha256" for SHA-256,	"sha384" for SHA-384, and "sha512" for
	      SHA-512.	Defaults to "sha256".  Ignored if -Y is	"none".

       -e curve
	      Specifies	 the EC	curve used to generate an ECDH key for key ex-
	      change.  Defaults	to secp256r1 (see -k and -K for	 the  list  of
	      available	EC curves).  Ignored if	-Y is "none".

       -c     If  specified,  forces  clients to authenticate by sending their
	      RSA / ECDSA public key in	a CLIENT_KEY message.  Client key fin-
	      gerprints	 and proxy key fingerprints specified by -H and	-j re-
	      spectively will NOT be checked unless -c is specified.   Ignored
	      if -Y is "none".

       -m max_nak_count
	      Specifies	 the  number of	times a	client reports naks beyond the
	      maximum percentage before	getting	 dropped.   Valid  values  are
	      1-10.  Default is	1.

       -k key_file

       -K {rsa:key_len | ec:curve}
	      These  two  options  are	used to	read and/or write the server's
	      RSA/ECDSA	private	key.  Both are ignored if -Y is	"none".

	      The -K option creates an RSA or ECDSA private key.  New keys are
	      specified	as either rsa:key_length, which	creates	an RSA private
	      key key_length bits wide,	or as ec:curve,	which  creates	an  EC
	      key using	the curve "curve".

	      The  supported  EC curves	are secp256r1 (prime256v1), secp384r1,
	      and secp521r1.

	      If neither -k nor	-K are specified,  an  EC  private  key	 using
	      curve secp256r1 is generated and not persisted.

	      If  -k  is specified but not -K, the RSA or ECDSA	private	key is
	      read from	key_file.

	      If -k is not specified but -K is,	an RSA or ECDSA	private	key is
	      generated	but not	persisted.

	      If  both -k and -K are specified,	an RSA or ECDSA	private	key 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, UFTP uses CNG	(Cryptography API: Next	Gener-
	      ation).  Under CNG, all RSA and EC private keys must  be	stored
	      in a key container (technically only keys	used to	sign data, but
	      for UFTP's purposes this is the case).  Key containers  are  in-
	      ternal  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.

	      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.   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)

       -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.

       -b block_size
	      Specifies	the size of a data block.  This	value should be	around
	      100-200 bytes less that the path MTU to provide ample  room  for
	      all  headers  and	extensions, up to and including	the IP and UDP
	      headers.	Prior to version 4.0, this option  specified  the  MTU
	      and calculated the block size based on that.  Default is 1300.

       -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.

	      Not currently supported on Windows.

       -z     Enables sync mode.  Clients will check if	an incoming  file  ex-
	      ists.   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.

	      As of version 4.1, parsable output that was previously generated
	      by this option is	now enabled separately via the -S option.

       -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

       -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.

       -u source_port
	      The UDP port number to send from.	 Default is 0,	which  uses  a
	      random port number.

       -j proxylist_file
	      A	 file  containing a list of proxies the	server is expecting to
	      hear from.  The file should contain the ID 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 specified  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:

       -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 us-
	      ing the temp directory option (-T) so that clients that success-
	      fully 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_{groupID}_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 CNG, private keys are normally	stored
	      in the key container of the running user.	 Specifying  this  op-
	      tion  stores  keys  in the system	key container.	On non-Windows
	      systems, this option has no effect.

       -U UID The unique ID for	this server, specified as an 8 digit hexadeci-
	      mal  number  (0xnnnnnnnn).  The default value is based on	the IP
	      address of the outgoing multicast	address	as  specified  by  -I.
	      If this address is IPv4, the UID is the address.	If it is IPv6,
	      the UID is the last 4 bytes of the address.

       -a max_passes
	      The maximum number of passes that	are made through the file  for
	      transmission before any clients that have	not yet	fully received
	      the current file are aborted.  Valid values  are	0-65535.   De-
	      fault is 65535.

       -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.

       -W txweight
	      Sets  the	 maximum file transfer time, expressed as a percentage
	      of the optimal time.  Valid values are  110-10000.   Ignored  if
	      congestion control is enabled.  Default is no maximum time.

       -H { host[,host...] | @hostlist_file }
	      Specifies	the clients for	closed group membership.  Can be spec-
	      ified as either a	comma separated	list of	client IDs, 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.

       -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  address  to announce	on.  May be either a multicast
	      address or a unicast address, and	either IPv4  or	 IPv6.	 If  a
	      unicast  address	is specified, the -P option is ignored and all
	      data moves over the specified unicast address.  If  a  multicast
	      IPv6  address  is	specified, -P must also	be specified.  Default

       -P priv_multicast_addr
	      The private multicast address that the data is  transferred  to.
	      One  or  more parts of the IP address (other that	the first) may
	      be replaced with the letter 'x', resulting in  a	random	number
	      being  chosen  for  that part, either 0-255 for IPv4 or 0-0xFFFF
	      for IPv6.	 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 for IPv4  and
	      ff3x::/32	 for IPv6 (here	x specifies the	multicast scope).  The
	      values for -M and	-P must	both be	the same IP version.

       -N max_nak_pct
	      Specifies	the maximum percentage of NAKs that a client  can  re-
	      port  for	 a  particular section.	 This option works with	the -m
	      option, which specifies the number of times a client may	exceed
	      this  limit  before  getting dropped.  This allows the server to
	      keep a very slow client from stalling the	 session  for  others.
	      Valid values are 0-100.  Default is 100.

       -C cc_type
	      Specifies	 the  congestion  control mode to use.	Currently sup-
	      ported values are	"none" and "tfmcc".  Specifying	 "none"	 means
	      data will	be sent	at a fixed rate	as specified by	the -R option.
	      Specifying "tfmcc" will use the TCP Friendly  Multicast  Conges-
	      tion  Control  scheme  as	specified in RFC 4654.	Normally TFMCC
	      will limit the rate based	strictly on loss, however  a  minimum,
	      maximum,	and initial rate in Kbps may each be optionally	speci-
	      fied	     for	   TFMCC	    mode	    as
	      "tfmcc:min=min_rate:init=init_rate:max=max_rate",	and any	or all
	      of these may be applied and in  any  order.   Default  value  is

	      TFMCC  will  make	 use  of  the Explicit Congestion Notification
	      (ECN) bits in the	IP header on systems that support it natively.
	      Known  supported	systems	are Linux, FreeBSD, Windows XP (sender
	      only), Windows Vista and	later  (receiver  only),  and  Solaris
	      (sender only).


       -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 specified 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  specified
	      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.

       -S status_file
	      Prints  easily  parsable status information to a file.  This in-
	      formation	was previously only available in sync  mode  (-z)  and
	      was  mixed  with the normal logging output.  Setting this	option
	      to @LOG results in status	info being mixed with  normal  logging

	      The  following  is printed for each client after all have	regis-


	      Where "status" is	either "success" or "failed", and "target"  is
	      the name of the client.

	      The following is printed after each file:


	      Where "target" is	the name of the	client,	"filename" 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.
	      Only generated in	sync mode.

	      skipped: The file	was declined by	the client because it is older
	      that the existing	file.  Only generated in sync mode.

	      rejected:	The file was rejected, because the file	was sent  with
	      an  absolute  pathname and either	the client is using a temp di-
	      rectory or the filename doesn't match one	of the client's	desti-
	      nation directories.

	      The following is printed at the end of the session:


	      Where "target" is	the name of the	client,	"num_copy" is the num-
	      ber of files sent	with "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:


       -r init_grtt[:min_grtt:max_grtt]
	      Specifies	the initial value, and optionally the min and max val-
	      ues, of the Group	Round Trip Time	(GRTT) used in timing calcula-
	      tions.  The GRTT changes dynamically based on the	network	condi-
	      tions.   This  option is useful if the initial connection	period
	      is too short or long, if receivers are getting bogged  down  and
	      cannot  respond to the server quick enough before	timing out, or
	      if receivers are getting flagged with too	high  of  an  RTT  and
	      take  too	 long  to recover to a reasonable value.  Valid	values
	      are 0.001	to 1000.  Defaults are 0.5  for	 init_grtt,  0.01  for
	      min_grtt,	and 15.0 for max_grtt.

       -s robust
	      Specifies	the robustness factor for message retransmission.  The
	      server will resend particular messages up	to robust times	 while
	      waiting  for client responses.  Valid values are 10-50.  Default
	      is 20.

       -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.

	      There  are also special metafile names that can send commands to
	      the clients.   The  @DELETE:{filename}  metafile	instructs  the
	      client  to delete	the given filename.  nhe usual rules regarding
	      which of the client's destination	directories to	use  also  ap-
	      plies  here.   The  @FREESPACE metafile will cause the client to
	      report back the amount of	free disk space	in the primary	desti-
	      nation directory.

       Starting	with the default options:

	    uftp the_file

       The  server sends the_file with no encryption at	1000 Kbps, sending an-
       nouncements over and later messages over 230.5.5.x (x is ran-
       domly  selected).  Any client that responds to the announcement will be
       accepted.  The payload portion of the packets will be 1300 bytes.

       To send at 50 Mbps:

	    uftp -R 50000 the_file

       Or to allow the transmission rate to be determined dynamically:

	    uftp -C tfmcc the_file

       To send multiple	files:

	    uftp file_1	file_2 file_3


	    uftp dir_1 dir_2 file_3

       To send multiple	files that all land in a certain subdirectory on  each

	    uftp -D dest_dir file_1 file_2

       To  send	 announcements over multicast address	and later mes-
       sages over

	    uftp -M -P file

       Or for IPv6:

	    uftp -M ff02::1:2:3	-P ff02::4:5:6 file

       Or in unicast mode:

	    uftp -M host_or_ip file

       Where host_or_ip	is the hostname	or unicast IP address of the  host  to
       send to.

       To send only to certain hosts:

	    uftp -H client_id_1,client_id_2,client_id_3	file_to_send


	    uftp -H @file_containing_list_of_clients file_to_send

       If  you	want  to  use jumbo ethernet frames of 9000 bytes (leaving 200
       bytes of	space for headers):

	    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-CBC and SHA-1 hashing, using an
       autogenerated 512-bit RSA key to	negotiate the session:

	    uftp -Y aes256-cbc -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-cbc -h sha1 -k key_file_or_container	file_to_send

       The following exit values are returned:

       0      The file transfer	session	finished with at least one client  re-
	      ceiving at least one file.

       1      An invalid command line parameter	was specified.

       2      An error occurred	while attempting to initialize network connec-

       3      An error occurred	while reading or generating cryptographic  key

       4      An error occurred	while opening or rolling the log file.

       5      A	memory allocation error	occurred.

       6      The server was interrupted by the	user.

       7      No client	responded to the ANNOUNCE message.

       8      No client	responded to a FILEINFO	message.

       9      All  client  either dropped out of the session or	aborted.  Also
	      returned if one client drops out or aborts when -q is specified.

       10     The session completed, but none of the specified files were  re-
	      ceived by	any client.

       uftpd(1), uftpproxyd(1),	uftp_keymgt(1).

       The   latest  version  of  UFTP	can  be	 found	at  http://uftp-multi-  UFTP is covered by the GNU  General  Public  Li-
       cense.	Commercial licenses and	support	are available from Dennis Bush

UFTP 5.0			 22 April 2020			       uftp(1)


Want to link to this manual page? Use this URL:

home | help