uftpd(1)

📦
version 5.0.3 · 2 versions
, in nixpkgs unstable, ubuntu stonking

uftpd 💖 — the client daemon of the UFTP suite

okay bestie, sit down, hydrate, because this is the manual page for uftpd from General Commands Manual, section 1. it's giving "encrypted UDP based ftp with multicast" and it is long, so buckle up. 🌸

✨ NAME ✨

uftpd — Encrypted UDP based ftp with multicast - client daemon 🦋

✨ SYNOPSIS ✨

uftpd [ -d ] [ -p port ] [ -B buf_size ]
    [ -E ] [ -Q dscp ] [ -U UID ] [ -x log_level ] [ -t ]
    [ -T temp_dir ] [ -D dest_dir[,dest_dir... ]]
    [ -A backup_dir[,backup_dir... ]] [ -L logfile ]
    [ -F status_file ] [ -q ] [ -P pidfile ] [ -o ]
    [ -S serverlist_file ] [ -R proxylist_file ]
    [ -r v4proxy[/fp] ] [ -c cache_size ]
    [ -k keyfile ] [ -K rsa:key_len | ec:curve ]
    [ -m ] [ -N priority ] [ -i ] [ -s postreceive_script ]
    [ -g max_log_size ] [ -n max_log_count ]
    [ -H hb_server[:port][,hb_server[:port]...] ]
    [ -h hb_interval ] [ -I interface[,interface...] ]
    [ -M pub_mcast_addr[,pub_mcast_addr...] ]

like, look at all those brackets. that's not a synopsis, that's a fit check. 💅

✨ DESCRIPTION ✨

so uftpd is the client daemon of the UFTP suite. she listens on one or more multicast addresses to receive files from servers. that's her whole job and she does it flawlessly. 👑

this version of the client supports servers and proxies running UFTP 4.x and 5.x. periodt.

✨ OPTIONS ✨

the following options are supported, and yes we are going through all of them, no skipping, i don't make the rules (i do, actually, and the rule is: every flag gets love). 💖

  • -d — turns on debug mode. the process runs in the foreground and all output goes to stderr. and bestie, listen — if you specify this one, the -L option is ignored. bye bye logfile. 🙈
  • -p port — the UDP port number to listen on. default is 1044. classic.
  • -U UID — the unique ID for this client, 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's IPv6, the UID is the last 4 bytes of the address. slay, math.
  • -B buf_size — the size in bytes of the UDP receive buffer to use. valid values are 65536-104857600 (that's 64KB-100MB for the rest of us). defaults to 262144. 💾
  • -E — only allow incoming sessions if encryption is enabled. the default is to allow both encrypted and unencrypted sessions. so -E is the "no unencrypted visitors, we're a gated community" button. 🔐
  • -Q dscp — specifies the Differentiated Services Code Point (DSCP), formerly known as Type of Service (TOS), in the IP header for all outgoing packets. valid values are 0-63 and you can write them in either decimal or hexadecimal. default is 0.
not currently supported on Windows, sorry windows girlies 😭
  • -x log_level — specifies the 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. so if you want the full tea, crank it to 5. 🍵
  • -t — receive each file into a temp file in the same directory as the destination file. the temp file will have an extension of .~uftp-{group-id}-{file-id}, where {group-id} and {file-id} are the group ID of the current session and the file ID of the current file. and if -A is also specified, the existing destination file is not moved to the backup directory until after the file is fully received. safety first, bestie. 🛟
  • -T temp_dir — temp directory where files are received, then moved to dest_dir when the session is complete. if omitted, files are received directly into dest_dir. it must reside on the same filesystem as the destination directory.

the -T option MUST be specified to allow the client to save the state of failed file transfers that can be resumed later. yes, that's the resume feature, and yes, she needs -T to live.

not compatible with -A or -t. not compatible with -D when multiple destination directories are specified. also, if this option is specified, no incoming files with an absolute path will be accepted, and sync mode will not work properly since there is no existing file to check.

IMPORTANT 💀 when full directories are received, the entire directory is moved at once to the destination directory, removing any existing file/directory. this means that if an existing directory in dest_dir is the same name as a directory received into temp_dir, all files under the existing directory are deleted. the -i option prevents this by moving all files individually.

like. read that twice. that's not a vibe check, that's a data check. 🙈

  • -D dest_dir[,dest_dir...] — destination directories for all received files. when an incoming file specifies an absolute path, it must match one of the destination directories, otherwise the file will be rejected. incoming files that don't specify an absolute path will be received into the first destination directory in the list. default is /tmp for UNIX-like systems, C:\temp for Windows. 🗂️
  • -A backup_dir[,backup_dir...] — specifies backup directories. each backup directory corresponds to a destination directory, so the number of each MUST be the same. i said what i said. ✋

existing files that would be overwritten by incoming files are moved to the corresponding backup directory for the selected destination directory, first under timestamped directories, then under the full path of the existing file.

for example, if /full/path/to/file would be overwritten, it is moved to {backup_dir}/YYYYMMDD/HHMMSS/full/path/to/file. under Windows, drive letters for local files are not part of the name, but host/share names for network files are. so C:\path\to\file would be backed up to {backup_dir}\YYYYMMDD\HHMMSS\path\to\file, and \\host\share\path\to\file would be backed up to {backup_dir}\YYYYMMDD\HHMMSS\host\share\path\to\file.

not compatible with -T.

  • -L logfile — specifies the log file. default is /tmp/uftpd.log for UNIX-like systems systems, C:\uftpd_log.txt for Windows. (yes it really says "systems systems" in the source of truth, and honestly? iconic.) 📓
  • -F status_file — prints easily parsable status information to a file. setting this option to @LOG results in status info being mixed with normal logging output. two-for-one, we love efficiency. 💅

the following is printed when the client registers with a server:

CONNECT;timestamp;server_id;session_id;server_ip;server_name

where "timestamp" is the time in yyyy/mm/dd-hh:mm:ss format, "server_id" is the ID of the server, "session_id" is the ID of the session with the server, "server_ip" is the IP address that the server message came from, and "server_name" is the name associated with server_ip.

the following is printed after each file:

RESULT;timestamp;server_id;session_id;filename;size;status

where "timestamp" is the time in yyyy/mm/dd-hh:mm:ss format, "server_id" is the ID of the server, "session_id" is the ID of the session with the server, "filename" is the name of the current file, "size" is the size of the file in kilobytes (i.e. 1234KB), and status is:

  • copy: The file was received. ✅
  • overwrite: The file was received, and overwrote an existing file. Only generated in sync mode.
  • skipped: The file was declined because it is older that the existing file. Only generated in sync mode. (👵 not today, grandma file)
  • rejected: The file was rejected, because the file was sent with an absolute pathname and either the client is using a temp directory or the filename doesn't match one of the client's destination directories.
  • -q — when the client receives an ANNOUNCE from the server, it normally prints the hostname associated with the IP address where the ANNOUNCE came from. specifying this option prevents a DNS lookup of the server IP, saving time. speed. ⚡
  • -P pidfile — the pidfile to write the daemon's pid to on startup. default is no pidfile. she simply does not leave a note. 🙈
  • -o — enables source specific multicast (SSM) to join all multicast groups. setting this option requires that the public multicast addresses specified by -M are valid SSM addresses, and requires the -S option to specify the IP addresses of server in order to join the relevant SSM group as well as the -R option if any servers communicate through a proxy. this also requires servers talking to this client to use a SSM address for the private multicast address, otherwise the message will be rejected. no SSM address, no entry. 🚫

valid SSM addresses are in the 232.0.0.0/8 range for IPv4 and the ff30::/96 range for IPv6.

  • -S serverlist_file — a file containing a list of servers the client will allow to send files to it and the proxy the server communicates through, if any. the file should contain the ID of the server, the IP address the client expects the server's request to come from, the ID of the client or response proxy it goes through, and optionally the server's public key fingerprint, with one entry for a server on each line. if a proxy is not used by the server, a value of 0 must be specified. if a key fingerprint is given, the key specified by the server must match the fingerprint.

this option is required if the -o option is also specified, and is required if any server communicates through a proxy.

example contents:

0x11112222|192.168.1.101|0x22223333|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|0

if a particular server is running version 4.x, the file should list the IP and fingerprint of the client proxy instead of the server. in version 4.x mode, the proxy can authenticate the server. 🎀

  • -R proxylist_file — a file containing a list of proxies the client will allow to send files to it. the file should contain the ID of the proxy, the IP address the client expects the proxy's request to come from, and optionally the proxy's public key fingerprint, with one entry for a server on each line. if a key fingerprint is given, the key specified by the proxy must match the fingerprint.

this option is required if the -o option is specified and any server uses a proxy. not required otherwise unless proxies are to be authenticated.

example contents:

0x22223333|192.168.1.102|3E:5D:E7:2B:38:33:FE:1E:B6:DC:83:68:6C:04:D7:3E:03:90:F1:26
0x33334444|fe80::213:72ff:fed6:38f3|
  • -r v4proxy[/fingerprint] — specifies the name/IP of the response proxy that all responses from version 4.x servers are forwarded to. if fingerprint is given, it specifies the proxy's public key fingerprint. upon startup, the client will query the proxy for its public key, retrying every 5 seconds until it gets a successful response. the client cannot accept an encrypted file transfer from a 4.x server until it gets the proxy's key. so like, she's gonna keep asking. she's persistent like that. 💅

and that's where part one lands bestie — the rest of the options are still coming, so don't wander off 🫶

  • -c cache_size — bestie, this sets the size in bytes of the cache that holds received data packets before they get written to disk. Tuning this value right can greatly increase efficiency at speeds in the gigabit range. Valid values are 10240-20971520 (10KB-20MB). Default is 1048576 (1MB). 💾
  • -k keyfile — this is the partner-in-crime option to -K, and the whole key situation is explained right below. 🔑
  • -K {rsa:key_len | ec:curve} — okay so -k and -K are the duo used to read and/or write the client's RSA/ECDSA private key.

The -K option creates an RSA or ECDSA private key. 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 supported EC curves are secp256r1 (prime256v1), secp384r1, and secp521r1.

  • If only -K is specified, a key is created and not persisted.
  • If only -k is specified, this option reads an RSA or ECDSA private key from the specified keyfile.
  • If -k and -K are both specified, the key created by -K is written to the keyfile listed by -k.
  • If neither -k nor -K are specified, an EC private key using curve secp256r1 is generated and not persisted.

The definition of keyfile depends 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_file is actually the name of the key container.

All other systems use OpenSSL for the crypto library (although under Windows UFTP can 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.

  • -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. Super useful when running as a service. On non-Windows systems, this option has no effect. 🪟
  • -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.

  • -i — when -T is specified, directories are normally moved from the temp directory to the destination directory at once, removing all existing files in that subdirectory within the destination directory. This option causes directories to be traversed so that all received files are moved individually, preventing unwanted deletions. This also affects the operation of the -s option. If -T is not specified, this option has no effect.
  • -s postreceive_script — the full path to an external command or script to be called when files are received. The command will be called as follows:
postreceive_script -I session_id file [ file... ]

Where session_id is an 8 hexadecimal digit number identifying the current session, and file is the full pathname to one or more received files/directories in the destination directory specified by -D.

The way this script is called depends on whether or not a temp directory is specified by -T, and if -i is specified. If a temp directory is not specified, or if both -T and -i are specified, the script gets called once for each file as soon as the file is received. If a temp directory is specified but -i is not, the script gets called once at the end of the session, and is passed all top level files/directories received. Here, "top level files/directories" refers to all entries in the temp directory for the session, but not subdirectories. So the script would be responsible for traversing any listed directories to find files contained within them.

  • -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/uftpd.log, it will be renamed /tmp/uftpd.log.1 and a new /tmp/uftpd.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.
  • -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.
  • -I interface[,interface...] — lists one or more interfaces to listen to multicast traffic on. Interfaces can be specified either by interface name, by hostname, or by IP. When receiving a closed group membership request, the client will participate if any of these interfaces matches an IP in the announcement. When receiving an open group membership request, the first interface listed is the one the client will report back to the server. This may not necessarily be the interface that the ANNOUNCE was received on. 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. If specifying by hostname or IP, may be a mixture of IPv4 and IPv6 addresses, except on systems that don't support dual mode sockets such as Windows XP.
  • -M pub_mcast_addr[,pub_mcast_addr...] — the list of public multicast addresses to listen on. May be a mixture of IPv4 and IPv6 addresses, except on systems that don't support dual mode sockets such as Windows XP. Default is 230.4.4.1.

✨ EXAMPLES ✨

Starting with the default options:

uftpd

The client runs as a daemon and listens for announcements on UDP port 1044 on multicast address 230.4.4.1 on all non-loopback network interfaces. Incoming files are received directly into /tmp (C:\temp on Windows). An EC key using curve secp256r1 is generated to handle encrypted sessions. 💅

Suppose you want an external process to handle incoming files in /tmp/dest. Since you don't want to pick up incomplete files, you might want them to be received into /tmp/receiving then moved to /tmp/dest when done. Then call the client like this:

uftpd -D /tmp/dest -T /tmp/receiving

If the client expects to receive from different servers, one sending on 230.4.4.1 and one sending on ff02:4:4:2:

uftpd -M 230.4.4.1,ff02:4:4:2

If incoming packets aren't being read quickly enough, and you want to increase the UDP receive buffer size to 2 MB:

uftpd -B 2097152

🚪 EXIT STATUS 🚪

The following exit values are returned:

  • 0 — The client 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 client was interrupted by the user.

👀 SEE ALSO 👀

uftp(1), uftpproxyd(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).

That's the whole page, bestie. It's from UFTP 5.0, dated 22 April 2020, and it's uftpd(1). Periodt. Stay iconic 💖✨

📦 where this page comes from