Debugging Problems

Users of ProFTPD will often encounters problems. It happens with all software, not just ProFTPD. How, then, does the user track down the cause of the problem, and fix it? This is the art of debugging. When users post these problems are the mailing lists, it is extremely helpful to include the following bits of information to help find the answer. Even better is when the user follows these steps and determines the solution for themselves.

Know the Version
Various problems afflict various versions of the code, so when tracking down problems, it is good to know the version being used: 

  proftpd -vv
It is possible that the problem you are encountering is due to some bug that may already be fixed in a more current version, fixed in the CVS repository, or has a bug report with an attached patch. Searching http://bugs.proftpd.org will often yield useful information, depending on the keywords used in the search.

Know the Modules
System administrators who compile and install the server from the souce code distribution will probably already know this, but administrators who install using RPMs or other package formats may not know the specifics of the contained pre-built binary. To list the modules compiled into the server: 

  proftpd -l
Knowing the modules helps to pinpoint the source of error messages (e.g. mod_tls and certificate files).

Perform Configuration Check
When making changes to the configuration file, it is often helpful to make sure that your changes are valid. The easiest way to do this is to do an informative syntax check: 

  proftpd -td5
The -t option directs the server to only do a syntax check, to parse the configuration file but stop before actually starting its operations as a server. The -d5 will cause the server to display debugging messages during this testing of the configuration file. Another useful command is: 
  proftpd -c /path/to/new/config/file -td5
which lets you test the syntax of some new configuration file before it is put into production. If you are still having problems, and you have verified that your proftpd.conf is correct, the next step is see what debugging messages are generated during an FTP session, as described next.

Collect Debug Information
proftpd has built-in debug information reporting capabilities - the trick is in enabling that reporting, and tracking down where it is sent. The easiest way to get the debugging information is to start the server from the command line using: 

  proftpd -nd6
Note: make sure that no other proftpd instances are running before using this command, otherwise you will see: 
  Failed binding to 0.0.0.0, port 21: Address already in use
This message means that some other program is already bound to the socket at that address/port. This message will also appear if you attempt the debugging command with a ServerType of inetd; this is described below.

Once working, the above debugging command will display lots of information on the connected terminal's screen, both as the server starts up and during the servicing of any clients. If clients are having trouble logging in or authenticating, the debug messages reported by the server when a client connects are much more useful than knowing the messages displayed by the client, as the client does not know why it cannot log in. If asked to send debugging information to the mailing list, you can send the relevant snippets (if you know what the relevant debug messages are), or you can capture the debug output to a file: 

  proftpd -nd5 2>&1 >& /path/to/debug/file
and send that file, compressed, along with your post.

The above method works if you have ServerType standalone in your configuration file. If you run the server in inetd mode instead, and are unable or unwilling to make the changes necessary to run the server in standalone mode for the sake of debugging, then use of the SystemLog configuration directive is necessary for capturing the debug information. Add this directive to your configuration file, and add -d5 to your /etc/inetd.conf's ftp line, or to the server_args tag in your xinetd configuration file for the server. Be sure to restart inetd/xinetd so that your configuration changes will take effect.

Note that use of the SystemLog directive is not necessarily confined to inetd mode servers. If you are interested in letting your standalone server run unattended and want to have that debugging information in the log file, use SystemLog and add -d5 (or whatever your preferred debug level is) to the server startup script.

As of version 1.2.8rc1, ProFTPD supports a DebugLevel configuration directive. This lets you set a debugging level in your proftpd.conf file, without needing to edit inetd.conf or xinetd configuration file.

Locate Log Files
A common response on the mailing lists to a posted question is: "What do your server logs say?" Locating the server's log files can be troublesome, depending on your configuration. If the SystemLog configuration directive is in effect, you know exactly where the server's log file is. If not, then by default the server uses syslog for logging. The location of syslog'd log files is set in your system's /etc/syslog.conf file. You may need to read your system's man pages for syslog.conf or syslogd to understand the format of that file. Note that the server will log using a syslog facility of daemon (and level debug when debugging) for most of its messages; during authentication, messages are logged using the authpriv facility.

Common Problems
One common question is: "I changed the configuration file, but the new configuration is not being seen!" The solution depends on your configured ServerType. Almost certainly it will be standalone, as inetd-mode servers pick up configuration changes almost instantly (the server is started from the ground up for each connection). For configuration changes to be seen by a standalone server, you need to either stop, then start the server (the hard way), or to send the HUP signal the the daemon process.

Another common question involves use of ProFTPD's <Limit> directive to restrict certain FTP commands. These limits always function in addition to the normal filesystem permissions, not instead of them. If having problems writing, deleting, or updating files, check your directory and file permissions first.

Once you have the debug output and various other information, and are still in need of help, search the FAQ, Userguide, and mailing list archives for material related to the problem. If you're unable to find anything helpful in these sources, post your question to the appropriate mailing list. Be sure to include the version used, your proftpd.conf, and possibly any debug information.

The following document describes how to ask good questions that are likely to be answered: 

  http://www.catb.org/~esr/faqs/smart-questions.html

Last Updated: $Date$