Configuration and Setup

Last updated: July 31, 2026Latest Frontend Version: 2.17.4

tiCrypt Audit requires three configuration files:

/etc/tiaudit/tiaudit.toml for the tiaudit service
/etc/tiaudit/log-streamer.toml for the tiaudit-logger service
/etc/tiaudit/log-uploader.toml for the tiaudit-log-uploader program

The configuration files are similar. Some information must be repeated in each configuration file.

The types of values used in the parameter descriptions are:

Type	Example	Description
String	"an example"	String value
Bool	true, false	Boolean value
Int	42	Whole number value
Port	22	Number between 0 and 65535
Size	16 MiB, 3 GB	File size with unit of measure
ArrString	["a", "b", "c"]	List/Array of string values

tiAudit Service Configuration

/etc/tiaudit/tiaudit.toml

This is the configuration file for the tiaudit service.

Parameter	Type	Required	Description
`hostname`	String	✅	The hostname for the server
`port`	Port	✅	Port for the server
`baseURL`	String	✅	The URL as seen from outside
`geoip`	String		See geo
`management-db`	String	✅	Path to user management file
`[sessions]`	Section	✅	See below
`[clickhouse]`	Section	✅	See clickhouse
`[smtp]`	Section		See smtp

info

If you deploy using Nginx, set hostname = "localhost" and make sure that baseURL points to the external URI set in Nginx and that port has the same value as in the configuration file /etc/nginx/conf.d/audit.ticrypt.conf.

By setting management-db="/var/log/tiaudit/management.db", you make use of the preparations in the rest of this document.

Session Management Secrets

[sessions] sub-section

This is a critical subsection that specifies secrets for session management.

caution

If you do not set or change these values, the old cookies will be invalid and you will have to ask users to delete the existing cookies manually.

Parameter	Type	Required	Description
`authKey`	String	✅	64-byte Base64 secret
`encryptionKey`	String	✅	32-byte Base64 secret

Generate authKey using:

openssl rand -base64 64

and encryptionKey with:

openssl rand -base64 32

note

If the authKey and encryptionKey have the wrong size, tiaudit cannot use them.

tiAudit Logger Configuration

/etc/tiaudit/log-streamer.toml

This is the configuration file for the tiaudit-logger service.

Parameter	Type	Required	Description
`hostname`	String	✅	The hostname to listen on
`port`	Port	✅	Port to listen on
`geoip`	String		See geo
`ipFallback`	String		IP to use if geolocation fails
`[clickhouse]`	Section	✅	See clickhouse
`[smtp]`	Section		See smtp
`[drivers]`	Section	✅	See drivers

tiAudit Log-Uploader Configuration

/etc/tiaudit/log-uploader.toml

This is the configuration file for the tiaudit-log-uploader program.

Parameter	Type	Required	Description
`batch`	Int		Batch size
`geoip`	String		See geo
`ipFallback`	String		IP to use if geolocation fails
`[clickhouse]`	Section	✅	See clickhouse
`[smtp]`	Section		See smtp
`[drivers]`	Section	✅	See drivers

info

The batch parameter controls the upload batch size. Writes into ClickHouse are faster with larger batches. Set this to at least 10,000.

Common Configuration Options

note

Some configuration options are common to all three configuration files.

Geolocation

Parameter	Type	Required	Description
`geoip`	String		Location of GeoIP2 .mmdb file

note

If geoip is not set, geolocation is not available.

ClickHouse Database

section [clickhouse]

The [clickhouse] section specifies how to access the ClickHouse database. There are two options:

Specify the uri parameter with complete information.
Specify some of the other parameters.

caution

This information must be identical in all three configuration files.

Parameter	Type	Description
`uri`	String	The ClickHouse URI
`scheme`	tcp,udp	Type of communication, default TCP
`username`	String	The ClickHouse user name
`password`	String	The corresponding password
`host`	String	Format host:port, default localhost:9000
`database`	String	The ClickHouse database

If all of the following are true, only the database parameter is required:

ClickHouse runs on the same server as tiCrypt Audit
The firewall blocks external access to port 9000
Only admins have server access

Email Sending

section [smtp]

The alert subsystem finds important events in the tiCrypt event log. When such alerts are raised, one possible action is to send emails to interested parties. This section configures email sending through an SMTP server.

If the email driver is used, this section must be present; otherwise, no emails can be sent.

Parameter	Type	Description
`server`	String	The SMTP server
`port`	Port	The SMTP port
`username`	String	The SMTP user name
`password`	String	The SMTP user password
`from`	String	From email address
`to`	ArrString	List of emails to send to
`cc`	ArrString	Same but CCed
`bcc`	ArrString	Same but BCCed

Set up a dedicated account for tiCrypt Audit rather than reusing an existing account.

Use the to, cc, and bcc parameters to determine who receives emails and in what form.

Drivers

section [drivers]

The drivers allow tiCrypt Audit to push alerts outside the system. As of version 1.4.0, tiCrypt Audit supports three types of drivers: print, email, and Splunk.

Each driver must be defined in a section [drivers.name_of_driver], where name_of_driver must be unique across all drivers.

Provide meaningful names for the drivers.

To disable a driver, set disabled = true rather than removing it from the configuration file.

Print driver

The print driver writes alerts to stdout or stderr. This is not useful for the tiaudit-logger service but is useful for the tiaudit-log-uploader program.

Parameter	Type	Required	Description
`type`	print	✅	Type of driver
`disabled`	Bool	✅	Is the driver disabled?
`encoding`	String		Encoding (e.g. text/plain)
`dest`	String		Destination: stderr or stdout

Email driver

The email driver assumes that tiCrypt Audit can send emails, i.e., that the [smtp] section is configured correctly.

Parameter	Type	Required	Description
`type`	smtp	✅	Type of driver
`disabled`	Bool	✅	Is the driver disabled?
`encoding`	String		Encoding (e.g. text/plain)
`from`	String		From field. E.g. server@example.com
`to`	ArrString	✅	E.g. [ "monitoring@example.com" ]
`server`	String	✅	E.g. smtp.example.com
`port`	Port		Default: 587
`username`	String	✅	SMTP user name
`password`	String	✅	SMTP password
`max-retries`	Int		How many times to retry

Splunk driver

The splunk driver allows integration with Splunk.

Parameter	Type	Required	Description
`type`	splunk	✅	Type of driver
`disabled`	Bool	✅	Is the driver disabled?
`url`	String	✅	The Splunk collection point
`token`	String	✅	The Splunk token
`certified`	Bool		Set to false to disable the TLS certificate check
`source`	String	✅	Splunk source, e.g. tiCrypt
`sourceType`	String	✅	Splunk source type, e.g. tiCryptAlert
`index`	String		Splunk index, default main

tiCrypt Audit pushes alerts to Splunk as JSON.

Nginx integration

To serve the tiCrypt Audit application, configure Nginx to forward traffic to the tiaudit service.

The following configuration file is based on Mozilla's SSL Configuration Generator.

We assume that:

The tiCrypt Audit server is available at tiaudit.example.com
The tiaudit service runs on port 8081
The TLS/SSL combined certificate and chain are stored in /etc/pki/tls/certs/example-stacked.crt
The TLS/SSL trust chain is stored in /etc/pki/tls/certs/example-chain.crt
The TLS/SSL key is stored in /etc/pki/tls/private/example.key

Create the file /etc/nginx/conf.d/audit.ticrypt.conf with content similar to:

    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    upstream audit-backend {
        server 127.0.0.1:8081;
    }

    server {
        listen 443 ssl;
        server_name audit.example.com;
        root /var/www/ticrypt-audit;

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

        ssl_session_timeout 1d;
        ssl_protocols TLSv1.2 TLSv1.3;
        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:*";

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

        location @proxy {
            proxy_pass http://audit-backend;
            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;
            proxy_set_header    Upgrade             $http_upgrade;
            proxy_set_header    Connection          $connection_upgrade;
        }
    }

Customize the values for your environment.

The configuration file above assumes that the TLS/SSL certificate is stacked. A stacked/bundled certificate is the concatenation of the actual certificate and the local certificate authority chain of certificates.

Create the static directory for tiCrypt Audit

mkdir -p /var/www/ticrypt-audit

Verify the TLS certificate

openssl x509 -in /etc/pki/tls/certs/example-stacked.crt -text -noout

Verify the TLS private key

openssl rsa -in /etc/pki/tls/private/example.pem -check

If the certificate or private key is invalid, Nginx will not start. Check the validity before restarting Nginx.

The following steps remain:

Create or download non-standard Diffie-Hellman parameters.

Alternatively generate new ones yourself:

openssl dhparam -outform pem -out /etc/pki/tls/dhparam.pem 2048

Or download from Mozilla:

curl https://ssl-config.mozilla.org/ffdhe2048.txt > /etc/pki/tls/dhparam.pem

Tell SELinux that Nginx can connect

setsebool -P httpd_can_network_connect=true

Restart Nginx:

systemctl restart nginx

Loading the logs

Everything is now ready to load the log history and start live log loading.

We assume that the tiCrypt log files are in /var/log/ticrypt. If you imported the logs from another server, place the files, unchanged, in any directory.

Do not unpack existing archived log files. The log uploader reads both compressed and uncompressed files.

As long as you have access to the log files, you do not need to be root to run the loading command.

Load the tiCrypt history

tiaudit-log-uploader -c /etc/tiaudit/log-uploader.toml /var/log/ticrypt

The process takes anywhere from a few seconds to several minutes, depending on the log size. At the end, the uploader prints statistics on the number of events of each type processed and the number of errors. Verify that no errors are reported.

Start the services:

systemctl start tiaudit systemctl start tiaudit-logger

Verify that both services are running:

systemctl status tiaudit systemctl status tiaudit-logger

Create the first user/admin

Initially, there are no users in the tiCrypt Audit application. No functionality except registration is available without user accounts.

User registration is based on invitations. To create the first invitation for user me@example.com (upon registration, this account becomes an admin account), run:

sudo -u tiaudit tiaudit -c /etc/tiaudit/tiaudit.toml -i me@example.com

Do not run tiaudit as root, since doing so sets the wrong permissions on the database file and prevents the tiaudit service from writing data.

One of the last lines displayed looks like:

2020/05/25 16:27:55 URL: https://tiaudit.example.com/?email=me@example.com&invite=JWL8-3y2XCX_rg7LGpBG8gJdaTdeTMJGOS5bLrhdrdkK

Ignore

Ignore the error about binding.

Copy and paste the URL into a web browser. With the tiaudit service running, the URL takes you to the registration page with the Email field already filled in. Fill in the information and verify that you can log in and that you are an admin.

If you lose your password, follow the same process to get a valid invitation. You can then change the password. This process does not make you an admin if you are not already.

tiAudit Service Configuration​

Session Management Secrets​

tiAudit Logger Configuration​

tiAudit Log-Uploader Configuration​

Common Configuration Options​

Geolocation​

ClickHouse Database​

Email Sending​

Drivers​

Print driver​

Email driver​

Splunk driver​

Nginx integration​

Create the static directory for tiCrypt Audit

Verify the TLS certificate

Verify the TLS private key

Create or download non-standard Diffie-Hellman parameters.

Alternatively generate new ones yourself:

Or download from Mozilla:

Tell SELinux that Nginx can connect

Loading the logs​

Load the tiCrypt history

Create the first user/admin​

tiAudit Service Configuration

Session Management Secrets

tiAudit Logger Configuration

tiAudit Log-Uploader Configuration

Common Configuration Options

Geolocation

ClickHouse Database

Email Sending

Drivers

Print driver

Email driver

Splunk driver

Nginx integration

Loading the logs

Create the first user/admin