Provided by: uftp_4.10.2-1.1build2_amd64 bug

NAME

       uftpproxyd - Encrypted UDP based ftp with multicast - proxy daemon

SYNOPSIS

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

DESCRIPTION

       uftpproxyd  is  the  proxy daemon of the UFTP suite.  It performs multicast 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 forwarded 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  multicast  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 second 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 downstream
       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  specified),  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 traffic 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.  Messages 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 messages 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 multiple 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  recommended 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  prevents 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 environment, 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, multicast messages from each proxy only go to
       the clients it serves.  Also, since the proxies are not on the same network as the server,
       messages 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[:curve]
              Sets up the proxy as a response proxy.  If "curve" is given, specifies the EC curve
              to  use for ECDH key exchange (see -k and -K for details), otherwise no ECDH key is
              generated.  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.

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

       -U UID The  unique  ID  for  this  proxy,  specified  as  an  8  digit  hexadecimal 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 CryptoAPI or CNG, 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.

       -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), formerly 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\Services\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:
              0x00001111|66:1E:C9:1D:FC:99:DB:60:B0:1A:F0:8F:CA:F4:28:27:A6:BE:94:BC
              0x00002222

       -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 public 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, if
              your system supports source specific multicast (SSM), the proxy will  subscribe  to
              all  public  and  private  multicast  addresses  using  SSM for all servers listed.
              Response proxies perform both of the above functions

              When this option is specified, the public and private addresses  specified  by  the
              server  must be valid SSM addresses.  Any ANNOUNCE that specifies a private IP that
              is not a valid SSM address will be rejected.  Valid SSM addresses are in the  232/8
              range for IPv4 and the ff30::/96 range for IPv6.

              Example contents:
              0x11112222|192.168.1.101|66:1E:C9:1D:FC:99:DB:60:B0:1A:F0:8F:CA:F4:28:27:A6:BE:94:BC
              0x11113333|fe80::213:72ff:fed6:69ca

       -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  list  of supported EC curves is as follows (availability may vary depending on
              system settings and crypto library used):

              sect163k1 sect163r1 sect163r2 sect193r1  sect193r2  sect233k1  sect233r1  sect239k1
              sect283k1  sect283r1  sect409k1  sect409r1  sect571k1 sect571r1 secp160k1 secp160r1
              secp160r2 secp192k1 prime192v1 secp224k1 secp224r1 secp256k1  prime256v1  secp384r1
              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 RSA private key 512 bytes in length is
              generated and not persisted.

              If -k is specified but not -K, the RSA or ECDSA private keys  are  read  from  each
              keyfile.

              The  definition  of  keyfile is dependent on the crypto library UFTP is compiled to
              use.

              On Windows systems, UFTP can built  to  use  either  CNG,  which  is  the  new  API
              supported by Windows Vista and Windows 7, or CryptoAPI, which is the legacy API and
              the only one available to Windows XP.

              Under  CryptoAPI,  all  RSA  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 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  not  persisted.
              Elliptic Curve algorithms are not supported under CryptoAPI.

              Under  CNG,  RSA  and ECDSA private keys are also stored in key containers, and RSA
              keys created by CrypoAPI may  be  read  by  CNG.   Like  CryptoAPI,  key_file  also
              specifies  the  key container name, and the generated key is not persisted if -k is
              not specified.  CNG only supports 3 named EC  curves:  prime256v1,  secp384r1,  and
              secp521r1.

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

       -e ecdh_curve
              Specifies the EC curve type to use for a response proxy's ECDH private  key.   This
              option  MUST  be specified for a response proxy to use an ECDH key exchange scheme.
              If unspecified, no ECDH key will be created.  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 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-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 230.4.4.1.

EXIT STATUS

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

       3      An error occurred while reading or generating cryptographic key data.

       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.

SEE ALSO

       uftp(1), uftpd(1), uftp_keymgt(1).

NOTES

       The latest version of UFTP can be found at http://uftp-multicast.sourceforge.net.  UFTP is
       covered  by the GNU General Public License.  Commercial licenses and support are available
       from Dennis Bush (bush@tcnj.edu).