Professional Documents
Culture Documents
README PureFTPd
README PureFTPd
Many people new to Unix are running Pure-FTPd because they find it easy to
install. But that software is also used on embedded systems and highly loaded
production servers, especially for hosting services.
For large sites with centralized user management, Pure-FTPd provides flexible
authentication schemes including SQL and LDAP backends, plus the ability to
easily write new custom handlers in any language.
In its current form, Pure-FTPd uses some OS-specific system calls. And although
some portability work has been done in order to ease its port to other
operating systems, only Linux FreeBSD, NetBSD, OpenBSD, ISOS, MirBSD, BSDi,
DragonflyBSD, Darwin, Solaris, Tru64, Irix, AIX and HPUX are known to work,
other operating systems may need some tweaks. With Linux, any modern
distribution should be ok.
Create a specific, unprivileged user and group called _pure-ftpd, without any
valid shell. Don't use this for anything else, including FTP virtual users.
groupadd _pure-ftpd
useradd -g _pure-ftpd -d /var/empty -s /etc _pure-ftpd
If having a user whose name begins with an underscore is a no-go for you,
you can also call it pure-ftpd, without the underscore.
* Step 2:
If you have Cdialog or Xdialog installed on your system, try the following
command to build and install Pure-FTPd:
make -f Makefile.gui
If you don't have Cdialog or if you prefer the conventional way, here it is:
./configure
make install-strip
* Step 3:
/usr/local/sbin/pure-ftpd &
If you installed a binary package (RPM, SLP, Debian), maybe use the
following command instead:
/usr/sbin/pure-ftpd &
Your server is ready. Just type 'ftp localhost' to test it. If you want to
automatically run the server when the system boots, add the previous command
to /etc/rc.d/rc.local or /etc/rc.d/boot.local . Don't forget the '&' sign.
Note:
The "./configure" script accepts some arguments you might want to add before
the compilation:
/--------------------
"--with-" switches
--------------------/
--with-tls: enable TLS support. Read README.TLS for more about this feature.
--with-certfile=<file>: the file with the TLS certificate (see README.TLS). The
default is /etc/ssl/private/pure-ftpd.pem .
--with-everything: build a big server with almost all features turned on:
altlog, cookies, throttling, ratios, ftpwho, upload script, virtual users
(puredb), quotas, virtual hosts, directory aliases, external authentication,
Bonjour and privilege separation.
--with-language=english
--with-language=german
--with-language=romanian
--with-language=french
--with-language=polish
--with-language=spanish
--with-language=danish
--with-language=italian
--with-language=brazilian-portuguese
--with-language=slovak
--with-language=dutch
--with-language=korean
--with-language=swedish
--with-language=norwegian
--with-language=russian
--with-language=traditional-chinese
--with-language=simplified-chinese
--with-language=hungarian
--with-language=catalan
--with-language=czech: change the language of server messages.
Default is english. If you want to contribute a translation, please
translate the 'src/messages_en.h' file and send it to <j at pureftpd dot org> .
--with-ldap: use the native LDAP directory support. When this option is
enabled, system accounts can be bypassed. You need OpenLDAP to use that
feature. If OpenLDAP is installed in a custom location, you can use the
--with-ldap=<directory> syntax. See the README.LDAP file for more info about
LDAP and Pure-FTPd.
--with-mysql: use the native MySQL support for users database. When this
option is enabled, system accounts can be bypassed. MySQL client libraries
should be installed to use that feature. If MySQL is installed in a custom
location, you can use the --with-mysql=<directory> syntax. See the
README.MySQL file for more info about MySQL and Pure-FTPd.
--with-pgsql: use the native Postgres support for users database. When this
option is enabled, system accounts can be bypassed. Postgres client libraries
should be installed to use that feature. If Postgres is installed in a custom
location, you can use the --with-pgsql=<directory> syntax. See the
README.PGSQL file for more info about Postgres and Pure-FTPd.
--with-quotas: enable virtual quotas. With virtual quotas, you can restrict
the maximal number of files a user can store in his account. You can also
of course restrict the total size. See the "quotas" section later in this
document.
/-----------------------
"--without-" switches
-----------------------/
--without-privsep: disable privilege separation (see notes about this later),
not recommended.
--without-humor: if you find what this option does without peeking at the
source code, you're a lucky guy!
/--------------
Other notes
--------------/
FYI, the binary RPM packages of Pure-FTPd are configured with the following
command line:
/usr/local/sbin/pure-ftpd &
When the previous command is run, the server will listen for incoming
connections on every interface, all IP addresses and the standard FTP port
(21) . If your system has IPv6 addresses, they should work as well.
/usr/local/sbin/pure-ftpd -S 42
Service names are also allowed ('-S smtp' and the daemon will be accepting
connections on the SMTP port (25) . Very uncommon, but we should please
everybody anyway, even disturbed minds) .
Now, what if your system has many IP addresses and you want the FTP server
to be reachable on only one of these addresses, let's say 192.168.0.42?
Just use the following command line:
/usr/local/sbin/pure-ftpd -S 192.168.0.42,
The final comma is important, don't forget it. Actually, it's a shorthand for:
/usr/local/sbin/pure-ftpd -S 192.168.0.42,21
/usr/local/sbin/pure-ftpd -S ftp.example.com,21
With previous command lines, the server will run in the default
configuration. Anonymous FTP logins will be allowed if there's a system
account called 'ftp' and every user of your system will be able to access
the FTP server using their regular login/password pair.
/usr/local/sbin/pure-ftpd -c 50 &
or
When you run 'ps auxw|grep pure-ftpd', the result looks like this:
root 15211 0.1 0.3 1276 452 ? S 13:53 0:00 pure-ftpd [SERVER]
root 15212 0.1 0.5 1340 672 ? S 13:54 0:00 pure-ftpd [IDLE]
root 15214 0.0 0.5 1340 672 ? S 13:56 0:00 pure-ftpd
[DOWNLOADING]
[SERVER] is the main server. If you kill this process, the server will exit
after the next connection.
[IDLE] shows a client with no transfer activity.
[DOWNLOADING] shows a client downloading a file.
[UPLOADING] show a client uploading a file.
If you want to stop the server, you can just kill the processes:
pkill -x pure-ftpd
Of course, don't use -9 unless the server is completely stuck. -9 doesn't
let processes any chance to clean things up and should never be used except
where there's absolutely nothing else to do.
Pure-FTPd can also run with the help of a super-server, like telnet, wu-ftp,
finger or Qmail. This is not recommended. If this is an option, start it in
standalone mode instead. Using a super-server is usually slower than the
standalone mode. But if you love tcpwrappers or built-in filtering abilities
of your super-server, Pure-FTPd can cope with them.
Unix has tons of super-servers: Inetd (the most common one), TCPserver,
G2S, Xinetd, Rlinetd, ... Only the first three will be covered here, but
integration with other super-servers should be painless.
The line may also end with "proftpd" or "wuftpd", but it should start with
"ftp stream tcp".
service ftp
{
socket_type = stream
server = /usr/local/sbin/pure-ftpd
protocol = tcp
user = root
wait = no
disable = no
}
You can add that line to your system local startup scripts
(usually /etc/rc.d/boot.local or /etc/rc.d/rc.local) . If it doesn't work,
replace 'tcpserver' with its full path (eg. '/usr/local/bin/tcpserver') .
The previous steps should be enough to get a running FTP server. But you can
add some command-line arguments to change its behavior. These arguments have
to be added after the pure-ftpd path in your super-server configuration.
For instance, you want to add the '-s' and '-a 42' flags. Here are what the
configuration lines will look like in your super-server:
- Inetd:
ftp stream tcp nowait root /usr/sbin/tcpd
/usr/local/sbin/pure-ftpd -s -a42
or
ftp stream tcp nowait root /usr/local/sbin/pure-
ftpd pure-ftpd -s -a42
If you use Inetd, don't put space between options and arguments. e.g. use
-a42 instead of -a 42 . Inetd has trouble dealing with a lot of options and
with characters like ':' .
- Xinetd:
service ftp
{
socket_type = stream
server = /usr/local/sbin/pure-ftpd
server_args = -s -a 42
protocol = tcp
user = root
wait = no
disable = no
}
- TCPserver:
tcpserver -DHRl0 0 21 /usr/local/bin/pure-ftpd -s -a 42 &
- G2S:
{
SERVICE ftp
DESCRIPTION "Pure-FTPd"
RUN /usr/local/sbin/pure-ftpd -s -a 42
}
- '-0': when a file is uploaded and there is already a previous version of the
file with the same name, the old file will neither get removed nor truncated.
Upload will take place in a temporary file and once the upload is complete,
the switch to the new version will be atomic. For instance, when a large PHP
script is being uploaded, the web server will still serve the old version and
immediately switch to the new one as soon as the full file will have been
transferred.
- '-2 <file>': when using TLS, set the path to the certificate file.
If you want to chroot() everyone, but root, use the following flag:
- '-A': chroot() everyone, but root. There's no such thing as a trusted
group. '-A' and '-a <gid>' are mutually exclusive.
- '-b': Ignore parts of RFC standards in order to deal with some totally
broken FTP clients, or broken firewalls/NAT boxes. Also, non-dangling
symbolic links are shown as real files/directories.
- '-C <max connection per ip>': Limit the number of simultaneous connections
coming from the same IP address. This is yet another very effective way to
prevent stupid denial of services and bandwidth starvation by a single user.
It works only when the server is launched in standalone mode (if you use a
super-server, it is supposed to do that) . If the server is launched with
'-C 2', it doesn't mean that the total number of connections is limited to 2.
But the same client, coming from the same machine (or at least the same IP),
can't have more than two simultaneous connections. This feature needs some
memory to track IP addresses, but it's recommended to use it.
- '-d': Send various debugging messages to the syslog. Don't use this
unless you really want to debug Pure-FTPd. Passwords aren't logged.
Duplicate '-d' to log responses, too.
- '-D': List files beginning with a dot ('.') even when the client doesn't
append the '-a' option to the list command. A workaround for badly
configured FTP clients. If you are a purist, don't enable this. If you
provide hosting services and if you have lousy customers, enable this.
- '-e': Only allow anonymous users. Use this on a public FTP site with no
remote FTP access to real accounts.
- '-g <pid file>': Change the location of the pid file when the server is
run in standalone mode. The default is /var/run/pure-ftpd.pid .
- '-I <timeout>': Change the maximum idle time. The timeout is in minutes
and defaults to 15 minutes. Modern FTP clients are trying to fool timeouts
by sending fake commands at regular interval. We disconnect these clients
when they are idle for twice (because they are active anyway) the normal
timeout.
- '-J <ciphers>': Sets the list of ciphers that will be accepted for
TLS connections.
- '-K': Allow users to resume and upload files, but *NOT* to delete or rename
them. Directories can be removed, but only if they are empty. However,
overwriting existing files is still allowed (to support upload resume) . If
you want to disable this too, add -r (--autorename) .
- '-m <cpu load>': Don't allow anonymous download if the load is above <cpu
load> . A very efficient way to prevent overloading your server. Upload is
still allowed, though.
- '-n <max files>:<max size>': If the server has been compiled with support
for virtual quotas, enforce these quota settings for all users (except
members of the 'trusted' group) . <max size> is in Megabytes. See the
"virtual quotas" section later in this document.
- '-N': NAT mode. Force ACTIVE mode. If your FTP server is behind a NAT box
that doesn't support applicative FTP proxying, or if you use port
redirection without a transparent FTP proxy, use this. Well... the previous
sentence isn't very clear. Okay: if your network looks like this:
(FTP server)-------(NAT/masquerading gateway/router)------(Internet)
and if you want people coming from the internet to have access to your FTP
server, please try without this option first. If Netscape clients can
connect without any problem, your NAT gateway rulez. If Netscape doesn't
display directory listings, your NAT gateway sucks. Use '-N' as a workaround.
- '-O <format>:<log file>': Record all file transfers into a specific log
file, in an alternative format. Currently, four formats are supported: CLF
(Apache-like), Stats, W3C and xferlog.
<date> is a GMT timestamp (time()) and <session id> identifies the current
session. <file> is unquoted, but it's always the last element of a log line.
"U" means "Upload" and "D" means "Download".
Warning: the session id is only designed for statistics purposes. While it's
always an unique string in the real world, it's theoretically possible to have
it non unique in very rare conditions. So don't rely on it for critical
missions.
- '-p <first port>:<last port>': Use only ports in the range <first port>
to <last port> inclusive for passive-mode downloads. This is especially
useful if the server is behind a firewall without FTP connection tracking.
Use high ports (40000-50000 for instance), where no regular server should be
listening.
- '-P <ip address or host name>': Force the specified IP address in reply to
a PASV/EPSV/SPSV command. If the server is behind a masquerading (NAT) box
that doesn't properly handle stateful FTP masquerading, put the ip address
of that box here. If you have a dynamic IP address, you can put the public
host name of your gateway, that will be resolved every time a new client will
connect.
- '-u <uid>': Don't allow uids below <uid> to log in. '-u 1' denies access
to root (safe), '-u 100' denies access to virtual accounts on most Linux
distros.
- '-U <umask for files>:<umask for dirs>': Change the file creation mask.
The default is 133:022. If you want a new file uploaded by a user to only be
readable by that user, use '-U 177:077'. If you want uploaded files to be
executable, use 022:022 (files will be readable -but not writable- by other
users) or 077:077 (files will only be executable and readable by their
owner) . Please note that Pure-FTPd support the SITE CHMOD extension, so a
user can change the permissions of his own files.
- '-V <ip address>': Allow non-anonymous FTP access only on this specific
local IP address. All other IP addresses are only anonymous. With that
option, you can have routed IPs for public access and a local IP (like
10.x.x.x) for administration. You can also have a routable trusted IP
protected by firewall rules and only that IP can be used to login as a
non-anonymous user.
- '-v <name>': Set the service name for Apple's Bonjour. Only available on
MacOS X when Bonjour support is compiled in.
- '-w': Support the FXP protocol only for authenticated users. FXP works
with IPv4 and IPv6 addresses.
- '-W': Support the FXP protocol. FXP allows transfers between two remote
servers without any file data going to the client asking for the transfer.
However:
****************************************************************************
****************************************************************************
****************************************************************************
When used in conjunction with "-a", members of the trusted group can bypass
'-x'/'-X' restrictions.
****************************************************************************
/usr/local/sbin/pure-ftpd -y 3:20 -c 15 -C 5 -B
Here, we allow:
* A max total of 15 sessions.
* 5 connections max coming from the same IP address.
* 3 connections max with the same user name.
* 20 anonymous users max.
With such a setup, a single user can't easily fill all slots.
- '-z': Allow anonymous users to read files and directories starting with a
dot ('.') .
If you prefer long options (GNU-style) over standard ones, the following
aliases are available. You can get this list at any time by typing
'pure-ftpd --help' .
-0 --notruncate
-1 --logpid <file>
-4 --ipv4only
-6 --ipv6only
-8 --fscharset <charset>
-9 --clientcharset <charset>
-a --trustedgid <gid>
-A --chrooteveryone
-b --brokenclientscompatibility
-B --daemonize
-c --maxclientsnumber <number>
-C --maxclientsperip <number>
-d --verboselog
-D --displaydotfiles
-e --anonymousonly
-E --noanonymous
-f --syslogfacility <facility>
-F --fortunesfile <file>
-g --pidfile <path to pid file>
-G --norename
-h --help
-H --dontresolve
-i --anonymouscantupload
-I --maxidletime <time (min)>
-j --createhomedir
-J --tlsciphersuite <ciphers>
-k --maxdiskusagepct <percentage>
-K --keepallfiles
-l --login <auth> or <auth>:<config file>
-L --limitrecursion <number:number>
-m --maxload <load>
-M --anonymouscancreatedirs
-N --natmode
-o --uploadscript
-O --altlog <format>:<log file>
-p --passiveportrange <minport:maxport>
-P --forcepassiveip <ip address>
-q --anonymousratio <upload ratio>:<download ratio>
-Q --userratio <upload ratio>:<download ratio>
-r --autorename
-R --nochmod
-s --antiwarez
-S --bind <ip address,port>
-t --anonymousbandwidth <bandwidth (KB/s)>
-T --userbandwidth <bandwidth (KB/s)> or [<up bw>]:[<down bw>]
-u --minuid <uid>
-U --umask <mask>
-v --bonjour <name>
-V --trustedip <ip address>
-w --allowuserfxp
-W --allowanonymousfxp
-x --prohibitdotfileswrite
-X --prohibitdotfilesread
-y --peruserlimits <per user max>:<max anonymous sessions>
-Y --tls <0:no TLS | 1:TLS+cleartext | 2:enforce TLS |
3: enforce encrypted data channel as well>
-z --allowdotfiles
-Z --customerproof
-W --allowanonymousfxp
-z --allowdotfiles
-w --allowuserfxp
-O --altlog <format>:<log file>
-t --anonymousbandwidth <bandwidth (KB/s)>
-M --anonymouscancreatedirs
-i --anonymouscantupload
-e --anonymousonly
-q --anonymousratio <upload ratio>:<download ratio>
-s --antiwarez
-r --autorename
-A --chrooteveryone
-9 --clientcharset <charset>
-j --createhomedir
-Z --customerproof
-B --daemonize
-D --displaydotfiles
-H --dontresolve
-h --help
-4 --ipv4only
-6 --ipv6only
-K --keepallfiles
-c --maxclientsnumber <number>
-C --maxclientsperip <number>
-k --maxdiskusagepct <percentage>
-I --maxidletime <time (min)>
-m --maxload <load>
-u --minuid <uid>
-N --natmode
-E --noanonymous
-R --nochmod
-G --norename
-0 --notruncate
-v --bonjour <name>
-p --passiveportrange <minport:maxport>
-y --peruserlimits <per user max>:<max anonymous sessions>
-g --pidfile <path to pid file>
-X --prohibitdotfilesread
-x --prohibitdotfileswrite
-f --syslogfacility <facility>
-J --tlsciphersuite <ciphers>
-a --trustedgid <gid>
-V --trustedip <ip address>
-U --umask <mask>
-o --uploadscript
-T --userbandwidth <bandwidth (KB/s)> or [<up bw>]:[<down bw>]
-Q --userratio <upload ratio>:<download ratio>
-d --verboselog
If a 'ftp' user exists and its home directory exists, Pure-FTPd will
accept anonymous login, as 'ftp' or 'anonymous'.
There's no need for 'bin', 'lib', 'etc' and 'dev' directories, nor any
external program. Don't chown the public files to 'ftp', just writable
directories such as 'incoming'.
In each directory, you may also have a '.message' file. Its content will be
printed when a client enters the directory. Such a file can contain important
information ("Don't download version 1.7, it's broken!") .
A funny random message can be displayed in the initial login banner. The
random cookies are extracted from a text file, in the standard "fortune"
format. If you installed the "fortune" package, you should have a directory
(usually /usr/share/fortune) with binary files (xxxx.dat) and text files
(without the .dat extension) . To use Pure-FTPd cookies, just add the name
of a text file to the '-F' option. For instance:
/usr/local/sbin/pure-ftpd -F /usr/share/fortune/zippy
If you want to have your own fortune files, just create a text file with the
following structure.
For security paranoia, the text file has to be readable by everybody (chmod
644 the file if necessary), or the server will ignore it.
Apart from the "-a" flag, Pure-FTPd has another way to fine-tune chroot()
rules. Let's take an /etc/passwd entry:
mimi:x:501:100:Mimi:/home/mimi:/bin/zsh
Without any special rule, mimi will be able to log in and to retrieve any
public-readable file in the filesystem. Now, let's change a bit of its home
directory:
mimi:x:501:100:Mimi:/home/mimi/./:/bin/zsh
So what? Mimi's home directory is still the same and common applications
shouldn't notice any difference. But Pure-FTPd understands "chroot() until
/./". So when mimi next carries out a FTP log in, only the /home/mimi
directory will be reachable, not the whole filesystem. If you don't like the
"-a" and its trusted gid thing, this is a good way to only chroot() some
users. Another trick is to add something after "/./":
mimi:x:501:100:Mimi:/home/mimi/./public_html:/bin/zsh
If a user is chrooted with the /./ trick *and* belongs to the trusted group
(-a) he *will* be chrooted, but he will have no ratio and will be allowed to
access dot files.
If you want to force people to upload new files before being able to
download other files, ratios are for you. It's a very good way to get lotsa
fresh stuff on a public FTP server and a must for warez traders. I don't
like that kind of business, but well... Pure-FTPd has to be designed to
please everybody.
To enable ratios, just use the '-q' option, followed by the upload:download
ratio:
-q 2:5
If ratios should apply to everyone (anon and non-anon), use the '-Q' option
the same way.
Note: 'root' never has ratios. Neither have users of the trusted group when
'-Q' in used with the '-a' or '-A' option.
* You want to limit FTP throughput so that uploading and downloading files
through that protocol can't fill up your network bandwidth.
* You want to allow less bandwidth to your anonymous users than your
authenticated ones. So that during a bandwidth starvation, real users can
still upload/download properly.
Example:
/usr/local/sbin/pure-ftpd -t 64
And uploading/downloading files can't take more than 64 KB/sec whatever real
bandwidth you have.
/usr/local/sbin/pure-ftpd -t 256:64
/usr/local/sbin/pure-ftpd -t 256:
/usr/local/sbin/pure-ftpd -t:64
With no column, the value applies to both, so '-t 64' is an alias for
'-t 64:64' .
Using Virtual servers is a convenient way of hosting several FTP sites on the same
computer. Let's say, you got two customers. The former owns the 'cgx.org'
domain name, while the latter owns the 'example.com' domain name. Both are
hosted on the same computer, but they don't want to share the same files.
ftp://ftp.cgx.org/ should show different content than ftp://ftp.example.com/
.
The FTP protocol doesn't allow name-based selection. So, if you want to host
<N> different virtual FTP servers on the same host and keep the standard port,
you need <N> different IP addresses. Yes, Sir. Or use HTTP.
Assign the needed IP addresses to your network adapter (with "ifconfig eth0:x
..." or "ip addr add dev eth0 a.b.c.d").
Now, create a /etc/pure-ftpd directory if it doesn't exist:
mkdir /etc/pure-ftpd
To add a virtual FTP server, you only need to create a symbolic link in
/etc/pure-ftpd/ from the virtual host IP to the directory that contains the
file for that virtual host.
Example:
ln -s /home/customers/example.com/ftp /etc/pure-ftpd/216.226.17.77
ln -s /home/customers/cgx.org/ftp /etc/pure-ftpd/212.73.209.252
With that feature, every account on the server can have its own public
anonymous FTP area. If you are providing hosting services, this is a nice
feature for your customers.
If you are a hosting service provider and if each customer has its own IP
address, it may be a nice idea to have a trusted IP you give to all your
customers, so that they can manage the files in their account. That IP is
the same for all customers. You can easily restrict access to that IP with
firewall rules if your customers have static IP addresses.
Use '-V <trusted ip>' and link /etc/pure-ftpd/<customer ip> to
~customer/ftp . Every customer will have his own *anonymous only* FTP
server and hackers will have to find the trusted IP to get in.
Pure-FTPd has full IPv6 support (native IPv6 addresses and 4-in-6
addresses). But use a super-server that also understands the IPv6 protocol,
like Rlinetd or Xinetd. Recent versions of Inetd should also be ok
(unverified). IPv6 is supported everywhere: logging, configuration
switches, virtual hosts, protocol (EPSV/EPRT support), name resolution...
Log messages are sent to the syslog daemon. You can disable logging with
'-f none'.
If you want all FTP messages to be redirected to a file, say /var/log/ftp,
add this line to your /etc/syslog.conf file:
ftp.* /var/log/ftp
You can also drop your old "syslogd" and "klogd" programs for Metalog, an
efficient alternative: http://metalog.sourceforge.net/
/home/ftp//pub/bla.jpg
Since 0.97.7, you can type 'pure-ftpwho' at any time to watch current active
sessions.
+------+---------+-------+------+-------------------------------------------+
| PID | Login |For/Spd| What | File/IP |
+------+---------+-------+------+-------------------------------------------+
| 2239 | jedi | 00:17 | D/L | XFree86-clients-4.0.3.tar.gz |
| '' | '' | 41K/s| 33% | -> nestea.funboard.de |
+------+---------+-------+------+-------------------------------------------+
| 2385 | ftp | 00:02 | IDLE | |
| '' | '' | | | -> gw2.crn.kjop.co.uk |
+------+---------+-------+------+-------------------------------------------+
'D/L' means that the client is downloading and 'U/L' means he's uploading
some file whose name is shown in the next column. '33%' is the real-time
completion of the current operation. '41K/s' is the bandwidth used by the
client. You can track down who's starving your bandwidth with this.
'-c': the program is called via a web server (CGI interface) . Output is a
full HTML page with the initial content-type header. This option is
automatically enabled if an environment variable called GATEWAY_INTERFACE is
found. This is the default if you can access the program from a CGI-enabled web
server (Apache, Roxen, Caudium, WN, ...) .
'-n': don't resolve host names and only show IP addresses (faster).
'-s': output an easily parsable format for shell scripts (but not very user
friendly) .
There's only one line per client, with only numeric data, delimited by a '|'
character. It's not very human-readable, but it's designed for easy parsing by
shell scripts (cut/sed) . '|' characters in user names or file names are
quoted ('|' becomes '\|') .
'-W': output an HTML page with no header and no footer. This is an embedded
mode, suitable for inline calls from CGI, SSI or PHP scripts.
'-x': output well-formed XML data for post-processing. This is the most
acurate mode. Time is in seconds and file sizes are in bytes (in other
output formats, sizes are in kbytes for easier readability) .
'-v': verbose output in text mode. Additional info includes the size of
files being downloaded/uploaded, the local IP or local host name and the
connection port. This is especially useful for virtual hosts. Here's a
sample output of 'pure-ftpwho -v':
+------+---------+-------+------+-------------------------------------------+
| PID | Login |For/Spd| What | File/Remote IP/Size(Kb)/Local IP |
+------+---------+-------+------+-------------------------------------------+
| 9086 | j | 00:04 | DL | linux-2.4.4.tar.bz2 |
| '' | '' | 22K/s| 27% | -> localhost |
| '' | '' | | | Total size: 20859 Transferred: 5632 |
| '' | '' | | | <- localhost:21 |
+------+---------+-------+------+-------------------------------------------+
After an upload, any external program or shell script can be spawned with the
name of the newly uploaded file as an argument. You can use that feature to
automatically send a mail when a new file arrives. Or you can pass it to a
moderation system, an anti-virus, a MD5 signature generator or whatever you
decide can be done with a file.
IMPORTANT:
For security purposes, the server never launches any external program. It's
why there is a separate daemon, that reads new uploads pushed into a named
pipe by the server. Uploads are processed synchronously and sequencially.
It's why on loaded or untrusted servers, it might be a bad idea to use
pure-uploadscript with lengthy or cpu-intensive scripts.
The easiest way to run pure-uploadscript is 'pure-uploadscript -r <script>':
/usr/local/sbin/pure-uploadscript -r /bin/antivirus.sh
The absolute path of the newly uploaded file is passed as a first argument.
Some environment variables are also filled with interesting values:
- '-u <uid>' and '-g <gid>' to switch the account pure-uploadscript will run
as. The script will be spawned with the same identity.
Please have a look at the man page ('man pure-uploadscript') for additional
info.
The built-in 'ls' supports all common options of a regular 'ls' command.
Here are the ones you should know for a better life with FTP:
If you aren't very familiar with Unix, log in to your FTP server and try
these variants:
ls
ls -F
ls -l
ls -la
ls -lR
ls -Sl
ls -Slr
ls -tl
ls -tlr
ls */gnome*.rpm
------------------------ VIRTUAL QUOTAS ------------------------
With virtual quotas, you can restrict the maximum number of files and the
total size of a user directory.
These quotas are "virtual" because they aren't handled at kernel-level, but
by the FTP server itself. There are some advantages over kernel quotas:
- Virtual quotas are specific to the FTP server. You can have different
system quotas to handle other files (eg. mail) on the same partition.
- You can have different virtual quotas for every user, even if they share
the same system uid.
- Virtual quotas are working even on filesystems that don't support system
quotas.
However, virtual quotas are slower and can't be as reliable as kernel quotas,
so don't trust them ultimately, they are probably races allowing to bypass
them. Also the filesystem users directories are on must properly support file
locking.
Quotas can be enabled for all users for the -n (--quotas) option. This
option is followed by the max number of files and the max size (in Megabytes)
. Every user will have the same quota. Exception: members of the trusted
group, if -a is enabled.
You can also have different quotas for every user if you use PureDB or SQL
databases. See the "README.Virtual-Users" file for more info about PureDB
databases.
So, if you want 1000 files max and 10 Mb max for all your customers, run
the server like this:
/usr/local/sbin/pure-ftpd -n 1000:10
".ftpquota" files are created on demand when they are missing. However, when
they are created, the server assumes that the account was empty. If this is
not the case, you must run the "pure-quotacheck" utility to create an
initial ".ftpquota" file.
"pure-quotacheck" is a tool that computes the size and the number of files
in a directory and create a ".ftpquota" file with this info.
You can run pure-quotacheck whenever you want, even when ".ftpquota" files
are already there. This is even a good idea to run this for all users in
crontab, so that stored quotas are always exact, even if something went wrong
(server bug, filesystem corruption, savagely killed server, etc) .
-l unix
-l pam
-l puredb:/path/to/puredb_database
-l ldap:/path/to/ldap_config_file
-l mysql:/path/to/mysql_config_file
-l pgsql:/path/to/postgres_config_file
-l extauth:/path/to/authd/socket
(read README.Authentication-Modules for more info about external
authentication)
Multiple authentication methods can be chained. For instance, you can run the
server like this:
/usr/local/sbin/pure-ftpd -lldap:/etc/pureftpd-ldap.conf \
-lpuredb:/etc/pureftpd.pdb -lunix
Every method is tried in order. With the previous command line, an LDAP
directory is probed first. If a user isn't found in the directory, a
PureDB database is scanned for the same user name. If that user is still not
found, /etc/passwd is scanned.
If the user is found in the LDAP directory, but the given password is wrong,
further authentication methods are skipped.
If you don't specify any -l option, PAM is assumed by default if the server
is compiled with PAM support and Unix is assumed by default otherwise.
Directory aliases provides "shortcuts" for the "cd" command. For instance,
if you define an alias called "pictures" for "/usr/misc/pictures", when an
user will type "cd pictures" and if no real "pictures" directory exists, he
will be automatically redirected to "/usr/misc/pictures". Unlike symbolic
links, "cd pictures" will work from any directory. Tildes are *not* expanded.
a user can get the list of available aliases with the following command:
SITE ALIAS
Example:
pictures
/usr/misc/pictures
sources
/usr/src
When privilege separation is enabled, each session will spawn two processes :
a "privileged" process running as root, but that can only do very basic
and trusted actions (binding a port and remove the ftpwho scoreboard) and
the "client" process. The "client" process definitely revokes all privileges
after authentication and chroot() and punctually communicates with the
parent over a private channel.
Some old broken operating systems may allow the ptrace() system call on
processes that revoked privileges. On these platforms, enabling privilege
separation is a bad idea if untrusted users also have shell access. Use the
src/ptracetest program to check this. At least Solaris, ISOS, MirBSD,
OpenBSD, DragonflyBSD, FreeBSD and Linux are known to be safe.
Some modern clients like lftp will also try to use UTF-8 if the server
supports it.
Thus, charsets conversion can be very useful when dealing with file names
containing non-english characters.
/usr/local/sbin/pure-ftpd --fscharset=ISO-8859-15
But optionnally, you can specify the default charset for clients, with
--clientcharset:
If you are going to use Pure-FTPd on a highly loaded server, here are some
hints to get the best performances:
- Compile with:
- Run it in standalone mode. Don't use -C, don't enable pure-ftpwho nor
pure-uploadscript (-o), nor per-user limits (-y) .
- Increase your system max descriptors number and local port range. On a
Linux kernel, you can try:
/usr/local/sbin/pure-ftpd -f none -H
>>> QUOTE:
Drop into single user mode (do a shutdown now or boot -s) and enter
hw.ata.wc="1"
kern.ipc.nmbclusters="60000"
vfs.vmiodirenable=1
kern.ipc.maxsockbuf=2097152
kern.ipc.somaxconn=8192
kern.ipc.maxsockets=16424
kern.maxfiles=65536
kern.maxfilesperproc=32768
net.inet.tcp.rfc1323=1
net.inet.tcp.delayed_ack=0
net.inet.tcp.sendspace=65535
net.inet.tcp.recvspace=65535
net.inet.udp.recvspace=65535
net.inet.udp.maxdgram=57344
net.local.stream.recvspace=65535
net.local.stream.sendspace=65535
- You should always avoid the use of spaces in login names: applications
that are parsing log files often choke on this.
- On Solaris, to get chroot to work with pure-ftpd you need a dev directory
in your new rootdir with these:
ftp> ls
425 Can't create the data socket: Bad file number.
If all your users are chrooted, you have to create these files in every home
directory. Here's how:
mkdir dev
mknod dev/tcp c 11 42
chmod 0666 dev/tcp
mknod dev/udp c 11 41
mknod dev/zero c 13 12
mknod dev/ticotsord c 105 1
If you have question, suggestions or patches, feel free to post them to the
mailing list. Newbies and silly ideas are welcome.
Thank you,