diff -r 000000000000 -r 1d0ce1ebbc72 ftp.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ftp.1 Tue Dec 06 13:51:55 2022 +0000 @@ -0,0 +1,411 @@ +.\" $OpenBSD: ftp.1,v 1.114 2019/05/15 11:53:22 kmos Exp $ +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 +.\" +.\" Copyright (c) 2015 Sunil Nimmagadda +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 13 2015 $ +.Dt FTP 1 +.Os +.Sh NAME +.Nm ftp +.Nd Internet file transfer program +.Sh SYNOPSIS +.Nm +.Op Fl 46AVv +.Op Fl N Ar name +.Op Fl D Ar title +.Op Ar host Op Ar port +.Nm +.Op Fl 46ACMmVv +.Op Fl N Ar name +.Op Fl D Ar title +.Op Fl o Ar output +.Op Fl S Ar tls_options +.Op Fl U Ar useragent +.Op Fl w Ar seconds +.Ar url ... +.Sh DESCRIPTION +.Nm +is the user interface to the Internet standard File Transfer +Protocol (FTP). +The program allows a user to transfer files to and from a +remote network site. +.Pp +The latter usage format will fetch a file using either the +FTP, HTTP or HTTPS protocols into the current directory. +This is ideal for scripts. +Refer to +.Sx AUTO-FETCHING FILES +below for more information. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 4 +Forces +.Nm +to use IPv4 addresses only. +.It Fl 6 +Forces +.Nm +to use IPv6 addreses only. +.It Fl A +Force active mode FTP. +By default, +.Nm +will try to use passive mode FTP and fall back to active mode +if passive is not supported by the server. +This option causes +.Nm +to always use an active connection. +It is only useful for connecting +to very old servers that do not implement passive mode properly. +.It Fl C +Continue a previously interrupted file transfer. +.Nm +will continue transferring from an offset equal to the length of file. +.Pp +Resuming HTTP(S) transfers are only supported if the remote server supports the +.Dq Range +header. +.It Fl D Ar title +Specify a short title for the start of the progress bar. +.It Fl M +Causes +.Nm +to never display the progress meter in cases where it would do so by default. +.It Fl N Ar name +Use this alternative name instead of +.Nm +in some error reports. +.It Fl m +Causes +.Nm +to display the progress meter in cases where it would not do so by default. +.It Fl o Ar output +When fetching a file or URL, save the contents in +.Ar output . +To make the contents go to stdout, use `-' for +.Ar output . +.It Fl S Ar tls_options +TLS options to use with HTTPS transfers. +The following settings are available: +.Bl -tag -width Ds +.It Cm cafile Ns = Ns Ar /path/to/cert.pem +PEM encoded file containing CA certificates used for certificate validation. +.It Cm capath Ns = Ns Ar /path/to/certs/ +Directory containing PEM encoded CA certificates used for certificate +validation. +.It Cm ciphers Ns = Ns Ar cipher_list +Specify the list of ciphers that will be used by +.Nm . +See the +.Xr openssl 1 +.Cm ciphers +subcommand. +.It Cm depth Ns = Ns Ar max_depth +Maximum depth of the certificate chain allowed when performing validation. +.It Cm dont +Don't perform server certificate validation. +.It Cm protocols Ns = Ns Ar string +Specify the TLS protocols to use. +If not specified the value +.Qq all +is used. +Refer to the +.Xr tls_config_parse_protocols 3 +function for other valid protocol string values. +.It Cm muststaple +Require the server to present a valid OCSP stapling in the TLS handshake. +.It Cm noverifytime +Disable validation of certificate times and OCSP validation. +.It Cm session Ns = Ns Ar /path/to/session +Specify a file to use for TLS session data. +If this file has a non-zero length, the session data will be read from this file +and the client will attempt to resume the TLS session with the server. +Upon completion of a successful TLS handshake this file will be updated with +new session data, if available. +This file will be created if it does not already exist. +.El +.Pp +By default, server certificate validation is performed, and if it fails +.Nm +will abort. +If no +.Cm cafile +or +.Cm capath +setting is provided, +.Pa /etc/ssl/cert.pem +will be used. +.It Fl U Ar useragent +Set +.Ar useragent +as the User-Agent for HTTP(S) URL requests. +If not specified, the default User-Agent is +.Dq OpenBSD ftp . +.It Fl V +Disable verbose mode. +.It Fl v +Enable verbose mode. +This is the default if input if from a terminal. +Forces +.Nm +to show all responses from the remote server, as well as report on data +transfer statistics. +.It Fl w Ar seconds +Abort a slow connection after +.Ar seconds . +.El +.Pp +The host with which +.Nm +is to communicate may be specified on the command line. +If this is done, +.Nm +will immediately attempt to establish a connection to an +FTP server on that host; otherwise, +.Nm +will enter its command interpreter and await instructions +from the user. +When +.Nm +is awaiting commands, the prompt +.Dq ftp\*(Gt +is provided to the user. +The following commands are recognized +by +.Nm : +.Bl -tag -width Ds +.It Ic open Ar host Op Ar port +Establish a connection to the specified +.Ar host +FTP server. +An optional port number may be supplied, +in which case +.Nm +will attempt to contact an FTP server at that port. +.It Ic close +Terminate the FTP session with the remote server and +return to the command interpreter. +.It Ic help Op Ar command +Print an informative message about the meaning of +.Ar command . +If no argument is given, +.Nm +prints a list of the known commands. +.It Ic \&? Op Ar command +A synonym for +.Ic help . +.It Ic quit +Terminate the FTP session with the remote server and exit +.Nm . +.It Ic exit +A synonym for +.Ic quit . +.It Ic ls Op Ar remote-directory Op Ar local-file +Print a listing of the contents of a directory on the remote machine. +The listing includes any system-dependent information that the server +chooses to include; for example, most +.Ux +systems will produce output from the command +.Ql ls -l . +If +.Ar remote-directory +is left unspecified, the current working directory is used. +If no local file is specified, or if +.Ar local-file +is +.Sq - , +the output is sent to the terminal. +.It Ic nlist Op Ar remote-directory Op Ar local-file +Print a list of the files in a +directory on the remote machine. +If +.Ar remote-directory +is left unspecified, the current working directory is used. +If no local file is specified, or if +.Ar local-file +is +.Sq - , +the output is sent to the terminal. +Note that on some servers, the +.Ic nlist +command will only return information on normal files (not directories +or special files). +.It Ic pwd +Print the name of the current working directory on the remote +machine. +.It Ic cd Ar remote-directory +Change the working directory on the remote machine +to +.Ar remote-directory . +.It Ic get Ar remote-file Op Ar local-file +Retrieve the +.Ar remote-file +and store it on the local machine. +If the local +file name is not specified, it is given the same +name it has on the remote machine. +.It Ic passive Op Ic on | off +Toggle passive mode. +If passive mode is turned on (default is on), +.Nm +will send a +.Dv EPSV +command for all data connections instead of the usual +.Dv EPRT +command. +The +.Dv EPSV +command requests that the remote server open a port for the data connection +and return the address of that port. +The remote server listens on that port and the client connects to it. +When using the more traditional +.Dv EPRT +command, the client listens on a port and sends that address to the remote +server, who connects back to it. +Passive mode is useful when using +.Nm +through a gateway router or host that controls the directionality of +traffic. +.It Ic lcd Op Ar local-directory +Change the working directory on the local machine. +If +no +.Ar local-directory +is specified, the user's home directory is used. +.It Ic lpwd +Print the working directory on the local machine. +.It Ic put Ar local-file Op Ar remote-file +Store a local file on the remote machine. +If +.Ar remote-file +is left unspecified, the local file name is used. +.It Ic mget Ar remote-files +Do a +.Ic get +for each file name specified. +.It Ic mput Ar local-files +Do a +.Ic put +for each file name specified. +.El +.Sh AUTO-FETCHING FILES +In addition to standard commands, this version of +.Nm +supports an auto-fetch feature. +To enable auto-fetch, simply pass the list of hostnames/files +on the command line. +.Pp +The following formats are valid syntax for an auto-fetch element: +.Bl -tag -width Ds +.Sm off +.It Xo ftp:// +.Ar host Op : Ar port +.No / Ar file +.Xc +.Sm on +An FTP URL, retrieved using the FTP protocol if +.Ev ftp_proxy +isn't defined. +Otherwise, transfer using HTTP via the proxy defined in +.Ev ftp_proxy . +.Sm off +.It Xo http:// +.Ar host Op : Ar port +.No / Ar file +.Xc +.Sm on +An HTTP URL, retrieved using the HTTP protocol. +If +.Ev http_proxy +is defined, it is used as a URL to an HTTP proxy server. +.Sm off +.It Xo https:// +.Ar host Op : Ar port +.No / Ar file +.Xc +.Sm on +An HTTPS URL, retrieved using the HTTPS protocol. +If +.Ev http_proxy +is defined, this HTTPS proxy server will be used to fetch the +file using the CONNECT method. +.It Pf file: Ar file +.Ar file +is retrieved from a mounted file system. +.El +.Sh ENVIRONMENT +.Nm +utilizes the following environment variables: +.Bl -tag -width Ds +.It Ev ftp_proxy +URL of FTP proxy to use when making FTP URL requests +(if not defined, use the standard FTP protocol). +.It Ev http_proxy +URL of HTTP proxy to use when making HTTP(S) URL requests. +.El +.Sh PORT ALLOCATION +For active mode data connections, +.Nm +will listen to a random high TCP port. +The interval of ports used are configurable using +.Xr sysctl 8 +variables +.Va net.inet.ip.porthifirst +and +.Va net.inet.ip.porthilast . +.Sh HISTORY +The +.Nm +command first appeard in +.Bx 4.2 . +A complete rewrite of the +.Nm +command first appeared in +.Ox x.x . +.Sh AUTHORS +.An Sunil Nimmagadda Aq Mt sunil@openbsd.org +.Sh CAVEATS +While aborting a data transfer, certain FTP servers violate +the protocol by not responding with a 426 reply first, thereby making +.Nm +wait indefinitely for a correct reply.