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.
 * IP-based and/or IP-less virtual hosts.
 * 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.

VIRTUAL HOSTS

Net:FTPServer is capable of hosting multiple FTP sites on a single machine. Because of the nature of the FTP protocol, virtual hosting is almost always done by allocating a single separate IP address per FTP site. However, Net::FTPServer also supports an experimental IP-less virtual hosting system, although this requires modifications to the client.

Normal (IP-based) virtual hosting is carried out as follows:

 * For each FTP site, allocate a separate IP address.
 * Configure IP aliasing on your normal interface so that
   the single physical interface responds to multiple
   virtual IP addresses.
 * Add entries (A records) in DNS mapping each site's
   name to a separate IP address.
 * Add reverse entries (PTR records) in DNS mapping each
   IP address back to the site hostname. It is important
   that both forward and reverse DNS is set up correctly,
   else virtual hosting may not work.
 * In /etc/ftpd.conf you will need to add a virtual host
   section for each site like this:

     <Host sitename>

       ip: 1.2.3.4
       ... any specific configuration options for this site ...

     </Host>

   You don't in fact need the "ip:" part assuming that
   your forward and reverse DNS are set up correctly.
 * If you want to specify a lot of external sites, or
   generate the configuration file automatically from a
   database or a script, you may find the <Include filename>
   syntax useful.

There are examples in /etc/ftpd.conf. Here is how IP-based virtual hosting works:

 * The server starts by listening on all interfaces.
 * A connection arrives at one of the IP addresses and a
   process is forked off.
 * The child process finds out which interface the
   client connected to and reverses the name.
 * If:
     the IP address matches one of the "ip:" declarations
     in any of the "Host" sections, 
   or:
     there is a reversal for the name, and the name
     matches one of the "Host" sections in the configuration
     file,
   then:
     configuration options are read from that
     section of the file and override any global configuration
     options specified elsewhere in the file.
 * Otherwise, the global configuration options only
   are used.

IP-less virtual hosting is an experimental feature. It requires the client to send a HOST command very early on in the command stream -- before USER and PASS. The HOST command explicitly gives the hostname that the FTP client is attempting to connect to, and so allows many FTP sites to be multiplexed onto a single IP address. At the present time, I am not aware of any FTP clients which implement the HOST command, although they will undoubtedly become more common in future.

This is how to set up IP-less virtual hosting:

 * Add entries (A or CNAME records) in DNS mapping the
   name of each site to a single IP address.
 * In /etc/ftpd.conf you will need to list the same single
   IP address to which all your sites map:

     virtual host multiplex: 1.2.3.4

 * In /etc/ftpd.conf you will need to add a virtual host
   section for each site like this:

     <Host sitename>

       ... any specific configuration options for this site ...

     </Host>

Here is how IP-less virtual hosting works:

 * The server starts by listening on one interface.
 * A connection arrives at the IP address and a
   process is forked off.
 * The IP address matches "virtual host multiplex"
   and so no IP-based virtual host processing is done.
 * One of the first commands that the client sends is
   "HOST" followed by the hostname of the site.
 * If there is a matching "Host" section in the
   configuration file, then configuration options are
   read from that section of the file and override any
   global configuration options specified elsewhere in
   the file.
 * If there is no matching "Host" section then the
   global configuration options alone are used.

The client is not permitted to issue the HOST command more than once, and is not permitted to issue it after login.

VIRTUAL HOSTING AND SECURITY

Only certain configuration options are available inside the <Host> sections of the configuration file. Generally speaking, the only configuration options you can put here are ones which take effect after the site name has been determined -- hence "allow anonymous" is OK (since it's an option which is parsed after determining the site name and during log in), but "port" is not (since it is parsed long before any clients ever connect).

Make sure your default global configuration is secure. If you are using IP-less virtual hosting, this is particularly important, since if the client never sends a HOST command, the client gets the global configuration. Even with IP-based virtual hosting it may be possible for clients to sometimes get the global configuration, for example if your local name server fails.

IP-based virtual hosting always takes precedence above IP-less virtual hosting.

With IP-less virtual hosting, access control cannot be performed on a per-site basis. This is because the client has to issue commands (ie. the HOST command at least) before the site name is known to the server. However you may still have a global "access control rule".

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.

$ftps->ip_host_config ($ip_addr);

Look for a <Host> section which contains "ip: $ip_addr". If one is found, return the site name of the Host section. Otherwise return undef.

$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