$Id: README,v 1.7 2000/01/26 20:11:33 he Exp $ README file for eftp4linux ========================== eftp4linux is an Open Source (tm) implementation of the EUROFILE Transfer Protocol as standardised by a set of ETSI norms (in particular ETS 300-383 and ETS 300-075). It is freqently used to transfer files over ISDN. Currently, the only target OS is Linux >= 2.2.x. However, the design should allow for porting it to other POSIX operating systems that provide a select() system call and a socket interface to the X.25/ISO-8208 network layer protocol. (Some minor non-POSIX features are currently used as well for convenience). DISCLAIMER ========== Use on your own risk -- as usual with open (and even close) source software. However, as this is alpha test software, the risk might be higher than the risk of just using your favourite linux distribution. Read the COPYING* files present in the distribution for further details. WHAT'S NEW ========== See the CHANGES file for details. General features ================ eftp4linux consists of a core library that implements the EUROFILE related protocols. It also contains two important applications built on top of this library: - An EUROFILE client program with command line interface. Command line editing is supported by means of the GNU readline library. - An EUROFILE server which can serve multiple connections simulatneously and supports navigation (i.e. changing directories). User authentification is provided by a separate authentification library derived from wu-ftpd which allows for fine grained access control based on user-id, password, and remote isdn phone number. The design allows for easily exchanging the authentification routines by user-supplied versions. This is all still alpha test software. That means it does certain tasks well at my site, but I know that they are incomplete, non-conforming and have other bugs as well. However, they are becoming better and better now and I think that there are not so many vital missing features left now. Thus, experienced isdn4linux users are encouraged to test this and report bugs or success stories, or suggest and contribute improvements. The navigation support for the server is not fully conformant to the protocol specifications with respect to some regards. This might in theory confuse certain clients when the navigation facility is used. The server and client support extended directory service which could allow for handling of long filenames, but as several eft implementations don't support this, you might not take advantages of that. During several tests it turned out that many commercial EUROFILE implementations are not protocol conformant, either. One major inter-working problem is caused by implementations which don't handle uppercase/lowercase in filenames appropriately. The result is that some clients can only load either uppercase or lowercase filenames. A similar problem appears when changing working directories. Some clients even use upper/lowercase inconsistently when downloading and uploading files, such clients even cannot access a file uploaded by themselves before. An even worse problem is that at least one client replaces '/' characters in directory name by '\'. IMHO, this is a bug in the commercial EFT implementations. Until the suppliers of those implementations have fixed this, the server provides a work-around. If you add a '+' character in front of your login name, the server will try to treat file names case insensitively and replace '\' by '/' again. This compatibility mode is somewhat restricted: only the basename of a file will be handled case-insensitively, the dirname will currently always be treated as lower case, when the compatibility mode is active. Thus, in order to avoid trouble, you should always use lower case directory names in the servers file system tree. And of course, if multiple files with names differing only in the cases of the character, you can only access one of them. Details on this test distribution ================================== In addition to the files contained in this distribution, you will need - A recent Linux 2.2.x kernel (2.2.12 or newer is recommended). - There is also a patch ix25-2.1.128.diff that deals with a low layer (X.25) interworking problem observed with some clients (CSD isdn toolbox and maybe also some RVS clients). They send misformatted X.25 call request packets that confuse the linux X.25 layer. Applying this patch enables the kernel to correctly reject the misformatted frames. For working around the interworking problem you also need to uncomment the last line in include/net/x25.h. Please read the doc/INTERWORKING file for further details. The patch should also work with older or newer kernels than 2.1.128. - the current x25-utils-2.1.x package, which is available from ftp.hes.iki.fi:/pub/ham/linux/ax25/. The most important programme therein is the x25_route utility. (x25-utils-2.1.20 is still the most current release). Don't confuse the x25-utils with the ax25-utils. The latter is for amateur radio networking and not related to eftp4linux at all. (You can use eftp4linux without this packages, but local testing without isdn connection won't be possible then) - some of the recent isdn4k-utils, in particular isdnctrl (and loopctrl, if you want to test locally by means of the isdnloop driver). The isdn4k-utils-3.0beta2.tar.gz. (or newer) are fine. isdnctrl.c must be compiled against 2.2.x kernel header files. The most recent isdn4k-utils package is availabe from ftp.isdn4linux.de You can also use an even newer isdn4k-util snapshot from isdn4linux CVS server. See the isdn4linux FAQ for info about this. How to build: ============= See the INSTALL file. After having typed "make" in the top directory, there will (hopefully :-) be two important user level programs inside src/*/: - eftp is a simple EUROFILE client that allows for transferring files between a remote machine and your linux box by means of the EUROFILE transfer protocol on top of isdn. It's command line style user interface consists of a few ftp-like commands. - eftd is an EUROFILE server. Some older programmes, which are of less importance now, will also build if you type `make really_all': - x25.echod listens on an x25 socket and echoes back every packet received. Access to the x25 Q-bit is enabled to demonstrate this feature which is really necessary for eft and has no equivalent in TCP/IP sockets. - tdud.echod listens on an x25 socket and tries to fake an ETS 300 075 protocol session. It mainly encapsulates any received tdu messages in a t-response-positive tdu message and echoes it back. Now, you are prepared to test EUROFILE or X.25 on top of isdn4linux. For your convenience, some scripts are provided in the scripts directory that ease the task of setting up your system. See the end of the INSTALL file for quick start instruction or the files in the doc directory for details. The server's access control is similar as in the wu-ftp server. In fact, the access control is taken from wu-ftpd (Georg v.Zezschwitz ported this, see src/authlib/README for further information). If USER/PASSWD is omitted, anonymous ftp is assumed. Refer to the eft_wuauth man pages for learning more about ftp access control and configuring anonymous access. It turned out that most EUROFILE clients insert a default userid/passwd when a user/passwd is not provided explicitly. With such clients, supply the userid 'ftp' explicitly in order to access the anonymous EUROFILE account. Further, as some clients don't support navigation, you should create a symlink in ~ftp named ".++eft_flat" to, i.e., the pub directory (cd ~ftp; ln -s pub .++eft_flat). The server will cd to this directory after login whenever it thinks that the client does not support navigation. (this is in particular useful with anonymous access because the ~ftp directory usually contains no downloadable stuff). The authentication library can even evaluate the peer's isdn number for its decisions. For this to work reliably, you need to use the cvs version of isdn4linux as of 1998-08-31 or newer or a kernel >= 2.2.12 or 2.3.4. Other sources of information: ============================= As you will be using several somewhat exotic and cutting edge parts of the Linux kernel it might be useful to read the following mailing lists: isdn4linux@hub-wue.franken.de or newsgroup de.alt.comm.isdn4linux linux-x25@vger.rutgers.edu linux-kernel[-digest]@vger.rutgers.edu linux-net@vger.rutgers.edu All lists mentioned above can be subscribed to by sending an e-mail containing subscribe LISTNAME in the message body to majordomo@DOMAIN (Replace LISTNAME by the name and DOMAIN by the domain name of the mailing list). A description of the linux X.25 implementation and socket interface is available from the same locations as the x25-utility package. Watch out for a file x25-doc.tar.gz (MS-Word formatted documents). A lot of documentation of ITU-T protocols (in particular x.25 and isdn) is on the "Standards" CD-ROM from Infomagic (http://www.infomagic.com, reasonable price). Original ITU standards are quite expensive (http://www.itu.ch and http://www.etsi.fr). But some libraries collect technical standards, reading them inside the library is cheaper that ordering them from your national standard body. For locating such a library, contact the web server (such as www.din.de) of your natinal standards body. Users living in Germany might locate such a public library by following the links in http://www.beuth.de/partner/index.html. Good News: ETSI recently made their standards available for download -- Not totally free but at least free of charge. You need to register first. Quote from ETSI's announcent: This application is located on http://webapp.etsi.org/publicationssearch or can be reached by following "products", "publications Download" from the ETSI home page http://www.etsi.org. http://www.netsmart.gr/teltest/teltest1.1/Lab_file.html contains a descriptions on the eft core concepts. The home site of this file, older and (possibly) newer versions, is ftp://ftp.hamburg.pop.de/pub/LOCAL/linux/i4l-eft/ For reporting bugs or submitting patches, you can reach me by e-mail (eis@baty.hanse.de). The file Documentation/isdn/README.x25 present in the (patched) kernel sources contains general info on linux isdn-X.25 configuration. The sources of the user level programmes in directory src might also contain some documentation (and disclaimers :-). Remark on installing kernel image: ================================== If your Linux distribution does not support 2.2.x kernels, it is recommended that you don't install the compiled 2.2.x kernel as your default kernel image until you are sure that everything works as expected. You can add additional entries to the /etc/lilo.conf file in order to allow booting non-standard kernels from a different location. Please refer to the relevant lilo doc (man pages, doc files, HOWTOs,..) or refer to an older eftp4linux README file for examples. Thanks ====== Thanks to all the volunteers who made Linux the powerful OS it is today. In particular, to all who contributed to isdn4liunx. Some contributions have been of central importance to the EUROfile project and I'd like to mention them explicitly: Jonathan Naylor contributed the Linux X.25 protocol stack Fritz Elfert contributed the isdnloop driver which was very useful for keeping my phone bill low while testing. Lennart Koschella continuously operated a peer eft server that was used for tests during the initial developement phase. Point of Presence GmbH provided ftp server space. Georg v.Zezschwitz adapted the authentification code from the wu-ftpd which is now used inside the eft server. Martin Maurer provided protocol traces in the initial phase of development. Michael Dietrich helped fixing compile/build problems. Knuth Posern helped tracking down several low layer protocol compatibility problems. Matthias Stolte provided enhancements to the setup scripts and added more command line options to the server. Michael Mauch added readline and mget/mput support to eftp. As the eft server's authentication code is derived from wu-ftpd, the following acknowledgements hold: This product includes software developed by the Washington University in Saint Louis and its contributors. This product includes software developed by the University of California, Berkeley and its contributors. - Henner