| Current Path : /usr/local/share/doc/bsdftpd-ssl/ |
FreeBSD hs32.drive.ne.jp 9.1-RELEASE FreeBSD 9.1-RELEASE #1: Wed Jan 14 12:18:08 JST 2015 root@hs32.drive.ne.jp:/sys/amd64/compile/hs32 amd64 |
| Current File : //usr/local/share/doc/bsdftpd-ssl/INSTALL |
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
* Prepare for the compilation
* The compilation
* The 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 NetBSD
* Configuration notes for Linux
5. Compilation notes
* The usage of the config.sh script
* The ncurses library in different Linux distributives
* Special notes for users of some Linux distributives
* Note for NetBSD users
* Note for FreeBSD users
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, which is required for the command-line secure FTP
client (in some cases it can be substituted by the termcap library).
To compile BSDftpd-ssl, you also need:
* Berkeley Yacc (which is known as yacc or byacc), an LALR parser generator;
* The GNU Compiler Collection (gcc) 3.0 or higher.
* The GNU binary utilities (binutils).
Please note that in most cases it's possible to use the gcc 2.9x compiler too
(for example, gcc 2.95) - see the "Compilation notes" part for the information
about the usage of the config.sh script.
2. Compilation and installation
-------------------------------
* Prepare for the compilation
$ ./config.sh OS
where OS is the one of FreeBSD, NetBSD or Linux, or you can simple run
$ ./config.sh `uname`
In some cases additional command-line options may be required for the config.sh
script, please see the "Compilation notes" part.
* The compilation
$ make
If all required software is installed, this step should be completed without
problems.
To remove the generated object and binary files from the source tree, you can
run:
$ make clean
This command is supported for all operating systems, but it is possible that
for some operating systems the additional make targets are implemented, see the
"Compilation notes" part for such information.
* The installation
$ make install
Please note that you need root privileges for this step.
It's also possible to install the parts of this software:
$ make install-server
- to install only the secure FTP server.
$ make install-client
- to install only the TLS/SSL-aware FTP client.
$ make install-doc
- only the documentation will be installed.
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 the 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 is
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 handle 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 simpler 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.
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 has been 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) and ftpchroot(5) man pages
may be accessed by ftpd-ssl(8) and ftpchroot-ssl(5) names to avoid confusions
with the stock FreeBSD man pages.
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 ---
Alternatively, 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_opie.so no_warn no_fake_prompts
auth requisite pam_opieaccess.so no_warn allow_local
auth required pam_unix.so no_warn try_first_pass
account required pam_unix.so
session required pam_permit.so
--- cut line ---
The /etc/ftpusers file is usually installed with the 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 NetBSD
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) and ftpchroot(5) man pages
may be accessed by ftpd-ssl(8) and ftpchroot-ssl(5) names to avoid confusions
with the stock NetBSD man pages.
In case of installation from binary packages, the used directory layout is very
similar to the default one, but files will be placed into the /usr/pkg subtree
instead of the /usr/local one.
NetBSD doesn't use PAM, so no PAM configuration is required.
All vital configuration files, except the X.509 certificate, usually are
already exist, but it is possible that you need to edit some of them, such as
ftpusers and ftpchroot. If you want to run the server as an inetd-based
service, you also need to edit the /etc/inetd.conf file.
Normally, the /etc/ftpusers and /etc/ftpchroot files are already installed with
the operating system. The stock NetBSD FTP server and this server use rather
different syntax for these files, but the default NetBSD ones are compatible
with the BSDftpd-ssl FTP server and it parses them correctly. Therefore if you
want to use the existent /etc/ftpusers and /etc/ftpchroot files, and they are
not in the default state, you should convert them to the format of the
BSDftpd-ssl FTP server.
If you don't sure about the compatibility of the existent /etc/ftpusers and
/etc/ftpchroot file, you can start with the empty /etc/ftpchroot file and
restrict next users in the /etc/ftpusers file: root, toor, daemon, operator,
bin, news, games, postfix, named, ntpd, sshd, smmsp, uucp, nobody.
* 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 nullok
account required /lib/security/pam_unix.so
session required /lib/security/pam_unix.so
session required /lib/security/pam_limits.so
--- cut line ---
This configuration can also be recommended for Debian GNU/Linux distributions.
In a number of modern rpm-based 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 ---
The next configuration also can be used in some Linux distributions:
--- 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 ---
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 usage of the config.sh script
The config.sh script is used to prepare the source tree for the compilation.
There are several possible ways to use this script:
$ config.sh OS [OSFeature, [OSFeature, ...]]
- to prepare the configuration of the source tree.
$ config.sh clean
- to cleanup the configuration of the source tree.
$ config.sh _conv_gcc29x
- to convert the source code to the gcc 2.9x compatible state.
The conversion of the source code can be used to enable the compilation of the
software in the systems, whose use gcc 2.9x as the stock compiler. The original
versions of the source files modified during the conversion are saved with the
".gcc3" extensions.
The "OS" command-line parameter is the name of the target operating system,
currently "FreeBSD", "NetBSD" or "Linux". The "OSFeature" command-line
parameter can be used to enable or disable the support for some specific
features of the BSDftpd-ssl software. Currently the possible values of
"OSFeature" are:
NOPAM - don't use PAM.
Kerberos - add the "/usr/kerberos/include" directory into the list of the
include directories.
noncursesdir - don't use the "/usr/include/ncurses" directory.
sendfile - use the sendfile() system call.
nosendfile - don't use the sendfile() system call.
bsdnewbind - open a socket for a data transfer in active mode using euid
of the current user. This way is compatible with Linux and with
modern versions of FreeBSD (starting from 5.3).
nobsdnewbind - open a socket for a data transfer in active mode using euid
of the root user.
The config.sh script tries to autodetect the safeness of the usage of some
features, so usually there is no need to specify them explicitly. The known
exceptions are listed below.
* The ncurses library in different Linux distributives
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.
* Special notes for users of some Linux distributives
In Debian GNU/Linux the call for config.sh script should include the
"noncursesdir" parameter:
$ ./config.sh Linux noncursesdir
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
In the RedHat Linux 9 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
* Note for NetBSD users
1. For NetBSD 1.6.x the conversion of the source code to the gcc 2.9x
compatible state is required:
$ ./config.sh _conv_gcc29x
2. To completely clean the source tree and remove all of the files removed by
the "make clean" as well as any generated manual pages, you can run:
$ make cleandir
* Note for FreeBSD users
1. For FreeBSD 4.x the conversion of the source code to the gcc 2.9x compatible
state is required:
$ ./config.sh _conv_gcc29x
2. 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.
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.