<!doctype linuxdoc system>
  
<!-- This is the FTP HOWTO -->

<article>

<title>FTP mini-HOWTO

<author>Matthew Borowski <tt/(<htmlurl url="mailto:mkb@yahoo.com" name="mkb@yahoo.com"> )<newline> ( <htmlurl url="http://tarp.worldserve.net" name="http://tarp.worldserve.net/"> )/

<date>v0.2, 9 January 2000

<abstract>
How to use ftp clients and servers
</abstract>

<toc>

<!-- Begin of document -->

<sect>Preamble

<p>This document was written by Matthew Borowski for the Linux Documentation
Project. I have not yet finished adding everything I want to add. There will
be a section with information on operating an FTP server.

<sect1>Contacting Me

<p>Please contact me if you have any additions or changes for this document.
Please do not ask for technical support -- you may purchase Unix consulting
and support through my company, <bf/<htmlurl url="http://www.worldserve.net"
name="WorldServe">/, or you can ask for help on newsgroups such as
<bf/comp.os.linux.*/. Please also keep in mind that I can only understand English and Farsi.

<sect1>Legalities and Distribution

<p>This document is Copyright 1999 by Matthew Borowski. You may freely
distribute this document as long as the copyright notice remains unaltered.
If you distribute this HOWTO as part of a commercial product, I would like
to recieve a copy, but this is not required. If you wish to distribute a
modified or translated version of this document, please contact me first for
permission.

<sect1>History of this document

<p>
<itemize>
<item>991203: FTP HOWTO first written. Still a work-in-progress.
</itemize>

<sect>About FTP

<p>FTP (File Transfer Protocol) is a client/server protocol that allows a
user to transfer files to and from a remote network site. It works with TCP
and is most commonly used on the Internet, although it can also be used on a
LAN.

<p>An FTP site is a computer that is running FTP server software (also known
an FTP daemon, or <tt>ftpd</tt>). A public ftp site can usually be accessed
by anybody by logging in as <tt>anonymous</tt> or <tt>ftp</tt>. There are
many excellent public ftp sites that make repositories of free Unix software
available. By learning how to use FTP, you give yourself access to an
indespensible resource.

<p>Private FTP sites require a user name or password. If you have a shell
account with your ISP, you may be able to access your files via FTP (contact
your system administrator to check on this).

<p>An FTP client is the userland application that provides access to FTP
servers. There are many FTP clients available. Some are graphical, and some
are text-based. 

<p>FTP was first developed by the University of California, Berkeley for
inclusion in 4.2BSD (Berkeley Unix). The RFC (Request for Comments) is
available at <htmlurl url="ftp://nic.merit.edu/documents/rfc/rfc0959.txt">.

<sect>Beginner's guide to using ftp

<p><bf/A quick guide to using ftp./

<p>The standard ftp program is the original ftp client. It comes standard with
most Linux distributions. It first appeared in 4.2BSD, which was developed
by the University of California, Berkeley. 

<sect1>Running the <tt>ftp</tt> program
<p>It's easy to use ftp. Let's say you want to connect to the anonymous ftp
site metalab.unc.edu, to download the latest Linux kernel source.

<p>At the command line, type:

<tscreen><verb>
$ ftp metalab.unc.edu
</verb></tscreen>

<p>The ftp program will attempt to connect to metalab.unc.edu. Another way
to do this is to run <tt>ftp</tt> from the command line with no parameters, and use
the <tt>open</tt> command, with the site name as an argument:

<tscreen><verb>
$ ftp
ftp> open metalab.unc.edu
</verb></tscreen>

<sect1>Logging into an FTP server

<p>When you connect to an FTP site, it will ask you for a login (pressing enter
will log in as your local user name, in this case, <tt>foo</tt>: We log in as <tt>anonymous</tt> or <tt>ftp</tt>, to get to the public archive.


<tscreen><verb>
220 helios.oit.unc.edu FTP server (Version wu-2.6.0(2) Wed Nov 17 14:44:12
EST 1999) ready.
Name (metalab.unc.edu:foo): 
</verb></tscreen>


<p>
Now, we enter a complete e-mail address as the password (this is what most
public FTP sites request).
 
<tscreen><verb>
331 Guest login ok, send your complete e-mail address as password.
Password:
</verb></tscreen>

<p>
After a successful login, the following information is given to us:

<tscreen><verb>
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> 
</verb></tscreen>

<sect1>File transfer types

<p>After you log in to an ftp site, <tt>ftp</tt> will print out the file
transfer type. In our case, it is binary. Binary mode transfers the files,
bit by bit, as they are on the FTP server. Ascii mode, however, will download
the text directly. You can type <tt>ascii</tt> or <tt>binary</tt> to switch
between the types.

<p>You want to download the kernel source, so you leave the file transfer type
at binary. The binary type is also what you would use for any non-text files
-- such as graphic images, zip/gzip archives, executable programs, etc. If
in doubt, use binary mode.


<sect1>Navigating and listing directories
<p>You do an <tt>ls</tt> to see a list of the files. The <tt>ls</tt> command on ftp servers is
executed on the remote server, so the command line options that you can use
with it vary from server to server. The most common options are generally
available, check the manpage for <tt>ls</tt> for details.

<tscreen><verb>
ftp> ls
200 PORT command successful.
150 Opening ASCII mode data connection for /bin/ls.
total 33590
-r--r--r--   1 root     other    34348506 Dec 03 03:53 IAFA-LISTINGS
lrwxrwxrwx   1 root     other           7 Jul 15  1997 README -> WELCOME
-rw-r--r--   1 root     other         890 Nov 15 13:11 WELCOME
dr-xr-xr-x   2 root     other         512 Jul 15  1997 bin
dr-xr-xr-x   2 root     other         512 Jul 15  1997 dev
dr-xr-xr-x   2 root     other         512 Jul 18  1997 etc
drwxrwxrwx  11 ftp      20           4608 Nov 28 16:00 incoming
lrwxrwxrwx   1 root     other          13 Jun 04  1998 ls-lR -> IAFA-LISTINGS
dr-xr-xr-x  17 root     root          512 Jun 08 11:43 pub
dr-xr-xr-x   3 root     other         512 Jul 15  1997 unc
dr-xr-xr-x   5 root     other         512 Jul 15  1997 usr
226 Transfer complete.
</verb></tscreen>

<p>If the <tt>ls</tt> command lists so many files that they scroll off the top of the
screen, you can use Shift-PageUp to scroll up. This works in Linux console
mode as well as in xterm or rxvt.

<p>On public FTP archives, the downloadable resources are usually held in the
<tt>/pub</tt> directory. In this example, you already know that the kernel sources
are in the directory <tt>/pub/Linux/kernel</tt>, so you type the following to get
into that directory:

<tscreen><verb>
ftp> cd pub/Linux/kernel
250-README for kernel
250-
250-What you'll find here: kernel sources and patches
250-
250-
250 CWD command successful.
</verb></tscreen>

<p>The messages you see, which begin with "250", are information messages sent
by the server. In this case, the ftp server is configured to automatically
send you the README file when you cd into the directory.

<sect1>Downloading and uploading files

<p>Now, after doing another <tt>ls</tt>, you see that you want to <tt>cd</tt> into the v2.2
directory. You do yet another <tt>ls</tt>, and find the file you want to download. It
is <tt>linux-2.2.13.tar.gz</tt>. So you type this:

<tscreen><verb>
ftp> get linux-2.2.13.tar.gz
local: linux-2.2.13.tar.gz remote: linux-2.2.13.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for linux-2.2.13.tar.gz (15079540
bytes).
</verb></tscreen>

<p>The ftp program has started saving the remote file
<tt>linux-2.2.13.tar.gz</tt> as the local file <tt>linux-2.2.13.tar.gz</tt>.

<p>If you wanted to save it as the local file <tt>foo.tar.gz</tt>, you could have
specified it like this:

<tscreen><verb>
ftp> get linux-2.2.13.tar.gz foo.tar.gz
local: foo.tar.gz remote: linux-2.2.13.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for linux-2.2.13.tar.gz (15079540
bytes).
</verb></tscreen>

<p>If you want to download more than one file at a time, you'll have to use the
<tt>mget</tt> (multiple get) command. You can use <tt>mget</tt> together with a
space-delimited list of filenames you want to download, or you can use wildcards
with the <tt>mget</tt> command. For example:

<tscreen><verb>
ftp> mget linux*
</verb></tscreen>

<p>Would get all files starting with the string "linux". Normally,
<tt>mget</tt> will prompt you for each file before it downloads it. You can
toggle this by using the <tt>prompt</tt> command.

<p>Now let's say you've written a piece of software, and you want to upload it
to MetaLab to be included in their Linux software archive. First, you'd
change to the /incoming directory (most public FTP servers have a directory,
usually called incoming or uploads, where files can be uploaded), then you'd
use the put command:

<tscreen><verb>
ftp> cd /incoming
ftp> put foo.tar.gz
local: foo.tar.gz remote: foo.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for foo.tar.gz.
226 Transfer complete.
10257 bytes sent in 0.00316 secs (3.2e+03 Kbytes/sec)
</verb></tscreen>

<p>The <tt>put</tt> command works the same way as the <tt>get</tt> command,
so you can use <tt>mput</tt> to upload multiple files at the same time. You
can also upload a local file with a different filename on the server by
specifying the remote filename and/or pathname as an argument.

<p>What if the file <tt>foo.tar.gz</tt> is not in your current local directory when you
try to upload it? You can switch local directories by using the <tt>lcd</tt> (local
change directory) command:

<tscreen><verb>
ftp> lcd /home/foo/
Local directory now /home/foo
</verb></tscreen>

<sect1>Running shell commands

<p>The ftp client supports using the bang (!) to run local commands. For
example, to get a listing of files in your current local directory, do this:

<tscreen><verb>
ftp> !ls
</verb></tscreen>

<p>The way this works is that ftp calls the shell (specified in the
<tt>$SHELL</tt> environment variable), and it is the shell which runs
<tt>ls</tt>. Thus, you can run any command-line which works with your shell
simply by prepending "!" to it (the default shell in most Linux
distributions is bash, the Bourne Again SHell). Please note that <tt>!cd</tt> does
not work as you would expect, this is why the <tt>lcd</tt> command exists.

<sect1>Hash marks and tick

<p>Wouldn't it be nice if you could watch the progress while you're
downloading a file with ftp? You can use the hash command to print out hash
marks as you download a file:

<tscreen><verb>
ftp> hash
Hash mark printing on (1024 bytes/hash mark).
</verb></tscreen>

<p>As you can tell, ftp will print a hash mark for every 1024 bytes of data
you download.

<p>There is also a <tt>tick</tt> option.

<tscreen><verb>
ftp> tick           
Tick counter printing on (10240 bytes/tick increment).

This will print something to this effect as you download a file:

Bytes transferred: 11680
</verb></tscreen>


<sect1>Other ftp commands

<p>There are many other ftp commands. If you have the permissions to do so
(which you should, if you are connected to your own private shell account),
you can make a directory on the remote server using the <tt>mkdir</tt> command. You
can remove a file on the remote server using the <tt>delete</tt> command, or
<tt>rmdir</tt> to remove a directory. You can also change file permissions
using the <tt>chmod</tt> command. 

<p>For more elaborate information on using ftp, please see the online help in
the ftp program (accessible by typing help with no arguments for a list of
commands, or help &lt;commandname&gt; for specific help on a command). You can
also read the Unix man page for ftp by typing <tt>man ftp</tt> at your
command prompt.

<sect>Console FTP clients

<p>The original ftp program was the original ftp client, and it is a good
investment to learn it. It's the only ftp client that you can be certain is
available on most systems (even Win32 comes with the ftp command, albeit an
archaic, braindead version of it).

<p>There are many other console-mode (text-only) ftp clients available. The
listing here is by no means comprehensive, but includes the most popular
ones. Search at <htmlurl url="http://www.freshmeat.net" name="FreshMeat"> to find more.


<sect1>NcFTP

<p>NcFTP is the all-time favorite ftp client of many Unix users. It comes
bundled with most Linux distributions, and offers many advanced features
such as tab completion and bookmarks. Version 2 of NcFTP had a curses based
full-screen mode. This was done away with in Version 3 (now in beta). 

<p>It's not 100% compatible with the commands that standard ftp uses. For
example, get and put in NcFTP act like mget and mput do in standard ftp. So
if you want to save a remote file as a different local filename, you'd have
to do get -z remotename localname. Thankfully, NcFTP has a nice online help
system to assist you in learning the commands. 

<p>You can get the latest version of NcFTP at <htmlurl url="http://www.ncftp.com">.

<sect1>lukemftp

<p>A port of the NetBSD FTP client to other systems, lukemftp derives its name
from the author of most of the enhanced features, which include:
command-line editing, command-line fetches of FTP and HTTP URLs (including
via proxies), context-sensitive word completion, dynamic progress bar, IPv6
support, modification time preservation, paging of local and remote files,
passive mode support (with fallback to active mode), SOCKS support, TIS FWTK
gate-ftp server support, and transfer rate throttling.

<p>I highly recommend lukemftp to users who don't want to change to anything
drastically different from the standard ftp client, but want more advanced
features.

<p>You can get the latest version of lukemftp at <htmlurl url="ftp://ftp.netbsd.org/pub/NetBSD/misc/lukemftp/">.

<sect1>lftp

<p>lftp is a sophisticated command line based FTP client. Like bash, it has job
control. It uses the GNU readline library for input, so you have command
line completion and editing. lftp also has bookmarks, mirroring support, and
can transfer several files in parellel.

<p>You can get the latest version of lftp at <htmlurl url="http://ftp.yars.free.net/projects/lftp/">.

<p>Debian packages are available at <htmlurl url="ftp://ftp.freshmeat.net/pub/debs/lftp/">.

<sect1>cftp

<p>Comfortable FTP (cftp) is a full screen mode client. What it lacks in
features, it makes up for in ease of use. You browse through the directories
using the arrow keys and enter.

<p>You should be able to get the latest version of cftp at <htmlurl url="http://ftp.giga.or.at/pub/nih/cftp/">.

<sect1>yafc

<p>Yafc is a very nice ftp client, with features including directory cache,
remote filename completion, aliases, colorized ls, recursive get/put/ls/rm,
nohup mode transfers, tagging (queueing), multiple connections, proxy
support and more. It has support for Kerberos4 authentication.

<p>You can get the latest version of yafc from <htmlurl url="http://www.stacken.kth.se/~mhe/yafc/">.

<p>Debian packages are available at <htmlurl url="http://members.home.com/decklin/experimental/">.

<p>Redhat packages are available at <htmlurl url="http://lz.freeservers.com/linux/yafc.html">.


<sect>X Window FTP clients

<p>There are several graphical FTP clients designed to run on the X Window
system. These clients offer ease of use for users who are used to graphical
environments, and sometimes offer versatile options that would be hard to
implement in a text-based ftp client.

<sect1>gFTP

<p>gFTP is an FTP client for X Windows written using Gtk. The interface has
some similarities to the popular WS_FTP software commonly used on a certain
unstable operating system. 

<p>gFTP features simultaneous downloads, resuming of interrupted file transfers,
file transfer queues, downloading of entire directories, ftp proxy support,
remote directory caching, passive and non-passive file transfers,
drag-n-drop support, a very nice connection manager and more.

<p>If you are running Red Hat Linux and have the GNOME desktop installed, then
you probably already have gFTP. If not, you can download gFTP from its
homepage at <htmlurl url="http://gftp.seul.org/">.

<sect1>WXftp

<p>WXftp is an FTP client for the X Window System designed to be used mainly on
Linux workstations. It is written using the WXWindows toolkit, so it
can be compiled to use either Motif or GTK+

<p>It includes an intuitive user interface (much like WS_FTP), a session
manager, on-line help, a progress bar, and more

<p>Check out WXftp's homepage at <htmlurl url="http://www.wxftp.seul.org">.

<sect1>LLNL XDIR and XFTP

<p>LLNL XFTP was one of the first graphical FTP clients for Linux. It supports
FXP (file transfer between two remote hosts), and has a Motif based
interface.

<p>More information is available at <htmlurl url="http://www.llnl.gov/ia/xdir_xftp/">.

<sect1>guiftp

<p>Guiftp is a simple ftp client written with the GTK+ toolkit. It's good if
you don't need many features and want a simple, clean look.

<p>Guiftp's homepage is at <htmlurl url="http://www.altern.org/ldufresne/guiftp/">.


<sect>FTP Servers

<sect1>How an FTP Server works

<p>
A traditional FTP server is executed from inetd (the internet superserver
daemon). The standard FTP port is port 21. When a user tries to log in, the
FTP server uses a standard system call to check the user name and password
against the entries in the system password file, or the NIS tables if you
are using NIS. If the login is correct, the user is given access to the
system.

<p>
Anonymous FTP works differently. The user logs in with either the anonymous
or the ftp username (this can be defined in the config file). He is then
given access to a directory tree that has been chroot()'ed. This ensures
that the user can not gain access to directory trees he is not authorized
for. The chrooted directory tree usually contains a mock filesystem, with
bin/, etc/, and lib/ directories. The files for download are usually put in
the pub/ directory.

<p>
The reason for a mock filesystem in an anonymous FTP tree is that the FTP
daemon runs external commands for ls requests. You can also place additional
programs in the bin directory, and a user can run them with the SITE command
in his ftp client. For example, Red Hat's FTP includes the RPM command (for
users to query RPM packages on the site).

<p>
Some FTP servers work differently. For example, some will allow user
accounts to be set up independant of the system-wide password file (FTP-only
accounts). Some servers (ProFTPD and NcFTPd for instance) have built-in ls commands and
do not need a special directory tree within the chroot structure. Other ftp
servers stray altogether from the standard ftp concept. FTP4ALL, for
example, does not use system passwords at all. It uses it's own user and
group file, and has features such as upload/download ratio and customizable
server messages.

<sect1>Help with FTP Servers

<sect2>WU-FTPD

<p>WU-FTPD is the ftp daemon included with many Linux distributions,
including Red Hat and Caldera. You can learn more about WU-FTPD at <htmlurl
url="http://www.wu-ftpd.org">.

<p>
The WU-FTPD FAQ can be found on the web at <htmlurl
url="http://www.cetis.hvu.nl/~koos/wu-ftpd-faq.html">.

<sect2>ProFTPD

<p>ProFTPD is a powerful FTP server that includes Apache-style
configuration, extensive support for virtual hosts, and internal ls.

<p>A complete command reference and downloads can be found at <htmlurl
url="http://www.proftpd.org">

</article>
