source: TI05-delivery/trunk/src/bbftp-client-3.2.0/doc/bbftp.1 @ 773

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI05-delivery/trunk/src/bbftp-client-3.2.0/doc/bbftp.1@1077
Revision 773, 38.1 KB checked in by spascoe, 14 years ago (diff)

Initial import of bbftp source

Line 
1.\" Automatically generated by Pod::Man version 1.15
2.\" Mon May 30 11:02:19 2005
3.\"
4.\" Standard preamble:
5.\" ======================================================================
6.de Sh \" Subsection heading
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
14.de Sp \" Vertical space (when we can't use .PP)
15.if t .sp .5v
16.if n .sp
17..
18.de Ip \" List item
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
24.de Vb \" Begin verbatim text
25.ft CW
26.nf
27.ne \\$1
28..
29.de Ve \" End verbatim text
30.ft R
31
32.fi
33..
34.\" Set up some character translations and predefined strings.  \*(-- will
35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
36.\" double quote, and \*(R" will give a right double quote.  | will give a
37.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
38.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
40.tr \(*W-|\(bv\*(Tr
41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
42.ie n \{\
43.    ds -- \(*W-
44.    ds PI pi
45.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
46.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
47.    ds L" ""
48.    ds R" ""
49.    ds C` ""
50.    ds C' ""
51'br\}
52.el\{\
53.    ds -- \|\(em\|
54.    ds PI \(*p
55.    ds L" ``
56.    ds R" ''
57'br\}
58.\"
59.\" If the F register is turned on, we'll generate index entries on stderr
60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
61.\" index entries marked with X<> in POD.  Of course, you'll have to process
62.\" the output yourself in some meaningful fashion.
63.if \nF \{\
64.    de IX
65.    tm Index:\\$1\t\\n%\t"\\$2"
66..
67.    nr % 0
68.    rr F
69.\}
70.\"
71.\" For nroff, turn off justification.  Always turn off hyphenation; it
72.\" makes way too many mistakes in technical documents.
73.hy 0
74.if n .na
75.\"
76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
77.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
78.bd B 3
79.    \" fudge factors for nroff and troff
80.if n \{\
81.    ds #H 0
82.    ds #V .8m
83.    ds #F .3m
84.    ds #[ \f1
85.    ds #] \fP
86.\}
87.if t \{\
88.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89.    ds #V .6m
90.    ds #F 0
91.    ds #[ \&
92.    ds #] \&
93.\}
94.    \" simple accents for nroff and troff
95.if n \{\
96.    ds ' \&
97.    ds ` \&
98.    ds ^ \&
99.    ds , \&
100.    ds ~ ~
101.    ds /
102.\}
103.if t \{\
104.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
105.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
106.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
107.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
108.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
109.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
110.\}
111.    \" troff and (daisy-wheel) nroff accents
112.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
113.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
114.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
115.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
116.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
117.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
118.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
119.ds ae a\h'-(\w'a'u*4/10)'e
120.ds Ae A\h'-(\w'A'u*4/10)'E
121.    \" corrections for vroff
122.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
123.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
124.    \" for low resolution devices (crt and lpr)
125.if \n(.H>23 .if \n(.V>19 \
126\{\
127.    ds : e
128.    ds 8 ss
129.    ds o a
130.    ds d- d\h'-1'\(ga
131.    ds D- D\h'-1'\(hy
132.    ds th \o'bp'
133.    ds Th \o'LP'
134.    ds ae ae
135.    ds Ae AE
136.\}
137.rm #[ #] #H #V #F C
138.\" ======================================================================
139.\"
140.IX Title "BBFTP 1"
141.TH BBFTP 1 "perl v5.6.1" "2005-05-30" "User Contributed Perl Documentation"
142.UC
143.SH "NAME"
144bbftp \- transfer files using compression and parallel streams
145.SH "SYNOPSIS"
146.IX Header "SYNOPSIS"
147\&\fBbbftp\fR \fB\-v\fR
148.PP
149\&\fBbbftp\fR \fB[Options]\fR [\fB\-u\fR RemoteUsername] \fB\-i\fR ControlFile [RemoteHost]
150.PP
151\&\fBbbftp\fR \fB[Options]\fR [\fB\-u\fR RemoteUsername] \fB\-e\fR ControlCommands [RemoteHost]
152.SH "DESCRIPTION"
153.IX Header "DESCRIPTION"
154Use the \fBbbftp\fR command to transfer files between the local host and a
155remote host. In order to get better performance on a loaded Wide Area Network
156than transferring with the standard ftp command, use the bbftp command. bbftp
157has been designed to take advantage of the \fB\s-1RFC\s0 1323\fR and uses multiple
158streams is order to speed up transfer. It also implements an automatic retry
159in case of failure of commands contained in the \fBControlFile\fR or in the
160\&\fBControlCommands\fR.
161.PP
162\&\fBbbftp\fR allows two methods of connection to the remote host, a direct
163connection on the control port of the remote \fBbbftpd\fR daemon or the ability
164to remotely start a \fBbbftpd\fR daemon through an ssh tunnel. For the first
165method, the \fBbbftpd\fR daemon has to be started (by inetd or as a standalone
166daemon) on the remote host and all user information (username, password) are
167transmitted encrypted to the daemon; for the second the \fBbbftpd\fR binary has
168to be accessible somewhere on the remote host and all control data are
169transmitted through the ssh tunnel.
170.PP
171A third additionnal authenticate mode allows to use certificates to log on.
172This mode is based on the Grid Security Infrastructure and requires Globus
173software to be installed. The client side needs a certificate to identify
174itself and the daemon needs a host certificate.
175.PP
176The behaviour of \fBbbftp\fR is controled by the \fBControlFile\fR which contains
177the commands to be executed (option \-i) or by commands separated by
178semicolons (option \-e). The format of these commands are given in
179\&\fB\s-1CONTROL\s0 \s-1COMMANDS\s0\fR.
180.PP
181\&\fBbbftp\fR may be used in one of the following ways:
182.PP
183% bbftp
184.PP
185to print a short help
186.PP
187% bbftp \-v
188.PP
189to write the version of the software and default values to standard output.
190.PP
191% bbftp [Options] \fB\-i\fR ControlFile [\fB\-u\fR RemoteUsername] [\fBRemoteHost\fR]
192.PP
193% bbftp [Options] \fB\-e\fR ControlCommands [\fB\-u\fR RemoteUsername] [\fBRemoteHost\fR]
194.PP
195to request the execution of commands contained in the control file
196\&\fBControlFile\fR or the \fBControlCommands\fR using \fBRemoteUsername\fR on
197\&\fBRemoteHost\fR.
198.PP
199Depending on the \fIOptions\fR a password for the \fBRemoteUsername\fR on
200\&\fBRemoteHost\fR may be requested interactively (see \fB\s-1OPTIONS\s0\fR section,
201for a full description of the \fIOptions\fR).
202.PP
203The \fBRemoteUsername\fR value is ignored in the \fBcertificate authentication mode\fR.
204The remote user is automatically detected by the daemon using the Globus
205gridmap file.
206.SH "OPTIONS"
207.IX Header "OPTIONS"
208Options can be separated into two classes, those describing the way \fBbbftp\fR
209connects to the \fBbbftpd\fR daemon and those modifying the behaviour of the
210control commands.
211.Sh "\s-1CONNECTION\s0 \s-1OPTIONS\s0"
212.IX Subsection "CONNECTION OPTIONS"
213.Ip "\-u" 4
214.IX Item "-u"
215Use this option to specify the user on the remote host. In \s-1SSH\s0 mode (see below)
216this option is optional: if not specified, the user in \s-1SSH\s0 config file will be
217used, or the local user if not in the \s-1SSH\s0 config file.
218When compiled with the certificates authentication module, the use of this
219option will determine the way the authentication is done: if \-u is used, the
220classical user/password will be used, otherwise the certificate will be used.
221.Ip "\-s" 4
222.IX Item "-s"
223Use this option to use ssh to remotely start a \fBbbftpd\fR daemon. It usually
224starts the binary \*(L"bbftpd \-s\*(R", but this can be changed througth the \fB\-E\fR
225option.
226.Ip "\-S" 4
227.IX Item "-S"
228Same as \fB\-s\fR but ask ssh to run without asking a question (no password, no
229host key checking). It implies the usage of the identity file (for those
230familiar to ssh, this in done in setting the ssh
231options BatchMode to yes and the option StrictHostKeyChecking to no).
232.Ip "\-E Server command to run" 4
233.IX Item "-E Server command to run"
234This option has to be used if the binary to be started on the remote host is
235not the
236default one (usually \*(L"bbftpd \-s\*(R"). This option also implies the usage
237of the ssh mode (no need to add the \fB\-s\fR option)
238.Ip "\-I \s-1SSH\s0 identity file" 4
239.IX Item "-I SSH identity file"
240This option has to be used if the ssh identity file is not the default one
241(usually \f(CW$HOME\fR/.ssh/identity).
242This option also implies the usage of the ssh mode (no need to add the \fB\-s\fR
243option)
244.Ip "\-L \s-1SSH\s0 command" 4
245.IX Item "-L SSH command"
246If your ssh command is not the default one (usually \*(L"ssh \-q\*(R"), use this
247option to change it.
248This option also implies the usage of the ssh mode (no need to add the
249\&\fB\-s\fR option)
250.Ip "\-P Private authentication string" 4
251.IX Item "-P Private authentication string"
252If your client have been compiled with a private authentication schema,
253this option allow
254to pass an arbitrary string to the authentication module. You can determine
255if your client
256is using a private authentication module with the \fB\-v\fR option.
257.Ip "\-w Control port number" 4
258.IX Item "-w Control port number"
259Use this option to change the control port for connection to on the
260\&\fBRemoteHost\fR.
261This option is meaningless in ssh mode.
262.Sh "\s-1PROTOCOL\s0 \s-1OPTIONS\s0"
263.IX Subsection "PROTOCOL OPTIONS"
264.Ip "\-D[min:max] Domain for ephemeral ports" 4
265.IX Item "-D[min:max] Domain for ephemeral ports"
266Use this option to use protocol V2 (non-passive mode) instead of V3 (passive mode).
267min and max are the range of ports used for data sockets. If min and max are not
268specified, free ports will be used (or built-in ports at compilation time).
269.Sh "\s-1BEHAVIOUR\s0 \s-1OPTIONS\s0"
270.IX Subsection "BEHAVIOUR OPTIONS"
271.Ip "\-b" 4
272.IX Item "-b"
273Use this option to run \fBbbftp\fR
274in the background after all interactive requests.
275.Ip "\-c" 4
276.IX Item "-c"
277Use this option to gzip the data during transmission. Compression and
278uncompression
279are done \*(L"on the fly\*(R" and do not require any additionnal disk space.
280Do not use it if
281the files to transmit are not compressible, as this will only lead to a
282waste of \s-1CPU\s0 and
283time. This option can be overridden by the control command \fBsetoption\fR
284\&\fBgzip\fR
285.Ip "\-f ErrorFile" 4
286.IX Item "-f ErrorFile"
287Use this option to redirect the data generated on the standard error to
288\&\fBErrorFile\fR
289.Ip "\-g Globus service name" 4
290.IX Item "-g Globus service name"
291Use this option in certificate mode if the server does not use a host server.
292The service name will be the subject of the certificate the server is
293actually using.
294.Ip "\-m" 4
295.IX Item "-m"
296Use to special output on file transfer. The ouput is in the following format:
297.Sp
298Direction NumberOfBytes NumberOfSeconds BuffersizePerStream SendWinSize
299RecvWinSize NumberOfStreams Compression
300.Sp
301BuffersizePerStream, SendWinSize, RecvWinSize are expressed in KiloBytes
302.Sp
303For example :
304.Sp
305get 10000 10 256 256 256 2 gzip
306.Sp
307means that 10000 Bytes have been transfered in 10 seconds in compressed mode
308using 2 streams,
309a buffer size per stream of 256 KBytes, a \s-1TCP\s0 send window size of 256 KBytes
310and a \s-1TCP\s0 receive window size
311of 256 KBytes.
312.Sp
313This option is useful when trying to choose the best parameters between two
314sites.
315.Sp
316When this option is set \fB\-V\fR, \fB\-W\fR and \fB\-t\fR options are not available.
317.Ip "\-n" 4
318.IX Item "-n"
319Use this option to simulate the transfer. All commands will be executed but
320no data will be transfered with
321the get, mget put and mput commands. Output is the same as a real transfer.
322\&\fBOutputFile\fR
323.Ip "\-o OutputFile" 4
324.IX Item "-o OutputFile"
325Use this option to redirect the data generated on the standard output to
326\&\fBOutputFile\fR
327.Ip "\-q" 4
328.IX Item "-q"
329Use this option to mark packets for
330\&\fB\s-1QBSS\s0\fR (QBone Scavenger Service)
331.Ip "\-p NumberOfParallelStreams" 4
332.IX Item "-p NumberOfParallelStreams"
333Use this option to increase the number of streams to use during the file
334transfer. Default is 1.
335This option can be overridden by the control command
336\&\fBsetnbstream\fR
337.Ip "\-r NumberOfTries" 4
338.IX Item "-r NumberOfTries"
339Use this option to change the number of tries to use when a transfer fails.
340The default is usually 5.
341.Ip "\-R .bbftprc file" 4
342.IX Item "-R .bbftprc file"
343After a successful connection to the daemon the client is going to execute
344all control commands located in the \*(L"$HOME/.bbftprc\*(R" file. The location of
345this file
346can be changed with this option. Take care, not all control commands are
347allowed
348in the .bbftprc file (See \fB\s-1CONTROL\s0 \s-1COMMANDS\s0\fR to know the authorized one)
349If this option is not provided and \*(L"$HOME/.bbftprc\*(R" does not exists, the
350client tries to execute all commands in \*(L"/etc/bbftp.conf\*(R".
351.Ip "\-t" 4
352.IX Item "-t"
353Use this option to have a timestamp on all output (overridden by \-m option).
354.Ip "\-V" 4
355.IX Item "-V"
356Use this option to set the client in verbose mode (overridden by \-m option).
357.Ip "\-W" 4
358.IX Item "-W"
359Use this option to print warnings to stderr (overridden by \-m option).
360.SH "CONTROL COMMANDS"
361.IX Header "CONTROL COMMANDS"
362The control commands are either contained by an \s-1ASCII\s0 file (
363\&\fB\-i\fR option) or written on the bbftp line (
364\&\fB\-e\fR
365option). They can be divided into two classes, the \*(L"File related commands\*(R"
366and the \*(L"Behaviour
367commands\*(R".
368.PP
369All \*(L"Behaviour commands\*(R" may be put in a .bbftprc file, but all \*(L"File related commands\*(R"
370are forbiden in that file.
371.PP
372\&\fB\s-1IMPORTANT\s0 \s-1NOTE\s0\fR
373.PP
374Under the \s-1RFIO\s0 mode (see
375\&\fBsetoption remoterfio\fR
376and
377\&\fBsetoption localrfio\fR
378) all file related commands have to be given in absolute mode.
379.Sh "\s-1FILE\s0 \s-1RELATED\s0 \s-1COMMANDS\s0"
380.IX Subsection "FILE RELATED COMMANDS"
381.if n .Ip "\fBcd """"RemoteDirectory""""\fR" 4
382.el .Ip "\fBcd ``RemoteDirectory''\fR" 4
383.IX Item "cd "RemoteDirectory"
384Change the current directory of the daemon on the remote host.
385.Sp
386If the
387\&\fBRemoteDirectory\fR
388is given in relative mode (not beginning by a /), it is supposed to be
389relative to the directory where the daemon is currently running. After the
390first connection, the current directory is the home directory of the
391\&\fBRemoteUsername\fR .
392.Sp
393The client keeps in mind the current remote directory so
394in case of broken connection during a transfer, it can reset
395the current directory of the daemon to the correct directory.
396.Sp
397If the daemon has been set in \s-1RFIO\s0 mode (see
398\&\fBsetoption remoterfio\fR
399) this option is unavailable.
400.if n .Ip "\fBget """" RemoteFile LocalFile""""\fR" 4
401.el .Ip "\fBget `` RemoteFile LocalFile''\fR" 4
402.IX Item "get " RemoteFile LocalFile"
403Transfer the remote file
404\&\fBRemoteFile\fR
405to the local host with the name
406\&\fBLocalFile\fR.
407If the local file already exists it is overwritten (only in case of successful transfer
408if the
409\&\fBsetoption tmpfile\fR
410has been set). Under some circumstances
411(No space left on device, Access denied, File is a directory ...), no retry is done
412and the next command is processed.
413.Sp
414If the
415\&\fBRemoteFile\fR
416is given in relative mode (not beginning by a /), it is supposed to be
417relative to the current directory on the remote host (which is set to
418the home directory of the
419\&\fBRemoteUsername\fR
420at the beginning).
421If the
422\&\fBLocalFile\fR
423is given in relative mode (not beginning by a /) the file is created
424relative to the directory where the
425\&\fBbbftp\fR command is running (which may have been changed with the
426\&\fBlcd\fR command).
427.if n .Ip "\fBget """" RemoteFile LocalDir/""""\fR" 4
428.el .Ip "\fBget `` RemoteFile LocalDir/''\fR" 4
429.IX Item "get " RemoteFile LocalDir/"
430Transfer the remote file
431\&\fBRemoteFile\fR
432to the local host with the name
433\&\fBRemoteFile\fR
434(without path) in the
435\&\fBLocalDir\fR
436directory.
437.Sp
438If the local file already exists it is overwritten (only in case of successful transfer
439if the
440\&\fBsetoption tmpfile\fR
441has been set). Under some circumstances
442(No space left on device, Access denied, File is a directory ...), no retry is done
443and the next command is processed.
444.Sp
445If the
446\&\fBRemoteFile\fR
447is given in relative mode (not beginning by a /), it is supposed to be
448relative to the current directory on the remote host (which is set to
449the home directory of the
450\&\fBRemoteUsername\fR
451at the beginning).
452.Sp
453If the
454\&\fBLocalDir\fR
455is given in relative mode (not beginning by a /) the file is created
456relative to the directory where the
457\&\fBbbftp\fR
458command is running (which may have been changed with the
459\&\fBlcd\fR
460command).
461.if n .Ip "\fBget """" RemoteFile""""\fR" 4
462.el .Ip "\fBget `` RemoteFile''\fR" 4
463.IX Item "get " RemoteFile"
464Transfer the remote file
465\&\fBRemoteFile\fR
466to the local host with the name
467\&\fBRemoteFile\fR.
468.Sp
469If the
470\&\fBRemoteFile\fR
471is given in relative mode (not beginning by a /), it is supposed to be
472relative to the current directory on the remote host (which is set to
473the home directory of the
474\&\fBRemoteUsername\fR
475at the beginning) and created on the local host relative to the directory where the
476\&\fBbbftp\fR
477command is running (which may have been changed with the
478\&\fBlcd\fR
479command).
480.if n .Ip "\fBlcd """" LocalDirectory""""\fR" 4
481.el .Ip "\fBlcd `` LocalDirectory''\fR" 4
482.IX Item "lcd " LocalDirectory"
483Change the current directory on the local host.
484If the
485\&\fBLocalDirectory\fR
486is given in relative mode (not beginning by a /), it is supposed to be
487relative to the directory where the client is currently.
488.Sp
489If the client has been set into \s-1RFIO\s0 mode (see
490\&\fB setoption localrfio\fR
491) this option is unavailable.
492.if n .Ip "\fBmget """" RemoteFiles LocalDirectory""""\fR" 4
493.el .Ip "\fBmget `` RemoteFiles LocalDirectory''\fR" 4
494.IX Item "mget " RemoteFiles LocalDirectory"
495Expand the
496\&\fB RemoteFiles\fR
497on the remote machine and do a \*(L"get\*(R" for each file name thus produced. 
498Files are transferred into the
499\&\fBLocalDirectory\fR.
500.if n .Ip "\fBmget """" RemoteFiles""""\fR" 4
501.el .Ip "\fBmget `` RemoteFiles''\fR" 4
502.IX Item "mget " RemoteFiles"
503Expand the
504\&\fB RemoteFiles\fR
505on the remote machine and do a \*(L"get\*(R" for each file name thus produced. 
506Files are transferred into the local working directory, which can be changed
507with the
508\&\fBlcd\fR
509command.
510.if n .Ip "\fBmkdir """" RemoteDirectory""""\fR" 4
511.el .Ip "\fBmkdir `` RemoteDirectory''\fR" 4
512.IX Item "mkdir " RemoteDirectory"
513Create the directory
514\&\fBRemoteDirectory\fR
515on the remote host. If the directory already exist no retry is done
516and the next command of the file is processed. If the
517\&\fBRemoteDirectory\fR
518is given in relative mode (not beginning by a /) the directory
519is created relative to the current remote directory.
520.Sp
521If one directory in the given path does not exist the command will fail if the
522\&\fBsetoption nocreatedir\fR
523is set. If the
524\&\fBsetoption createdir\fR
525has been set all unexisting directories will be created.
526.if n .Ip "\fBmput """" LocalFiles RemoteDirectory""""\fR" 4
527.el .Ip "\fBmput `` LocalFiles RemoteDirectory''\fR" 4
528.IX Item "mput " LocalFiles RemoteDirectory"
529Expand wild cards in the list of local files  given  as
530arguments  and  do a \*(L"put\*(R" for each file in the resulting
531list. Files are transfered into the
532\&\fB RemoteDirectory\fR.
533.if n .Ip "\fBmput """" LocalFiles""""\fR" 4
534.el .Ip "\fBmput `` LocalFiles''\fR" 4
535.IX Item "mput " LocalFiles"
536Expand wild cards in the list of local files  given  as
537arguments  and  do a \*(L"put\*(R" for each file in the resulting
538list. Files are transfered into the  current remote directory which can be changed
539with the
540\&\fB cd\fR
541command.
542.if n .Ip "\fBput """" LocalFile RemoteFile""""\fR" 4
543.el .Ip "\fBput `` LocalFile RemoteFile''\fR" 4
544.IX Item "put " LocalFile RemoteFile"
545Transfer the local file
546\&\fBLocalFile\fR
547to the remote host with the name
548\&\fBRemoteFile\fR.
549If the remote file already exists it is overwritten. Under some circumstances
550(No space left on device, Access denied ...), no retry is done
551and the next command of the file is processed.
552.Sp
553If the
554\&\fBLocalFile\fR
555is given in relative mode (not beginning by a /) the file is supposed to be
556relative to the directory where the
557\&\fBbbftp\fR
558command is running (which may have been changed with the
559\&\fBlcd\fR
560command).
561.Sp
562If the
563\&\fBRemoteFile\fR
564is given in relative mode (not beginning by a /), it is created
565relative to the current directory on the remote host (which is set to
566the home directory of the
567\&\fBRemoteUsername\fR
568at the beginning).
569.if n .Ip "\fBput """" LocalFile RemoteDir/""""\fR" 4
570.el .Ip "\fBput `` LocalFile RemoteDir/''\fR" 4
571.IX Item "put " LocalFile RemoteDir/"
572Transfer the local file
573\&\fBLocalFile\fR
574to the remote host with the name
575\&\fBLocalFile\fR
576(without the path) in the
577\&\fBRemoteDir\fR
578directory
579.Sp
580If the remote file already exists it is overwritten. Under some circumstances
581(No space left on device, Access denied ...), no retry is done
582and the next command of the file is processed.
583.Sp
584If the
585\&\fBLocalFile\fR
586is given in relative mode (not beginning by a /) the file is supposed to be
587relative to the directory where the
588\&\fBbbftp\fR
589command is running (which may have been changed with the
590\&\fBlcd\fR
591command).
592.Sp
593If the
594\&\fBRemoteDir\fR
595is given in relative mode (not beginning by a /), it is created
596relative to the current directory on the remote host (which is set to
597the home directory of the
598\&\fBRemoteUsername\fR
599at the beginning).
600.if n .Ip "\fBput """" LocalFile""""\fR" 4
601.el .Ip "\fBput `` LocalFile''\fR" 4
602.IX Item "put " LocalFile"
603Transfer the local file
604\&\fBLocalFile\fR
605to the remote host with the name
606\&\fBLocalFile\fR.
607.Sp
608If the
609\&\fBLocalFile\fR
610is given in relative mode (not beginning by a /) the file is supposed to be
611relative to the directory where the
612\&\fBbbftp\fR
613command is running (which may have been changed with the
614\&\fBlcd\fR
615command) and created relative to the current directory on the remote host (which is set to
616the home directory of the
617\&\fBRemoteUsername\fR
618at the beginning).
619.if n .Ip "\fBdir """" RemoteDir""""\fR" 4
620.el .Ip "\fBdir `` RemoteDir''\fR" 4
621.IX Item "dir " RemoteDir"
622If used with '\-m', lists the content of the remote directory. Each line has the following format:
623.Sp
624\&\s-1LINE:\s0 <\s-1LINK_CHAR\s0><\s-1TYPE_CHAR\s0><\s-1SP\s0><\s-1FILE_NAME\s0>
625.Sp
626\&\s-1LINK_CHAR:\s0 'l' if file is a link else blank
627.Sp
628\&\s-1TYPE_CHAR:\s0 'd' if file is a directory, 'f' if it is a reguler file or 'u' if it is
629an invalid link
630.Sp
631\&\s-1SP:\s0 ' '
632.Sp
633\&\s-1FILE_NAME:\s0 \s-1STRING\s0
634.Sp
635If \-m is not used, the result will be only '\s-1OK\s0' or '\s-1FAILED\s0'. This can be used to test the
636existence of a directory without printing its content.
637.if n .Ip "\fBrm """" RemoteFile""""\fR" 4
638.el .Ip "\fBrm `` RemoteFile''\fR" 4
639.IX Item "rm " RemoteFile"
640Deletes the remote file
641\&\fBRemoteFile\fR
642.if n .Ip "\fBstat """" RemoteFile""""\fR" 4
643.el .Ip "\fBstat `` RemoteFile''\fR" 4
644.IX Item "stat " RemoteFile"
645If used with '\-m', print statistics about the file or the directory in the following format:
646.Sp
647device inode mode size block_size blocks uid gid (access time) (modification time) (change time)
648.if n .Ip "\fBdf """" RemoteDir""""\fR" 4
649.el .Ip "\fBdf `` RemoteDir''\fR" 4
650.IX Item "df " RemoteDir"
651If used with '\-m', print statistics about the file system that contains the directory RemoteDir in the following format:
652.Sp
653total_blocks blocks_available block_size total_inode inode_available filename_max_length
654.Sh "\s-1BEHAVIOUR\s0 \s-1COMMANDS\s0"
655.IX Subsection "BEHAVIOUR COMMANDS"
656\&\fBsetoption \*(L" Option\*(R"\fR
657.Sp
658To negate an option just add \*(L"no\*(R" before the option (ie setoption nocreatedir).
659The options are the following :
660.Ip "\fBcreatedir\fR" 4
661.IX Item "createdir"
662All file-related commands will create missing directories if needed (default createdir).
663.Ip "\fBgzip\fR" 4
664.IX Item "gzip"
665All file transfers will be compressed using the gzip algorythm (default nogzip).
666.Ip "\fBkeepaccess\fR" 4
667.IX Item "keepaccess"
668The access time and modify time will be kept on each file transferred (default keepaccess).
669.Ip "\fBkeepmode\fR" 4
670.IX Item "keepmode"
671The file mode will be kept on each file transferred (default keepmode).
672.Ip "\fBlocalrfio\fR" 4
673.IX Item "localrfio"
674All local files will be created with \s-1RFIO\s0 functions (default nolocalrfio).
675.Ip "\fBremoterfio\fR" 4
676.IX Item "remoterfio"
677All remote files will be created with \s-1RFIO\s0 functions (default noremoterfio).
678.Ip "\fBqbss\fR" 4
679.IX Item "qbss"
680All the packets will be marked for \s-1QBSS\s0 (default noqbss).
681.Ip "\fBtmpfile\fR" 4
682.IX Item "tmpfile"
683All files will be created under a temporary name (FileName.bbftp.tmp.HostName.Pid) and renamed to
684the correct file name if transfer is successful (default tmpfile)
685.if n .Ip "\fBsetbuffersize """" Buffersize""""\fR" 4
686.el .Ip "\fBsetbuffersize `` Buffersize''\fR" 4
687.IX Item "setbuffersize " Buffersize"
688Set the size in Kbytes of the buffer used for reading or writing the files. This command
689set the local and remote buffer size. (Each stream will use the same buffer size)
690.if n .Ip "\fBsetlocalcos """" LocalCos""""\fR" 4
691.el .Ip "\fBsetlocalcos `` LocalCos''\fR" 4
692.IX Item "setlocalcos " LocalCos"
693Set the local \s-1COS\s0 to the value specified by
694\&\fBLocalCos\fR.
695This \s-1COS\s0 will be used for further rfio funtions. It is used if the
696\&\fB setoption localrfio\fR
697has been set and if the file is a \s-1HPSS\s0 file.
698A value of 0 allows to select the \s-1COS\s0 according to the file size.
699A negative value allows to not set the \s-1COS\s0.
700The default value is 0.
701.if n .Ip "\fBsetlocalumask """" LocalUmask""""\fR" 4
702.el .Ip "\fBsetlocalumask `` LocalUmask''\fR" 4
703.IX Item "setlocalumask " LocalUmask"
704Set the local umask to the value specified by
705\&\fBLocalUmask\fR.
706This umask will be used for further i/o funtions. The
707\&\fBLocalUmask\fR
708has to be given in
709\&\fB \s-1OCTAL\s0\fR
710.if n .Ip "\fBsetnbstream """" NumberOfParallelStreams""""\fR" 4
711.el .Ip "\fBsetnbstream `` NumberOfParallelStreams''\fR" 4
712.IX Item "setnbstream " NumberOfParallelStreams"
713Set the number of parallel streams to
714\&\fBNumberOfParallelStreams\fR.
715This number will be used for further transfer commands.
716.if n .Ip "\fBsetremotecos """" RemoteCos""""\fR" 4
717.el .Ip "\fBsetremotecos `` RemoteCos''\fR" 4
718.IX Item "setremotecos " RemoteCos"
719Set the remote \s-1COS\s0 to the value specified by
720\&\fBRemoteCos\fR.
721This \s-1COS\s0 will be used for further rfio funtions. It is used if the
722\&\fB setoption remoterfio\fR
723has been set and if the file is a \s-1HPSS\s0 file.
724A value of 0 allows to select the \s-1COS\s0 according to the file size.
725A negative value allows to not set the \s-1COS\s0.
726The default value is 0.
727.if n .Ip "\fBsetremoteumask """" RemoteUmask""""\fR" 4
728.el .Ip "\fBsetremoteumask `` RemoteUmask''\fR" 4
729.IX Item "setremoteumask " RemoteUmask"
730Set the remote umask to the value specified by
731\&\fBRemoteUmask\fR.
732This remote umask will be used for further i/o funtions. The
733\&\fBRemoteUmask\fR
734has to be given in
735\&\fB \s-1OCTAL\s0\fR
736.if n .Ip "\fBsetrecvwinsize """" WindowSize""""\fR" 4
737.el .Ip "\fBsetrecvwinsize `` WindowSize''\fR" 4
738.IX Item "setrecvwinsize " WindowSize"
739Set size in Kbytes of the receive \s-1TCP\s0 window of each stream of the
740\&\fB bbftpd\fR
741daemon. This also set the send window size of the client to the same value.
742.if n .Ip "\fBsetsendwinsize """" WindowSize""""\fR" 4
743.el .Ip "\fBsetsendwinsize `` WindowSize''\fR" 4
744.IX Item "setsendwinsize " WindowSize"
745Set size in Kbytes of the send \s-1TCP\s0 window of each stream of the
746\&\fB bbftpd\fR
747daemon. This also set the receive window size of the client to the same value.
748.if n .Ip "\fBsetackto """" Acknowledge time-out""""\fR Set time-out (in seconds) to wait for an acknowledge. Default value is 100" 4
749.el .Ip "\fBsetackto `` Acknowledge time-out''\fR Set time-out (in seconds) to wait for an acknowledge. Default value is 100" 4
750.IX Item "setackto " Acknowledge time-out Set time-out (in seconds) to wait for an acknowledge. Default value is 100"
751.PD 0
752.if n .Ip "\fBsetrecvcontrolto """" Input control time-out""""\fR" 4
753.el .Ip "\fBsetrecvcontrolto `` Input control time-out''\fR" 4
754.IX Item "setrecvcontrolto " Input control time-out"
755.PD
756Set time-out (in seconds) to wait while reading on the control socket. Default value is 180
757.if n .Ip "\fBsetsendcontrolto """" Output control time-out""""\fR" 4
758.el .Ip "\fBsetsendcontrolto `` Output control time-out''\fR" 4
759.IX Item "setsendcontrolto " Output control time-out"
760Set time-out (in seconds) to wait while writing on the control socket. Default value is 180
761.if n .Ip "\fBsetdatato """" Data time-out""""\fR" 4
762.el .Ip "\fBsetdatato `` Data time-out''\fR" 4
763.IX Item "setdatato " Data time-out"
764Set time-out (in seconds) to wait while reading on the data socket. Default value is 300
765.PP
766\&\fB\s-1NOTES\s0\fR
767If the option
768\&\fBtmpfile\fR
769is used then if the new file (
770\&\fBRemoteFile\fR
771for a put or
772\&\fBLocalFile\fR
773for a get)
774did not exist before, bbftp ensures that the file transfer was correct if the file exists.
775.PP
776In case of an already existing file, if the size, the last access and
777modification time are correct (if option
778\&\fB keepaccess\fR
779has been set) bbftp ensures that the file transfer was correct.
780.SH "TURL NOTATION"
781.IX Header "TURL NOTATION"
782The \s-1TURL\s0 notation can be used with commands relatives to files and directory.
783.PP
784If you use this notation, you should not specify the server name in command.
785.PP
786\&\s-1BBFTP\s0 support 3 types of \s-1TURL:\s0
787.Sh "Remote \s-1TURL\s0"
788.IX Subsection "Remote TURL"
789\&\fIbbftp://bbftp_servername/path_to_file_or_directory\fR
790.PP
791The path to file can be relative or absolute (start with '/')
792.PP
793For example:
794.if n .Ip """""mkdir bbftp://bbftp.domain/dir""""" 4
795.el .Ip "``mkdir bbftp://bbftp.domain/dir''" 4
796.IX Item ""mkdir bbftp://bbftp.domain/dir"
797is the command to create a directory
798\&\fBdir\fR
799on the remote bbftp server under the user's home directory
800.if n .Ip """""cd bbftp://bbftp.domain//tmp""""" 4
801.el .Ip "``cd bbftp://bbftp.domain//tmp''" 4
802.IX Item ""cd bbftp://bbftp.domain//tmp"
803is the command to change into
804\&\fB/tmp\fR
805on the remote bbftp server
806.Sh "Local \s-1TURL\s0"
807.IX Subsection "Local TURL"
808\&\fIfile://path_to_file\fR
809.PP
810The path to file can be relative or absolute (start with '/')
811.PP
812For example:
813.if n .Ip """""put file://file bbftp://bbftp.domain//tmp/file""""" 4
814.el .Ip "``put file://file bbftp://bbftp.domain//tmp/file''" 4
815.IX Item ""put file://file bbftp://bbftp.domain//tmp/file"
816is the command to transfer the file
817\&\fBfile\fR
818located on the local host server under the current directory to the remote host
819\&\fBbbftp.domain\fR
820under the
821\&\fB/tmp\fR
822directory
823.Sh "Local rfio \s-1TURL\s0"
824.IX Subsection "Local rfio TURL"
825\&\fIrfio://path_to_file\fR
826.PP
827The path to file can be relative or absolute (start with '/')
828.PP
829For example:
830.if n .Ip """""put rfio:///path/to/MSS/file bbftp://bbftp.domain//tmp/file""""" 4
831.el .Ip "``put rfio:///path/to/MSS/file bbftp://bbftp.domain//tmp/file''" 4
832.IX Item ""put rfio:///path/to/MSS/file bbftp://bbftp.domain//tmp/file"
833is the command to transfer a file retrived via the rfio path
834\&\fB/path/to/MSS/file\fR
835into the remote host
836\&\fBbbftp.domain\fR
837under the
838\&\fB/tmp\fR
839directory
840.PP
841When the 'rfio://' notation is used, the option 'localrfio' is no longer necessary.
842.Sh "Remote \s-1TURL\s0 with rfio"
843.IX Subsection "Remote TURL with rfio"
844It is possible to use rfio on the remote side using mixed \s-1TURL\s0 like:
845.PP
846\&\fIbbftp://bbftp_servername/rfio://path_to_rfio_file\fR
847.PP
848When the 'bbftp://bbftp_servername/rfio://' notation is used, the option 'remoterfio' is no longer necessary.
849.SH "RETURN VALUES"
850.IX Header "RETURN VALUES"
851The following exit values are returned:
852.if n .Ip """""0""""" 4
853.el .Ip "``0''" 4
854.IX Item ""0"
855if all commands were successfuly executed
856.if n .Ip """"">0""""" 4
857.el .Ip "``>0''" 4
858.IX Item "">0"
859if one command failed.
860.PP
861It may happend that a non-zero value is returned even if all files were
862correctly transfered, if during one transfer a retry was needed. This
863will be corrected in future releases.
864.SH "MESSAGES AND ERRORS"
865.IX Header "MESSAGES AND ERRORS"
866All informative messages are written to the standard ouput (or to the
867\&\fBOutputFile\fR
868).
869All error messages are written to the standard error (or to the
870\&\fBErrorFile\fR
871).
872.SH "WARNING"
873.IX Header "WARNING"
874The bbftp client version 2.0.0 is unable to talk with a daemon in release 1.x.x.
875.PP
876The rfioxxx or xxxrfio commands are no longer supported, use instead the
877options
878\&\fBlocalrfio\fR
879or
880\&\fBremoterfio\fR
881in conjunction with put and get commands to obtain the same result.
882.SH "RESULT FILE"
883.IX Header "RESULT FILE"
884If the
885\&\fB\-i\fR
886option was used a result file will be created in the same directory as the
887\&\fBControlFile\fR.
888Its name is ControlFile with the extension \*(L".res\*(R". It contains the
889same lines as the
890\&\fBControlFile\fR
891plus the keyword \*(L"\s-1OK\s0\*(R", in case of success, or \*(L"\s-1FAILED\s0\*(R", in case of failure.
892.PP
893If the
894\&\fB\-e\fR
895option was used and the
896\&\fB\-V\fR
897option was not used, the software will print the command executed plus the keyword \*(L"\s-1OK\s0\*(R",
898in case of success, or \*(L"\s-1FAILED\s0\*(R", in case of failure to standard output.
899.SH "CONNECTION EXAMPLES"
900.IX Header "CONNECTION EXAMPLES"
901\&\fBbbftp \-i ctrlfile \-u jon \-p 5 \-c cchost.in2p3.fr\fR
902.PP
903means that bbftp is going to connect to remote host cchost.in2p3.fr using username jon.
904If the connection is successful then the commands in ctrlfile will be executed. All transfer
905commands will use five streams and gzip compression.
906.PP
907\&\fBbbftp \-i ctrlfile \-u phg \-s cchost.in2p3.fr\fR
908.PP
909means that bbftp is going to start a remote bbftp via sshd on host cchost.in2p3.fr using username phg.
910ssh will first try an RSAAuthentication if it is allowed by cchost.in2p3.fr; otherwise
911ssh will ask for a password for user phg on cchost.in2p3.fr. Then the sshd on cchost.in2p3.fr
912will log user phg and try to start the command \*(L"bbftpd \-s\*(R"
913.PP
914\&\fBbbftp \-i ctrlfile \-u jon \-E '/tmp/bbftpd \-s' cchost.in2p3.fr\fR
915.PP
916Same behaviour as preceding, except that the remote command will be \*(L"/tmp/bbftpd \-s\*(R"
917.PP
918\&\fBbbftp \-i ctrlfile \-u gilles \-S cchost.in2p3.fr\fR
919.PP
920means that bbftp is going to start using ssh a remote bbftpd on host cchost.in2p3.fr using username gilles.
921ssh will try an RSAAuthentication if it is allowed by cchost.in2p3.fr, otherwise
922the connection will be broken.
923.PP
924\&\fBbbftp \-e 'setrecvwinsize 1024 ; put file1 file2'  \-u jon cchost.in2p3.fr\fR
925.PP
926means that bbftp is going to connect to remote host cchost.in2p3.fr using jon username.
927If the connection is successful then the commands
928\&\fBsetrecvwinsize 1024\fR
929and
930\&\fB put file1 file2\fR
931will be executed. All tranfer commands will use one stream.
932.PP
933\&\fBbbftp \-e 'put file1 file2' cchost.in2p3.fr\fR
934.PP
935means (in the certification authentication mode) that bbftp is going to connect to remote host cchost.in2p3.fr using a certificate.
936The remote user will be detected by the daemon which will check for the certificate provided and will accept or not the connection.
937.Sh "Using \s-1SSH\s0 to start a \s-1BBFTPD\s0 daemon linked with dynamic libraries"
938.IX Subsection "Using SSH to start a BBFTPD daemon linked with dynamic libraries"
939If you have linked the daemon with dynamic libraries with \-L/path/to/lib option, you need to specify
940this location in \f(CW$LD_LIBRARY_PATH\fR. To be taken into account by \s-1SSHD\s0, this environment variable must be modified
941in the
942\&\fB$HOME/.ssh/environment \fR
943file.
944.PP
945See your \s-1SSH\s0 or \s-1SSHD\s0 manual for more details.
946.SH "EXAMPLES"
947.IX Header "EXAMPLES"
948User jon want to transfer files from host localhost to remotehost on the
949account bbrdist. The bbrdist account has /home/babar/bbrdist as default
950directory on remotehost but has no subdirectories. We are going to study a control file in order
951to understand bbftp behaviour (we do not care here about the connection method; see
952\&\fB \s-1CONNECTION\s0 \s-1EXAMPLES\s0\fR
953for that).
954.PP
955User jon on the local host is on the /home/babar/jon directory and has the
956following control file (all lines have a number which must not exists but which are there just
957for clarity) :
958.PP
959\&\fB1\fR setnbstream 20
960.PP
961\&\fB2\fR setremoteumask 022
962.PP
963\&\fB3\fR setoption nocreatedir
964.PP
965\&\fB4\fR put /home/babar/jon/f1 /home/babar/bbrdist/newfiles/f1
966.PP
967\&\fB5\fR setoption createdir
968.PP
969\&\fB6\fR put /home/babar/jon/f1 /home/babar/bbrdist/newfiles/f1
970.PP
971\&\fB7\fR setnbstream 5
972.PP
973\&\fB8\fR setrecvwinsize 1024
974.PP
975\&\fB9\fR setoption gzip
976.PP
977\&\fB10\fR put /home/babar/jon/f2 /home/babar/bbrdist/newfiles/f2
978.PP
979Command 1 just sets the number of parallel streams to 20 for further get or put commands.
980.PP
981Command 2 sets the remote umask for further put commands.
982.PP
983Command 3 indicates that no directory has to be created on further put or get commands.
984.PP
985Command 4 tries to send the local file /home/babar/jon/f1 to /home/babar/bbrdist/newfiles/f1. This
986command will fail because bbrdist has no subdirectory and directory creation is inhibed.
987.PP
988Command 5 resets the createdir option.
989.PP
990Command 6 will be successful (if the connection does not break), because the creation of the
991directory /home/babar/bbrdist/newfiles has been authorized by the createdir option.
992.PP
993Command 7 reduces the number of streams to 5
994.PP
995Command 8 sets the receive \s-1TCP\s0 window size to 1024 Kbytes on remotehost and the
996send \s-1TCP\s0 window size to 1024 Kbytes on localhost.
997.PP
998Command 9 sets the gzip option for further get or put commands.
999.PP
1000Command 10 will transfer file /home/babar/jon/f2 to /home/babar/bbrdist/newfiles/f2
1001with 5 streams in compressed mode.
1002.SH "AUTHORS"
1003.IX Header "AUTHORS"
1004\&\fBbbftp\fR was developed by Gilles Farrache.
1005It is now maintained by Lionel Schwarz at
1006\&\fB \s-1IN2P3\s0 Computing Center\fR
1007, Villeurbanne (\s-1FRANCE\s0).
1008.SH "CONTRIBUTORS"
1009.IX Header "CONTRIBUTORS"
1010Tim Adye (Idea and implementation of ssh mode)
1011.PP
1012Gilles Gallot (Mutli-IP addresses support, secondary groups support, port on various systems and bug fixes)
1013.PP
1014Andrew Goodney (Port to Darwin)
1015.PP
1016Paola Grosso (Idea and implementation of the \-q client option)
1017.PP
1018Petr Holub (Port to Windows cygwin)
1019.PP
1020Dan Schrager (Idea and implementation of the \-D client option)
1021.PP
1022Rod Walker & Kostas Georgiou (Idea and implementation of the \-g client option)
1023.PP
1024Shuwei Ye (Bug fix)
1025.SH "BUGS"
1026.IX Header "BUGS"
1027Send bugs / comments to bbftp@in2p3.fr
1028.SH "SEE ALSO"
1029.IX Header "SEE ALSO"
1030\&\fIbbftpd\fR\|(1).
Note: See TracBrowser for help on using the repository browser.