Skip to content

Latest commit

 

History

History
193 lines (136 loc) · 7.04 KB

piler.rst

File metadata and controls

193 lines (136 loc) · 7.04 KB
Raw

Piler

Piler is an open-source mail archiving solution.

This Piler application for NS8 configures a :ref:`Mail server <email-section>` instance to act as its archive, recording any message sent or received by the server for a configurable duration. If a message is lost, authorized users (known as "auditors") can access the Piler UI, search for the message in the archive, and send it back to the original recipient.

Note

  1. This application allows auditor users to view other users' mail messages. Ensure its use complies with your country's privacy laws, regulations, and company policies.
  2. After the initial configuration, Piler starts with default credentials. For security reasons, refer to section :ref:`default-piler-credentials` to change the default passwords immediately.

Configuration

Once installed, navigate to the application Settings page and fill in the required fields:

  • Piler FQDN: Enter the fully-qualified domain name where the Piler web UI will be accessible. If the FQDN is already registered in the public DNS, you can enable the Let's Encrypt certificate switch to obtain a valid encryption certificate.
  • HTTP to HTTPS: Enable this switch to ensure that all communications with the Piler UI are encrypted. This is recommended if the UI is accessed through a public or untrusted network.
  • Mail server: Choose one of the Mail server instances in the cluster. They are labeled as follows:
    1. Archiving can be configured: This means the Mail server currently has no archive configured and can be safely selected.
    2. The archive destination is…: This indicates that the Mail server already copies any message sent or received to another archive or external email address. If such an entry is selected and the form is saved, the previous configuration is overwritten, so use it with caution. See also the Mail :ref:`Always BCC <mail-archive-section>` setting.
  • Retention duration: This field contains the number of days an email message is retained in the archive. After that period, a daily cron job purges the message from the archive.

It is important to understand that the Mail server selection is allowed only once during the configuration of a Piler instance. In other words, you cannot change the Mail server selection once the Piler instance is initially configured.

Warning

If an incorrect Mail server is selected, there is no way to change the selection. The preferred way to recover from this situation is to remove the incorrect Piler instance, then install and configure a new one.

Other configuration settings can be changed as needed.

Default credentials

After the initial configuration, Piler starts with default credentials. For security reasons, the default passwords must be immediately changed for the two existing default accounts:

  1. User admin@local: This user has full administrative rights over the Piler application. They can create new user accounts and grant any kind of rights. However, they cannot read email messages archived in the Piler DB. The default password is pilerrocks.
  2. User auditor@local: This user, as the name suggests, has the auditor role. They can search for any email message in the archive and send it back to the original recipient. The default password is auditor.

After logging into the Piler website, navigate to Settings under the menu in the upper right corner of the screen. Scroll down to the bottom of the personal Settings page, enter the new password in the two password fields (the second one is for confirmation), and submit the form.

Administrators can change the password of other users from the Users action under the Administration menu.

Restore email messages

Auditor users can search for and recover archived email messages.

When a message is handled by the Mail server, a copy is sent to the archive. However, Piler does not index the received messages immediately. They are placed in an archive queue, and every half hour, a scheduled task indexes a batch of queued messages. Duplicate messages count as one.

Once a message is indexed, auditors can search for it. Found messages can be downloaded or forwarded to an arbitrary email address.

If multiple messages are selected, they are compressed into a ZIP archive before download.

When one or more messages are forwarded to an email address, the message and its original headers are preserved. Therefore, when received, the message will be sorted with its original date. Furthermore, Piler adds a MIME header X-piler-id to forwarded messages.

Import existing email

Existing email messages can be imported from the chosen Mail server instance into the Piler archive.

Warning

The import process may take hours or even days, depending on the number of users and the size of their mailboxes. Additionally, message indexing is a memory- and CPU-intensive operation that may impact node performance.

Access a root terminal and run the following command:

runagent -m piler1 import-emails --help

Replace piler1 with the correct Piler application instance identifier, visible on the Status page. The above command just prints the command help text.

The optional command arguments -A (after) and -B (before) can limit the time range for the import. As times must be expressed in Unix timestamp format, the date command can be invoked to obtain the desired timestamp from a date string, for example:

date -d 2024-05-01 +%s

Fine-tune Piler's configuration

After the application has been configured for the first time and secured by changing the default users' credentials, Piler is ready to archive emails.

This is a brief list of common configuration tasks, with links to the official documentation:

  • Administration tasks, to manage users, permissions, and check the audit log.
  • Rules and policies, to define what messages are archived and how long they will stay. For example, you can define a special policy for spam messages.

Note that the official administration documentation refers to the "enterprise edition" of Piler; therefore, some content is not relevant for the "community edition", which is the base of the NS8 application.

Known limitations

  1. Email messages received with :ref:`Imapsync <imapsync-section>` are not archived.

  2. Some features are not active/effective but are still visible in the Piler UI.

    For administrators:

    • In the Administration menu, the Import action.
    • In the Monitor menu, the Archive accounting action.

    For auditors:

    • In the message preview screen area, the Restore to mailbox action.