2. Installing EFS

There are a few customisations after installation you might need to make. The ideal configuration is to have the FTP process running on the same machine as you are running Emacs on, but this is not always possible since some machines cannot access hosts outside the local network. In this case, the FTP process needs to be run on a machine which does have access to the local world -- this is called the gateway host. EFS has facilities to make use of a gateway host when accessing remote hosts.

2.1 How to get the EFS source code

The latest separately distributed version of EFS should always be available from Mike Sperber's home page at

http://www-pu.informatik.uni-tuebingen.de/users/sperber/software/efs/

There are also some ftp locations:

Switzerland

/anonymous@itp.ethz.ch:/sandy/efs/

Massachusetts, USA

/anonymous@alpha.gnu.ai.mit.edu:/efs/

California, USA

/anonymous@ftp.hmc.edu:/pub/emacs/packages/efs/

Failing these, someone on the EFS mailing list (see See section 4. Getting help.) may be able to help you find the latest version.

2.2 Installing the source

For byte-compiling the EFS package, you should follow the instructions at the top of the `INSTALL'. If you have any problems, please let us know so that we can fix them for other users. Don't even consider using EFS without byte compiling it. It will be far too slow.

If you decide to byte compile efs by hand, it is important that the file `efs-defun.el' be byte compiled first, followed by `efs.el'. The other files may be byte compiled in any order.

To use EFS, simply put the byte compiled files in your load path and add

(require 'efs)

in your `.emacs' file. Note this takes awhile, and some users have found this to be unbearably slow. Therefore ...

If you would like efs to be autoloaded when you attempt to access a remote file, put

(require 'efs-auto)

in your `.emacs' file. Note that there are some limitations associated with autoloading EFS. A discussion of them is given at the top of `efs-auto.el'.

Note that, in XEmacs, EFS automatically loads `efs-auto' when the user accesses a remote file. Therefore, no additional require statements should be necessary to use EFS. Just fire away ...

The above instructions should allow you to access all hosts that your local machine can access. If your local host has limited access, however, you may wish to have EFS working through a gateway machine. If so, read on. Otherwise, to get started using EFS, see See section 3. Using EFS.

2.3 Customizing EFS

There are many customization options for EFS, and only a few of them need to be touched in any specific setup. All options are available through the Custom package, see @xref{(Custom)Top}. EFS provides access through the customization group efs.

2.4 Using a gateway

Sometimes it is necessary for the FTP process to be run on a different machine than the machine running Emacs. This can happen when the local machine has restrictions on what hosts it can access.

Suppose you are running Emacs (and EFS, of course) on a machine X (let's call it the `local host') and you want to access a file on a machine Z (which we will call the `remote host'). Unfortunately, X does not have FTP access to Z: when you try a manual FTP something like the following happens:

X$ ftp Z.foo.bar.com
ftp: connect: Host is unreachable

2.5 Setting up a gateway

1. Set the variable efs-gateway-host to the name of your ftp gateway machine if your net world is divided into two domains according to efs-local-ftp-host-regexp. If you need to use a nonstandard port to access this host for gateway use, then specify efs-gateway-host as <hostname>#<port>.

2. Set the variable efs-ftp-local-host-regexp to a regular expression that matches the names of hosts which can be reached using ftp, without requiring any explicit connection to a gateway. If you have a smart ftp client which is able to transparently go through a gateway, this will differ from efs-local-host-regexp.

   For example:

   "\\.hp\\.com$\\|^[^.]*$"

   will match all hosts that are in the .hp.com domain, or don't have an explicit domain in their name, but will fail to match hosts with explicit domains or that are specified by their ip address.

3. Set the variable efs-local-host-regexp to machines that you have direct TCP/IP access. In other words, you must be able to ping these hosts. Even if the host is accessible by a very transparent FTP gateway, it does not qualify as a local host. The test to determine if machine A is local to your machine is if it is possible to ftp from `A' back to your local machine. Also, open-network-stream must be able to reach the host in question.

4. Set the variable efs-gateway-tmp-name-template to the name of a directory plus an identifying filename prefix for making temporary files on the gateway. For example: "/tmp/hplose/ange/efs"

5. If the gateway and the local host share cross-mounted directories, set the value of efs-gateway-mounted-dirs-alist accordingly. It is particularly useful, but not mandatory, that the directory of efs-gateway-tmp-name-template be cross-mounted.

6. Set the variable efs-gateway-type to the type gateway that you have. This variable is a list, the first element of which is a symbol denoting the type of gateway. The following arguments give data on how to use the gateway; it depends on the gateway types--see See section 2.6 Supported gateway types.

2.6 Supported gateway types

`local'

This means that your local host is itself the gateway. However, it is necessary to use a different FTP client to gain access to the outside world. If the name of the FTP client were xftp, you might set efs-gateway-type to

(list 'local "xftp" efs-ftp-program-args)

If xftp required special arguments, then give them in place of efs-ftp-program-args.

`proxy'

This indicates that your gateway works by first FTP'ing to it, and then issuing a USER command of the form

USER <username>@<host>

In this case, you might set efs-gateway-type to

(list 'proxy "ftp" efs-ftp-program-args)

If you need to use a nonstandard client, such as iftp, give this instead of ftp. If this client needs to take special arguments, give them instead of efs-ftp-program-args.

`remsh'

For this type of gateway, you need to start a remote shell on your gateway, using either remsh or rsh. You should set EFS-GATEWAY-TYPE to something like

(list 'remsh "remsh" nil "ftp" efs-ftp-program-args)

If you use rsh instead of remsh, change the second element from "remsh" to "rsh". Note that the symbol indicating the gateway type should still be 'remsh. If you want to pass arguments to the remsh program, give them as the third element. For example, if you need to specify a user, make this (list "-l" "sandy"). If you need to use a nonstandard FTP client, specify that as the fourth element. If your FTP client needs to be given special arguments, give them instead of efs-ftp-program-args.

`interactive'

This indicates that you need to establish a login on the gateway, using either telnet or rlogin. You should set efs-gateway-type to something like

(list 'interactive "rlogin" nil "exec ftp" efs-ftp-program-args)

If you need to use telnet, then give "telnet" in place of the second element "rlogin". If your login program needs to be given arguments, then they should be given in the third slot. The fourth element is for the name of the FTP client program. Giving this as "exec ftp", instead of "ftp", ensures that you are logged out if the FTP client dies. If the FTP client takes special arguments, give these instead of efs-ftp-program-args. Furthermore, you should see the documentation at the top of `efs-gwp.el'. You may need to set the variables efs-gwp-setup-term-command, and efs-gwp-prompt-pattern.

`raptor'

This is a type of gateway where EFS is expected to specify a gateway user, and send a password for this user using the ACCOUNT command. For example, to log in to `foobar.edu' as sandy, while using the account ange on the gateway, the following commands would be sent:

open raptorgate.com quote USER sandy@foobar.edu ange quote pass <sandy's password on foobar> quote account <ange's password on raptorgate>

For such a gateway, you would set efs-gateway-type to

(list 'raptor efs-ftp-program efs-ftp-program-args <GATEWAY USER>)

where <GATEWAY USER> is the name of your account on the gateway. In the above example, this would be "ange". You can set your gateway password by simply setting an account password for the gateway host. This can be done with either efs-set-account, or within your .netrc file. If no password is set, you will be prompted for one.

`sidewinder'

This is for the Sidewinder proxy: EFS ftp's to the proxy, and then gives a USER command of the form USER <username>@<host>. This connects to <host>. Then EFS sends another USER command USER <user>.

For such a gateway, you would set efs-gateway-type to

(list 'sidewinder efs-ftp-program efs-ftp-program-args)

`interlock'

This is a type of gateway where you are expected to send a PASS command after opening the connection to the gateway. The precise login sequence is

open interlockgate quote PASS <sandy's password on interlockgate> quote USER sandy@foobar.edu quote PASS <sandy's password on foobar.edu>

For such a gateway, you should set efs-gateway-type to

(list 'interlock efs-ftp-program efs-ftp-program-args)

If you need to use a nonstandard name for your FTP client, then replace efs-ftp-program with this name. If your FTP client needs to take nonstandard arguments, then replace efs-ftp-program-args with these arguments.

If your gateway returns both a 220 code and a 331 code to the "open interlockgate" command, then you should add a regular expression to efs-skip-msgs that matches the 220 response. Returning two response codes to a single FTP command is not permitted in RFC 959. It is not possible for efs to ignore the 220 by default, because than it would hang for interlock installations which do not require a password.

`kerberos'

With this gateway, you need to authenticate yourself by getting a kerberos "ticket" first. Usually, this is done with the kinit program. Once authenticated, you connect to `foobar.com' as user sandy with the sequence: (Note that the "-n" argument inhibits automatic login. Although, in manual use you probably don't use it, EFS always uses it.)

iftp -n open foobar.com user sandy@foobar.com

You should set efs-gateway-type to something like

(list 'kerberos "iftp" efs-ftp-program-args "kinit" <KINIT-ARGS>)

If you use an FTP client other than iftp, insert its name instead of "iftp" above. If your FTP client needs special arguments, give them as a list of strings in place of efs-ftp-program-args. If the program that you use to collect a ticket in not called "kinit", then give its name in place of "kinit" above. <KINIT-ARGS> should be any arguments that you need to pass to your kinit program, given as a list of strings. Most likely, you will give this as nil.

See the file `efs-kerberos.el' for more configuration variables. If you need to adjust any of these variables, please report this to us so that we can fix them for other users.

If EFS detects that you are not authenticated to use the gateway, it will run the kinit program automatically, prompting you for a password. If you give a password in your `.netrc' file for login the value of efs-gateway-host and user kerberos, then EFS will use this to obtain gateway authentication.

`Transparent gateways'

If your gateway is completely transparent (for example it uses socks), then you should set efs-gateway-type to nil. Also, set efs-ftp-local-host-regexp to ".*". However, efs-local-host-regexp, must still be set to a regular expression matching hosts in your local domain. EFS uses this to determine which machines that it can open-network-stream to. Furthermore, you should still set efs-gateway-host to the name of your gateway machine. That way EFS will know that this is a special machine having direct TCP/IP access to both hosts in the outside world, and hosts in your local domain.

2.7 Common Problems with Gateways

2.7.1 Spurious 220 responses

Some proxy-style gateways (eg gateway type 'proxy or 'raptor), return two 3-digit FTP reply codes to the USER command. For example:

open gateway.weird
220 Connected to gateway.weird
quote USER sandy@foobar
220 Connected to foobar
331 Password required for sandy

This is wrong, according to the FTP Protocol. Each command must return exactly one 3-digit reply code. It may be preceded by continuation lines. What should really be returned is:

quote USER sandy@foobar
331-Connected to foobar.
331 Password required for sandy.

or even

quote USER sandy@foobar
331-220 Connected to foobar.
331 Password required for sandy.

Even though the `"331-220"' looks strange, it is correct protocol, and EFS will parse it properly.

If your gateway is returning a spurious 220 to USER, a work-around is to add a regular expression to efs-skip-msgs that matches this line. It must not match the 220 line returned to the open command. This work-around may not work, as some system FTP clients also get confused by the spurious 220. In this case, the only solution is to patch the gateway server. In either case, please send a bug report to the author of your gateway software.

2.7.2 Case-sensitive parsing of FTP commands

Some gateway servers seem to treat FTP commands case-sensitively. This is incorrect, as RFC 959 clearly states that FTP commands are always to be case-insensitive. If this is a problem with your gateway server, you should send a bug report to its author. If EFS is using a case for FTP commands that does not suit your server, a possible work-around is to edit the efs source so that the required case is used. However, we will not be making any changes to the standard EFS distribution to support this type of server behaviour. If you need help changing the efs source, you should enquire with the efs-help mailing list.

2.8 Using archie.el with EFS

To use archie.el (by Jack Repenning) with EFS, you need at least archie.el V3.0.1. Problems using EFS with archie may be posted to the EFS mailing lists.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.