uftpproxyd(1)							 uftpproxyd(1)



NAME
       uftpproxyd - Encrypted UDP based ftp with multicast - proxy daemon

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

DESCRIPTION
       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, and 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
       inserted	 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 to 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.  Clients in this  environment  are
       configured  to  send  all responses to a specific response proxy.  Mes‐
       sages sent directly from response  proxies  to  clients	use  multicast
       (either	the  primary public address, or the private address, depending
       on the message).


EXAMPLES
   Server / Client Proxies
       Figure 1

       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       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
       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
		|		    |
		|		    ------------
		|			       |
       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 reaches both	 clients,  not
       just the client it serves.

       Figure 3

       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       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
       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
	  |		|	     |	  |
	  |		------------||	  |
       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
       responses, 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

       xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       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
       local  network.	 A  setup  like this is the most scalabile, and is the
       most flexible since another server on a different network  can  utilize
       the response proxies in the same way.


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

       -n     Prevents name lookups of servers, clients, or other proxies when
	      receiving messages.  Useful if name resolution takes a long time
	      and  delays  message  forwarding.	  This option does NOT prevent
	      name lookups for clients, servers, or proxies specified  by  any
	      other command line options.

       -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 19, 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‐
	      ies.

       -U UID The unique ID for this proxy.  May be specified either  as  a  6
	      digit  hexadecimal  number (0xnnnnnn) or as an IP address of the
	      form 0.n.n.n.

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

       -T interval_pct
	      Specifies	 the  percentage  of the announce interval (for REGIS‐
	      TERs) or status interval (for STATUSes  or  COMPLETEs)  to  wait
	      after  receiving	the  first  client  response before sending an
	      aggregate response upstream.  Valid values are 10-99.   Defaults
	      to 50.  Applies only to client proxies.

       -m     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.	Useful
	      when running as a service.  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 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.

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

	      HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Ser‐
	      vices\Tcpip\Parameters\DisableUserTOSSetting

	      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
	      receive 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:
	      192.168.1.101 66:1E:C9:1D:FC:99:DB:60:B0:1A:F0:8F:CA:F4:28:27:A6:BE:94:BC

       -S serverlist_file
	      A	 file  containing  a list of servers.  The file should contain
	      the name/IP of a server optionally followed by the server's pub‐
	      lic key fingerprint, with one 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, ff your system supports source  specific	multi‐
	      cast  (SSM),  the proxy will subscribe to all public and private
	      multicast addresses using SSM for all servers  listed.   See  -C
	      for the syntax of the file.

	      When  this  option  is specified, the public address given by -M
	      must be a valid SSM address.  Any ANNOUNCE that specifies a pri‐
	      vate IP that is not a valid SSM address will be rejected.	 Valid
	      SSM addresses are in the range 232.0.0.0-232.255.255.255.


       -k keyfile[,keyfile...]

       -K new_key_length
	      These two options are used to read and/or write the proxy's  RSA
	      private key.

	      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  keys  are  read
	      from each keyfile.

	      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 the
	      first keyfile, and subsequent key files are ignored.

	      The definition of keyfile 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, keyfile 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, keyfile specifies a file name where the RSA private key is
	      stored unencrypted in PEM format (the OS is expected to  protect
	      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 proxy will
	      exit.  When -k is not specified, the generated key is  not  per‐
	      sisted.	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.

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

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

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