Go to the first, previous, next, last section, table of contents.

Using ange-ftp

Once you have ange-ftp installed, you never need worry about using FTP again. The interface is completely transparent, and you may now use Emacs commands such as C-x C-f (find-file) on any file that your local host (or, if you are using one) your gateway can access. That file may be a regular file (for editing, viewing etc.), a directory (for invoking Dired) or even a symbolic link (pointing to a directory or a regular file). All it takes is an extended filename syntax. For example, if you give the filename

/ange@anorman:/tmp/notes

to find-file, then ange-ftp will spawn an FTP process, connect to the host anorman as user ange, get the file `/tmp/notes' and pop up a buffer containing the contents of that file as if it were on the local filesystem. If ange-ftp needed a password to connect then it would prompt the user in the minibuffer. From then on you can edit that file as if it were any other file: saving is with C-x C-s as usual -- in fact, everything is as usual.

Ange-ftp is also extremely useful for regular "file-transfer" FTP jobs. Since Dired also works on remote directories when using ange-ftp, you will be able to browse the filesystem on your favourite archive site with consummate ease.

Remote filename syntax

The general form of the extended filename syntax is

/user@host:path

which refers to the file pointed to by path on machine host when logging in as user user. When path is supplied as a relative file-name (that is, without a leading `/') it is relative to user's home directory (although such relative filenames are ultimately converted to absolute ange-ftp pathnames). You may even refer to home directories of users on remote Unix sites using the standard tilde `~' notation. host needs to be the fully qualified pathname if the local or gateway machine requires it to be (however hostname completion is available if it is included in your `.netrc' -- See section Using a .netrc file), or it may be an IP number if your nameserver can't find the site. The user@ part may be omitted, in which case the username is chosen on the basis of the variable ange-ftp-default-user (See section Other user options) and your `.netrc'. If a password is requested by the FTP process, ange-ftp will either prompt you for it, or generate one on the basis of the variables ange-ftp-default-password, and your `.netrc'.

Thus the following are all valid ange-ftp filenames:

/anonymous@waldo.uranium.com:pub/games/wumpus
/root@127.44.3.1:/etc/passwd
/jbrown@freddie.ucla.edu:~mblack/
/alpha.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.Z

Using Dired

This feature of ange-ftp is particularly useful when file-transfers, as opposed to file-editing, are the order of the day. Simply run find-file on a directory to get a listing of the files in that directory. For example, you might run find-file on

/anonymous@archive.site.com:pub

to see what's in the `pub' directory of your favourite archive site. This brings up a Dired buffer of all the files in that directory. The f command is useful for looking at `README' files -- if you then decide to save it C-x C-w is useful. You can also use this method to copy files, but the c command is easier. The f command can also be used to descend the directory tree by applying it to directories.

You can also use Dired to refresh ange-ftp's internal cache. If you (or anybody else) has changed a remote directory since you first accessed it with ange-ftp, completion is not provided on any new files that ange-ftp does not know about. If you have (or create) a Dired buffer which contains the modified directory, executing revert-buffer with a prefix argument (C-u g in the Dired buffer) will force a refresh of both the the buffer and also ange-ftp's internal cache. If you find that filename completion isn't working on a file that you know is there, this is how to fix the problem.

The version of Dired supplied with Emacs version 18.58 (and earlier versions) does not include a capability for multiple file transfers. The Tree Dired package (See section How to get the ange-ftp source code), however, is ideal for this application. Tree Dired provides facilities for maintaining an entire directory tree in a Dired buffer, for marking files which match a certain regexp (or you can select files interactively) and then copying all those files to your local host (or even a different remote host). Another useful feature is Virtual Dired, which allows you to save Dired buffers of remote hosts, allowing you to browse them at a later date without actually needing to connect to the host. See the documentation for Tree Dired for more details.

Since ange-ftp is mostly transparent, modifying Dired or Tree Dired by means of hooks or keybindings should still work.

Using a .netrc file

Being prompted for passwords all the time can get rather annoying, but there is a way to fix the problem -- a `.netrc' (but See section Other user options and ange-ftp-netrc-filename if you want another filename) file in your home directory. Basically, this is a file (in the format of Unix netrc(5)) which contains the names of all the machines you regularly login to, as well as the username and password you use for that machine. You can also supply an account password, if required.

Your `.netrc' file consists of lines of the form

machine <machine-name> login <user-name> password <password>

It doesn't all have to be on the one line, though: any login or password commands in the file refer to the previous machine command. You can also have account <account-passwd> commands if you need special account passwords.

For example, you might have the following line in your `.netrc':

machine Y.local.lan.edu login myname password secret

Then if you run find-file on the file `/Y.local.lan.edu:somefile' you will automatically be logged in as user myname with password secret. You can still login under another name and password, if you so desire: just include the user@ part of the filename.

You may also include a default option, as follows:

default login <user-name> password <password>

which applies to any other machines not mentioned elsewhere in your `.netrc'. A particularly useful application of this is with anonymous logins:

default login myname password myname@myhost.edu

so that accessing `/anyhost:anyfile' will automatically log you in anonymously, provided the host is not mentioned in the `.netrc'. Note also that if the value of ange-ftp-default-user is non-nil, its value will have precedence over the username supplied in the default option of the `.netrc'.

The `.netrc' file is also useful in another regard: machines included in it are provided with hostname completion. That is, for any machine in the `.netrc', you need only type a slash and the first few characters of its name and then press TAB to be logged in automatically with a username and password from the `.netrc' file. So it's a good idea to put hosts you use regularly in your `.netrc' as well:

machine archive.site.com login anonymous password myname@X.local.lan.edu

Ange-ftp commands

Ange-ftp supplies a few interactive commands to make connecting with hosts a little easier.

Command ange-ftp-set-user: Prompts for a hostname and a username. Next time access to the host is attempted, ange-ftp will attempt to log in again with the new username.

Command ange-ftp-set-passwd: Prompts for a hostname, user and password. Future logins to that host as that user will use the given password.

Command ange-ftp-set-account: Prompts for a hostname, user and account. Future logins to that host as that user will use the given account.

Note that the effects of the above three commands only last the duration of the current Emacs session. To make their effects permanent, you may include them as lisp code in your `.emacs':

(ange-ftp-set-user HOST USER)
(ange-ftp-set-password HOST USER PASSWORD)
(ange-ftp-set-account HOST USER ACCOUNT)

This is an alternative to using a `.netrc'; See section Using a .netrc file.

Command ange-ftp-kill-ftp-process: kill the FTP process associated with a given buffer's filename (by default the current buffer). This is an easy way to achieve a resynch: any future accesses to the remote host will cause the FTP process to be recreated.

Descriptive directory listings

Some hosts (such as cs.uwp.edu) now use descriptive directory listings (which in fact contain less information than the standard listing!) when issued the ls command, and ange-ftp has been modified to cope with this. Ange-ftp can detect such listings, but if you regularly use a remote host which uses this extended listing format you should set the variable ange-ftp-dl-dir-regexp to a regular expression which matches directories using the extended listing format. You shouldn't anchor the regexp with `$' -- that way the regexp will match subdirectories as well. Alternatively, you can use the interactive command ange-ftp-add-dl-dir to temporarily add a remote directory for this Emacs session only.

Tree Dired has been modified to work with such descriptive listings.

Using ange-ftp with non-Unix hosts

Ange-ftp also works with some non-Unix hosts, although not necessarily with all the features available with Unix hosts. VMS, CMS, and MTS systems will all now work with ange-ftp and Tree Dired (although Classical Dired may well be broken on such systems.) Filename completion also now works on these hosts.

Ange-ftp should be able to automatically detect which type of host you are using (VMS, CMS or MTS), but if it is unable to do so you can fix the problem by setting the appropriate ange-ftp-TYPE-host-regexp variable (where TYPE is one of `vms', `cms' or `mts') -- see below. If ange-ftp is unable to automatically detect any VMS, CMS or MTS host, please report this as a bug: See section Bugs and Wish List.

In all cases the file-name conventions of the remote host are converted to a UNIX-ish format, and this is the format you should use to find files on such hosts.

VMS support

VMS filenames are of the form FILE.TYPE;##, where both FILE and TYPE can be up to 39 characters long, and ## is an integer version number between 1 and 32,767. Valid characters in filenames are `A'-`Z', `0'-`9', `_', `-' and `$', however `$' cannot begin a filename and `-' cannot be used as the first or last character.

Directories in VMS are converted to the standard UNIX `/' notation. For example, the VMS filename

PUB$:[ANONYMOUS.SDSCPUB.NEXT]README.TXT;1

would be entered as

/PUB$$:/ANONYMOUS/SDSCPUB/NEXT/README.TXT;1

(The double `$' is required to prevent Emacs from attempting to expand an environment variable.) Similarly, to anonymously FTP the file `[.CSV.POLICY]RULES.MEM;1' from ymir.claremont.edu you would type C-x C-f /anonymous@ymir.claremont.edu:CSV/POLICY/RULES.MEM;1. You can always drop off the `;##' part at the end of the filename to get the latest version.

Sandy Rutherford provides some tips for using VMS hosts:

Ange-ftp should automatically detect that you are using a VMS host. If it fails to do so (which should be reported as a bug) you can use the command ange-ftp-add-vms-host to inform ange-ftp manually. For a more permanent effect, or if you use a VMS host regularly, it's a good idea to set ange-ftp-vms-host-regexp to a regular expression matching that host's name. For instance, if use use ymir.claremont.edu a lot, place the following in your .emacs:

(setq ange-ftp-vms-host-regexp "^ymir.claremont.edu$")

CMS support

Ange-ftp has full support, including Tree Dired support, for hosts running CMS.

CMS filenames are entered in a UNIX-y way. Minidisks are treated as UNIX directories; for example to access the file `READ.ME' in minidisk `*.311' on `cuvmb.cc.columbia.edu', you would enter

/anonymous@cuvmb.cc.columbia.edu:/*.311/READ.ME

If `*.301' is the default minidisk for this account, you could access `FOO.BAR' on this minidisk as

/anonymous@cuvmb.cc.columbia.edu:FOO.BAR

CMS filenames are of the form `FILE.TYPE', where both `FILE' and `TYPE' can be up to 8 characters. Again, beware that CMS filenames are always upper case, and hence must be entered as such.

Sandy Rutherford provides some tips on using CMS hosts:

Ange-ftp should automatically detect that you are using a CMS host. If it fails to do so (which should be reported as a bug) you can use the command ange-ftp-add-cms-host to inform ange-ftp manually. For a more permanent effect, or if you use a CMS host regularly, it's a good idea to set ange-ftp-cms-host-regexp to a regular expression matching that host's name.

MTS support

Ange-ftp has full support, including Tree Dired support, for hosts running the Michigan terminal system, and should be able to automatically recognise any MTS machine.

MTS filenames are entered in a UNIX-y way. For example, if your account was `YYYY', the file `FILE' in the account `XXXX:' on `mtsg.ubc.ca' would be entered as

/YYYY@mtsg.ubc.ca:/XXXX:/FILE

In other words, MTS accounts are treated as UNIX directories. Of course, to access a file in another account, you must have access permission for it. If `FILE' were in your own account, then you could enter it in a relative path fashion as

/YYYY@mtsg.ubc.ca:FILE

MTS filenames can be up to 12 characters. Like UNIX, the structure of the filename does not contain a type (i.e. it can have as many `.''s as you like.) MTS filenames are always in upper case, and hence be sure to enter them as such! MTS is not case sensitive, but an EMACS running under UNIX is.

Ange-ftp should automatically detect that you are using an MTS host. If it fails to do so (which should be reported as a bug) you can use the command ange-ftp-add-mts-host to inform ange-ftp manually. For a more permanent effect, or if you use an MTS host regularly, it's a good idea to set ange-ftp-mts-host-regexp to a regular expression matching that host's name.

File- and host-name completion

Full filename completion is supported on all remote UNIX hosts and some non-Unix hosts. Hostnames also have completion if they are mentioned in the `.netrc' and no username is specified. However using the filename completion feature can be a bit of a two edged sword.

To understand why, we need to discuss how ange-ftp works. Whenever ange-ftp is asked to find a remote file (or directory) an ls command is sent to the FTP process to list all the files in the directory. This list is maintained in an internal cache, to provide filename completion for later requests on that directory. Ange-ftp keeps this cache up-to-date by monitoring Emacs commands which affect files and directories, but if a process outside Emacs (such as another user) changes a directory (e.g. a new file is added) completion won't work on that file since ange-ftp doesn't know about it yet. The solution if to force ange-ftp to reread the directory and update it's cache, and the easiest way to do that is with Dired -- See section Using Dired to see how.

Another problem is that the ls command can take a long time, especially when dealing with distant hosts over slow links. So if you're after a file in the `pub/images' directory but nothing else, it's a better idea to type pub/images/file TAB than pub/im TAB which will force a read of the `pub' directory (since ange-ftp needs to know how to complete im). A little extra typing can often save a lot of waiting. Don't be afraid to use the TAB key once the directory is cached, though.

Accessing the FTP process buffer

The FTP process used to access the remote files is available for access if you wish. It will be in a buffer called `"*ftp remote-file-name*"', i.e. if you found the file

/anonymous@archive.site.com:pub/README

there will be a buffer

*ftp anonymous@archive.site.com*

where all the transfers are taking place. You can have a look at the buffer using C-x b as usual, and even type in commands to the FTP process under an interface very much like `shell-mode'. There are two instances when doing this can be very useful: one is accessing non-UNIX hosts, where Dired and filename completion may not work (if ange-ftp even works at all). The other is multiple (i.e. wildcard) file transfers which the standard version of Dired does not handle (but Tree Dired does, and is worth installing for this feature alone.) If you are going to use mget or mput, make sure you type glob first: ange-ftp turns globbing off by default. Don't be afraid of changing directories, either -- ange-ftp always uses absolute pathnames when communicating with the FTP process.

You can kill the FTP process at any time simply by killing this buffer. This won't cause ange-ftp any grief whatsoever -- if you later make another request to that host, ange-ftp will simply fire up another process and create a new buffer to hold it.


Go to the first, previous, next, last section, table of contents.