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 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 to 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 mes- sages 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 pri- vate 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 rec- ommended 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 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, 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 finger- print 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 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 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 proxies. -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 follow- ing 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 public 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 multicast (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 private 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 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 proxy will exit. When -k is not specified, the generated key is not persisted. Unlike CryptoAPI, servers, clients, and proxies will not step on each other in this case. These PEM files may also be manipulated via the openssl(1) command line tool. Keys can also be generated and viewed via the uftp_keymgt(1) utility. -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_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.6 3 December 2011 uftpproxyd(1)