Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
uftpd(1)		    General Commands Manual		      uftpd(1)

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...] ]

DESCRIPTION
       uftpd  is  the  client  daemon of the UFTP suite.  It listens on	one or
       more multicast addresses	to receive files from servers.

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

OPTIONS
       The following options are supported:

       -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.

       -U UID The unique ID for	this client, specified as an 8 digit hexadeci-
	      mal 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.

       -B buf_size
	      The  size	in bytes of the	UDP receive buffer to use.  Valid val-
	      ues are 65536-104857600 (64KB-100MB).  Defaults to 262144.

       -E     Only allow incoming sessions if encryption is enabled.   Default
	      is to allow both encrypted and unencrypted sessions.

       -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.

	      Not currently supported on Windows.

       -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.

       -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	file ID	of the current
	      file.  If	-A is also specified, the existing destination file is
	      not  moved to backup directory until after the file is fully re-
	      ceived.

       -T temp_dir
	      Temp directory in	 which	files  are  received,  then  moved  to
	      dest_dir	when  the  session is complete.	 If omitted, files are
	      received directly	 into  dest_dir.   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.

	      Not compatible -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  ac-
	      cepted,  and  sync mode will not work properly since there is no
	      existing file to check.

	      IMPORTANT: When full directories are received, the entire	direc-
	      tory is moved at once to the destination directory, removing any
	      existing file/directory.	This means that	if an existing	direc-
	      tory  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.

       -D dest_dir[,dest_dir...]
	      Destination  directories for all received	files.	When an	incom-
	      ing 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  re-
	      ceived  into  the	 first destination directory in	the list.  De-
	      fault 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.  Existing files that  would	 be  overwritten  by  incoming
	      files  are  moved	 to the	corresponding backup directory for the
	      selected destination directory, first under timestamped directo-
	      ries, 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.

       -F status_file
	      Prints easily parsable status information	to  a  file.   Setting
	      this option to @LOG results in status info being mixed with nor-
	      mal logging output.

	      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  as-
	      sociated 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 cur-
	      rent 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  ex-
	      isting file.  Only generated in sync mode.

	      rejected:	 The file was rejected,	because	the file was sent with
	      an absolute pathname and either the client is using a  temp  di-
	      rectory or the filename doesn't match one	of the client's	desti-
	      nation directories.

       -q     When the client receives an ANNOUNCE from	the  server,  it  nor-
	      mally  print  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.

       -P pidfile
	      The pidfile to write the daemon's	pid to on startup.  Default is
	      no pidfile.

       -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 mul-
	      ticast address, otherwise	the message will be rejected.

	      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  op-
	      tionally 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 finger-
	      print.

	      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.

       -c cache_size
	      Specifies	the size in bytes of the cache used to	hold  received
	      data  packets before they	are written to disk.  Proper tuning of
	      this value can greatly increase efficiency at speeds in the  gi-
	      gabit  range.  Valid values are 10240-20971520 (10KB-20MB).  De-
	      fault is 1048576 (1MB).

       -k keyfile

       -K {rsa:key_len | ec:curve}
	      These two	options	are 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 pri-
	      vate key from the	specified keyfile.

	      If -k and	-K are both specified, the key created by -K is	 writ-
	      ten 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	is dependent  on  the  crypto  library
	      UFTP is compiled to use.

	      On Windows systems, UFTP uses CNG	(Cryptography API: Next	Gener-
	      ation).  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  in-
	      ternal  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 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  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	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  op-
	      tion  stores keys	in the system key container.  Useful when run-
	      ning 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 fol-
	      lowing 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 the that subdirectory within the destina-
	      tion 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	 host-
	      name,  or	 by  IP.  When receiving a closed group	membership re-
	      quest, 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 ac-
	      cepted 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	inter-
       faces.  Incoming	files are received directly into /tmp (C:\temp on Win-
       dows).  An EC key using curve secp256r1	is  generated  to  handle  en-
       crypted 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	 back-
	      ground.

       1      An invalid command line parameter	was specified.

       2      An error occurred	while attempting to initialize network connec-
	      tions.

       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-multi-
       cast.sourceforge.net.  UFTP is covered by the GNU  General  Public  Li-
       cense.	Commercial licenses and	support	are available from Dennis Bush
       (bush@tcnj.edu).

UFTP 5.0			 22 April 2020			      uftpd(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=uftpd&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help