README

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

COPYRIGHT NOTICE

SUPPORTED PLATFORMS

moftpd is currently developed on these platforms:

* Mac OS X 10.3 / Darwin 7

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

* NetBSD 1.6

* 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 (5.something most likely)

* 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

Optional software

moftpd uses these optional software if found:

* OpenSSL

* PAM

* MySQL

Configuration

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

Normally you shouldn’t have to give any extra arguments, moftpd will enable all features it can find. Just make sure your LIBRARY_PATH and CPATH or similar are properly setup to find everything (in particular, the mysql library might be in weird locations). At the end of the configure script you’ll see the result. 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).

PAM SUPPORT

Starting with version 1.2, moftpd support PAM. However it still also uses its own permissions system. That means that in addition to a successful PAM authentication, AllowLogin (or AllowSecLogin) must be true. Also, there’s several things that’s not checked with PAM:

* Anonymous users.

* Users with passwords provided in the moftpd config file or by SQL.

* Logins by certificate.

PAM credentials and sessions are still used for these as well though. For logins that are checked with PAM, MaxLoginAttempts is ignored. moftpd trusts PAM to indicate too many tries.

See docs/moftpd.pam for an example PAM file.

SQL SUPPORT

moftpd now supports SQL (only MySQL so far). This is done by performing a select query for users and directory access upon login. See moftpd.conf.dist for more information.

REMOTE ADMINISTRATION

There is some support for remote administration. This is all done by the SITE ADMIN command. The syntax is identical to that of moftpadmin (except -f) so se moftpadmin(8) for more information.

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.

SECURING FTP

moftpd supports the TLS FTP extension as per defined in draft-murray-auth-ftp-ssl-15.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

This applies to OpenSSL only. For gnutls all valid certificates in the TrustedCertsDir are trusted.

For OpenSSL, 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.

I also recommend you run configure like this:
> ./configure CFLAGS=’-g -Werror -DDEBUG’

Submitting patches

If you want your patch to go into the official moftpd send them to (moftpd-bugs at lists.morth.org). However, I can only accept patches if you are willing to give me complete copyright of their content. Please provide a written statement that this is the case. I have no intension to stop giving out moftpd under the GNU GPL, but I’ve seen several examples of code with too many copyright holders to be usable, and wish to avoid that.