NAME

Net::FTPServer - A secure, extensible and configurable Perl FTP server

SYNOPSIS

ftpd [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file]

DESCRIPTION

Net::FTPServer is a secure, extensible and configurable FTP server written in Perl.

Current features include:

* Authenticated FTP access.
* Anonymous FTP access.
* Complete implementation of current RFCs.
* ASCII or binary type file transfers.
* Active or passive mode file transfers.
* Run standalone or from inetd(8).
* Security features: chroot, resource limits, tainting,
  protection against buffer overflows.
* Complete access control system.
* Anonymous read-only FTP personality.
* Virtual filesystem allows files to be served
  from a database.
* Directory aliases and CDPATH support.
* Extensible command set.

INSTALLING AND RUNNING THE SERVER

A standard ftpd.conf file is supplied with the server. You should study the comments in the file and edit it to your satisfaction, and then copy it to /etc/ftpd.conf.

cp ftpd.conf /etc/
chown root.root /etc/ftpd.conf
chmod 0755 /etc/ftpd.conf

Two start-up scripts are supplied with the ftp server, to run it in two common configurations: either as a full FTP server or as an anonymous-only FTP server. The scripts are ftpd and anonftpd. You may need to edit these scripts if Perl is not stored in the standard place on your system (the default path is /usr/bin/perl).

You should copy the appropriate script, either ftpd or anonftpd to a suitable place (for example: /usr/sbin/in.ftpd).

cp ftpd /usr/sbin/in.ftpd
chown root.root /usr/sbin/in.ftpd
chmod 0755 /usr/sbin/in.ftpd

STANDALONE SERVER

If you have a high load site, you will want to run Net::FTPServer as a standalone server. To start Net::FTPServer as a standalone server, do:

/usr/sbin/in.ftpd -S

You may want to add this to your local start-up files so that the server starts automatically when you boot the machine.

To stop the server, do:

killall in.ftpd

RUNNING FROM INETD

Add the following line to /etc/inetd.conf:

ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd

(This assumes that you have the tcpd package installed to provide basic access control through /etc/hosts.allow and /etc/hosts.deny. This access control is in addition to any access control which you may configure through /etc/ftpd.conf.)

After editing this file you will need to inform inetd:

killall -HUP inetd

CONFIGURING AND EXTENDING THE SERVER

Net::FTPServer can be configured and extended in a number of different ways.

Firstly, almost all common server configuration can be carried out by editing the configuration file /etc/ftpd.conf.

Secondly, commands can be loaded into the server at run-time to provide custom extensions to the common FTP command set. These custom commands are written in Perl.

Thirdly, one of several different supplied personalities can be chosen. Personalities can be used to make deep changes to the FTP server: for example, there is a supplied personality which allows the FTP server to serve files from a relational database. By subclassing Net::FTPServer, Net::FTPServer::DirHandle and Net::FTPServer::FileHandle you may also write your own personalities.

The next sections talk about each of these possibilities in turn.

EDITING /etc/ftpd.conf

A standard /etc/ftpd.conf file is supplied with Net::FTPServer in the distribution. This contains all possible configurable options, information about them and defaults. You should consult the comments in this file for authoritative information.

LOADING CUSTOMIZED COMMAND SETS

XXX

STANDARD PERSONALITIES

XXX

SUBCLASSING THE Net::FTPServer CLASSES

By subclassing Net::FTPServer, Net::FTPServer::DirHandle and/or Net::FTPServer::FileHandle you can create custom personalities for the FTP server.

Typically by overriding the hooks in the Net::FTPServer class you can change the basic behaviour of the FTP server - turning it into an anonymous read-only server, for example.

By overriding the hooks in Net::FTPServer::DirHandle and Net::FTPServer::FileHandle you can create virtual filesystems: serving files into and out of a database, for example.

The current manual page contains information about the hooks in Net::FTPServer which may be overridden.

See Net::FTPServer::DirHandle(3) for information about the methods in Net::FTPServer::DirHandle which may be overridden.

See Net::FTPServer::FileHandle(3) for information about the methods in Net::FTPServer::FileHandle which may be overridden.

METHODS

Net::FTPServer->run ([\@ARGV]);

This is the main entry point into the FTP server. It starts the FTP server running. This function never normally returns.

If no arguments are given, then command line arguments are taken from the global @ARGV array.

$ftps->reply ($code, $line, [$line, ...])

This function sends a standard single line or multi-line FTP server reply to the client. The $code should be one of the standard reply codes listed in RFC 959. The one or more $line arguments are the (free text) of the reply. Do not include carriage returns at the end of each $line. This function adds the correct line ending format as specified in the RFC.

$ftps->config ($name);

Read configuration option $name from the configuration file.

$sock = $self->open_data_connection;

Open a data connection. Returns the socket (an instance of IO::Socket) or undef if it fails for some reason.

$self->pre_configuration_hook ();

Hook: Called before command line arguments and configuration file are read.

Status: optional.

Notes: You may append your own information to $self-{version_string}> from this hook.

$self->options_hook (\@args);

Hook: Called before command line arguments are parsed.

Status: optional.

Notes: You can use this hook to supply your own command line arguments. If you parse any arguments, you should remove them from the @args array.

$self->post_configuration_hook ();

Hook: Called after all command line arguments and configuration file have been read and parsed.

Status: optional.

$self->pre_accept_hook ();

Hook: Called in daemon mode only just before accept(2) is called in the parent FTP server process.

Status: optional.

$self->post_accept_hook ();

Hook: Called both in daemon mode and in inetd mode just after the connection has been accepted. This is called in the child process.

Status: optional.

$rv = $self->access_control_hook;

Hook: Called after accept(2)-ing the connection to perform access control. Detailed request information is contained in the $self object. If the function returns -1 then the socket is immediately closed and no FTP processing happens on it. If the function returns 0, then normal access control is performed on the socket before FTP processing starts. If the function returns 1, then normal access control is not performed on the socket and FTP processing begins immediately.

Status: optional.

$rv = $self->process_limits_hook;

Hook: Called after accept(2)-ing the connection to perform per-process limits (eg. by using the setrlimit(2) system call). Access control has already been performed and detailed request information is contained in the $self object.

If the function returns -1 then the socket is immediately closed and no FTP processing happens on it. If the function returns 0, then normal per-process limits are applied before any FTP processing starts. If the function returns 1, then normal per-process limits are not performed and FTP processing begins immediately.

Status: optional.

$rv = $self->authentication_hook ($user, $pass, $user_is_anon)

Hook: Called to perform authentication. If the authentication succeeds, this should return 0. If the authentication fails, this should return -1.

Status: required.

$self->user_login_hook ($user, $user_is_anon)

Hook: Called just after user $user has successfully logged in.

Status: required.

$dirh = $self->root_directory_hook;

Hook: Return an instance of Net::FTPServer::DirHandle (or a subclass) corresponding to the root directory.

Status: optional.

$self->pre_command_hook;

Hook: This hook is called just before the server begins to wait for the client to issue the next command over the control connection.

Status: optional.

$rv = $self->command_filter_hook ($cmdline);

Hook: This hook is called immediately after the client issues command $cmdline, but before any checking or processing is performed on the command. If this function returns -1, then the server immediately goes back to waiting for the next command. If this function returns 0, then normal command filtering is carried out and the command is processed. If this function returns 1 then normal command filtering is not performed and the command processing begins immediately.

Important Note: This hook must be careful not to overwrite the global $_ variable.

Do not use this function to add your own commands. Instead use the $self->{command_table} and $self->{site_command_table} hashes.

Status: optional.

$self->post_command_hook

Hook: This hook is called after all command processing has been carried out on this command.

Status: optional.

BUGS

The SIZE, REST and RETR commands probably do not work correctly in ASCII mode.

You cannot abort a transfer in progress yet. Nor can you check the status of a transfer in progress. Using the telnet interrupt commands can cause the FTP server to fail.

User upload/download limits.

Limit number of clients. Limit number of clients by host or IP address.

Virtual hosts.

The following commands are recognized by wu-ftpd, but are not yet implemented by Net::FTPServer:

SITE CHMOD   There is a problem supporting this with our VFS.
SITE GPASS   Group functions are not really relevant for us.
SITE GROUP   -"- ditto -"-
SITE GROUPS  -"- ditto -"-
SITE INDEX   This is a synonym for SITE EXEC.
SITE MINFO   This command is no longer supported by wu-ftpd.
SITE NEWER   This command is no longer supported by wu-ftpd.
SITE UMASK   This command is difficult to support with VFS.

Symbolic links are not handled elegantly (or indeed at all) yet.

The program needs to log a lot more general transfer and access information to syslog.

Equivalent of ProFTPD's ``DisplayReadme'' function.

The ability to hide dot files (probably best to build this into the VFS layer). This should apply across all commands. See ProFTPD's ``IgnoreHidden'' function.

Do ident (RFC913) authentication at login. Have a way to turn this on and off.

Access to LDAP authentication database (can currently be done using a PAM module). In general, we should support pluggable authentication.

Log formatting similar to ProFTPD command LogFormat.

More timeouts to avoid various denial of service attacks. For example, the server should always timeout when waiting too long for an active data connection.

Support for IPv6 (see RFC 2428), EPRT, EPSV commands.

See also "XXX" comments in the code for other problems, missing features and bugs.

FILES

/etc/ftpd.conf
/usr/lib/perl5/site_perl/5.005/Net/FTPServer.pm
/usr/lib/perl5/site_perl/5.005/Net/FTPServer/DirHandle.pm
/usr/lib/perl5/site_perl/5.005/Net/FTPServer/FileHandle.pm
/usr/lib/perl5/site_perl/5.005/Net/FTPServer/Handle.pm

AUTHORS

Richard Jones (rich@annexia.org).

COPYRIGHT

Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK

SEE ALSO

Net::FTPServer::Handle(3), Net::FTPServer::FileHandle(3), Net::FTPServer::DirHandle(3), Authen::PAM(3), Net::FTP(3), perl(1), RFC 765, RFC 959, RFC 1579, RFC 2389, RFC 2428, RFC 2577, RFC 2640, Extensions to FTP Internet Draft draft-ietf-ftpext-mlst-NN.txt.

cpanm Net::FTPServer

perl -MCPAN -e shell
install Net::FTPServer