Installation guide for Linux

Last modified by Aurelie Bertrand on 2024/11/25 11:18

This guide provides installation and configuration instructions in a production environment on Ubuntu 20.04 and Ubuntu 22.04.

Java is required to run DigDash. The minimum requirement is Java 11. We recommend using Java 17.

This document describes how to install DigDash on Linux.

To install DigDash on Windows, please refer to the Installation Guide for Windows.

To update an existing installation, please refer to the Upgrade Guide.

Supported versions

The following versions are supported :

  • Tomcat 9 : last patch
  • OpenDJ (recommended) : version 4.6.2 and later
  • MariaDB : OS version or last patch of last LTS version
  • Nginx : system version

Digdash

OpenJDK

It is recommended to install JDK 17. 
​​​​​​JDK 11 is supported.

# Install last version of openjdk
sudo apt install default-jdk

# Check the installation
java -version

Tomcat 9

Installation

sudo apt install tomcat9

Creating the file tree

# Location of webapps
sudo mkdir -p /home/digdash/webapps/default/
# Working directory
sudo mkdir -p /home/digdash/appdata/default/
# Location of the .properties file
sudo mkdir -p /etc/digdash/
# Location of logs
sudo mkdir -p /var/log/digdash/

Changing folder rights

sudo chown -R tomcat:tomcat /home/digdash
sudo chown -R tomcat:tomcat /var/log/digdash
sudo chmod a+w /var/log/digdash

Configuring server.xml

Location : /etc/tomcat9/server.xml

Location of webapps

# Replace the appBase value
<Host name="localhost"  appBase="webapps"

# by this one
<Host name="localhost"  appBase="/home/digdash/webapps/default"

Connector Valve

# Complete the Connector valve
 <Connector port="8080" protocol="HTTP/1.1"
              connectionTimeout="20000"
              redirectPort="8443" ></Connector>

# as follows
<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               maxConnections="30000"
               maxParameterCount="100000"
               maxThreads="10000" maxPostSize="62914560"
             redirectPort="8443" compression="on" ></Connector>

Reverse Proxy Valve

# Add this valve in the Host element near the end of the file
<Valve className="org.apache.catalina.valves.RemoteIpValve"
               internalProxies="127\.0\.[0-1]\.1"
               remoteIpHeader="X-Forwarded-For"
               requestAttributesEnabled="true"
               protocolHeader="X-Forwarded-Proto"
               protocolHeaderHttpsValue="https"></Valve>

In the case of an IPv6 server, use:

<Valve className="org.apache.catalina.valves.RemoteIpValve"
               internalProxies="127\.0\.[0-1]\.1|0:0:0:0:0:0:0:1|::1"
               remoteIpHeader="X-Forwarded-For"
               requestAttributesEnabled="true"
               protocolHeader="X-Forwarded-Proto"
               protocolHeaderHttpsValue="https"></Valve>

In very rare cases, the reverse proxy is not installed on the machine. Then replace the value "127\.0\.[0-1]\.1" with the IP address of the reverse proxy.
❗Attention: the use of “.*” should only be done as a last resort.

Log Valve

# Add this valve in the Host element near the end of the file
<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false" ></Valve>

Limiting the localhost_access_log file (optional)

To limit the size of the localhost_access_log file, add the maxDays parameter to the Access Log Valve and give it the value of the desired number of days.

# For example
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" maxDays="10" ></Valve>

Editing the context.xml file

Location: /etc/tomcat9/context.xml

# Add the following line in the <Context> tag
<Resources cachingAllowed="true" cacheMaxSize="100000"></Resources>

edit_context_file.png

Changing RAM

# Edit the following file
sudo vi /etc/default/tomcat9

# Replace the existing JAVA_OPTS by
JAVA_OPTS="-Djava.awt.headless=true -XX:+UseShenandoahGC -Xms6G -Xmx6G -Djava.security.egd=file:/dev/urandom -DPROP_MAX_CONCURRENT_TOTAL=5000 -DPROP_MAX_CONCURRENT_CON_PER_HOST=5000"

# Change the 6G parameter depending on the capacity of the machine, leaving at least 2G for the OS.
# In the example above, the machine has 8G of RAM.
# It is recommended to use the same value for Xms and Xmx.

Activating log write permission for tomcat

# Create the folder in /etc/systemd/system/
sudo mkdir -p /etc/systemd/system/tomcat9.service.d

# Create the file
sudo vi /etc/systemd/system/tomcat9.service.d/logging-allow.conf

# Add the following lines
[Service]
ReadWritePaths=/var/log/digdash/

# Reload the "daemon" configuration
sudo systemctl daemon-reload

sudo systemctl restart tomcat9.service

Enabling automatic service start on startup

sudo systemctl enable tomcat9

Deploying Digdash Version 24R1

Download Digdash version.

Unzip the version you have just downloaded.

Properties files

Place the digdash.properties file (located at the root of the unzipped folder) in the folder /etc/digdash.

Create the following file in the folder /etc/digdash :

Edit the digdash.properties file previously copied.

# Add these lines at the beginning of the file

# Log files location
ddenterpriseapi.ddlog4j.properties.file=/etc/digdash/log4j2_api.properties
studio.ddlog4j.properties.file=/etc/digdash/log4j2_studio.properties
digdash_dashboard.ddlog4j.properties.file=/etc/digdash/log4j2_dash.properties

# Appadata location
ddenterpriseapi.AppDataPath=/home/digdash/appdata/default
digdash_dashboard.AppDataPath=/home/digdash/appdata/default
studio.AppDataPath=/home/digdash/appdata/default
adswrapper.ads.instance.name=/home/digdash/appdata/default/ldapdigdash

adminconsole.adminconsole_domain=adminconsole
adminconsole.webstudio_domain=studio
adminconsole.server_domain_list=ddenterpriseapi
adminconsole.dashboard_domain=digdash_dashboard

studio.DOMAIN=ddenterpriseapi
studio.FORCEDOMAIN=true
studio.SERVERURL=http://localhost:8080
studio.FORCESERVERURL=true
studio.adminconsole_domain=adminconsole

digdash_dashboard.DOMAIN=ddenterpriseapi
digdash_dashboard.FORCEDOMAIN=true
digdash_dashboard.SERVERURL=http://localhost:8080
digdash_dashboard.FORCESERVERURL=true
digdash_dashboard.adminconsole_domain=adminconsole

########### Nettoyage automatique des fichiers programmé
########### Scheduled automatic file cleaning
ddenterpriseapi.startCleaner=true

########### Nettoyage des fichiers inutilisés  au démarrage du serveur
########### Clean up unused files on server startup
ddenterpriseapi.cleanOnStart=false

########### Sauvegarde automatique programmée
########### Scheduled automatic backup
ddenterpriseapi.autoBackup=true
ddenterpriseapi.autoBackupKeepDays=7
digdash_dashboard.CANCHANGEPASSWORD=true

Deploying WebApps

Place the following (contained in the <DD Install>\apache-tomcat\webapps directory) in the folder /home/digdash/webapps/default :

  • adminconsole.war
  • ddenterpriseapi.war
  • digdash_dashboard.war
  • studio.war
  • ROOT/ folder

OpenDJ

Installation

  1. Start by getting the latest version of the opendj-4.x.x_all.deb file from the website https://github.com/OpenIdentityPlatform/OpenDJ/releases :
wget https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/4.x.x/opendj-4.x.x_all.deb
  1. Run the installation : 
sudo dpkg -i opendj_4.x.x_all.deb

Initial setup

To simplify OpenDJ configuration, we are going to create a ‘setupOpenDJ.props’ file containing the options available to respond to the OpenDJ ‘setup’ utility (this avoids the configuration interface).
The contents of this file are detailed below:

❗Don't forget to replace the parameters with your own. For example, replace the password with the one you want (here ‘adminOpenDJ1’).

#
# Sample properties file to set up OpenDJ directory server
# See OpenDJ Setup command man for more options
#
rootUserDN                      =cn=Directory Manager
rootUserPassword                =adminOpenDJ1
hostname                        =localhost.localdomain
ldapPort                        =389
adminConnectorPort              =4444
backendType                     =je
baseDN                          =dc=digdash,dc=com
addBaseEntry                    =true
ldapsPort                       =636
enableStartTLS                  =false
generateSelfSignedCertificate   =true
start                           =true
#sampleData                     =2000

After saving the file, run the following command line:

sudo /opt/opendj/setup --cli --propertiesFilePath setupOpenDJ.props --acceptLicense --no-prompt

Additional setup

  1. Go to the OpenDJ installation directory:
cd /opt/opendj/bin/

  1. LDIF files can be downloaded by clicking on the following link LDIF_OpenDJ.

  2. Create organisations using the ‘neworganisation.ldif’ file below :
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" neworganisation.ldif
dn: ou=default,dc=digdash,dc=com

objectClass: organizationalUnit

ou: default
  1. Set the password checker "Custom Character-set Password Validator": 
sudo /opt/opendj/bin/dsconfig create-password-validator --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1"  --validator-name "Custom Character-set Password Validator" --set character-set:1:abcdefghijklmnopqrstuvwxyz --set character-set:1:ABCDEFGHIJKLMNOPQRSTUVWXYZ --set character-set:1:0123456789 --set "character-set:1:\!\"#$%&'()*+,-./:;<=>?@[]^_\`{|}~" --set enabled:true --type character-set --no-prompt --trustAll --set allow-unclassified-characters:true
  1.  Set the second password checker "Custom length Password Validator":
sudo /opt/opendj/bin/dsconfig create-password-validator --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1"  --validator-name "Custom length Password Validator" --set min-password-length:12 --set enabled:true --type length-based --no-prompt
  1. Apply the two password checkers :
sudo /opt/opendj/bin/dsconfig set-password-policy-prop --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" --policy-name "Default Password Policy" --set password-validator:"Custom Character-set Password Validator" --set password-validator:"Custom length Password Validator" --no-prompt
  1. Set the password policy for users using the ‘ppolicy.ldif’ file below:
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" ppolicy.ldif
dn: cn=ppolicy,ou=default,dc=digdash,dc=com
objectClass: top
objectClass: subentry
objectClass: pwdPolicy
cn: ppolicy
pwdAttribute: userPassword
pwdAllowUserChange: TRUE
pwdCheckQuality: 1
pwdExpireWarning: 600
pwdFailureCountInterval: 30
pwdGraceAuthNLimit: 5
pwdInHistory: 5
pwdLockout: TRUE
pwdLockoutDuration: 900
pwdMaxAge: 0
pwdMaxFailure: 5
pwdMinAge: 0
pwdMustChange: FALSE
pwdSafeModify: FALSE
subtreeSpecification: {base "ou=users", specificationFilter "!(uid=admin)" }
  1. Set a second password policy for admin using the ‘ppolicy-admin.ldif’ file below:
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" ppolicy-admin.ldif
dn: cn=ppolicy-admin,ou=default,dc=digdash,dc=com
objectClass: top
objectClass: subentry
objectClass: pwdPolicy
cn: ppolicy-admin
pwdAttribute: userPassword
pwdAllowUserChange: TRUE
pwdCheckQuality: 1
pwdFailureCountInterval: 30
pwdGraceAuthNLimit: 5
pwdInHistory: 5
pwdLockout: FALSE
pwdMaxAge: 0
pwdMinAge: 0
pwdMustChange: FALSE
pwdSafeModify: FALSE
subtreeSpecification: {base "ou=users", specificationFilter "(uid=admin)" }
  1. Change password policy to allow pre-encoded passwords (useful for restores in Digdash):
sudo /opt/opendj/bin/dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set allow-pre-encoded-passwords:true --hostname localhost --trustAll --bindDN "cn=directory manager" --bindPassword "adminOpenDJ1" --no-prompt
  1. Create an admin user for Digdash using the “create_user_admin.ldif” file below:
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" create_user_admin.ldif
dn: uid=admin,ou=default,dc=digdash,dc=com
objectClass: shadowAccount
objectClass: inetOrgPerson
cn: Admin Domain Default
sn: Default
uid: admin_default
  1. Assign the admin user the necessary rights using the “add_admin_right.ldif” and “add_admin_right2.ldif” files below:
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" add_admin_right.ldif
dn: ou=default,dc=digdash,dc=com
changetype: modify
add: aci
aci: (target ="ldap:///ou=default,dc=digdash,dc=com")(targetattr = "userpassword || shadowlastchange")(version 3.0; acl "allow write on userpassword and shadowlastchange for admin"; allow(write) (userdn = "ldap:///uid=admin,ou=default,dc=digdash,dc=com");)
aci: (target ="ldap:///ou=default,dc=digdash,dc=com")(targetattr = "userpassword || shadowlastchange")(version 3.0; acl "allow read,write on userpassword and shadowlastchange for auth users"; allow(read) (userdn = "ldap:///all");)
aci: (target ="ldap:///ou=default,dc=digdash,dc=com")(targetattr = "userpassword || shadowlastchange")(version 3.0; acl "allow read on userpassword and shadowlastchange for anonymous"; allow(selfwrite) (userdn = "ldap:///anyone");)
aci: (target ="ldap:///ou=default,dc=digdash,dc=com")(targetattr = "*")(version 3.0; acl "allow write on * for admin"; allow(all) (userdn = "ldap:///uid=admin,ou=default,dc=digdash,dc=com");)
aci: (target ="ldap:///ou=default,dc=digdash,dc=com")(targetattr = "*")(version 3.0; acl "allow read on * for anonymous"; allow(read) (userdn = "ldap:///all");)
sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" add_admin_right2.ldif
dn: uid=admin,ou=default,dc=digdash,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: config-read
ds-privilege-name: password-reset
ds-privilege-name: unindexed-search
  1. Generate an administrator password and remember it for later:
sudo /opt/opendj/bin/ldappasswordmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" --authzID "u:admin"

💡 If you want to set your own password for the admin user, you need to use a variation of the previous command:

sudo /opt/opendj/bin/ldappasswordmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" --authzID "u:admin" --newPassword "mdpAdmin" 

Enabling automatic service start on startup

  1. Create the opendj.service file:
sudo vi /etc/systemd/system/opendj.service
  1. And paste the following lines:
[Unit]

Description=OpenDJ Server Daemon

Wants=network-online.target

After=network-online.target

Conflicts=shutdown.target

 [Service]

Type=simple

Restart=no

TimeoutSec=5min

IgnoreSIGPIPE=no

KillMode=process

GuessMainPID=no

RemainAfterExit=yes

ExecStart=/opt/opendj/bin/start-ds --quiet

ExecStop=/opt/opendj/bin/stop-ds --quiet

 [Install]

WantedBy=multi-user.target
  1. Then type the following commands:
systemctl daemon-reload

systemctl enable --now opendj

systemctl status opendj

Useful option

The operation below is not part of the installation.
However, it may be useful to know it for later use.

Extending the limit for LDAP searches

It is possible to extend the LDAP search limit to more than 1000 users with the “extend_search_limit.ldif” file below.

sudo /opt/opendj/bin/ldapmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword "adminOpenDJ1" extend_search_limit.ldif
dn: uid=admin,ou=default,dc=digdash,dc=com
changetype: modify
add: ds-rlim-size-limit
ds-rlim-size-limit: 10000

MariaDB (Recommended)

The MariaDB database will be used to store the following elements: comments, audit data and data entry.

This database is more durable than an H2 database, that is why we recommend its use. If you already have a database that Digdash can write to and read from then proceed to the configuration step.

Mysql and Postgresql are also compatible.

Installation

sudo apt install mariadb-server
#start mariadb
sudo systemctl start mariadb
#Stop mariadb
sudo systemctl stop mariadb
#Reload to take into account the configuration changes
sudo systemctl reload mariadb
sudo systemctl force-reload mariadb
#Display the version
mariadb --version

Launch mysql_secure_installation. This will secure the installation.

sudo mysql_secure_installation

# Enter yes at all steps

Enabling automatic service start on startup

sudo systemctl enable mariadb

Database configuration

We will create a base for each domain and each webapps (for example prod_ddaudit and dev_ddaudit and so on)

In the example below, we will consider that there is only one 'default' environment.

# Start mariadb
sudo mariadb -u root -p

# Create all necessary databases domain_module.
CREATE DATABASE default_ddaudit;
CREATE DATABASE default_comment;
CREATE DATABASE default_ddentry;

# Create a user for each database domaine_user_module. The password is a new one to create.
CREATE USER 'default_user_ddaudit'@'localhost' IDENTIFIED BY 'mynewpassword';
CREATE USER 'default_user_comment'@'localhost' IDENTIFIED BY 'mynewpassword';
CREATE USER 'default_user_ddentry'@'localhost' IDENTIFIED BY 'mynewpassword';

# Assign rights on the databases to the user
GRANT ALL PRIVILEGES ON default_comment.* TO 'default_user_comment'@'localhost';
GRANT ALL PRIVILEGES ON default_ddaudit.* TO 'default_user_ddaudit'@'localhost';
GRANT ALL PRIVILEGES ON default_ddentry.* TO 'default_user_ddentry'@'localhost';

NGINX (Optional)

Nginx is used as reverse proxy.

Installation

sudo apt install nginx

Enabling automatic service start on startup

sudo systemctl enable nginx

Configuration

Create the configuration file with the name of your machine or environment. In this example, we use 001-digdash.

In the /etc/nginx folder:

# Create the conf file
sudo vi /etc/nginx/sites-available/001-digdash.conf
# Add the following content inside.
# Replace .mydomain.com for server and paths
Certificate(s) and private key, par vos informations.
upstream backend_tomcat{
    least_conn;
    server localhost:8080 fail_timeout=0;
}


server {
  listen [::]:80;
  listen      80;
  server_name *.mondomaine.com;

 # Redirect all non-https requests
  rewrite ^ https://$host$request_uri? permanent;

  error_log  /var/log/nginx/digdash.com.error_log  warn;
  access_log  /var/log/nginx/digdash.com.access.log;
}

server {
  listen [::]:443 ssl http2 default_server;
  listen      443 ssl http2 default_server;
  server_name *.mondomaine.com;

  client_max_body_size 4G;
  proxy_read_timeout 300;
  proxy_connect_timeout 300;
  proxy_send_timeout 300;

  error_log  /var/log/nginx/digdash.com.error_log  warn;
  access_log  /var/log/nginx/digdash.com.access.log;

 # Certificate(s) and private key
  ssl_certificate_key /emplacement/de/la/clé/macle.key;
  ssl_certificate /emplacement/du/certificat/moncertif.crt;

 #DigDash Management SSL
  include digdash_ssl_params;

   location / {
        include proxy_params;
        proxy_intercept_errors on;
        proxy_pass  http://backend_tomcat;
        proxy_cookie_path ~^/(.+)$ "/$1; HTTPOnly; Secure;samesite=none;";
  }
}

Then create a symbolic link in sites-enabled

sudo ln -s  /etc/nginx/sites-available/001-digdash.conf /etc/nginx/sites-enabled/001-digdash.conf

Create the digdash_ssl_params file containing the security policy:

sudo vi digdash_ssl_params
# Or, generate random dhparam
# openssl dhparam 4096 -out /etc/ssl/dhparam.pem
#ssl_dhparam /etc/ssl/dhparam.pem;

ssl_protocols TLSv1.3 TLSv1.2;

ssl_prefer_server_ciphers on;
ssl_ecdh_curve secp521r1:secp384r1;
ssl_ciphers EECDH+AESGCM:EECDH+AES256;

ssl_session_cache shared:TLS:2m;
ssl_buffer_size 4k;

# OCSP stapling
ssl_stapling on;
ssl_stapling_verify on;
resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001]; # Cloudflare

# Set HSTS to 365 days
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains; preload' always;

Configuring DigDash after installation

Starting Digdash

  1. Restart Tomcat service.
sudo service tomcat9 restart
  1. Check the war deployment in the installation folder home/digdash/webapps/default.
  2. Access DigDash homepage at the following address : http://localhost:8080/adminconsole
    The login/password is admin/admin.

Connecting Digdash to the installed OpenDJ server

Open http://localhost:8080/adminconsole/, Configuration -> Server settings -> Servers -> LDAP Server.

  • Port:  389
  • User: uid=admin, ou=default,dc=digdash,dc=com
  • Password: OpenDJ admin password

LDAP server

Then click the LDAP Queries button and enter "ou=default" in the Domain Tree field for all the fields to be automatically filled as below.

LDAP queries

Changing the supervisor password and creating the LDAP account

Changing the supervisor password

Open Configuration  -> Server settings > Servers -> Enterprise Server and enter a new password in the Supervisor Password field.

Supervisor password

Creating the LDAP account

  1. Open Configuration -> User management -> Users. 
  2. Create a new admin user and assign him all roles and authorizations groups.
  3. In the Password field, enter the new supervisor password defined above.

User password

Database configuration

Audit data database

Open Configuration -> Server settings -> Databases -> Audit data and enter the URL, user and password.

URL : jdbc:mariadb://localhost:3306/default_ddaudit

This solution makes it possible to secure access to the audit database.

Audit data

Comments database

Open Configuration -> Server settings -> Databases -> Audit data and enter the URL, user and password.

URL : jdbc:mariadb://localhost:3306/default_comment

This solution makes it possible to secure access to the comment database.

Comments

Data entry database

Open Configuration -> Server settings -> Databases -> Data entry and enter the URL, user and password.

Select the Enable data entry checkbox and select a database in the drop-down list below. 

Data_entry.png

You must first have created a connection to the database from the Data connection manager in the Studio.
Enter default.user.ddentry for the user and password defined in the previous step.
The name defined in the Login Name field is the one that will appear in the database selection drop-down list.

DigDash Services

Open the Server status page : http://localhost:8080/ddenterpriseapi/serverstatus?adminDomain=adminconsole&serverDomain=ddenterpriseapi

Check that the DigDash services are activated and that the maximum memory is well adapted to the capacity of the server. You must leave at least 4 GB for the system.

Server status