Online demo Privacy policy GoBD notes Blog

This is an old revision of the document!


Notes for Debian/Ubuntu users: Debian ships a pretty outdated version (2.0.4) of sphinxsearch. I strongly suggest to grab a recent 2.2.x release (either a deb package or the source) from the sphinx website.

Debian and Ubuntu users please see the FAQ to avoid a common pitfall, and fix /etc/default/sphinxsearch before start using sphinx.

Before installing piler you need to install the following packages (including the -dev or -devel packages as well):


  • openssl
  • MariaDB, MySQL or Percona
  • php 5.3+ (with the following modules: LDAP, GD, Memcache, PDO, MySQL, CURL)
  • a rewriting rule capable webserver, eg. apache, lighttpd, nginx, … (in case of apache be sure to enable the rewrite module)
  • mpstat utility (eg. the 'sysstat' package on Debian Linux)
  • python with mysqldb support (python-mysqldb package on debian/ubuntu)

Highly recommended:


Preinstall tasks, recommendations

Before you install you must create a DNS entry for piler. It must have a valid and resolvable hostname. In this guide we'll use as the FQDN of the archive.

Since piler archives your emails it may need lots of disk space. To keep things tidy, I recommend you to put all piler related data (including your log files) under the /var (or /var/piler) partition. I recommend using logical volumes.

An example layout you may create:

/     - 2 GB
/tmp  - 256 MB
/var  - several hundreds of GBs (or even more)
swap  - 1 GB

The used filesystem is not a concern, however if you choose XFS, then be aware of a 32 bit vs. 1 TB issue.

Note that piler stores all emails and attachments as separate files. You may tweak inode ratio, if necessary.

Create a dedicated and non-privileged user to run piler

groupadd piler
useradd -g piler -m -s /bin/sh -d /var/piler piler
usermod -L piler
chmod 755 /var/piler

Unpack and compile piler

tar zxvf piler-x.y.z.tar.gz
cd piler-x.y.z
./configure \
        --localstatedir=/var \
        --with-database=mysql \

su -c 'make install'

Make sure your system looks in /usr/local/lib for shared libraries! If not, then add this path to /etc/

Note: If you use Percona version of mysql, you may switch to the XtraDB engine. To do this, execute the following command before creating the tables:

sed 's/InnoDB/XtraDB/g' util/db-mysql.sql > a; mv a util/db-mysql.sql

Compiling on FreeBSD

FreeBSD is supported from build 881 (since 2014.07.21), see the master branch.

You also need the following packages from either the ports collection, or install them from whatever source:

  • textproc/libtre
  • textproc/unrtf
  • textproc/catdoc
  • archivers/libzip
  • database/mysql56-client
  • graphics/poppler-utils

Then run the following:

LDFLAGS="-L/usr/local/lib" CPPFLAGS="-I/usr/local/include" ./configure \
                                                                    --localstatedir=/var \
                                                                    --with-database=mysql \
gmake clean all

Additional notes: the piler 'make install' creates piler.conf.dist, sphinx.conf.dist and config-site.dist.php files. You may either create the actually used piler.conf and sphinx.conf files by hand from these template-like files, or run 'make postinstall' (see below) to have the postinstall procedure to create them.

Post install tasks

After a fresh install (ie. when it's not an upgrade) a few post install tasks must be done. Execute the post install script as root. It leads you through a series of questions, and eventually executes a set of commands to create SQL tables, cron jobs, populate the virtualhost directory, etc. If you want to perform the post install tasks manually, then checkout the manual post install.

Important! The 'hostid' parameter in piler.conf should be the hostname of piler, what is configured on your mailserver at always_bcc (see below). Eg. if you set on your mailserver, then set in piler.conf

$ su
# make postinstall

Start both searchd and piler:

/etc/init.d/rc.piler start
/etc/init.d/rc.searchd start

Notes for Ubuntu users: make sure to remove /etc/cron.d/sphinxsearch as it interferes with the piler indices.

Configure your mail server to forward a copy of each email it receives or sends to piler

To archive emails, piler must receive them somehow. So you have to configure your mail server to send a copy of each received emails to piler via smtp. Since piler is actually an SMTP server, you should not put postfix, exim, … on the archive itself. If you need it for some reason, then put it to, and set the listen_addr variable in piler.conf to listen on eth0 or similar.

If you have MS Exchange, then turn on journaling.

If you have postfix (including zimbra), then add the following to


   smtpd_recipient_restrictions = reject_non_fqdn_recipient, ..., \
                     check_recipient_access pcre:$config_directory/x-add-envelope-to, ...

   always_bcc =

   /(.*)/   prepend X-Envelope-To: $1

If you have Exim, then add the following at the beginning of the routers-section:

begin routers

  debug_print = "R: mailarchive for $local_part@$domain"
  driver = manualroute
  domains = *
  transport = remote_smtp
  # piler listening on port 25:
  route_list = * ""
  self = send


IMPORTANT! Make sure you never lose/overwrite the key otherwise you won't access your archive ever again. So whenever you upgrade be sure to keep your existing key file. Also NEVER change the iv parameter in piler.conf after installation

Website postinstall tasks

This task depends greatly on what webserver you use. Basically you have to create a virtualhost dedicated to piler, and enable rewriting rules. The piler GUI expects to be in the DocumentRoot not in a subdirectory. Example webserver configurations are available in the contrib/webserver/ directory.

Log in as administrator using the following account:


Then add your own domains that piler will receive emails for in the Administration/Domain menu.

Centos / Redhat users should fix /etc/sudoers to have the following entries:

Defaults requiretty

Defaults:%apache !requiretty

What next?

Be sure to review Administering piler / Retention rules, and set the appropriate retention rules, if needed. Otherwise piler will retain everything for 'default_retention_days'. Also go to Administration / Domains in the GUI, and add all your hosted domains.

Google Analytics Alternative