Skip to end of metadata
Go to start of metadata

Table of Contents

What are the minimum set of database privileges required to install ADSS Server?

The minimum set of database privileges required to install ADSS Server are:
  • Create
  • Drop
  • Alter
  • Delete
  • Index
  • Insert
  • Select
  • Update
  • Temporary Tables
  • Alter Routine
  • Create Routine
  • Execute

How to move the ADSS Server database from one machine to another?

If you are planning to move the ADSS Server database from one database server machine to another then follow these steps:
  1. Stop the ADSS Server Core, Console and Service components
  2. Take a backup of your current ADSS Server database
  3. Import the database backup on the new database server
  4. Then follow the instructions given in the below sections:
  5. Start the ADSS Server Core, Console and Service components

How to change the database name, machine name, port and username if ADSS Server is already installed?

To change the database name, machine name, port and username edit the hibernate.cfg.xml file in a text editor from location [ADSS Server installation directory]/conf, modify these properties: 
  • hibernate.connection.url
  • hibernate.connection.username

Restart the ADSS Core, Console and Service instances from Windows NT Services panel or UNIX daemon in order to take the password change into effect.

Icon

If the ADSS Server Core, Console and Service components are running on separate machines then the changes have to be made on all the ADSS Server instances separately

 

How to change the database password if ADSS Server is already installed?

Follow these steps to change the ADSS Server database password:
  1. Go to [ADSS-Server-Installation-Directory]\util\bin
  2. Run the "change_database_password.bat/sh"
  3. Provide the old and new password to change the password.
  4. Restart the ADSS Core, Console and Service instances from Windows NT Services panel or UNIX daemon in order to take the password change into effect.
Icon

If the ADSS Server Core, Console and Service components are running on separate machines then the changes have to be made on all the ADSS Server instances separately

 

How to move the ADSS Server database from SQL Server to Azure SQL? 

If you are planning to move the ADSS Server database from SQL Server to Azure SQL then follow these steps:
  1. Stop the ADSS Server Core, Console and Service components
  2. Take a backup of your current ADSS Server database
  3. Import the database backup on the Azure SQL
  4. Uninstall the existing ADSS Server
  5. Place the zipped package for the same version of ADSS Server at a different location on the same machine / a new machine
  6. Extract the ADSS Server package
  7. Copy the following files from the existing ADSS Server installation directory to the new one:
    • [ADSS-Server-Installation-Dir]\conf\adss.keystore
    • [ADSS-Server-Installation-Dir]\conf\pkcs11.properties
    • [ADSS-Server-Installation-Dir]\jdk\jre\lib\security\jssecacerts

    For ADSS Server v5.9 or later version, copy the Master Encryption Keys, these would be required at the time of installation

  8. Go to [Newly-Extracted-ADSS-Server-Installation-Dir]\tomcat\bin and edit these files: 

    Icon

    Please note that the following changes are only required if you are using ADSS Server v5.10 or older.

    For Linux

      • Edit catalina.sh file in a text editor and search for the parameter JAVA_OPTS and add parameter -Dcom.sun.net.ssl.enableECC=false at the end and save the changes as shown below:

        catalina.sh


    For Windows

      • Edit catalina.bat file in a text editor and search for the strings %JAVA_OPTS% %CATALINA_OPTS% and add parameter -Dcom.sun.net.ssl.enableECC=false at the end of each string and save the changes as shown below:

        catalina.bat
      • Edit the service.bat file in a text editor and search for the parameter --JvmOptions and ++JvmOptions one by one, add parameter ;-Dcom.sun.net.ssl.enableECC=false at the following location for both of them and save the changes

        service.bat
  9. Go to [Newly-Extracted-ADSS-Server-Installation-Dir]/setup directory and run the install.bat/sh file by right clicking and choosing Run as administrator option
  10. On the ADSS Server Installation Type dialog, select the option I want to install  ADSS Server using existing database
  11. This step is required for ADSS Server v5.9 or later. Import the keys by selecting the Key folder path and give password for all three keys that you have set in the previous installation.

  12. Select the appropriate ADSS Server license file
  13. Select the database type Azure SQL
  14. Provide the credentials for the restored database on Azure SQL
  15. Continue with the installation and click the Finish button to complete the installation. More detailed instructions can be found in section 3.1.4 of the ADSS Server installation guide.
  16. If there were load balanced instance(s) with the existing installation then add those again by reinstalling on the machine(s) reserved for this purpose. More detailed instructions can be found in section 3.1.2 of the ADSS Server installation guide.

How to change the default database connection pool size limits in ADSS Server?

The database connection pool can be re-configured for the ADSS Server Core, Console and Service instances to meet specific high volume needs by following these configurations:

Core Instance:

  1. Go to Global Settings > Advanced Settings page and select Core from the down:
  2. Change the value of hibernate.c3p0.maxPoolSize property according to your needs. The default value is 100.
  3. Restart the Core instance for this change to take effect.

Console Instance:

  1. Go to Global Settings > Advanced Settings page and select Console from the down:
  2. Change the value of hibernate.c3p0.maxPoolSize property according to your needs. The default value is 50.
  3. Restart the Console instance for this change to take effect.

Service Instance:

  1. Go to Global Settings > Advanced Settings page and select Service from the down:
  2. Change the value of hibernate.c3p0.maxPoolSize property according to your needs. The default value is 1000.
  3. Restart the Service instance for this change to take effect.

What are the possible issues when ADSS Server is unable to connect with the configured database?

The following are the possible issues when ADSS Server is unable to connect with the configured database with their solutions:
  • Verify that DB Server is up and running
  • Verify that DB Server machine is accessible from the ADSS Server machine
  • Verify that DB Server is accessible from other machine if ADSS Server machine is unable to communicate
  • Verify that DB Server is accessible from other client tool from the machine where ADSS Server is installed
  • Verify that DB password/rights are not changed for the user configured in ADSS Server
  • Verify that DB pool size is not exhausted, if so then restarted the DB Server and then ADSS Server
  • Check the DB health so that it response in a timely fashion
  • Verify that disk space is not fully utilized where DB Server is installed
  • Verify that logs/CRL archiving is not on the same drive where DB Server/ADSS Server is installed so that space is not consumed by them
  • Verify that "Store input and output documents in the transactions log" option is unchecked if not deemed necessary in the Server Manager sub-module of the Signing, Verification and Go>Sign Service so that database size does not grow and also to keep the DB size small.

How can I configure ADSS Server with database server running over SSL/TLS Authentication?

The following are the steps to configure the ADSS Server with database server running over SSL/TLS Authentication:
Icon

If the ADSS Server Core, Console and Service components are running on separate machines then the changes have to be made on all the ADSS Server instances separately

  1. Launch the ADSS Server Console and register the issuer CA of the database TLS/SSL Server Authentication Certificate in the Trust Manager with purpose CA for verifying SSL client certificates.

    Database Machine Name

    Icon

    Make Sure that TLS Server authentication certificate must include Machine Name/Domain Name/IP Address of the relevant database server deployment in certificate's Common Name and also as SAN extension.

  2. Stop the ADSS Server Core, Console and Service instances from Windows services or Unix daemons
  3. Uninstall these services by executing the [ADSS-Server-Installation-Dir]/setup/uninstall.bat/sh script by right clicking and choosing Run as administrator in case of Windows
  4. Open the [ADSS -Server-Installation-Dir]/setup/bin/internal.bat/sh file in edit mode and add the parameter -Djsse.enableCBCProtection=false after the memory parameters as shown below:

    internal.bat
  5. Edit the [ADSS -Server-Installation-Dir]/tomcat/bin/service.bat/sh file and add the parameter -Djsse.enableCBCProtection=false for ++JvmOptions as shown in the following snippet:

    service.bat
  6. Open the [ADSS -Server-Installation-Dir]/util/bin/export_logs.bat/sh file in edit mode and add the parameter -Djsse.enableCBCProtection=false after the memory parameters as shown below:

    export_logs.bat
  7. Open the [ADSS-Server-Installation-Dir]/setup/bin/compute_hmac.bat/sh file in edit mode and add the parameter -Djsse.enableCBCProtection=false to compute the HMAC over SSL:

    compute_hmac.bat
  8. Open the [ADSS -Server-Installation-Dir]/conf/hibernate.cfg.xml file in edit mode and update the hibernate.connection.url element by appending ;ssl=require as shown below:

    hibernate.cfg.xml
  9. Open the  [ADSS -Server-Installation-Dir]/tomcat/bin directory and run the install_core.bat/sh, install_console.bat/sh, install_service.bat/sh scripts by right clicking, choosing the Run as administrator one by one in case of Windows.

  10. Start the ADSS Server Core, Console and Service instances from Windows services or Unix daemons so that the connection is established with the database server over SSL/TLS Authentication.

How to change the ADSS Server database authentication scheme from SQL authentication to Windows authentication and vice versa?

 If you have an existing installation of ADSS Server which is using SQL authentication and you are planning to change it to Windows authentication (and vice versa) then follow these steps:
  1. Stop the ADSS Sever Core, Console and Service instances from the Windows Services Panel / UNIX Daemon.
  2. Go to location [ADSS Server Installation Directory]/conf/
  3. Open the file hibernate.cfg.xml in a text editor and search the property <property name="hibernate.connection.url"> and <"hibernate.connection.username">, make the changes accordingly:

    • For Windows Authentication (Kerberos):

      hibernate.cfg.xml

      Note: User name must be left empty or username property must be removed in case of Windows Authentication (Kerberos)


    • For Windows Authentication (NTLM):

      hibernate.cfg.xml
    • For SQL Authentication:

      hibernate.cfg.xml
  4. Change the password of the ADSS Server database by following this link: HowtochangethedatabasepasswordifADSSServerisalreadyinstalled
  5. Start the ADSS Sever Core, Console and Service instances from the Windows Services Panel / UNIX Daemon.

Why does the SQL Server database size increase after deleting records?

Background:
The SQL Server database grows upon deleting records because the transaction logs file substantially increases when the data is deleted/updated or created within the database.  Also upon deleting the data the used database space is not automatically released and a shrink operation needs to be performed.

Workaround:
The size of the ADSS Server database can be reduced by following these simple instructions, the instructions are written keeping in mind the SQL Server 2005 Enterprise, these may slightly change based on your specific version of the SQL Server database:
  1. Stop the ADSS Server Core, Console and Service instances from Windows NT Services panel
  2. Launch the SQL Server 2005 Enterprise management studio and connect to the database engine with relevant username and password
  3. Right click on the ADSS Server database > click on properties > point to Options tab
     
  4. On the above screen select the Recovery Model as “Simple” and click on “OK” buttonRight click on the ADSS Server database again > Point to Tasks > Shrink > Files
     
  5. On above screen select “Data” as File type, Enable the option to “Reorganize pages before releasing unused space” and provide the minimum recommended value for the “Shrink file to” parameter e.g. 681 in above case. Click on “OK” button.
  6. Wait for the database file shrink operation to complete.  The time required for the database file shrink operation depends upon the number of records present in the ADSS Server database.  In our lab, it took us 3 minutes to reduce the 2.5 GB database to 600 MB.
  7. Right click on the ADSS Server database again > Point to Tasks > Shrink > Files
     
  8. This time select “Log” as File type, select the option to “Reorganize pages before releasing unused space” and provide the minimum recommended value for the “Shrink file to” parameter e.g. 0 in above case.  Click on “OK” button
Database size reduction task has been performed.
  

Configuring SQL Server to use correct auto-increment for identity columns

Background: 
There is a "feature" (defect) in SQL 2012 where the identity values are jumping by around 1000 each time the service is restarted (Planed/Unplaned). Microsoft has changed the way they deal with identity values in SQL Server 2012 and as a result of this one can see identity gaps between database records after rebooting the SQL server instance or server machine. There are several connect item on the issue:
https://connect.microsoft.com/SQLServer/feedback/details/739013/failover-or-restart-results-in-reseed-of-identity

Workaround: 
Follow these instructions to configure SQL Server 2012 to work without problems with the ADSS Server:
  1. Open SQL Server Configuration Manager
  2. Click SQL Server Services on the left pane
  3. Right-click on your SQL Server instance name on the right pane -> Default: SQL Server(MSSQLSERVER)
  4. Click Properties.
  5. Click Startup Parameters.
  6. On the specify a startup parameter textbox type "-T272"
  7. Click Add and
  8. Confirm the changes

Currect Status

Icon

On planned shutdown the issue is fixed in SQL Server 2014 but still there for Unplaned shutdown

How can I handle the growing ADSS Server database temp db?

  1. Stop the ADSS Server Core, Console and Service instances from Windows services panel or UNIX daemon
  2. Launch the SQL Server management studio and connect to the database server
  3. Right click on the respective database for ADSS Server > Properties > Options
  4. Look for the property Is Read Committed Snapshot On, ensure that the value of this properly is set to False
     
  5. Start the ADSS Server Core, Console and Service instances from Windows services panel or UNIX daemon

 

How can I determine the number of DB connections acquired by the ADSS Server?

The following SQL Queries are used to determine the DB connection count:  

Special instructions for Percona XtraDB environment (Galera cluster)

  1. Disable the ECC cipher in Catalina. Follow this KB article and make changes accordingly in catalina.sh.
  2. Increase the value of max_connect_error parameter on MySQL. Follow the instructions at this link and set max_connect_errors=10000.

  3. If you're accessing the cluster through a load balancer, make sure that the idle timeout on the proxy is greater than 28800 seconds (default value in MySQL and hibernate).

 

Known issues when installing ADSS Server with MySQL

  1. Invalid default value for 'CreatedAt'
    Cause & solution: Error is occuring because of sql_modes. Please check your current sql_modes by command:

    And remove the sql_mode "NO_ZERO_IN_DATE,NO_ZERO_DATE" to make it work.

  2. MySQLSyntaxErrorException: Table XYZ doesn't exist
    Cause & solution: The issue is that table names in MySQL are case sensitive and hibernate is upper casing them.
    1. Drop the database.

    2. Add the following to /etc/mysql/my.conf:

    3. Restart mysqld.

    4. Install ADSS Server with new database.

  3. To solve database table explicit primary key problem, update /etc/mysql/my.cnf in all data nodes

  4. Database meta information is not shown on ADSS Server Console and will be picked up in a later release. Last updated when ADSS Server v5.5 was released.

 

Known issues when installing ADSS Server with ORACLE

If the Oracle database used for ADSS Server installation have multiple users then some times ADSS Server tries to connect with the first available database schema, follow these instruction to resolve this issue:

  1. Stop the ADSS Sever Core, Console and Service instances from the Windows Services Panel / UNIX Daemon. 
  2. Go to location: [ADSS-Server-Installation-Dir]\conf\
  3. Edit the hibernate.cfg.xml file and search for the property <property name="hibernate.connection.username">

  4. Place following property after the above one (Remeber to add the correct Database schema name):

    hibernate.cfg.xml
  5. Save the changes 
  6. Start the ADSS Sever Core, Console and Service instances from the Windows Services Panel / UNIX Daemon.

Configure ADSS Server with database SQL server running over TLS Authentication?

If you are running ADSS Server v5.6 or later then the following are the steps to configure the ADSS Server with database server over TLS Authentication:

If the ADSS Server Core, Console and Service components are running on separate machines then the changes have to be made on all the ADSS Server instances separately

  1. Generate a self-signed certificate with FQDN of the machine/server name in the CN and SAN extension of the TLS Server Authentication certificate (you can use ADSS Server to generate a self-signed certificate)
  2. Launch the ADSS Server Console and register the issuer CA of the database TLS Server Authentication Certificate in the Trust Manager with purpose CA for verifying SSL client certificates.
  3. Install the TLS Server Authentication key on database server and enable the TLS encryption of SQL Server by using SQL Server Configuration Manager utility. Follow the below link to enable the TLS encryption on SQL Server: https://support.microsoft.com/en-hk/help/316898/how-to-enable-ssl-encryption-for-an-instance-of-sql-server-by-using-mi

  4. Download the Microsoft JDBC driver from link: https://www.microsoft.com/en-us/download/details.aspx?id=56615.

  5. Extract the downloaded JDBC driver
  6. Copy the mssql-jdbc-6.4.0.jre8.jar file from the driver directory at the following directories:

    1. [ADSS-Server-Installation-Dir]\core\server\webapps\core\WEB-INF\lib

    2. [ADSS-Server-Installation-Dir]\consoleconsole\server\webapps\console\WEB-INF\lib

    3. [ADSS-Server-Installation-Dir]\serviceservice\server\webapps\service\WEB-INF\lib

  7. Stop the ADSS Server Core, Console and Service instances from Windows services or Unix daemons
  8. Go to [ADSS-Server-Installation-Dir]/conf/ and take a backup of the hibernate.cfg.xml file
  9. Edit the hibernate.cfg.xml file in edit mode and update the hibernate.connection.driver_classhibernate.connection.url  and hibernate.hbm2ddl.auto elements as following:

    hibernate.cfg.xml
  10. Start the ADSS Server Core, Console and Service instances from Windows services or Unix daemons so that the connection is established with the database server over TLS Authentication.

If you wish to configure the ADSS Server with SQL Server database using Windows Authentication option then additionally following these instructions:

  1. Copy the sqljdbc_auth.dll file from download package (sqljdbc_6.4\enu\auth\x64) of Microsoft JDBC driver and put the sqljdbc_auth.dll file at [ADSS-Server-Installation-Dir]\jdk\jre\bin change hibernate.cfg.xml file as following:

    hibernate.cfg.xml
  2. Configure the ADSS Server Services in Windows Services Panel to run under a domain user
  3. Start the ADSS Server Core, Console and Service instances from Windows Services Pane

Installation error with MySQL Database "Invalid default value for 'CreatedAt'"

If you are unable to install the MySQL database with error "Invalid default value for 'CreatedAt'" then follow these instructions:-

The default sql_mode variable has the following below value in a vanilla installation:

  • Create a new MySQL database
  • Extract a fresh copy of ADSS Server and run the installer
  • Copy the driver in core,console and service directories

 

  • No labels