Installation guide for Linux

Last modified by Aurelie Bertrand on 2024/07/11 16:30

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>

clipboard-202401241144-pb3ta.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
  2. Run the installation : 
    sudo dpkg -i opendj_4.x.x_all.deb

Initial setup

Launch the settings utility to follow the steps:

sudo /opt/opendj/setup

1.png
[Enter]
 

2.png

adminOpenDJ1
 

3.png

[Enter]
 

4.png

389
 

5.png

4444
 

6.png

[Enter]
 

7.png

[Enter]
 

8.png

dc=digdash,dc=com

9.png

2
 

https://lh7-us.googleusercontent.com/gs7BVYjtXGYivvccymzaxjIwiLn_ld-xJryFXxP8_aqZekStBkjWRjqRG-isbpEk97CVrMOFCsyCy-uzdIoltTdVWhurhNF_ycRAHaBeARw25JvamLrGFXuc-TIL7h6NQEb5iwhIMZIJOblCKog-n5c
oui
 

11.png

[Enter]
 

12.png

[Enter]
 

13.png

[Enter]
 

14.png

[Enter]
 

15.png

[Enter]

Additional settings

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

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

  3. Create the organizations using the “neworganization.ldif” file below:
    /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. To create a password checker:
    • Use the dsconfig.bat command, then log in with the Directory Manager credentials and accept the certificates.
    • Go to menu 29 then select “create a new Password Validator” > select “Character Set Password Validator” > enter “Custom Character Set Password Validator” > “true” > “true” > then configure 4 character-set as follows : 
      1:abcdefghijklmnopqrstuvwxyz
      1:ABCDEFGHIJKLMNOPQRSTUVWXYZ
      1:0123456789
      1:!"#$%&'()*+,-./:;\<=>?@[]^_`{|}~

      ➡ The result should look like this :
      Resultats.png

 

  1. For the second password checker, we can use a command line because it does not contain special characters: 
    /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 both password checkers:
    /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:
    /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 the admin using the “ppolicy-admin.ldif” file below:
    /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)" }

  2. Change the password policy to allow pre-encoded passwords (useful for restores in digdash) :
    /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
  3. Create an admin user for digdash via the “create_user_admin.ldif” file below
    /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:
    /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");)

    /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

  1. Generate a password for the administrator and remember it for later:
    /opt/opendj/bin/ldappasswordmodify --port 389 --bindDN "cn=Directory Manager" --bindPassword adminOpenDJ1 --authzID "u:admin"

Enabling automatic service start on startup

  1. Create the opendj.service file:
    sudo vi /etc/systemd/system/opendj.service
  1. Paste the following lines there:

    [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.

/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;

DigDash configuration 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