-
Notifications
You must be signed in to change notification settings - Fork 0
/
uftpd_man.txt
executable file
·459 lines (356 loc) · 20.9 KB
/
uftpd_man.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
uftpd(1) 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 ] [ -S serverlist_file ] [ -R proxy[/fp] ]
[ -c cache_size ] [ -k keyfile[,keyfile...] ]
[ -K rsa:key_len | ec:curve[,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 running UFTP 4.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.
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\Ser‐
vices\Tcpip\Parameters\DisableUserTOSSetting
Not currently supported on Windows Vista or later.
-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
received.
-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, no incoming files
with an absolute path will be accepted if this option is speci‐
fied.
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 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
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. 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.
-S 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
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 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
existing 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
directory or the filename doesn't match one of the client's des‐
tination 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.
-S serverlist_file
A file containing a list of servers the client will allow to
send files to it. The file should contain the ID of the server,
the IP address the client 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. If a key fingerprint is
given, the key specified by the server must match the finger‐
print. If your system supports source specific multicast (SSM),
the client will subscribe to all public and private multicast
addresses using SSM for all servers listed.
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
When expecting to receive from a server that is behind a proxy,
the file should list the ID of the server along with the IP and
fingerprint of the client proxy. The proxy can authenticate the
server.
-R proxy[/fingerprint]
Specifies the name/IP of the response proxy that all responses
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 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
gigabit range. Valid values are 10240-20971520 (10KB-20MB).
Default is 1048576 (1MB).
-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 client'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 Cryp‐
toAPI, 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 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 CryptoAPI or CNG, private keys are
normally stored in the key container of the running user. Spec‐
ifying this option stores keys in the system key container.
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 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 destion‐
aion 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
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_multicast_addr[,pub_multicast_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). A 512-bit RSA key 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
To handle incoming encrypted sessions with differing private keys:
uftpd -k
file_for_rsa_1024_key,file_for_rsa_2048_key,file_for_ec_prime256v1_key
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
License. Commercial licenses and support are available from Dennis
Bush (bush@tcnj.edu).
UFTP 4.7 16 May 2015 uftpd(1)