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

FreeBSD Manual Pages


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

       uftpproxyd - Encrypted UDP based	ftp with multicast - proxy daemon

       uftpproxyd { -s { dest |	fp=fingerprint } | -c |	-r }
	   [ -d	] [ -p port ] [	-t ttl ] [ -Q dscp ]
	   [ -N	priority ] [ -O	out_multi_interface ]
	   [ -U	UID ] [	-q dest_port ] [ -m ] [	-x log_level ]
	   [ -H	hb_server[:port][,hb_server[:port]...] ]
	   [ -g	max_log_size ] [ -n max_log_count ]
	   [ -h	hb_interval ] [	-B udp_buf_size	] [ -L logfile ]
	   [ -P	pidfile	] [ -C clientlist_file ] [ -o ]
	   [ -S	serverlist_file	] [ -k keyfile[,keyfile...] ]
	   [ -K	rsa:key_len | ec:curve[,rsa:key_len | ec:curve...]]
	   [ -e	ecdh_curve ] [ -I interface[,interface...] ]
	   [ -M	pub_mcast_addr[,pub_mcast_addr...] ]

       uftpproxyd  is  the proxy daemon	of the UFTP suite.  It performs	multi-
       cast tunneling, NAT traversal, and client response aggregation.	It  is
       used  in	one of two scenarios.  The first is when the server and	one or
       more clients are	on separate networks and cannot	 be  reached  directly
       via  multicast,	and/or	one  or	 both  sides  are behind a firewall or
       NAT'ed.	This allows applications to function when there	is  little  to
       no  access  to  routers.	  The  second  is  when	the server can contact
       clients directly	but there are too many of them to directly handle  the
       responses.  This	allows greater scalability.

       The  proxy  can	run  in	 one  of three modes: a	server proxy, a	client
       proxy, or response proxy.

       A server	proxy is typically local to a server and acts as the  upstream
       end  of a multicast tunnel.  It listens on the public multicast address
       (and private multicast address when specified) and forwards  downstream
       packets	to  a  specific	address	downstream.  Upstream packets are for-
       warded back where the announcement originated from.

       A client	proxy is typically local to one	or more	clients	and forms  the
       downstream  end	of  a multicast	tunnel.	 It receives unicast data from
       one or more server proxies and forwards downstream traffic to the  mul-
       ticast  address	specified in the packet	header.	 Upstream traffic from
       clients is gathered and forwarded back where the	announcement came from
       as an aggregated	response.

       If  a client proxy is behind a firewall,	the proxy can send a heartbeat
       message to the upstream proxy to	make a pinhole in  the	firewall  that
       the  upstream server proxy can connect to.  If the client proxy is also
       NATed, the upstream server proxy	may not	know the IP/port of the	client
       proxy,  so  the	server proxy can be configured to wait for a heartbeat
       message,	and use	the IP/port the	heartbeat came from as its  downstream
       address.	  If the server	proxy is also behind a firewall	or NAT,	a sec-
       ond server proxy	on a machine with a publicly accessible	IP can be  in-
       serted  between	the  first server proxy	and the	client proxy.  In this
       case, the first server proxy is set up to use the second	as  its	 down-
       stream  address,	and the	second server proxy is set up to use the first
       heartbeat it receives from a client proxy as its	downstream address.

       A response proxy	functions as a response	aggregator in situations where
       the server has direct multicast accessibility to	clients	but the	number
       of clients are too high for the server to handle	itself.	 It listens on
       the public multicast address (and private multicast address when	speci-
       fied), but does not forward packets from	the server since those packets
       reach clients directly.	It does	however	send some messages directly to
       clients in the process of establishing encryption keys.	Upstream traf-
       fic  from clients is gathered and forwarded back	where the announcement
       came from as an aggregated response.  Messages sent directly  from  re-
       sponse  proxies to clients use multicast	(either	the primary public ad-
       dress, or the private address, depending	on the message).

   Server / Client Proxies
       Figure 1

       x					      Network A	  x
       x   ----------						  x
       x   | Server |						  x
       x   ----------						  x
       x	|						  x
       x	|  multicast					  x
       x	|						  x
       x	|-----------------------------------------	  x
       x	|		    |			 |	  x
       x	v		    v			 v	  x
       x   ----------------    ----------------	     ----------	  x
       x   | Server Proxy |    | Server	Proxy |	     | Client |	  x
       x   ----------------    ----------------	     ----------	  x
       x	|		    |				  x
       x	|  unicast	    |  unicast			  x
		|		    |
		|		    ------------
		|			       |
       xxxxxxxxxxxxxxxxxxxxxxxxxxxxx   xxxxxxxxxxxxxxxxxxxxxxxxxxxx
       x	|	Network	B  x   x       |       Network C  x
       x	v		   x   x       v		  x
       x  ----------------	   x   x  ----------------	  x
       x  | Client Proxy |	   x   x  | Client Proxy |	  x
       x  ----------------	   x   x  ----------------	  x
       x       |		   x   x       |		  x
       x       |  multicast	   x   x       |  multicast	  x
       x       |		   x   x       |		  x
       x       |-------------	   x   x       |------------	  x
       x       |	    |	   x   x       |	   |	  x
       x       v	    v	   x   x       v	   v	  x
       x  ----------   ----------  x   x  ----------  ----------  x
       x  | Client |   | Client	|  x   x  | Client |  |	Client |  x
       x  ----------   ----------  x   x  ----------  ----------  x
       x			   x   x			  x
       xxxxxxxxxxxxxxxxxxxxxxxxxxxxx   xxxxxxxxxxxxxxxxxxxxxxxxxxxx

       In Figure 1 above there are a server and	five clients.  The server  and
       one  client  are	 on  network  A, two clients are on network B, and two
       clients are on network C.  There	is one client proxy on network	B  and
       one  on network C.  On network A	are two	server proxies,	one configured
       to send to the client proxy on network B	and the	 other	configured  to
       send to the client proxy	on network C.

       Client proxies normally should NOT run on the same machine as a client.
       Doing so	can result in the server getting confused when	it  sees  mes-
       sages  coming  from a proxy and a client	with the same IP and therefore
       cannot tell the difference.  This can only work if the machine has mul-
       tiple IPs and the client	proxy and client listen	on different IPs.

       NOTE: When using	proxies	in environments	where private IP addresses are
       in use (10.x.x.x, 172.16-31.x.x,	192.168.x.x), it  is  strongly	recom-
       mended  to  assign a unique ID to each client and client	proxy, and for
       servers to call out clients by unique ID	instead	of name/IP.  This pre-
       vents  IP address collisions at the server between two clients with the
       same local IP.

   Response Proxies
       Figure 2

	|-->| Server |
	|   ----------
	|      |
	|      |  multicast
	|      |
	|      |--------------------------------------
	|      |	  |		  |	     |
	|      |	  v		  |	     v
	|      |   ------------------	  |   ------------------
	|      |   | Response Proxy |	  |   |	Response Proxy |
	|      v   ------------------	  v   ------------------
	|  ----------	 ^	|     ----------    ^	    |
	|  | Client |	 |	|     |	Client |    |	    |
	|  ----------	 |	|     ----------    |	    |
	|      |	 |	|	  |	    |	    |
	|      |	 |	|	  |	    |	    |
	|      -----------	|	  ------------	    |
	|    client response	|	client response	    |
	|			|			    |
	|     proxy response	|			    |

       Figure 2	shows a	simplified setup involving a server, two clients,  and
       two  response  proxies, all on the same network segment.	 In this envi-
       ronment,	multicast messages from	each proxy  reach  both	 clients,  not
       just the	client it serves.

       Figure 3

       x					       Network A  x
       x   ----------						  x
       x ->| Server |<----------------------------------	  x
       x | ----------				       |	  x
       x |	|				       |	  x
       x |	|  multicast			       |	  x
       x |	|				       |	  x
       x |	|				       |	  x
       x | ------------------------------------------  |	  x
       x | |	    |			  |	    |  |	  x
       x | |	    v			  |	    v  |	  x
       x | |  ------------------	  |   ------------------  x
       x | |  |	Response Proxy |	  |   |	Response Proxy |  x
       x | |  ------------------	  |   ------------------  x
       x | |	|	^		  |	      ^		  x
       x |/|\----	|		  |	      |		  x
       x   |		|	     ----/|\-----------		  x
       x   |		|	     |	  |			  x
       x   |		|	     |	  |			  x
	  |		|	     |	  |
	  |		------------||	  |
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx || xxxxxxxxxxxxxxxxxxxxxxxxxxxx
       x  |	      Network B	  x || x  |	      Network C	  x
       x  |			  x || x  |			  x
       x  |			  x || x  |			  x
       x  ------------------	  x || x  ------------------	  x
       x       |	   |	  x || x       |	   |	  x
       x       v	   v	  x || x       v	   v	  x
       x  ----------  ----------  x || x  ----------  ----------  x
       x  | Client |  |	Client |  x || x  | Client |  |	Client |  x
       x  ----------  ----------  x || x  ----------  ----------  x
       x       |	   |	  x || x       |	   |	  x
       x       -------------------x-||-x--------------------	  x
       x			  x    x			  x
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx    xxxxxxxxxxxxxxxxxxxxxxxxxxxx

       In  Figure  3,  there  are two response proxies local to	the server and
       four clients in two remote networks, with each response proxy  handling
       the clients from	one network.  Multicast	messages from each proxy would
       reach all clients, not just the clients it  serves.   Even  though  the
       proxies	are  offloading	 work  from  the server	in handling client re-
       sponses,	the server's network still has to handle  responses  from  all
       clients	since  the  proxies are	on the server's	network.  As a result,
       this setup has limited scalability.

       Figure 4

       x		Network	A   x
       x   ----------		    x
       x ->| Server |<--------------x----------------
       x | ----------		    x		    |
       x |	|		    x		    |
       x |	|  multicast	    x		    |
       x |	|		    x		    |
       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx		    |
	 |	|				    |
	 |	|--------------------------	    |
	 |	|			  |	    |
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx    xxxxxxxxxxxxxxxxxxxxxxxxxxxx
       x |	|     Network B1  x    x  |	    | Network C1  x
       x | -------		  x    x  |-------  |		  x
       x | |	 |		  x    x  |	 |  |		  x
       x | |	 v		  x    x  |	 v  |		  x
       x | |  ------------------  x    x  |   ------------------  x
       x | |  |	Response Proxy |  x    x  |   |	Response Proxy |  x
       x | |  ------------------  x    x  |   ------------------  x
       x | |	|	^	  x    x  |	      ^		  x
       x |/|\----	|	  x    x  |	      |		  x
       x   |		|	  x  --x-/|\-----------		  x
       x   |		|	  x  | x  |			  x
       x   |		|	  x  | x  |			  x
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx  | xxxxxxxxxxxxxxxxxxxxxxxxxxxx
	  |		|	     |	  |
	  |		------------||	  |
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx || xxxxxxxxxxxxxxxxxxxxxxxxxxxx
       x  |	      Network B2  x || x  |	      Network C2  x
       x  |			  x || x  |			  x
       x  |			  x || x  |			  x
       x  ------------------	  x || x  ------------------	  x
       x       |	   |	  x || x       |	   |	  x
       x       v	   v	  x || x       v	   v	  x
       x  ----------  ----------  x || x  ----------  ----------  x
       x  | Client |  |	Client |  x || x  | Client |  |	Client |  x
       x  ----------  ----------  x || x  ----------  ----------  x
       x       |	   |	  x || x       |	   |	  x
       x       -------------------x-||-x--------------------	  x
       x			  x    x			  x
       xxxxxxxxxxxxxxxxxxxxxxxxxxxx    xxxxxxxxxxxxxxxxxxxxxxxxxxxx

       In Figure 4, each proxy is at least one hop away	from  the  clients  it
       serves,	and at least one hop away from the server.  In this case, mul-
       ticast messages from each proxy only  go	 to  the  clients  it  serves.
       Also, since the proxies are not on the same network as the server, mes-
       sages coming from the client don't have any effect on the server's  lo-
       cal  network.   A setup like this is the	most scalable, and is the most
       flexible	since another server on	a different network  can  utilize  the
       response	proxies	in the same way.

       The following options are supported:

       -s { dest | fp=fingerprint }
	      Sets up the proxy	as a server proxy.  If dest is specified, this
	      is the name/IP of	the downstream client proxy.   If  fingerprint
	      is  specified,  this  designates the public key signature	of the
	      downstream proxy.	 When this  proxy  gets	 a  heartbeat  message
	      signed  with the matching	key, it	will use the source IP:port of
	      the heartbeat for	its downstream address.	 Exactly  one  of  -s,
	      -c, or -r	must be	specified.

       -c     Sets  up the proxy as a client proxy.  Exactly one of -s,	-c, or
	      -r must be specified.

       -r     Sets up the proxy	as a response proxy.  Exactly one of  -s,  -c,
	      or -r must be specified.

       -d     Enable  debug  mode.  The	process	will run in the	foreground and
	      all output will go to stderr.  If	specified, the	-L  option  is

       -p port
	      The UDP port number to listen on.	 Default is 1044.

       -t ttl Specifies	the time-to-live for multicast packets.	 Default is 1.

       -N priority
	      Sets the process priority.  On Windows systems, valid values are
	      from -2 to 2, with a default of 0.  These	correspond to the fol-
	      lowing priorities:

	      -2 High
	      -1 Above Normal
	       0 Normal
	       1 Below Normal
	       2 Low

	      On  all  other  systems, this is the "nice" value.  Valid	values
	      are from -20 to 19p where	-20 is the highest priority and	19  is
	      the lowest priority.  Default is 0.

       -O out_multi_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.  Applies only to client prox-

       -U UID The unique ID for	this proxy, specified as an 8 digit  hexadeci-
	      mal  number  (0xnnnnnnnn).  The default value is based on	the IP
	      address of the first listed multicast capable interface  on  the
	      system.  If this address is IPv4,	the UID	is the address.	 If it
	      is IPv6, the UID is the last 4 bytes of the address.

       -q dest_port
	      The port number of the downstream	proxy (for server proxies)  or
	      clients (for client proxies).

       -m     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.  Useful when run-
	      ning as a	service.  On non-Windows systems, this option  has  no

       -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 hb_server[:port][,hb_server[:port]...]
	      Lists  one  or more proxies to send heartbeat messages to.  When
	      sending a	signed heartbeat message, the first key	 listed	 under
	      -k  is used to sign the message.	If port	is not specified for a
	      given proxy, the default port of 1044 is assumed.

       -h hb_interval
	      The time in seconds between sending heartbeat messages.  Ignored
	      if -H is not specified.

       -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/uftpproxyd.log, it will  be	renamed	 /tmp/uftpproxyd.log.1
	      and a new	/tmp/uftpproxyd.log will be created.  Ignored if -d is
	      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 -g is  not  specified.   Valid  values  are
	      1-1000.  Default is 5.

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

       -L logfile
	      Specifies	 the  log  file.   Default  is /tmp/uftpproxyd.log for
	      UNIX-like	systems	systems, C:\uftpproxyd_log.txt for Windows.

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


	      Not currently supported on Windows Vista or later.

       -P pidfile
	      The pidfile to write the daemon's	pid to on startup.  Default is
	      no pidfile.

       -C clientlist_file
	      A	 file containing a list	of clients the proxy will allow	to re-
	      ceive files from.	 The file should  contain  the	name/IP	 of  a
	      client followed by the client's public key fingerprint, with one
	      on each line.  The key specified by the client  must  match  the
	      fingerprint.  Applies only to client proxies.

	      Example contents:

       -o     When  applied to a server	proxy or client	proxy, use source spe-
	      cific multicast (SSM) to join  all  multicast  groups.   Setting
	      this option requires that	the public multicast address specified
	      by -M is a valid SSM address, and	 requires  the	-S  option  to
	      specify the IP addresses of server in order to join the relevant
	      SSM group.  This also requires servers talking to	this proxy  to
	      use  a  SSM address for the private multicast address, otherwise
	      the message will be rejected.

	      Valid SSM	addresses are in the range	for  IPv4  and
	      the ff30::/96 range for IPv6.

       -S serverlist_file
	      A	 file  containing  a list of servers.  The file	should contain
	      the ID of	the server, the	 IP  address  the  proxy  expects  the
	      server's	request	to come	from, and optionally the server's pub-
	      lic key fingerprint, with	one entry for a	server on  each	 line.
	      For  client  proxies, this is the	list of	servers	the proxy will
	      allow to connect,	and the	key specified by the server must match
	      the  fingerprint.	 For server proxies, the list of server	IPs is
	      used to join source specific multicast (SSM) groups  if  the  -o
	      option is	specified.  Response proxies perform both of the above

	      This option is required if the -o	option is also specified.

	      Example contents:

       -k keyfile[,keyfile...]

       -K "{ rsa:key_len | ec:curve }[,...]"
	      These two	options	are used to  read  and/or  write  the  proxy's
	      RSA/ECDSA	private	keys.

	      The  -K  option  creates	one or more RSA	or ECDSA private keys.
	      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 only -K is specified, the keys	created	are not	persisted.

	      If  only -k is specified,	this option reads RSA or ECDSA private
	      keys from	each keyfile.

	      If -k and	-K are specified, the keys created by -K  are  written
	      to the keyfiles listed by	-k.  In	this case, -k and -K must give
	      the same number of items.

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

	      The  definition  of  keyfile  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)

       -e ecdh_curve
	      Specifies	the EC curve type to use for a response	 proxy's  ECDH
	      private  key when	operating in version 4 compatibility mode.  If
	      unspecified, the default curve is	secp256r1.  Ignored if	-r  is
	      not specified.

       -I interface[,interface...]
	      For  server  proxies,  lists one or more interfaces to listen to
	      multicast	traffic	on.  For client	proxies, the interface it  re-
	      ports itself as to servers and clients.  Interfaces can be spec-
	      ified either by interface	name, by hostname, or by IP.  When re-
	      ceiving a	closed group membership	request, the client proxy will
	      participate if any of these interfaces matches an	IP in the  an-
	      nouncement.  The default is to listen on all active non-loopback
	      interfaces.  NOTE: Since Windows doesn't have  named  interfaces
	      (not  in the sense that UNIX-like	systems	do), only hostnames or
	      IP addresses are accepted	on Windows.

       -M pub_mcast_addr[,pub_mcast_addr...]
	      The list of public multicast addresses to	listen on.  Used  only
	      by server	proxies	and response proxies.  Default is

       The following exit values are returned:

       0      The proxy	started	successfully and is running in the background.

       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 proxy	was interrupted	by the user.

       uftp(1),	uftpd(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			 uftpproxyd(1)


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

home | help