Skip to main content

Install server

include::_macros.adoc[]

NOTE: All the commands in this section need to be executed as root

As of version {revnumber}, {tm} is only supported on CentOS/Redhat 7.0. Support for CentOS/RedHat 8.0 is planned for the future.

The main {ta} dependencies are:

  • a web server like Nginx
  • a firewall such as firewalld
  • the Clickhouse database
  • (optional) The MaxMind geolocation database:
  • (optional) OpenSSL for key generation

== Installing pre-requisites

=== Installing Nginx include::../common/install_nginx.adoc[]

=== Installing firewalld include::../common/install_firewalld.adoc[]

=== Installing {tm}

{tc} is made available in the form of RPMs for CentOS/RedHat 7.0. The latest version is available from link:{tm-dir}{tm-file}[]

The installation consists simply of downloading and installing the RPM.

[subs="attributes+"]​

Grab the {ta} RPM

wget {tm-dir}{tm-file}

Install

yum -y install {tm-file}

Remove

rm {tm-file}​

We need a place to put the .szip files: /var/www/ticrypt-mailbox​

Create the static directory for tiCrypt REST

mkdir -p /var/www/ticrypt-mailbox chmod a+rx /var/www/ticrypt-mailbox

chown ticrypt /var/www/ticrypt-pmailbox​

The {tm} service3 need to be enabled:​

systemctl enable ticrypt-mailbox​

== Configuration

=== Configurint {tm}

The configuration file for {tm} is /etc/ticrypt/mailbox.toml. The configuration optins supported are:

[options="header",cols="3,2,3,8"] |=== | Parameter | Type | Required | Description | hostname | String | Optional| Hostname to bind to | port | Int | Required | The port to bind to | baseURL | String | Required | The external URL for server | backendURL | String | Required | The URL of the {tc} server | mailbox | String | Required | Path to the application .szip file | secureCookie | Bool | Optional | Disable/enable secure cookie |===

Some notes on the configuration:

  • hostname should be 127.0.0.1 if you deploy behing Nginx
  • port should match the service port in Nginx config below
  • baseURL should match the external name configured in Nginx below
  • backendURL shoudl be fully qualified and accessible from the serfer, e.g. https://ticrypt.example.com. To test that it works do:

wget https://ticrypt.example.com/info​

And make sure you get a reply containing the system info. If that does not work, connectivity with the {tc} server is not working.

  • mailbox must point to a valid inbox-....szip file that the user nginx can read.

NOTE: To update the inbox, simply download a newer inbox....szip file and change the mailbox variable. The simply restart the service with sytemctl restart ticrypt-mailbox.

CAUTION: secureCookie=true is only useful for debugging, assuming https cannot be used, and should never be used in production.

=== Configuring the firewall

If you have not done already, you need to allow external access to https port​

firewall-cmd --permanent --zone=public --add-service=https

firewall-cmd --reload​

=== Setting up Nginx The recommended way to install the web application is to use an Nginx instance that is set up for serving flat files and deal with the TLS/SSL certificate for the respective domain. This can be accomplished by adding a file /etc/nginx/conf.d/mailbox.ticrypt.conf.

With the assumptions: . The {tm} service runs on port 8082 . We serve the mailbox from URL: https://mailbox.example.com . The TLS stacked certificate for the domain is stored in file /etc/pki/tls/certs/example-stacked.crt . The TLS private key is stored in file /etc/pki/tls/private/example.pem

The configuration file can look like:

upstream tc-mailbox { server 127.0.0.1:8082; }

server {

### Configuration based on Mozilla Configuration Tool
listen 443 ssl;
server_name mailbox.example.com
root /var/www/ticrypt-mailbox

ssl_certificate /etc/pki/tls/certs/example-stacked.crt;
ssl_certificate_key /etc/pki/tls/private/example.pem;

ssl_session_timeout 1d;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_dhparam /etc/pki/tls/dhparam.pem;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;

#add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "script-src 'unsafe-inline' 'unsafe-eval' 'self' https://code.getmdl.io; frame-ancestors 'self' http://127.0.0.1:*";

#### This is critical for tiCrypt  ####
client_max_body_size 16M;

ssl_session_tickets off;
location / {
    try_files $uri @proxy;
}

location @proxy {
    proxy_pass http://tc-mailbox;
    proxy_redirect off;
    proxy_buffering off;
    proxy_cache off;
    proxy_http_version 1.1;
    proxy_read_timeout 900s;
    proxy_connect_timeout 360s;
    proxy_send_timeout 360s;
    proxy_set_header    Host                $host;
    proxy_set_header    X-Real-IP           $remote_addr;
    proxy_set_header    X-Forwarded-Proto   https;
    proxy_set_header    X-Forwarded-Ssl     on;
    proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
}

}

CAUTION: Failure to set client_max_body_size to at least 16M will prevent large file uploads and will result in mysterious failures.

include::../common/nginx_critical.adoc[]

=== Wrapping up

To wrap up the installation, we simply start the {tm} service with:​

systemctl start ticrypt-mailbox​

and verify that the service works by navigating to the public url. You should get a message telling you that you do not have the required credentials but the page should load.

=== Debugging

If the application is not served correctly, check the error logs of {tm} to ensure that the mailbox file can be found and that it is correctly signed.

NOTE: You need to update the mailbox .szip file soon after it becomes available since it might contain security patches and usability improvements.

== Updating the {tm} server

The {tm} server is very simple and need updating rarely. In the event that you need to update it, do:

. Install the new .rpm packages

. Restart the {tm} service with:​

systemctl restart ticrypt-mailbox​