BSDftpd-ssl project  <URL: http://bsdftpd-ssl.sc.ru/ >

This document describes the compilation and installation procedure of
BSDftpd-ssl software.

Contents
==============================
1. Requirements
2. Compilation and installation
3. Configuration
  * Create the server certificate
  * Edit PAM configuration
  * Edit /etc/ftpusers file, if required
  * Start the FTP server
4. Supplement information
  * Certificate management scripts
  * Configuration notes for FreeBSD
  * Configuration notes for Linux
5. Compilation notes
  * The ncurses library in different Linux distributions
  * FreeBSD
  * Slackware Linux
  * RedHat Linux 9

1. Requirements
---------------

To install BSDftpd-ssl, you need:

* OpenSSL 0.9.6 or higher, OpenSSL 0.9.7 is recommended;
* The libwrap library from the TCP_Wrappers package
* The ncurses library (it's required for the command-line secure FTP client).

To compile BSDftpd-ssl, you also need:

* Berkeley Yacc (yacc), an LALR parser generator;
* The GNU Compiler Collection (gcc 2.95 or higher);
* The GNU binary utilities (binutils).

2. Compilation and installation
-------------------------------

$ ./config.sh OS
(where OS must be either of FreeBSD or Linux)
or
$ ./config.sh `uname`

In some Linux distributions an additional command-line options may be required,
please see the "Supplement information" part.

$ make
$ make install

Please note that you need root privileges for the last step.

3. Configuration
----------------

You need root privileges for following steps. See also the "Supplement
information" part for some configuration particulars.

  * Create the server certificate

It consists of two parts: RSA Private Key and correspondent X509 Certificate.
These parts can be stored in one file (by default both will be searched in 
certs/ftpd.pem file in OpenSSL directory) or separated to two different files,
but both of them must be available for FTP server application. See ftpd(8) man
page for more information.

In both cases KEEP THE FILE WITH RSA PRIVATE KEY SECRET! It's recommended that
only root user have access rights to the file that contains Private Key. The
correspondent X509 Certificate is a publicly accessible information, so the
file, which contains X509 Certificate and doesn't contain Private Key, may be
world-readable.

The easiest way to generate your own certificate is to make dummy self-signed
certificate. Simple run the cert-dummy.sh script from the cert/ subdirectory of
the source tree, rename cert-dummy.pem to ftpd.pem and place it into the
OpenSSL's certs/ directory.

If you require the real certificate, run the cert-nopass.sh script from cert/.
It will create newcert-key.pem (RSA Private Key) and newcert-csr.pem
(Certificate Signing Request, CSR). After signing the CSR by Certificate
Authority (CA) you will have the certificate. You can concatenate RSA Private
Key and signed Certificate to one file and place it as described above.

See also an accompanying documentation for more information.

  * Edit PAM configuration

PAM (Pluggable Authentication Modules) is a suite of shared libraries that
enable the local system administrator to choose how applications authenticate
users. In other words, without (rewriting and) recompiling a PAM-aware
application, it is possible to switch between the authentication mechanism(s)
it uses.

Some templates for PAM configurations for different operating systems are
available in the "Supplement information" part.

See also the PAM-related documentation of your operating system for more
information (in particular, the pam(8) man page).

  * Edit /etc/ftpusers file, if required

This file describes a list of users those are restricted to log into the
system. Each line of this file corresponds to one login name or, if it's
started with a "@" symbol, to one group name. Lines beginning with the "#"
symbol are ignored and can be used to include comments.

The list of login names, those are recommended to be restricted by default, is
specific to each operating system, so such information may be obtained from
the "Supplement information" part.

  * Start the FTP server

The FTP server has a number of features, whose may be turned on or off with
help of command-line options. Please see the ftpd(8) man page for details about
available features and corresponding command-line options.

There are two ways to use the FTP daemon: as an inetd-based service or in
a daemon mode. The most common manner is to run the ftpd as the inetd-based
service. In this case the internet "super-server" listens for connections, do
access control and starts the server to service the request. In the daemon mode
the ftpd itself accepts connections on the FTP port and forks children
processes to handle them. This mode has the lower overhead and thus is useful
on busy servers to reduce load.

There are two popular implementations of the "super-server": inetd and
xinetd.

The capabilities of inetd may vary in different operating systems: modern
distributions of BSD systems usually use an enhanced version of this software
as a default "super-server", but in other systems, include most Linux
distributions, a more simple one is available.

The xinetd is a powerful replacement for inetd and it's used as the default
internet "super-server" in a number of modern Linux distributions, but it's
also available for some other operating systems, include most popular BSD ones.

As a matter of fact FreeBSD 4.x and 5.x operating systems use inetd, and xinetd
is available in the ports collection. Fedora Core 1 and Mandrake Linux (and
also RedHat Linux starting from 7.x series) operating systems use xinetd.

In case of inetd you need to edit the /etc/inetd.conf file and to add something
like this into it:

--- cut line ---
# Example 1: Accept both normal and TLS/SSL FTP clients
ftp	stream	tcp	nowait root	/usr/local/libexec/ftpd	ftpd
--- cut line ---
# Example 2: Accept only TLS/SSL-aware FTP clients
ftp	stream	tcp	nowait root	/usr/local/libexec/ftpd	ftpd -z secure
--- cut line ---

The xinetd configuration may be stored in the /etc/xinetd.conf file or in
separate files (with the same syntax as xinetd.conf) with arbitrary names in
the /etc/xinetd.d/ directory. If the xinetd.d/ directory exists, then
xinetd.conf contains some defaults and xinetd.d/ contains configurations of
individual services.

Next configuration may be recommended as a template:

--- cut line ---
# file: /etc/xinetd.d/bsdftpd-ssl
# default: off
# description: BSDftpd-ssl supports TLS/SSL for both control and data
# connections, but also fully compatible with standard FTP protocol.
service ftp
{
	disable     = yes
	flags       = REUSE NAMEINARGS
	socket_type = stream
	protocol    = tcp
	wait        = no
	user        = root
	server      = /usr/local/sbin/ftpd
	server_args = ftpd
}
--- cut line ---

In this example the service is disabled by default, so you need to change the
"disable" flag from "yes" to "no" to enable the secure FTP server. After
changing of the configuration you need to force inetd or xinetd to re-read it.
See also the documentation of the corresponding software for more information,
in particular the inetd(8) and/or xinetd(8) man pages.

If your distribution of operating system doesn't use inetd or xinetd, please
see its documentation for conventions for ways to run inetd-based services.

Alternatively, it's possible to run the server in the daemon mode. In this case
you need to run the ftpd with the "-D" command-line option. Please read the
documentation of your operating system for information about starting and
stopping daemons during system's startup and shutdown (some information usually
is available in the init(8) man page).

4. Supplement information
-------------------------

  * Certificate management scripts

If BSDftpd-ssl software was installed, from the source or binary package, the
certificate management scripts from the cert/ subdirectory of the source tree
are installed as a part of the documentation.

  * Configuration notes for FreeBSD

Default location of the FTP server (ftpd) is /usr/local/libexec/, TLS/SSL-aware
FTP client utility (ftps) - /usr/local/bin, man pages - /usr/local/man/,
documentation - /usr/local/share/doc/. The ftpd(8) man page may also be
accessed by ftpd-ssl(8) name to avoid confusion with the FreeBSD's own ftpd(8)
man page.

PAM configuration may be stored in the /etc/pam.conf file (it's the default
location for FreeBSD 4.x) or in the /etc/pam.d/ directory (it's the default
location for FreeBSD 5.x, but it may be used in FreeBSD 4.x too). See the
pam(8) man page for more information.

If the PAM configuration is stored in /etc/pam.conf, add something like this
into it:

--- cut line ---
ftpd	auth	sufficient	pam_skey.so
ftpd	auth	required	pam_cleartext_pass_ok.so
ftpd	auth	required	pam_unix.so			try_first_pass
ftpd	account	required	pam_unix.so
ftpd	session	required	pam_permit.so
--- cut line ---

Or, if the /etc/pam.d/ directory exists, create the file named ftpd in it and
write something like this into it (in this case leave pam.conf intact):

--- cut line ---
#%PAM-1.0
auth	sufficient	pam_skey.so
auth	required	pam_cleartext_pass_ok.so
auth	required	pam_unix.so			try_first_pass
account	required	pam_unix.so
session	required	pam_permit.so
--- cut line ---

The /etc/ftpusers file is usually installed with operating system and contains
all login names those are needed to be restricted. In FreeBSD 4.10 they are:
root, toor, daemon, operator, bin, tty, kmem, games, news, man, sshd, bind,
uucp, xten, pop, www, nobody, mailnull, smmsp.

  * Configuration notes for Linux

Default location of the FTP server (ftpd) is /usr/local/sbin/, the
TLS/SSL-aware FTP client utility (ftps) - /usr/local/bin, man pages -
/usr/local/man/, the documentation - /usr/local/doc/. If installing from
sources, the ftpd(8) man page may also be accessed by the ftpd-ssl(8) name to
avoid a potential confusion with another ftpd(8) man page (another FTP server
may be already installed from a binary package).

If installing from binary packages, all required configuration files (except
the X.509 certificate), such as PAM and xinetd configurations, are installed
automatically, but it's possible that you need to edit some of them (the xinetd
configuration) or some of existing configuration files, such as inetd.conf.
The subdirectory layout and locations of binary files, man pages and the
documentation depend to defaults of each distributive. The set and locations of
the existing configuration files needed to be edited are also depend to the
conventions of each distributive.

The editline(3) and editrc(5) man pages, those are mentioned in ftps(1) page,
are accessible as ftps-editline(3) and ftps-editrc(5), respectively, to avoid
confusions with any possible Linux ports of libedit (such ports may install
same pages, but they are available for a limited number of Linux
distributions).

The PAM configuration must be stored in /etc/pam.d/ftpd. Write something like
this into it:

--- cut line ---
#%PAM-1.0
auth       required	/lib/security/pam_unix.so
account    required     /lib/security/pam_unix.so
session    required     /lib/security/pam_unix.so
--- cut line ---

In Debian GNU/Linux 3.0 the recommended configuration is:

--- cut line ---
auth	required	pam_unix_auth.so shadow nullok use_first_pass
account	required	pam_unix_acct.so
session	required	pam_unix_session.so
session	required	pam_limits.so
--- cut line ---

In a number of modern Linux distributions (include Fedora Core, last versions
of RedHat Linux) the next configuration is recommended:

--- cut line ---
#%PAM-1.0
auth       required	/lib/security/pam_stack.so service=system-auth
account    required	/lib/security/pam_stack.so service=system-auth
session    required	/lib/security/pam_stack.so service=system-auth
--- cut line ---

If installing from a binary package, the /etc/ftpusers file will be installed
automatically, otherwise it must be created manually. The list of login names
those may be recommended to restriction is: root, bin, daemon, adm, lp, sync,
shutdown, halt, mail, news, uucp, operator, games, gopher, nobody, gdm,
postgres, named.

5. Compilation notes
--------------------

  * The ncurses library in different Linux distributions

There are two known ways to place the include files from the ncurses library
into the location of standard C include files (the /usr/include/ directory):
- To place them directly into the root of the standard include directory. In
  this case the ncurses library is also used as the replacement of the termcap
  library.
- To place them into the ncurses/ subdirectory in the standard include
  directory. In this case the termcap library can be installed too.

The first way is used by Debian GNU/Linux and some other Linux distributions,
the second way is used by RedHat Linux and some similar distributions. The
secure FTP client utility (ftps) uses the termcap.h include file, which can be
provided by both ncurses and termcap libraries, but the ncurses library is
preferred.

If your operating system doesn't have /usr/include/ncurses directory and has
the /usr/include/termcap.h file, you need to run the config.sh script by the
next way:
$ ./config.sh Linux noncursesdir

This method, for example, is required for Debian GNU/Linux.

  * FreeBSD

The FTP server (ftpd) can use the sendfile() system call, which greatly speeds
up sending a regular file to a stream socket and reduces the CPU load.

But all FreeBSD versions, whose are released before 1 December 2003, include
-RELEASE, -STABLE and -CURRENT branches, have a broken implementation of
sendfile() system call, which corrupts the data sent with help of this system
call. The set of affected versions includes 4.9-RELEASE, 5.1-RELEASE and the
earlier releases in the 4.x and 5.x branches. This problem has been fixed in
5.2-RELEASE and 4.10-RELEASE.

The config.sh script enables the support for sendfile() depending to the
version of the operating system. The support will be enabled for 5.2 and
later versions in the 5.x series, and for 4.10 and later versions in the 4.x
series.

It's possible to force the support for sendfile() to be enabled or disabled by
the next ways, respectively:
$ ./config.sh FreeBSD sendfile
$ ./config.sh FreeBSD nosendfile

Enabling the support for sendfile() may be recommended for users of the
4-STABLE series if the operating system has been updated from the CVS
repository after 1 December 2003 (the problem with this system call is fixed,
but the configuration script can't recognize it).

The users of pre-release versions of the 5.2 release (which was officially
released in January, 2004; such versions may have different names, include
5.2-RC, 5.2-RELEASE, etc) must disable the support for sendfile(2) if they were
extracted from the CVS repository before 1 December 2003.

  * Slackware Linux

Slackware Linux doesn't use PAM. To enable Slackware's implementation of the
user authentication, config.sh must be called (at the step of the compilation)
by the next way:
$ ./config.sh Linux NOPAM

  * RedHat Linux 9

In this operating system the Kerberos headers are required by OpenSSL ones for
the compilation if an application uses OpenSSL, but the krb5-devel package
installs them into an unexpected location (into the /usr/kerberos/include/
directory). To compile the BSDftpd-ssl software, the config.sh script must be
called by the next way:
$ ./config.sh Linux Kerberos
