DragonFly On-Line Manual Pages
uftpproxyd(1) DragonFly General Commands Manual uftpproxyd(1)
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 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 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 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, 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_length | ec:curve[,rsa:key_length | 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_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
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).
UFTP 4.8 5 January 2016 uftpproxyd(1)