Apache with PHP, JSP, Perl and MySQL on FreeBSD

Updated: December 3rd, 2011Published: March 9th, 2004
Time to read: 32 min

Article tags:

This setup is well suited for a VPS provider, such as DigitalOcean.

MySQL 4.x Client Installation

Note! You will need to mount devfs or at least mknod a /dev/random inside this jail, otherwise MySQL will only throw out SSL Connection Error when you are trying to establish a SSL encrypted connection! The same goes for SSHd.

In order to be able to connect to our MySQL server, which has its own jail, we'll need to install the mysql-client in each user's chroot. First, let's compile MySQL without the server (i.e. client only). This is really easy:

$ cd /usr/ports/databases/mysql40-client/
# make WITH_OPENSSL=yes all install clean

Remember those SSL certificates we created earlier? We'll need them again. Copy them over from the host system to the jailcell:

# mkdir /var/jail/
# cp /root/openssl/cacert.pem /var/jail/
# cp /root/openssl/client-cert.pem /var/jail/
# cp /root/openssl/client-key.pem /var/jail/

Edit the jailcell's /etc/my.cnf. Define the following:

port     = 3306
host     =
ssl-ca   = /etc/ssl/certs/cacert.pem
ssl-cert = /etc/ssl/certs/client-cert.pem
ssl-key  = /etc/ssl/certs/client-key.pem

You can safely delete the part under [mysqld] of the config file, it's somewhat irrelevant when we only have a MySQL client installed in this jail.

libnss-mysql Installation

Installing libnss-mysql in the jail even easier than on the host system:

# cd /usr/ports/net/libnss-mysql/; make all install clean

After that, edit /usr/local/etc/libnss-mysql.cfg and /usr/local/etc/libnss-mysql-root.cfg. Note that you'll need to at least touch libnss-mysql-root.cfg, otherwise the setup will not work. One should use a separate MySQL user account for the jail then the host system.

PostgreSQL client installation

This is required if we wish to compile PHP with PostgreSQL support. There is apparently no package or port for Postgresql 7.4 at the time of writing, thus I'm compiling from source. Note that PostgreSQL requires gmake.

# pkg_add -r gmake
$ fetch ftp://ftp.se.postgresql.org/pub/databases/relational/postgresql/latest/postgresql-7.4.1.tar.bz2
$ tar xfvj postgresql-7.4.1.tar.bz2
$ cd postgresql-7.4.1
$ ./configure --with-openssl
$ gmake
# gmake -C src/bin install
# gmake -C src/include install
# gmake -C src/interfaces install
# gmake -C doc install

This installs the client portion of PostgreSQL. No need to install the server portion here, as it's already installed in another jail.

Perl 5.8.x and DBI-modules installation

We'll need to install Perl before PHP and mod_perl (and thus also before Apache) if we want a newer version than Perl 5.6.x, as PHP's libmcrypt has a dependency to Perl. Currently, however, there is no package for Perl-5.8.2_1 for some reason. We'll have to use the ports. Use mount_nullfs on the host system to loopback mount /usr/ports to the jailcell. After that, jail yourself back to the cell, and execute the following:

# cd /usr/ports/lang/perl5.8/; make all install clean
# use.perl port

Next up was the DBI installation. The jail will probably not have job control, so you'll want to use this instead of the CPAN shell:

# perl -MCPAN -e 'install Bundle::DBI'

Always answer "yes" when you get the following question:

Shall I follow them and prepend them to the queue
of modules we are processing right now? [yes]

I decided to compile DBD::mysql by hand since I wanted SSL support. For some reason make will not find the MySQL libraries and headers unless specified, so I executed the following while inside the jailcell:

# cd /root/
# fetch http://www.perl.com/CPAN/modules/by-module/DBD/DBD-mysql-2.9003.tar.gz
# tar xfvz DBD-mysql-2.9003.tar.gz
# cd DBD-mysql-2.9003
# perl Makefile.PL --ssl
# make
# make install

Warnings about mysql_config can safely be ignored. Notice especially the --ssl argument to Makefile.PL. If you're going to compile this on the host system, you'd probably want to do something like this instead:

# perl Makefile.PL --ssl --cflags="-I/var/jail/" \
--libs="-L/usr/lib-lz -lcrypt -lm -L/usr/lib -lssl -lcrypto \
-L/var/jail/ -lmysqlclient"

SSH Installation

The commercial SSH daemon supports chrooting of certain groups using the ChRootGroup feature and certain users using the ChRootUser feature. OpenSSH can be patched to support these. OpenSSH can also be patched to chroot with the magic token /./ in a user's home directory (https://chrootssh.sourceforge.net/), while the commercial SSHd cannot.

However, the commercial version of SSH does not read obey login.conf, which is a feature I definitely want. Thus, I'm patching OpenSSH to support the /./ magic token.

$ fetch ftp://ftp.fi.debian.org/pub/OpenBSD/OpenSSH/portable/openssh-3.8p1.tar.gz
$ tar xfvz openssh-3.8p1.tar.gz
$ cd openssh-3.8p1
$ ./configure --with-md5-passwords
$ make
# make install

After the installation, edit the jail's /usr/local/etc/ssh/sshd_config. If you're going to run SSHd on the host system (for administrative purposes or whatnot), be sure to limit the allowed users using the AllowedUsers directive in sshd_config. Otherwise, people could just connect to that server and slip past our chroot/jail!

SSHd requires that you have devfs mounted in the webserver jail. To mount it, issue the following command on the host system:

# mount_devfs devfs /var/jail/

Insert the above command in the host system's /usr/local/etc/rc.d/mount.sh (or something similar), if you wish to have it mounted automatically at boot, as devfs cannot be mounted directly from fstab. Remember to chmod the file 0700.

To start SSHd automatically in the jail, define the following in the jail's /etc/rc.conf:


The following might be good options to put in the jail's /usr/local/etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication yes
PermitEmptyPasswords no

Note that you don't have to define UseLogin yes; the limits in login.conf are enforced anyway. Actually, setting UseLogin yes will break the chroot! Depending on the user's shell, a maxproc limit would yield a following error message in Bash: fork: Resource temporarily unavailable.

Note that if you wish to use gftp's SSH2 support, you'll need to copy /usr/local/bin/sftp-server inside each user's chroot (/bin will be just fine).

I tried breaking out of the chroot in various ways, but it seemed secure. mknod is disabled in a jail. The chdir(".."); trick does not work. traceroute and ping will not work inside the chroot (or inside the jail for that matter), as they are not allowed open raw sockets. Later we'll install Perl and PHP along with the suexec wrapper, so that the scripts will be executed using the user's UID/GID instead of the server's UID/GID.

Now, you'll still need to create a directory structure for the chrooted SSH/SFTP users. I wrote a small Perl script for the task. It's meant to be executed on the host system, probably as root (might even work as a regular user if the permissions are right. Haven't tested that though.) The script requires the DBI and an appropriate DBD Perl module. I've tested the script with Perl 5.6.0 and 5.8.2.

dtach installation

I wanted to offer my chrooted users the GNU screen's 'detach' feature, but installing full screen just for the detach feature seemed too bloated for this kind of use. Then I found a small program called dtach (sic) which emulates screen's detach feature. Get it at https://dtach.sourceforge.net/.

However, we need to make some modifications to dtach for it to work on FreeBSD 5.1-RELEASE. After decompressing the sources, remove the libutil.h ifdef from detach.h. Otherwise, you'll get an error such as this when running make:

gcc -g -O2 -W -Wall -I. -c ./attach.c
In file included from detach.h:40,
                 from attach.c:19:
/usr/include/libutil.h:76: syntax error before "uid_t"
*** Error code 1

Stop in /var/jail/

I had the problem of getting some garbage data in my console when detaching or exiting from a program, namely the string 1;2c. I solved this by commenting out (by adding /* and */) the following in attach.c (line 49 in version 0.5):


You could optionally remove the whole line from attach.c. Now you can proceed to build dtach as you normally would:

$ ./configure
$ make

This will build a dtach binary you can copy into the user's chroot, along with /usr/lib/libutil.so.4. You will need to create appropriate pseudo-terminals in the user's /dev, if you do not with to have devfs mounted inside the user's chroot. I didn't, so I took the MAKEDEV script from the last distribution it was included in, i.e. FreeBSD 5.0-RELEASE, and basically included the functionality in my mkchroot.pl Perl script.

dtach also needs to be able to read /var/run/ld-elf.so.hints inside the chroot!

Apache 1.x Installation

Download and install Apache. I am aware that version 2.x is available, and even considered stable by the Apache team, but I'm not upgrading just yet, due to lack of third-party modules and (currently) slightly worse performance than the 1.x series. I'm going to use the www user, which exists by default on FreeBSD.

$ fetch http://www.tux.org/pub/net/apache/dist/httpd/apache_1.3.29.tar.gz
$ tar xfvz apache-1.3.29.tar.gz

Before we can compile Apache, we need to add mod_ssl support:

$ fetch http://www.modssl.org/source/mod_ssl-2.8.16-1.3.29.tar.gz
$ tar xfvz mod_ssl-2.8.16-1.3.29.tar.gz
$ cd mod_ssl-2.8.16-1.3.29
$ ./configure --with-apache=../apache_1.3.29
$ cd ..

We still need to add mod_perl support. Note: Do not compile mod_perl as DSO (Dynamic Shared Object)! According to various sources, Apache will crash (I never tried):

$ fetch http://perl.apache.org/dist/mod_perl-1.0-current.tar.gz
$ tar xfvz mod_perl-1.0-current.tar.gz
$ cd mod_perl-1.29
$ perl Makefile.PL \
APACHE_SRC=../apache_1.3.29/src \
# make && make install
$ cd ../apache_1.3.29

Now we're ready to configure Apache. Apache comes with a ready layout for FreeBSD (see config.layout), which I will use here. No reason to break hier(8):

$ ./configure --with-layout=config.layout:FreeBSD \
          --enable-module=ssl \
          --enable-shared=ssl \
          --enable-module=rewrite \
          --enable-shared=rewrite \
          --disable-module=imap \
          --with-perl=/usr/bin/perl \
          --enable-module=so \
          --server-uid=www \
          --server-gid=www \
          --without-execstrip \
          --enable-suexec \
          --suexec-caller=www \
          --suexec-uidmin=1000 \
          --suexec-gidmin=1000 \
          --suexec-docroot=/home/*/home/public_html \
          --suexec-logfile=/usr/local/apache/logs/suexec_log \
          --activate-module=src/modules/perl/libperl.a \
$ make
# make certificate TYPE=existing CRT=/etc/ssl/certs/server-cert.pem KEY=/etc/ssl/certs/server-key.pem
# make install

Congratulations, Apache is now installed. You can now start the HTTP server by issuing the following command (note that startssl will not work yet!):

# /usr/local/sbin/apachectl start

After the server has started, check Apache's error log file (/var/log/error_log by default) to see if the server has indeed started. Do not rely on the status apachectl reports. The error log should contain something like the following:

[Fri Jan  2 20:14:41 2004] [notice] Apache/1.3.29 (Unix) mod_perl/1.29 configured -- resuming normal operations
[Fri Jan  2 20:14:41 2004] [notice] suEXEC mechanism enabled (wrapper: /usr/local/sbin/suexec)

If one or both are missing, something went wrong with the compilation. Issue a make clean, check your configure options and compile again.

Now comes the fun part; configuring Apache.

In order for name-based virtual hosts to work, you need to set the following in /etc/httpd.conf:


<IfDefine SSL>

BindAddress *
NameVirtualHost *

MySQL virtualhosts. The choice of using SSL is up to you, there isn't any too sensitive data transmitted on this connection.

O'Reilly's 'Writing Apache Modules with Perl and C' was of huge help in this case. In it, we learn that VirtualHosts can be specified in the following fashion using mod_perl:

$VirtualHost{''} = {
  ServerName   => 'www.testnet.org',
  DocumentRoot => '/home/httpd/testnet/htdocs',
  ErrorLog     => '/home/httpd/testnet/logs/error.log',
  TransferLog  => '/home/httpd/testnet/logs/access.log',
  ServerAdmin  => '[email protected]',

However, the %VirtualHost syntax from the previous section would not work with name-based virtual hosts, since assigning a hash reference for the given IP address will overwrite the original entry. The solution is to use an array reference whose values are hash references, one for each virtual host entry. For example, like this:

$VirtualHost{''} = [
     ServerName   => 'foo.test.net',
     ServerAdmin  => '[email protected]',
     ServerName   => 'bar.test.net',
     ServerAdmin  => '[email protected]',

Now, pulling the data from MySQL and inserting it into the array/hashes, doesn't require that much code. In a simple form, this could be something like this:

# use strict;

  use DBI;
  my $i = 0;
  use vars qw(%VirtualHost);

  # Define anonymous array in vhost hash
  $VirtualHost{'*:80'} = [];

  # open database connection
  my $dbh = DBI->connect("DBI:mysql:database=hosting;host=;port=3306;mysql_compression=1", 'www', 'GoodPassword');

  my $sth = $dbh->prepare("SELECT domainname,aliases,docroot,serveradmin,suid,sgid,xferlog,errlog FROM domains");

  # populate the anonymous array with SQL data
  while (my @row = $sth->fetchrow_array()) {
   $VirtualHost{'*:80'}->[$i]->{'ServerName'} = "@row[0]";
   $VirtualHost{'*:80'}->[$i]->{'ServerAlias'} = "@row[1]";
   $VirtualHost{'*:80'}->[$i]->{'DocumentRoot'} = "@row[2]";
   $VirtualHost{'*:80'}->[$i]->{'ServerAdmin'} = "@row[3]";
   $VirtualHost{'*:80'}->[$i]->{'User'} = "@row[4]";
   $VirtualHost{'*:80'}->[$i]->{'Group'} = "@row[5]";
   $VirtualHost{'*:80'}->[$i]->{'TransferLog'} = "@row[6]";
   $VirtualHost{'*:80'}->[$i]->{'ErrorLog'} = "@row[7]";

   # Enable userdirs only for certain hosts
   if ("@row[0]" eq ("www.foobar.org" || "quux.org")) {
    $VirtualHost{'*:80'}->[$i]->{'UserDir'} = "/home/*/home/public_html";
   } else {
    $VirtualHost{'*:80'}->[$i]->{'UserDir'} = "disabled";




NB! The User and Group directives are ordinarily ignored inside <VirtualHost> containers, but in a suexec-enabled server they take on new meaning for the virtual host, defining the identity under which CGI scripts requested through that host will be executed. If a virtual host doesn't have a User directive, it inherits the server-wide value (which defines the username under which the server itself is running) which will probably result in normal, non-suexec-enabled behaviour. The same goes for Group. Suexec does not need any additional configuration directives in httpd.conf.

Tip: You can debug the Perl sections in httpd.conf file by issuing perl -cx httpd.conf, assuming that you have the appropriate shebang and __END__.

Create the SQL database and table:

USE hosting;

CREATE TABLE domains (
 did integer unsigned auto_increment,
 domainname varchar(255) unique not null,
 aliases blob,
 docroot varchar(255) not null,
 serveradmin varchar(255) default 'hostmaster@your-domain',
 suid varchar(32) default 'nobody',
 sgid varchar(32) default 'nogroup',
 xferlog varchar(255) default '/var/log/apache/access_log',
 errlog varchar(255) default '/var/log/apache/error_log',
 stats char(3) default 'off',
 backup char(3) default 'off',
 template varchar(255),
 dtadded timestamp(14),
 contract_id integer unsigned,
 primary key (did)

By setting the SQL defaults for the suid and sgid columns to an unprivileged user, we can easily avoid a mistake, where no suid or sgid is inserted in the SQL table. If no uid/gid is found in the SQL table, the script is run using the web server's uid/gid, which is bad!

The stats, template and backup columns will be used by my awstats_sql_batch and backing up Perl scripts and are thus not required if you aren't going to use them. Both scripts use the very same SQL table as Apache. The dtadded and did columns just make administration easier, and they are not required either.

Don't forget to grant SELECT privilege to the user you chose, as otherwise your virtual domain setup will fail miserably:

GRANT SELECT ON hosting.domains TO www@ IDENTIFIED BY 'GoodPassword';

If you want to start Apache at boot time (i.e. when the jail is started), you can simply use a slightly modified apache.sh script, which can be found at the ports collection:

# cp /usr/ports/www/apache13/files/apache.sh /var/jail/
# chmod 0700 /var/jail/

Edit the file and change start to startssl if you wish to use SSL.

However, we run into a problem with name-based virtual hosts and SSL. Currently, SSL does not support name-based virtual hosting, but only IP-based hosting. In other words, you'll need one IP address/SSL enabled host. However, we can accomplish a "half-working" solution using one certificate and mod_rewrite. The following works reasonably well, at least until TLS (the next version of SSL) starts supporting name-based virtual hosting.

<VirtualHost _default_:443>

 RewriteEngine On
 RewriteMap lowercase int:tolower
 RewriteMap vhost-map prg:/etc/scripts/vhost.pl

 # allow Alias /icons/ to work - repeat for other aliases
 RewriteCond %{REQUEST_URI}  !^/icons/

 # Don't apply this rule for userdirs, that start with a tilde (~)
 RewriteCond %{REQUEST_URI}  !^/~(.*)
 RewriteRule ^/(.*)$   /${vhost-map:${lowercase:%{SERVER_NAME}}}/$1 [NS,L]

 # Emulate userdir behaviour, but only for certain hosts
 RewriteCond %{HTTP_HOST} ^(www.foobar.org|quux.org)$
 RewriteRule ^/~([^/]+)/?(.*)           //home/$1/home/public_html/$2 [NS,L]


vhost.pl is a small Perl script, which pulls the virtual host's documentroot from the SQL database. The double slashes ( // ) at the beginning of the paths prevent the document_root from being prefixed to the rewritten paths.

The advantage of this approach is that basically all hosts/URLs can be accessed using SSL encryption simply by using https://URL/. The problem with this approach is that you have only one certificate for all hosts, thus resulting in warnings by the browser accessing the host, saying that the hostname doesn't match the certificate's 'common name' field.

To start Apache automatically each time the jail is started, place the following script in /usr/local/etc/rc.d/apache.sh (or something similar):


case "$1" in
  echo -n "apache "
  /usr/local/sbin/apachectl startssl
  /usr/local/sbin/apachectl stop
  /usr/local/sbin/apachectl restart
  echo "Usage: $0 {start | stop | restart}"

Remember to chmod the file 0700.

PHP 4.x Installation

We'll need some additional software, if we wish to use PHP's extra functions. I wanted, so I installed the following inside the jailcell. You could use the ports just as well, but I found the packages to be a faster way:

# cd /usr/ports/security/libmcrypt; make all install clean
# pkg_add -r png
# pkg_add -r libtool15

Note that we'll need to install libmcrypt from the ports, as otherwise it won't use our newly installed Perl 5.8.2. Next up, download and decompress the full PHP sources:

$ fetch https://fi.php.net/get/php-4.3.4.tar.bz2/from/this/mirror
$ tar xfvj php-4.3.4.tar.bz2
$ cd php-4.3.4

Compile and install PHP as a CGI:

$ ./configure --enable-cgi --with-pear --enable-safe-mode --with-openssl \
--with-zlib --with-bz2 --enable-ftp --with-gd --with-mcrypt \
--with-mysql --disable-posix --with-pgsql --enable-force-cgi-redirect
$ make
# make install

make install will print out some useful information you might want to note somewhere, similar to this:

Installing PHP SAPI module:       cgi
Installing PHP CGI into: /usr/local/bin/
Installing shared extensions:     /usr/local/lib/php/extensions/no-debug-non-zts-20020429/
Installing PEAR environment:      /usr/local/lib/php/
[PEAR] Archive_Tar    - installed: 1.1
[PEAR] Console_Getopt - installed: 1.0
[PEAR] PEAR           - installed: 1.3b3
Wrote PEAR system config file at: /usr/local/etc/pear.conf
You may want to add: /usr/local/lib/php to your php.ini include_path
[PEAR] DB             - installed: 1.5.0RC2
[PEAR] HTTP           - installed: 1.2.1
[PEAR] Mail           - installed: 1.1.1
[PEAR] Net_SMTP       - installed: 1.2.3
[PEAR] Net_Socket     - installed: 1.0.1
[PEAR] XML_Parser     - installed: 1.0.1
[PEAR] XML_RPC        - installed: 1.0.4
Installing build environment:     /usr/local/lib/php/build/
Installing header files:          /usr/local/include/php/
Installing helper programs:       /usr/local/bin/
  program: phpize
  program: php-config
  program: phpextdist

You'll still need to copy over a default configuration file.

# cp php.ini-recommended /usr/local/lib/php.ini

We will NOT need the shebang line in every PHP file, if we place the PHP executable (interpreter) inside each user's DocumentRoot, and define the following Action in httpd.conf:

Action php-script /cgi-bin/php.cgi
AddHandler php-script .php .php3
AddType application/x-httpd-php-source .phps

However, be sure to check that there isn't a ScriptAlias for /cgi-bin/ defined in httpd.conf. Now, all you need to do is copy /usr/local/bin/php to each user's cgi-bin directory and name it php.cgi. You won't actually HAVE to rename it to php.cgi, but I like to keep it that way for consistency.

Next, load /usr/local/lib/php.ini in your favourite text editor and define at least the following:

short_open_tag = Off
safe_mode = On
open_basedir = /home
disable_functions = phpinfo,system,exec,escapeshellarg,escapeshellcmd,
mysql.allow_persistent = Off

Java Installation

Java SDK (JDK) Installation

Installing JDK on FreeBSD can be a bit tricky due to Sun's restrictive licensing.

$ cd /usr/ports/distfiles
$ lynx http://www.eyesbeyond.com/freebsddom/java/JDK13SCSLConfirm.html

Download the file to /usr/jail/

Download j2sdk-1_3_1_07-linux-i586.bin from http://java.sun.com/webapps/download/Display?BundleId=7479 to /usr/jail/

# cd /usr/ports/archivers/gtar; make all install clean
# cd /usr/ports/archivers/unzip; make all install clean
# cd /usr/ports/archivers/zip; make all install clean

Provided that you have linux kernel compatibility and /usr/ports/emulators/linux_base installed on the host system, you can simply do:

# cp /compat/linux/lib/ld-linux.so.2 /usr/jail/
# cp /compat/linux/lib/libc.so.6 /usr/jail/

After that, installing the JDK in the jailcell is easy:

# cd /usr/ports/java/linux-sun-jdk13; make all install clean

To confirm a proper installation:

$ /usr/local/linux-sun-jdk1.3.1/bin/java -version
# export JAVA_HOME="/usr/local/linux-sun-jdk1.3.1"

Tomcat Installation

$ cd /usr/local
$ wget http://cvs.apache.org/builds/jakarta-tomcat-5/nightly/jakarta-tomcat-5-bin-20030426.tar.gz
$ tar xfvz jakarta-tomcat-5-bin-20030426.tar.gz
# /usr/local/jakarta-tomcat-5/dist/bin/startup.sh

mod_jk Installation

Download the newest mod_jk.so from http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/freebsd/i386/ to /usr/jail/ and rename the file to mod_jk.so.

ProFTPd Installation

$ cd /tmp
$ wget ftp://ftp.proftpd.org/distrib/source/proftpd-1.2.8.tar.bz2
$ tar xfvj proftpd-1.2.8.tar.bz2
$ cd proftpd-1.2.8
$ ./configure --with-modules=mod_tls:mod_diskuse:mod_md5fs --sysconfdir=/etc \
  --with-libraries=/usr/lib/ --with-openssl-dir=/usr/lib
$ make
# make install

ProFTPd is now installed. Next, lets create the certificates for TLS/SSL over FTP.

$ cd /etc/ssl/certs
$ openssl req -new -x509 -days 365 -nodes -out rsa.pem -keyout rsa-key.pem
$ openssl dsaparam -out dsap-tmp 1024
$ openssl req -newkey dsa:dsap-tmp -x509 -days 365 -nodes -out dsa.pem -keyout dsa-key.pem
$ openssl dhparam -out dhparam.pem 1024
$ rm dsap-tmp

Finally, supervise ProFTPd. On the host system, do something like:

$ cd /service
# mkdir proftpd
# vim proftpd/run

Place something like this in the run file:

exec jail /usr/jail/ www /usr/local/sbin/proftpd -n

Chmod the run file +x and supervise should bring up ProFTPd a few seconds later.

Apache configuration

Cronolog installation

First, I installed cronolog, which is required by my Perl script later on.

# cd /usr/ports/sysutils/cronolog/; make all install clean

AwStats installation

By placing AwStats' icons in /usr/local/apache2/icons/awstats/, we can use Apache's /icons/ alias, thus making AwStats' icons available to all virtualhosts without the need to copy them over to each virtualhost's documentroot.

$ wget https://cesnet.dl.sourceforge.net/sourceforge/awstats/awstats-5.4.tgz
$ tar xfvz awstats-5.4.tgz
$ mkdir /usr/jail/
$ cp -r awstats-5.4/wwwroot/icon/* /usr/jail/

Next, copy over AwStats' configuration file to the proper location.

$ mkdir -p /usr/jail/
$ cp awstats-5.4/wwwroot/cgi-bin/awstats.model.conf /usr/jail/

Notice also the .tpl extension. This is actually a template used by my awstats_sql_batch Perl script. More on that later on. Finally, copy over the Perl scripts that AwStats consists of.

$ cp awstats-5.4/tools/* /usr/jail/
$ cp awstats-5.4/wwwroot/cgi-bin/awstats.pl /usr/jail/
$ cp -r awstats-5.4/wwwroot/cgi-bin/lang /usr/jail/
$ cp -r awstats-5.4/wwwroot/cgi-bin/lib /usr/jail/
$ cp -r awstats-5.4/wwwroot/cgi-bin/plugins /usr/jail/

We still need to modify Apache's configuration. I added this for my awstats_batch_sql Perl script in httpd.conf:

LogFormat "%V %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" mod_gzip:%{mod_gzip_result}n In:%{mod_gzip_input_size}n Out:%{mod_gzip_output_size}n:%{mod_gzip_compression_ratio}npct." vcommon
CustomLog "|/usr/local/sbin/cronolog --period=6hours /usr/local/apache2/logs/%Y/%m/%d/%H-access.log" vcommon

Note especially that the CustomLog directive is piped to a shell command, in this case cronolog, which splits the logfiles in to appropriate directories and files. However, cronolog does not rotate the log files. Also note, that you must specify a full path to cronolog (i.e. just logs/%Y/%m/%d/%H-access.log wouldn't work).

The following is adapted from the Awstats FAQ. I bolded the configuration I use:

HOW TO ROTATE LOGS WITHOUT LOSING DATA: I want to archive/rotate my logs using my web server system options or a third software (rotatelog, cronolog) but don't want to lose any visit information during the rotate process.

SOLUTION: If you use a rotate system (internal web server feature or third software), this means you probably not use AWStats PurgeLogFile nor ArchiveLogRecords parameter. If your config file is setup to process current log file (because you want to use the AllowToUpdateStatsFromBrowser option), if you don't want to lose any records during the rotate process, you can just run the AWStats update process on the archived log file just after the update process using the -logfile option (This will avoid you to change the config file). If you choose (for security reason, to avoid CPU abuse on large web site or other) to make updates by your scheduler only on archive files, this means you don't use the AllowToUpdateStatsFromBrowser "real-time" feature of AWStats. In this case all you have to do is to run the update process just after the rotate was done using a config/domain file configured to process the archived log files (using date tags of LogFile for examples). Note: For Apache users, use of cronolog seems to be a better choice than rotatelog (cronolog is available for Unix/Linux and Windows and is more flexible).

Now there's the issue of rotating the log files. I wrote a small Perl script that gets the users' Awstats preferences from a MySQL table, generates temporary Awstats config files from templates, and rotates the log files split by cronolog. In other words, this script batch builds several statistics with only one cron job and one or more template files. The advantage of this approach is that normally you would have to have one cron job and one config file for each statistic you want to build; i.e. this is my solution for mass virtual hosting. Install awstats_sql_batch Perl script as described in its README.

Now we still need to edit /etc/awstats/awstats.conf and change LogFormat to reflect our custom Apache log format:

LogFormat="%virtualname %host %other %logname %time1 %methodurl %code %bytesd %refererquot %uaquot %other %gzipin %gzipout"

mod_deflate Configuration

Added this for mod_deflate (mod_gzip in Apache 1.3). mod_deflate is a module that allows transparent gzip compression of data between the server and client, if the client supports it.

&lt;Location /&gt;
# Insert filter
SetOutputFilter DEFLATE

# Netscape 4.x has some problems...
BrowserMatch ^Mozilla/4 gzip-only-text/html

# Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip

# MSIE masquerades as Netscape, but it is fine
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

AddOutputFilterByType DEFLATE ^text/.* ^application/x-httpd-php ^httpd/unix-directory$

# Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary

mod_ssl configuration

Problem: When using TLS/SSL, virtualhosts must be IP-based, but I wanted to use name-based virtual hosting.

Solution: Use mod_rewrite as in the "Dynamically configured mass virtual hosting" document!

First, however, you need to create the certificates. Here, I'm also creating my own Certificate Authority (CA). This certificate authority will be valid for 10 years (3652 days):

$ cd /etc/ssl/certs
$ openssl genrsa -des3 -out ca.key 2048
$ openssl req -new -x509 -days 3652 -key ca.key -out ca.crt

This results in a file named ca.crt and a file named ca.key. Next, create a custom certificate:

$ openssl genrsa -out httpd.key 2048
$ openssl req -new -key httpd.key -out httpd.csr

Sign the certificate using the custom CA and mod_ssl's sign.sh:

$ ./sign.sh httpd.csr

After that, you can safely delete server.csr, it's not needed anymore. NOTE: The CA and the certificate CANNOT have the same common name!

Next, make Apache listen on the SSL port 443 as well as the standard HTTP port 80.


Finally, we need to set up Apache to support TLS/SSL ( is my jail's IP address that is NATed to the Internet in my router):

# Disable name-based virtual hosting
# NameVirtualHost *

<VirtualHost _default_:443>
 RewriteEngine On

 # a ServerName derived from a Host: header may be any case at all
 RewriteMap  lowercase  int:tolower

 ## deal with normal documents first:
 # allow Alias /icons/ to work - repeat for other aliases
 RewriteCond  %{REQUEST_URI}  !^/icons/
 #  allow CGIs to work
 RewriteCond  %{REQUEST_URI}  !^/cgi-bin/
 # do the magic
 RewriteRule  ^/(.*)$  /home/${lowercase:%{SERVER_NAME}}/public_html/$1

 ## and now deal with CGIs - we have to force a MIME type
 #RewriteCond  %{REQUEST_URI}  ^/cgi-bin/
 #RewriteRule  ^/(.*)$  /home/${lowercase:%{SERVER_NAME}}/cgi-bin/$1  [T=application/x-httpd-cgi]

 SSLEngine On
 SSLProtocol all -SSLv2
 SSLCertificateFile /etc/ssl/certs/server.crt
 SSLCertificateKeyFile /etc/ssl/certs/server.key

<VirtualHost _default_:80>
 RewriteEngine On

 # a ServerName derived from a Host: header may be any case at all
 RewriteMap  lowercase  int:tolower

 ## deal with normal documents first:
 # allow Alias /icons/ to work - repeat for other aliases
 RewriteCond  %{REQUEST_URI}  !^/icons/
 #  allow CGIs to work
 RewriteCond  %{REQUEST_URI}  !^/cgi-bin/
 # do the magic
 RewriteRule  ^/(.*)$  /home/${lowercase:%{SERVER_NAME}}/public_html/$1

 ## and now deal with CGIs - we have to force a MIME type
 #RewriteCond  %{REQUEST_URI}  ^/cgi-bin/
 #RewriteRule  ^/(.*)$  /home/${lowercase:%{SERVER_NAME}}/cgi-bin/$1  [T=application/x-httpd-cgi]

 SSLEngine Off

Problem: CGI scripts run using the webserver's UID/GID.

Solution: Use Apache's suexec wrapper.

Problem: PHP scripts run using the webserver's UID/GID.

Solution 1: Enable PHP's safe_mode.

Solution 2: Compile PHP as a CGI and use Apache's suexec wrapper.

I also uncommented the following lines in httpd.conf, so that support for CGI, SSI and PHP are available:

# Added for CGI
AddHandler cgi-script .cgi .pl

# Added for SSI
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

# Added for PHP4
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

All done! Fire up your Apache using the command:

# jail /usr/jail/ www /usr/local/apache2/bin/apachectl start

on the host system. Point your browser to http://<yourip>:80 and https://<yourip> to check that both Apache without SSL and Apache with SSL work. I haven't found an easy way to supervise Apache, however.


About the author
I'm a millennial digital nomad and a seasoned IT professional with over 20 years of cross-industry experience, ready to help you with supercharging your business. Drop me a note or read more about what I can do for you!


This website is only intended to provide a quick overview of what I do. Please drop me a line if you'd like me to send you my full CV, references, certifications or any additional information.


Subscribe now to get notified of blog updates (no more than one email/month). No spam, promise!

Unsubscribe at any time. Signing up implies that you agree to the Terms.
This blog contains affiliate links to third parties. By using this site you agree to the Terms.