uftpproxyd(1)
uftpproxyd(1) ✨ General Commands Manual ✨
okay so bestie, welcome to the manual page for uftpproxyd — the proxy daemon of the UFTP suite. 💅 This is part 1, so buckle up.
🌸 NAME 🌸
uftpproxyd — Encrypted UDP based ftp with multicast — proxy daemon. periodt. 💖
🎀 SYNOPSIS 🎀
Here's how you summon it, no cap:
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 ] [ -o ]
[ -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 💖
okay so uftpproxyd is the proxy daemon of the UFTP suite. It performs multicast tunneling, NAT traversal, and client response aggregation. It's used in one of two scenarios. The first: 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: 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. slay.
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. Messages sent directly from response proxies to clients use multicast (either the primary public address, or the private address, depending on the message). 🌈
✨ EXAMPLES ✨
Okay bestie, this is where it gets visual — we're doing diagrams. ASCII diagrams. They're giving very much "art gallery but make it network topology" and honestly? Iconic. 🎨✨
🫶 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 xxxxxxxxxxxxxxxxxxxxxxxxxxxxSo like, Figure 1 up there? One (1) server, five (5) clients. Let's count the vibes: the server + one client are chilling on Network A, two clients are posted up on Network B, and two more clients are on Network C. There's one client proxy on Network B and one on Network C. And on Network A there are two server proxies — one set up to send to the client proxy on Network B, the other set up to send to the client proxy on Network C. Slay, parallel structure. 💅
🚨 IMPORTANT NOTICE, bestie, listen up: Client proxies normally should NOT run on the same machine as a client. Like, do not do it. Why? Because the server gets all confused when it sees messages coming from a proxy and a client with the same IP — it literally cannot tell the difference between them. It's giving identity theft. 😭 The only way this works is if that machine has multiple IPs, and the client proxy and the client be listening on different IPs. That's the whole deal.
📝 NOTE: When you're using proxies in environments where private IP addresses are in play (10.x.x.x,172.16-31.x.x,192.168.x.x), it is strongly recommended that you assign a unique ID to each client and each client proxy — and that servers call out clients by that unique ID instead of by name/IP. Why bother? Because it prevents IP address collisions at the server between two clients that have the same local IP. Two identical local IPs walking into the server like 👯 "we're the same person" — no ma'am. Not on our watch. 🙅♀️
🌸 Response Proxies
Figure 2
----------
|-->| Server |
| ----------
| |
| | multicast
| |
| |--------------------------------------
| | | | |
| | v | v
| | ------------------ | ------------------
| | | Response Proxy | | | Response Proxy |
| v ------------------ v ------------------
| ---------- ^ | ---------- ^ |
| | Client | | | | Client | | |
| ---------- | | ---------- | |
| | | | | | |
| | | | | | |
| ----------- | ------------ |
| client response | client response |
| | |
| proxy response | |
-----------------------------------------------------Okay so Figure 2 is the simplified setup: one server, two clients, two response proxies, all on the same network segment. Cute and cozy, right? Yeah, except in this environment the multicast messages from each proxy reach both clients — not just the client it actually serves. It's giving "I said that to YOU specifically" but everyone heard it. 🙈
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 xxxxxxxxxxxxxxxxxxxxxxxxxxxxFigure 3 time! Here we've got two response proxies hanging out local to the server, and four clients spread across two remote networks, with each response proxy handling all the clients from one network. Here's the tea though: multicast messages from each proxy would reach all the clients, not just the clients it serves. And even though the proxies are out here offloading work from the server when it comes to handling client responses, the server's network still has to handle responses from all the clients — because the proxies are sitting on the server's network. So basically: this setup has limited scalability. It's trying its best. It's not enough. 💀
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 xxxxxxxxxxxxxxxxxxxxxxxxxxxxAnd FINALLY, Figure 4 — the glow-up. ✨ In this one, each proxy is at least one hop away from the clients it serves, and at least one hop away from the server. The result? Multicast messages from each proxy only go to the clients it actually serves. Boundaries! We love to see it. 🎀
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 at all. No crossover drama. A setup like this is the most scalable, and it's the most flexible too — because another server on a different network can utilize the response proxies in the same way. Sharing is caring, bestie. 👑
✨ OPTIONS ✨
Ok bestie, here's the whole menu of flags you can pass. Every one is iconic in its own way. 💅
-s { dest | fp=fingerprint }— sets this proxy up as a server proxy. If you give it adest, that's the name or IP of the downstream client proxy. If you give it afingerprint, that's the public key signature of the downstream proxy. When this proxy receives a heartbeat message signed with the matching key, it'll use the sourceIP:portof that heartbeat as its downstream address. Exactly one of-s,-c, or-rmust be specified.-c— sets this proxy up as a client proxy. Exactly one of-s,-c, or-rmust be specified.-r— sets this proxy up as a response proxy. Exactly one of-s,-c, or-rmust be specified.-d— enables debug mode. The process runs in the foreground and all output goes tostderr. If you set this, the-Loption is ignored. 🙈-p port— the UDP port number to listen on. Default is1044.-t ttl— sets the time-to-live for multicast packets. Default is1.-N priority— sets the process priority. On Windows systems, valid values are-2to2, with a default of0. These correspond to:-2— High-1— Above Normal0— Normal1— Below Normal2— Low
On all other systems, this is the "nice" value. Valid values are -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 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 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 are0-5, with0being the least verbose and5being the most verbose. Default is2, 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-kis used to sign the message. Ifportis not specified for a given proxy, the default port of1044is assumed.-h hb_interval— the time in seconds between sending heartbeat messages. Ignored if-His 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.1extension and a new log file is opened. For example, if the log file is/tmp/uftpproxyd.log, it will be renamed/tmp/uftpproxyd.log.1and a new/tmp/uftpproxyd.logwill be created. Ignored if-dis specified. Valid values are1-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-gis not specified. Valid values are1-1000. Default is5.-B buf_size— the size in bytes of the UDP send buffer and receive buffer to use. Valid values are65536-104857600(64KB-100MB). Defaults to262144.-L logfile— specifies the log file. Default is/tmp/uftpproxyd.logfor UNIX-like systems systems,C:\uftpproxyd_log.txtfor 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 are0-63and may be specified in either decimal or hexadecimal. Default is0. 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 to0, and reboot:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\DisableUserTOSSettingNot 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-o— when applied to a server proxy or client proxy, use source specific multicast (SSM) to join all multicast groups. Setting this option requires that the public multicast address specified by-Mis a valid SSM address, and requires the-Soption to specify the IP addresses of server in order to join the relevant SSM group. This also requires servers talking to this proxy to use a SSM address for the private multicast address, otherwise the message will be rejected. Valid SSM addresses are in the232.0.0.0/8range for IPv4 and theff30::/96range for IPv6.-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, the list of server IPs is used to join source specific multicast (SSM) groups if the-ooption is specified. Response proxies perform both of the above functions. This option is required if the-ooption is also specified. 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...]— Heads up:-kand-Kare the read/write duo for the proxy's RSA/ECDSA private keys. This option reads RSA or ECDSA private keys from each keyfile.-K "{ rsa:key_len | ec:curve }[,...]"— creates one or more RSA or ECDSA private keys. New keys are specified as eitherrsa:key_length, which creates an RSA private keykey_lengthbits wide, or asec:curve, which creates an EC key using the curve "curve". The supported EC curves aresecp256r1(prime256v1),secp384r1, andsecp521r1. If only-Kis specified, the keys created are not persisted. If only-kis specified, this option reads RSA or ECDSA private keys from each keyfile. If-kand-Kare specified, the keys created by-Kare written to the keyfiles listed by-k. In this case,-kand-Kmust give the same number of items. If neither-knor-Kare specified, an ECDSA private key using curvesecp256r1is generated and not persisted. The definition ofkeyfileis dependent on the crypto library UFTP is compiled to use. On Windows systems, UFTP uses CNG (Cryptography API: Next Generation). Under CNG, all RSA and EC 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_fileis actually the name of the key container. 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_filespecifies a file name where the RSA private key is stored unencrypted in PEM format (the OS is expected to protect this file). When both-kand-Kare 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-kis not specified, the generated key is not persisted. These PEM files may also be manipulated via theopenssl(1)command line tool. Keys can also be generated and viewed via theuftp_keymgt(1)utility.-e ecdh_curve— specifies the EC curve type to use for a response proxy's ECDH private key when operating in version 4 compatibility mode. If unspecified, the default curve issecp256r1. Ignored if-ris 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 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 is230.4.4.1.
✨ EXIT STATUS ✨
okay so here's the vibe check on how the proxy exits — these are the values it hands back 💅
0— slay 💖 the proxy started successfully and it's just... running in the background, living its best life, no notes.1— uh oh 🙈 an invalid command line parameter was specified. like, the args did not eat, bestie.2— an error occurred while attempting to initialize network connections. the networking said "not today" 😭3— an error occurred while reading or generating cryptographic key data. the crypto was giving nothing 🔐💀4— an error occurred while opening or rolling the log file.5— a memory allocation error occurred. rip 🪦6— the proxy was interrupted by the user. that was you, bestie, you pressed Ctrl+C 🫶
🦋 SEE ALSO 🦋
go read those too, iykwyk ✨
🌸 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). 💌
okay that's a wrap on uftpproxyd(1), you're officially soooo good at this 🎀 this page is from UFTP 5.0, dated 22 April 2020 — iconic, timeless, periodt 💅✨🦋
📦 where this page comes from
- nixpkgs unstable: uftp 5.0.3
- ubuntu stonking: uftp 5.0.3-0.1build1 · GPL-3.0-or-later WITH OpenSSL exception
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms