Provided by: uftp_4.10.2-1.1build2_amd64 
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).