Structure

First you should understand the directory and filestructure of OpenFTPD (which is inspired by UNIX) and then start editing files. There is a global configuration file, the so called registry and several other config files all placed in the etc/ directory.

The output of OpenFTPD can be customized with the message files in msg/, there you can change the welcome message for example.

Registry

The main configuration file of OpenFTPD is the registry (etc/ftpd.reg). You can change this file either on the shell with a normal texteditor or change its keys using SITE commands from any FTP client. The advantage of using the SITE REG command is that it doesn't require a restart of OpenFTPD to apply changes.

Configuration files

Besides the registry there are several configuration files in the etc/ directory.

This configuration allows to assign fixed ownership and permissions to certain directories. Its main purpose is to mount read-only media like CDROM. The first bit toggles the hidden flag.

This is the dupe checker. Whenever a file with a matching wildcard is to be uploaded, the program/script is executed. The script must return 0 if upload is ok, otherwise 1.

This is the most difficult configuration file (to be honest: the other ones are trivial). Limits.cfg is for restricting the number of simulanous users and the bandwidth consumed by the server, depending on the time of day and the day of week.

Each line is made of four sections: day of week, time of day, session limit and bandwidth limit. Each section has a different format, but there are two special operators that are valid for any section: * and ~. * means any time / no restriction. ~ means same values as the previous rule. Obviously, ~ cannot be used in the first rule (the first line), because there is no previous.

day of week must be in the format SS-EE, SS and EE may be mo, tu, we, th, fr, sa, su.

time of day must be in format HH:MM-HH:MM, HH must be in 24-hour format.

session limit must be in the format variable=value[,variable=value]...
variables are a (anonymous logins), u (user logins), i (anonymous logins per IP), d (anonymous logins per domain). a and u may be combined as one variable, meaning the sum of anonymous and user logins is given.

bandwidth limit must be in the format d=value,u=value or ud=value. value is the bandwidth limit in KB per second. Use 0 (zero) to prevent upload or download, -1 for unlimited bandwidth. ud means that upload and downloads count in total, otherwise they are treated separate.

The method that OpenFTPD hands out bandwith to user sessions is to calculate an average speed based on the bandwidth and the maximum number of users. When there is more than 50% bandwidth left, users get the double average bandwidth. When the remaining bandwith is between 50 and 25%, users get average bandwidth, otherwise (<25%) half average. The reason for this is, that there will be rarely all sessions in use. The first sessions take up the most bandwidth, further sessions average and in the unlikely case there are even more sessions, this additional sessions suffer penalty.

There is another method for handing out bandwith. You can specify a factor after the value, separated by a "/", e.g. d=100/3. In this case, users always get the remaining bandwidth divided by the factor. This method hands out even more bandwith to earlier sessions, and fewer to later ones than the first method. This method is extremely useful when you do not set the maximum number of logins, because in this case f4a cannot determine the average bandwidth.

The smallest amount of bandwith f4a hands out is 1 KB/s. f4a hands this amount out, even if there is no remaining bandwith left, or even if the maximum bandwith is already exceeded. An exception to this is if the maximum bandwidth is zero, because this prevents uploads or downloads at all.

The lines of the example explained:

mo-fr 08:00-18:00 u=20,a=0 ud=50 means:
On Mondays, Tuesdays, Wednesdays, Thursdays and Fridays from 08:00 to 18:00 there is a limit of 20 user sessions. No anonymous access is allowed in this time. The Bandwidth for uploads and downloads is restricted to 50 KB/s total.

sa-su ~ ua=40,i=1,d=2 u=50,d=50 means:
On Saturdays and Sundays from 08:00 to 18:00 the number of user and anonymous sessions is limited to 40 (There can be 10 user, 30 anonymous or vice versa). There is only one anonymous login per IP allowed, and 2 anonymous logins from the same class C network. The upload bandwidth is limited to 50 KB/s, and the download bandwidth too, resulting in a total bandwidth of 100 KB/s.

~ 18:00-08:00 * u=100/2 means:
On Saturdays and Sundays from 00:00 to 08:00 and 18:00 to 23:59 there is no limit in user sessions. However, upload bandwidth is restricted to 100 KB/s. The bandwidth is handed out by factor 2. This means: The server always hands out half of the available bandwidth. There is no download bandwidth limit.

* * u=100,a=100,i=2 * means:
On any time, there may be 100 users plus 100 anonymous online. There are up to two anonymous logins from the same IP allowed. There is no restriction for anonymous logins regarding the class C network. There is absolutely no bandwidth limit.

This file allows you to define seperated sections on your site, each with own stats and settings. It's possible to use the same stat/config file on multiple sections. The config files are expected in "etc/sections".

Message files

To customize the output of OpenFTPD or start scripts on several events you should check the message files in the msg/ directory.

User and group specific messages must be stored under msg/usr/<username> and msg/grp/<groupname>. User specific messages are preferred over group specific, and group specific over default. The following messages are supported:

Variables

There are several variables that can be used to either show dynamic information or as arguments for scripts.

The most important thing is the possibility to run external programs from these message files, this is a good way to do several actions on the even of your choice (for example announce new directories to an irc sitebot).

%#!<program> <arguments> = runs program with arguments, arguments can contain variables, too. This variable is valid only when it appears at the beginning of a line.

Color codes

These color codes can be used in all message files or scripts:

Users are able to choose if their client supports colors with the SITE COLOR command.