Introduction

NcFTPd has its own dynamic report generation package. This allows an administrator to view various statistics from a web browser. This requires that there be a HTTP (web) server installed on the machine that NcFTPd runs on. The report package consists of the following reports:

Installation

The report package is included with the NcFTPd download package, and is in the reports subdirectory. The primary file of interest is the reports.cgi script.

The report package is also available as a separate download. Run gzip -d -c reports.tar.gz | tar xf - to produce the uncompressed Perl script file, reports.cgi.

The reports requires Perl version 5 to run. Most systems already have Perl installed, especially since this is also required by the NcFTPd installer (the install_ncftpd.pl script).

Installing the CGI script

The reports.cgi script can be placed anywhere in your web server's document tree such that the file can be executed as a CGI program. Often, this means moving the file to the cgi-bin directory.

For example, with the Apache web server, you might have an entry like this in your httpd.conf file (but note that by default Apache does not include the needed ExecCGI in Options):

In this case, you could simply move the reports.cgi file to the /home/httpd/share/cgi-bin directory. However, we recommend that you create a separate directory for the reports, so you can properly secure the reports so that only authorized personnel can run the reports.

Here's a simple example with Apache that restricts the reports to users on the internal network, whose IP addresses are in the 192.168.1.0/24 network. In this case, you would create the /home/httpd/ncftpd directory, move the reports.cgi file to the directory, edit the httpd.conf file, and then restart httpd.

For other web server software, the process is similar -- either move the file to the cgi-bin directory, or configure it so that files with a .cgi extension are executed as CGI programs.

Configuring the script

Once you have decided on where the script will reside, you next need to edit the script itself with a text editor and configure a few variables. Skip down approximately 93 lines to the section that reads Change the following values as needed.

The first few variables to configure are $general_cf and $domain_cf. These point to the pathnames of your NcFTPd configuration files. Change the values so that they correspond to the actual pathnames used on your system.

You will also need to ensure that the general.cf and domain.cf files are readable by the web user (the user and group privileges that the web server processes are running with). Don't forget that the directories leading up to the files also need to be accessible!

The $plotting_graphs option may be set to "yes" or "no". The General Report can produce graphic output, for example, showing a chart of the number of files downloaded per day over the course of 30 days. Unfortunately, this feature complicates the installation because it requires a separate program (Gnuplot) and produces data files which need to be accessible in the web server's document tree.

Configuring for graphic output

The $gnuplot, $DocumentRoot, and $DocumentRoot_subdir_for_reports variables only need to be configured if you want graphs. If you don't want the graphs, you can leave these variables unchanged, and not bother with setting up a temporary output directory.

The $gnuplot variable should be set to the pathname to gnuplot on your system. You must have this installed for the graphic output to work. Gnuplot is not included with the NcFTPd distribution, but you can find a pointer to a pre-compiled copy of gnuplot at the NcFTP Software download page, or, you can build it yourself without too much trouble.

Next you need to decide where the reports can produce the image files (with .png extensions). This needs to be a location within the web server's document root, so that the images are accessible by remote web browsers. Change the $DocumentRoot variable so that it corresponds to the web server's document root. For Apache web servers, the httpd.conf file's default setting of its DocumentRoot variable is /home/httpd/htdocs, and this is what the reports.cgi script's $DocumentRoot variable is set to by default.

Creating the temporary output directory

The suggested location for the image files is a tmp/ncftpd subdirectory of the document root, and this is the default value for the $DocumentRoot_subdir_for_reports variable. The reports need an entire subdirectory for itself, so do not use a directory which is shared by other programs (i.e. tmp). The directory needs to be writable by the web server user. For example, if the web server user is httpd and your document root is /home/httpd/htdocs, you could create the directory like this:

Setting permissions for the web user

As you've seen, the web server processes must have permission to use just about everything in the reporting package. If your web server does not run as root (or runs the CGI programs as non-root), this web user must have permission to:

You will probably need to make arrangements to read the .cf files and log files and their parent directories, using chown and chmod. If the web user belongs to a group, you can change the group of the .cf and log files to this group, and give the group read permission to them. Otherwise you may need to give ownership of the .cf and log files to the web user, or make them public readable.

NcFTPd itself has options to allow you to tune the server so that it generates new log files that are automatically readable by the web server user. In the general.cf, you can use the log-owner, log-group, and log-umask options to set the owner, group, and umask for newly created log files and log directories. For example, if your web user is named httpd and there is a group named webgroup, you could do this in your general.cf:

It is important that you use these options when you are using the reporting package. Otherwise your reports won't be able to read the data from newly-generated logs.

Running the reports

If everything is installed correctly, you should be able to run the report request form from your web browser. For example, if reports.cgi is located in /home/httpd/cgi-bin, you would use http://yourhost.com/cgi-bin/reports.cgi as the URL. This page will give you instructions on which reports you can run. Similarly, if you put the script in the suggested private directory, /home/httpd/ncftpd, then you would use http://yourhost.com/ncftpd/reports.cgi as the URL.

Routine maintenance

If you are using the graphic output, you will need to periodically clean the temporary output directory. You could run the find program to have it delete files older than 15 minutes, for example.

The script includes some built-in functionality to clean the directory. Here's an example crontab entry which purges reports older than 15 minutes:

Closing remarks

The most common issue you may run into is your browser timing out before the report completes. Depending on the amount of log data to process, the report may not be able to finish on time. When that happens you need to decrease the amount of time the report covers. The script also includes a feature which only works with Netscape-based browsers (Mozilla, Firefox, Navigator) and Opera. This feature allows for the script to send mulitpart pages which can update every few seconds which should help prevent the browser from giving up.

Up
NcFTPd Home