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
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).
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):
<Directory "/home/httpd/cgi-bin"> AllowOverride None Options ExecCGI Order allow,deny Allow from all </Directory>
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.
ScriptAlias /ncftpd/ "/home/httpd/ncftpd/" <Directory "/home/httpd/ncftpd"> AllowOverride None Options ExecCGI Order allow,deny Allow from 192.168.1. </Directory>
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.
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.
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.
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:
root# cd /home/httpd/htdocs root# if [ ! -d tmp ] ; then mkdir tmp ; chmod 755 tmp ; chown httpd tmp ; fi root# mkdir tmp/ncftpd root# chown httpd tmp/ncftpd root# chmod 700 tmp/ncftpd root# ls -ld tmp tmp/ncftpd
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=httpd log-group=webgroup log-umask=027It 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.
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:
0 * * * * /home/httpd/ncftpd/reports.cgi -k 15 >/dev/null 2>&1
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.