318 lines
7.5 KiB
Groff
318 lines
7.5 KiB
Groff
.\" $Id: fetch.1,v 1.18 1997/07/25 19:35:41 wollman Exp $
|
|
.Dd July 2, 1996
|
|
.Dt FETCH 1
|
|
.Os FreeBSD 2.2
|
|
.Sh NAME
|
|
.Nm fetch
|
|
.Nd retrieve a file by Uniform Resource Locator
|
|
.Sh SYNOPSIS
|
|
.Nm fetch
|
|
.Op Fl MPabmnpqr
|
|
.Op Fl o Ar file
|
|
.Ar URL
|
|
.Op Ar ...
|
|
.Nm fetch
|
|
.Op Fl MPRmnpqr
|
|
.Op Fl o Ar file
|
|
.Op Fl c Ar dir
|
|
.Fl f Ar file
|
|
.Fl h Ar host
|
|
.Sh DESCRIPTION
|
|
.Nm fetch
|
|
allows a user to transfer files from a remote network site using
|
|
either the
|
|
.Tn FTP
|
|
or the
|
|
.Tn HTTP
|
|
protocol. In the first form of the command, the
|
|
.Ar URL
|
|
may be of the form
|
|
.Li http://site.domain/path/to/the/file
|
|
or
|
|
.Li ftp://site.domain/path/to/the/file.
|
|
To denote a local filename to be copied or linked to (see the
|
|
.Fl l
|
|
flag below), the
|
|
.Em file:/path/to/the/file
|
|
URL form is used.
|
|
.Pp
|
|
The second form of the command can be used to get a file using the
|
|
.Tn FTP
|
|
protocol, specifying the file name and the remote host with the
|
|
.Fl h
|
|
and the
|
|
.Fl f
|
|
flags.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width Fl
|
|
.It Fl a
|
|
Automatically retry the transfer upon soft failures.
|
|
.It Fl b
|
|
Work around a bug in some
|
|
.Tn HTTP
|
|
servers which fail to correctly implement the
|
|
.Tn TCP
|
|
protocol.
|
|
.It Fl c Ar dir
|
|
The file to retrieve is in directory
|
|
.Ar dir
|
|
on the remote host.
|
|
.It Fl f Ar file
|
|
The file to retrieve is named
|
|
.Ar file
|
|
on the remote host.
|
|
.It Fl h Ar host
|
|
The file to retrieve is located on the host
|
|
.Ar host .
|
|
.It Fl l
|
|
If target is a
|
|
.Ar file:/
|
|
style of URL, make a link to the target rather than trying
|
|
to copy it.
|
|
.It Fl M
|
|
.It Fl m
|
|
Mirror mode: Set the modification time of the file so that it is
|
|
identical to the modification time of the file at the remote host.
|
|
If the file already exists on the local host and is identical (as
|
|
gauged by size and modification time), no transfer is done.
|
|
.It Fl n
|
|
Don't preserve the modtime of the transfered file, use the current time.
|
|
.It Fl o Ar file
|
|
Set the output file name to
|
|
.Ar file .
|
|
By default, a ``pathname'' is extracted from the specified URI, and
|
|
its basename is used as the name of the output file. A
|
|
.Ar file
|
|
argument of
|
|
.Sq Li \&-
|
|
indicates that results are to be directed to the standard output.
|
|
.It Fl P
|
|
.It Fl p
|
|
Use the passive mode of the
|
|
.Tn FTP
|
|
protocol. This is useful for crossing certain sorts of firewalls.
|
|
.It Fl q
|
|
Quiet mode. Do not report transfer progress on the terminal.
|
|
.It Fl R
|
|
The filenames specified are ``precious'', and should not be deleted
|
|
under any circumstances, even if the transfer failed or was incomplete.
|
|
.It Fl r
|
|
Restart a previously interrupted transfer.
|
|
.It Fl t
|
|
Ensure that the use of T/TCP is not attempted for connections. This is
|
|
used to workaround bugs in some remote OS stacks that give improper
|
|
replies to T/TCP connections.
|
|
.It Fl T Ar seconds
|
|
Set timeout value to
|
|
.Ar seconds.
|
|
Overrides the environment variables
|
|
.Ev FTP_TIMEOUT
|
|
for ftp transfers or
|
|
.Ev HTTP_TIMEOUT
|
|
for http transfers if set.
|
|
.It Fl v
|
|
Increase verbosity. More
|
|
.Fl v Ns \&'s
|
|
result in more information.
|
|
.El
|
|
.Pp
|
|
Many options are also controlled solely by the environment (this is a
|
|
bug).
|
|
.Sh PROXY SERVERS
|
|
Many sites use application gateways (``proxy servers'') in their
|
|
firewalls in order to allow communication across the firewall using a
|
|
trusted protocol. The
|
|
.Nm fetch
|
|
program can use both the
|
|
.Tn FTP
|
|
and the
|
|
.Tn HTTP
|
|
protocol with a proxy server.
|
|
.Tn FTP
|
|
proxy servers can only relay
|
|
.Tn FTP
|
|
requests;
|
|
.Tn HTTP
|
|
proxy servers can relay both
|
|
.Tn FTP
|
|
and
|
|
.Tn HTTP
|
|
requests.
|
|
A proxy server can be configured by defining an environment variable
|
|
named
|
|
.Dq Va PROTO Ns Ev _PROXY ,
|
|
where
|
|
.Va PROTO
|
|
is the name of the protocol in upper case. The value of the
|
|
environment variable specifies a hostname, optionally followed by a
|
|
colon and a port number.
|
|
.Pp
|
|
The
|
|
.Tn FTP
|
|
proxy client passes the remote username, host and port as the
|
|
.Tn FTP
|
|
session's username, in the form
|
|
.Do Va remoteuser Ns Li \&@ Ns Va remotehost
|
|
.Op Li \^@ Ns Va port
|
|
.Dc .
|
|
The
|
|
.Tn HTTP
|
|
proxy client simply passes the originally-requested URI to the remote
|
|
server in an
|
|
.Tn HTTP
|
|
.Dq Li GET
|
|
request. HTTP proxy authentication is not yet implemented.
|
|
.Sh HTTP AUTHENTICATION
|
|
The
|
|
.Tn HTTP
|
|
protocol includes support for various methods of authentication.
|
|
Currently, the
|
|
.Dq basic
|
|
method, which provides no security from packet-sniffing or
|
|
man-in-the-middle attacks, is the only method supported in
|
|
.Nm fetch .
|
|
Authentication is enabled by the
|
|
.Ev HTTP_AUTH
|
|
and
|
|
.Ev HTTP_PROXY_AUTH
|
|
environment variables. Both variables have the same format, which
|
|
consists of space-separated list of parameter settings, where each
|
|
setting consists of a colon-separated list of parameters. The first
|
|
two parameters are always the (case-insensitive) authentication scheme
|
|
name and the realm in which authentication is to be performed. If the
|
|
realm is specified as
|
|
.Sq Li \&* ,
|
|
then it will match all realms not specified otherwise.
|
|
.Pp
|
|
For the
|
|
.Li basic
|
|
authentication scheme uses two additional optional parameters; the
|
|
first is a user name, and the second is the password associated with
|
|
it. If either the password or both parameters are not specified in
|
|
the environment, and the standard input of
|
|
.Nm
|
|
is connected to a terminal, then
|
|
.Nm
|
|
will prompt the user to enter the missing parameters. Thus, if the
|
|
user is known as
|
|
.Dq Li jane
|
|
in the
|
|
.Dq Li WallyWorld
|
|
realm, and has a password of
|
|
.Dq Li QghiLx79
|
|
there, then she might set her
|
|
.Ev HTTP_AUTH
|
|
variable to:
|
|
.Bl -enum -offset indent
|
|
.It
|
|
.Dq Li basic:WallyWorld:jane:QghiLx79
|
|
.It
|
|
.Dq Li basic:WallyWorld:jane ,
|
|
or
|
|
.It
|
|
.Dq Li basic:WallyWorld
|
|
.El
|
|
.Pp
|
|
and
|
|
.Nm
|
|
will prompt for the missing information if it is required. She might
|
|
also specify a realm of
|
|
.Dq Li \&*
|
|
instead of
|
|
.Dq Li WallyWorld
|
|
to indicate that the parameters can be applied to any realm. (This is
|
|
most commonly used in a construction such as
|
|
.Dq Li basic:* ,
|
|
which indicates to
|
|
.Nm
|
|
that it may offer to do
|
|
.Li basic
|
|
authentication for any realm.
|
|
.Sh ERRORS
|
|
The
|
|
.Nm
|
|
command returns zero on success, or a non-zero value from
|
|
.Aq Pa sysexits.h
|
|
on failure. If multiple URIs are given for retrieval,
|
|
.Nm
|
|
will attempt all of them and return zero only if all succeeded
|
|
(otherwise it will return the error from the last failure).
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width FTP_PASSIVE_MODE -offset indent
|
|
.It Ev FTP_TIMEOUT
|
|
maximum time, in seconds, to wait before aborting an
|
|
.Tn FTP
|
|
connection.
|
|
.It Ev FTP_LOGIN
|
|
the login name used for
|
|
.Tn FTP
|
|
transfers (default
|
|
.Dq Li anonymous )
|
|
.It Ev FTP_PASSIVE_MODE
|
|
force the use of passive mode FTP
|
|
.It Ev FTP_PASSWORD
|
|
the password used for
|
|
.Tn FTP
|
|
transfers (default
|
|
.Dq Va yourname Ns Li \&@ Ns Va yourhost )
|
|
.It Ev FTP_PROXY
|
|
the address (in the form
|
|
.Do Va hostname Ns
|
|
.Op Li : Ns Va port
|
|
.Dc )
|
|
of a proxy server which understands
|
|
.Tn FTP
|
|
.It Ev HTTP_AUTH
|
|
defines authentication parameters for
|
|
.Tn HTTP
|
|
.It Ev HTTP_PROXY
|
|
the address (in the form
|
|
.Do Va hostname Ns
|
|
.Op Li : Ns Va port
|
|
.Dc )
|
|
of a proxy server which understands
|
|
.Tn HTTP
|
|
.It Ev HTTP_PROXY_AUTH
|
|
defines authentication parameters for
|
|
.Tn HTTP
|
|
proxy servers
|
|
.It Ev HTTP_TIMEOUT
|
|
maximum time, in seconds, to wait before aborting an
|
|
.Tn HTTP
|
|
connection.
|
|
.Sh SEE ALSO
|
|
.Xr ftp 1 ,
|
|
.Xr tftp 1
|
|
.Sh HISTORY
|
|
The
|
|
.Nm fetch
|
|
command appeared in
|
|
.Fx 2.1.5 .
|
|
.Sh AUTHORS
|
|
The original implementation of
|
|
.Nm
|
|
was done by Jean-Marc Zucconi. It was extensively re-worked for
|
|
.Fx 2.2
|
|
by Garrett Wollman.
|
|
.Sh BUGS
|
|
There are too many environment variables and command-line options.
|
|
.Pp
|
|
The
|
|
.Fl a
|
|
option is only implemented for certain kinds of
|
|
.Tn HTTP
|
|
failures, and no
|
|
.Tn FTP
|
|
failures.
|
|
.Pp
|
|
Only the
|
|
.Dq basic
|
|
authentication mode is implemented for
|
|
.Tn HTTP .
|
|
This should be replaced by digest authentication.
|
|
.Pp
|
|
The
|
|
.Fl b
|
|
flag should not be necessary.
|