README

This file contains general, compile time and programming information about moftpd. For runtime information refer to the manpage moftpd(8). For runtime configuration options refer to moftpd.conf.dist.

COPYRIGHT NOTICE

SUPPORTED PLATFORMS

moftpd is currently developed on these platforms:

* NetBSD 1.6

* Mac OS X 10.2 / Darwin 6

These are the only two platforms I currently have access to. It has also been compiled on these platforms:

* RedHat 7.3

* SunOS 5.8

* Debian unstable as of 2003-09-18

It is highly likely that it will compile on many Unix like platforms as there’s nothing magic in the code. There might have to be some #defines added though.

If you have compiled and run moftpd on any platform except those listed above or an older version, feel free to contact me at (morth at morth.org).

INSTALLATION

Getting moftpd

The latest release of moftpd can be found at ftp://ftp.morth.org/moftpd/.

Required software

moftpd requires the following software to build:

* A C compiler.

* make. Most versions should work.

* perl

* bison or yacc

All of these should be included or easily added to most operating systems. If you plan to edit the code, you also want:

* mkdep

* GNU autoconf 2.5 or higher

Configuration

moftpd uses GNU autoconf to find out information about the build environment. Simply run the configuration script by typing
> ./configure

In addition to the normal configure arguments, moftpd supports these configuration flags:

* --disable-precompile

The configure script will look for the compiler flags --dump-pch and --load-pch by default and use them if found. Use this option if you want to disable the check and usage altogether.

* --with-native-charset=charset

moftpd normally operates with UTF-8 strings. In fact, that is the only valid charset except ASCII ftp may use acording to the rfcs. This option will let you set a charset used by moftpd when it detects a string that is not already UTF-8. This is used for both pathnames and incoming traffic. See further notes below. Default is iso8859-15.

To see detailed syntax about how to use the configure script, type
> ./configure --help

If you wish to, you can build moftpd in a different directories from the sources. To do that just create and stand in that dir and type
> path/to/moftpd-sources/configure
instead.

Building

To build moftpd after configuration simply type
> make
moftpd will build with both BSD and GNU make, even from different directories.

Installation

To install moftpd type
> make install
as the superuser. If you plan to use moftpd as your primary ftp server you also need to edit your startup script or inetd.conf to run moftpd instead of your normal ftp server.

moftpd will install into the location(s) given to the configure script (default /usr/local).

UTF-8 AND THE NATIVE CHARSET

moftpd is a UTF-8 enabled ftp server. That means it will talk in UTF-8 with it clients and will use the UTF-8 encoding when creating new files and folders. However, not all clients will talk UTF-8 with the server, and not all filesystems are UTF-8 encoded. When moftpd receives a pathname from the client, it first checks that raw pathname vs the filesystem. If the path is not found, it then checks UTF-8 NFC, UTF-8 NFD and the native charset, in that order. If none is found (when creating a new file/dir for example) UTF-8 NFC is used.

When a path is printed to the client it’s always transformed into UTF-8 NFC, if possible.

If you give the configure script the --without-native-charset option, moftpd will not be able to convert non-UTF-8 strings into UTF-8 or vice versa. These will then be used/printed without translation. It will still convert UTF-8 strings to and between NFC and NFD.

Adding a charset

Adding a new charset is pretty straight forward. Simply create a file in the utf8fs/charsets/ subdirectory. Take a look at iso8859-15 for syntax. The first field is the Unicode character. The following is the byte sequnce that generates it. There can only be a single sequence for each unicode character, but there’s a workround for this: In the file nfcTable, create a unicode character above 10FFFF (the first field), and map it to the real character. You can also map native bytes to sequences of unicode characters this way (but use a single character if there is one).

LOCALISATION

moftpd supports the LANG command to set the language on the server replies. It does this by scanning a file for the english text and returning the localised version instead. System errors will be localised automatically if the OS supports it, otherwise they will (probably) be English.

Adding a locale

You add a new locale by creating a new file in the locale/ subdirectory named the encoding name in lower case (for exampel en-us) plus the ending .loc. The first 3 bytes should an UTF-8 bom to help file editors recognise it as UTF-8. The rest is simply the English reply message (a format for printf() actually), the string " => " (without quotes), and the replacement string which is ended by a newline. Remember to make your replacement string UTF-8. The list of all current replies should be in the locale/messages file. If you skip to add a message, the English text will be used. Any line not containing " =>

If you’re using emacs and it won’t recognise your file as UTF-8 by default, type C-x <RET> c, select utf-8 and then type C-x C-f.

Why not gettext(3)?

Well, I might switch to gettext() later, but the locale is switched very often and I’m not sure how much overhead gettext() adds. Also, I only need to call it from one place so this was simpler. gettext() is not designed for a server process talking different languages to different clients.

SECURING FTP

moftpd supports the TLS FTP extension as per defined in draft-murray-auth-ftp-ssl-11.txt. With a complient client, you can secure both the control and the data connection. You can also put restrictions on the protection level required on a directory/file level. See the sample configuration file for more information.

Finding trusted certs

When a client certificate is received, the file name for the CA is looked up by its hash value. That means you need to create a symlink (or copy, or hardlink) to that value. The hash value can be found using the openssl command tool. For example my CA is in the file morth.org.ca.pem, so I type
> openssl x509 -in morth.org.ca.pem -noout -hash
to find out the hash value, ba3a2789. Then I symlink
> ln -s morth.org.ca.pem ba3a2789.0
Now moftpd can find the CA. The .0 is for when several certificates have the same hash value. OpenSSL checks for .0, .1 and so on.

MODIFYING MOFTPD

If you are going to make more than minor changes to the moftpd source, you’ll want to run make depend to create the source/header dependencies. mkdep is required for this to work.