Advanced configuration

In this chapter we will describe all the advanced configuration parameters of Knowage.

Thread manager

For Tomcat: the configuration of the pool of thread is available inside the TOMCAT_HOME/conf/server.xml. Refer to Code below.

Configuration of the pool of thread for Tomcat.
1
2
3
4
5
6
7
<Resource auth="Container" factory="de.myfoo.commonj.work.FooWorkManagerFactory"
    maxThreads="5"
    minThreads="1"
    queueLength="10"
    maxDaemons="10"
    name="wm/SpagoWorkManager"
    type="commonj.work.WorkManager"/>

For JBoss: the configuration of the pool of thread is available inside the JBOSS_HOME/ standalone/configuration/s Refer to Code below.

Configuration of the pool of thread for JBoss.
1
2
3
4
5
6
7
8
9
<object-factory name="java:global/SpagoWorkManager" module="de.myfoo.commonj"
  class="de.myfoo.commonj.work.MyFooWorkManagerFactory">
  <environment>
  <property name="maxThreads" value="5"/>
  <property name="minThreads" value="1"/>
  <property name="queueLength" value="10"/>
  <property name="maxDaemons" value="10"/>
  </environment>
</object-factory>

In both cases, the meaning of the configuration parameters is the following:

  • minThreads: the minimum number of threads in the thread pool. Default: 2;
  • maxThreads: the maximum number of threads in the thread pool. Default: 10;
  • queueLenght: the number of work items that can be queued - 0 means no queuing. Default: 10;
  • maxDaemons: the maximum number of daemon threads to allow for this work manager. Default: 10.

Cache parameters

First of all, the user must configure the distributed cache. This helps to coordinate the parallel access to the distributed cache, guaranteeing a thread-safe access. It is necessary to configure the hazelcast.xml file (available in the knowage/WEB-INF/classes/) typing in the ”member“ tag the IP address or hostname of the machine on which Knowage is installed (for example <member> 192.168.29.43</member>). In case of multi-node configuration, it is obviously important to report all cluster members. This operation must be carried out on every node. Furthermore, it is possible to implement a finer tuning of the cache behaviour, changing the Knowage configuration. The user must edit some values of the SBI_CONFIG table using the specific administrator interface.

  • SPAGOBI.CACHE.NAMEPREFIX: It configures the prefix of temporary table in the cache ( Default : ”sbicache“ )
  • SPAGOBI.CACHE.SPACE_AVAILABLE: It resizes cache dimension (bytes) ( Default : 1024 )
  • SPAGOBI.CACHE.LIMIT_FOR_CLEAN: It configures the maximum cache section (in percentage) that can be cleaned at runtime when the cache has not enough space to store a dataset. ( Default : 50)
  • SPAGOBI.CACHE.DS_LAST_ACCESS_TTL: It configures the Time To Live of a dataset inside the cache. This parameter defines the minimum TTL (in seconds) so to guarantee that a dataset remains in cache. A too-high value can lead the cache to breakdown (in this case, there is no way to insert new datasets), while a too low value can lead to situations when there are no certainties of the stability of the dataset in the cache. (Default 600 )
  • SPAGOBI.CACHE.DATABASE_SCHEMA: Name of the schema on which the tables are created. Such schema is defined by the datasource when it is set as Write-Default. Generally it is not necessary to configure this parameter since it is calculated at runtime. (default <empty> )
  • SPAGOBI.CACHE.LIMIT_FOR_STORE: It configures the ratio (in percentage) between the dimension of the cache and the maximum dimension of a dataset in the cache. If the dimension of the dataset which the user intends to persist is bigger than the configured percentage, the system blocks the that persistence attempt. ( Default : 10 )
  • SPAGOBI.CACHE.CREATE_AND_PERSIST_TABLE.TIMEOUT: It represents the maximum time (in seconds) to create temporary table for the dataset. ( Default : 120 )
  • SPAGOBI.WORKMANAGER.SQLDBCACHE.TIMEOUT: It represents the maximum waiting time (in milliseconds) of an asynchronous work. (Default: 180000 )
  • SPAGOBI.CACHE.HAZELCAST.TIMEOUT : It represents the maximum time (in seconds) to get a distributed lock. ( Default 120 )
  • SPAGOBI.CACHE.HAZELCAST.LEASETIME: It represents the maximum time (in seconds) for releasing a distributed lock already got. ( Default :240 )
  • SPAGOBI.CACHE.SCHEDULING_FULL_CLEAN: It schedules the recurring operation of complete cleaning of the cache. This periodic cleaning delete all dataset in the cache, without considering further parameters. At the end of the cleaning, the cache is empty. The allowable values are:
Option Description
EVERY_1_MIN(“EVERY_1_MIN”, “0 0/1 * 1/1 * ? * “) every minute starting the changing of hour
EVERY_10_MINS(“EVERY_10_MINS”, “0 0/10 * 1/1 * ? * “) every 10 minutes starting the changing of hour
EVERY_15_MINS(“EVERY_15_MINS”,”0 0/15 * 1/1 * ? * “) every 15 minutes starting the changing of hour
EVERY_20_MINS(“EVERY_20_MINS”, “0 0/20 * 1/1 * ? * “) every 20 minutes starting the changing of hour
EVERY_30_MINS(“EVERY_30_MINS”, “0 0/30 * 1/1 * ? * “) every 30 minutes starting the changing of hour
HOURLY(“HOURLY”,”0 0 0/1 1/1 * ? * “) every hour
DAILY(“DAILY”,”0 0 0 1/1 * ? * “) every day at midnight
WEEKLY(“WEEKLY”, “0 0 0 ? * SUN * “) every week at midnight on Sunday
MONTHLY(“MONTHLY”, “0 0 0 1 1/1 ? * “) at midnight on the first day of the month
YEARLY(“YEARLY”, “0 0 0 1 1 ? * “) at midnight on the first day of the year

Any value other than those listed above does not enable periodic cleaning. ( Default: DAILY )

Logging

Knowage uses the component Log4J to create the log applications. Each web application has its own file inside the folder /knowageXXXX/WEB-INF/classes/log4j.properties. The content of this file change accordingly to the settings: the appenders allows to modify the level of the log. As an example, in the following code block, we analyze the log file of Knowage. In the first part we can set the generation mechanism of the log file, while in the second one the level of tracing.

Log appender.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 log4j.rootLogger=ERROR, SpagoBI

 # SpagoBI Appender
 log4j.appender.SpagoBI=org.apache.log4j.RollingFileAppender
 log4j.appender.SpagoBI.File=${catalina.base}/logs/knowage.log
 log4j.appender.SpagoBI.MaxFileSize=10000KB
 log4j.appender.SpagoBI.MaxBackupIndex=0
 log4j.appender.SpagoBI.layout=org.apache.log4j.PatternLayout
 log4j.appender.SpagoBI.layout.ConversionPattern=[%t] %d{DATE} %5p %c.%M:%L - %m %n

 log4j.appender.SpagoBI.append=false

 log4j.appender.Quartz=org.apache.log4j.RollingFileAppender
 log4j.appender.Quartz.File=${catalina.base}/logs/Quartz.log
 log4j.appender.Quartz.MaxFileSize=10000KB
 log4j.appender.Quartz.MaxBackupIndex=10
 log4j.appender.Quartz.layout=org.apache.log4j.PatternLayout
 log4j.appender.Quartz.layout.ConversionPattern= [%t] %d{DATE} %5p %c.%M:%L - %m  %n

 log4j.appender.SpagoBI_Audit=org.apache.log4j.FileAppender
 log4j.appender.SpagoBI_Audit.File=${catalina.base}/logs/knowage_[1]\_OperatorTrace.log

 log4j.appender.SpagoBI_Audit.layout=org.apache.log4j.PatternLayout
 log4j.appender.SpagoBI_Audit.layout.ConversionPattern=%m%n

 log4j.appender.CONSOLE = org.apache.log4j.ConsoleAppender
 log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
 log4j.appender.CONSOLE.layout.ConversionPattern=%c.%M: %m%n #


 log4j.logger.Spago=ERROR, SpagoBI log4j.additivity.Spago=false

 log4j.logger.it.eng.spagobi=ERROR, SpagoBI, CONSOLE
 log4j.additivity.it.eng.spagobi=false

 log4j.logger.it.eng.spagobi.commons.utilities.messages=ERROR, SpagoBI
 log4j.logger.it.eng.spagobi.commons.utilities.urls.WebUrlBuilder=ERROR,SpagoBI
 log4j.logger.org.quartz=ERROR, Quartz, CONSOLE
 log4j.logger.org.hibernate=ERROR, SpagoBI

 log4j.logger.audit=INFO, SpagoBI_Audit log4j.additivity.audit=false

If the user wishes to enable the tracing of the information to DEBUG level it is enough to modify the following line

1
 log4j.logger.it.eng.spagobi=ERROR, SpagoBI, CONSOLE

in

1
log4j.logger.it.eng.spagobi=DEBUG, SpagoBI, CONSOLE

For further details we refer to the official Log4J documents.

Mail server

Knowage uses in some situations the mail server to send emails. The configuration of this feature can be done right straight through the Knowage GUI, after accessing with administrator credentials.

Selecting the category MAIL the user gets the list of parameters to configure for the following profiles:

  • trustedStore;
  • scheduler, used by the scheduler to send a report by mail;
  • user, used directly by the user when he intends to send a report by mail;
  • kpi_alarm, used by the alarm component to send mails.
installation-guide/media/image28.png

Mail server configuration.

Moreover, each profile has the following values:

  • smtphost: the smpt server,
  • Smtpport: the port in use,
  • from: the address to which the mail will be associated,
  • user: the user of the server connection,
  • password: user’s password,
  • security: the user must choose between NONE, SSL and STARTTLS.

Maximum file size

For security reasons, Knowage has a series of parameters which manage the maximum file size that can be loaded on the server through the web GUI. To modify those parameters, it is required to enter the Knowage server application as administrator and access the ”server settings“ section and then ”configuration management“. The parameters at issue are the following:

  • SPAGOBI.TEMPLATE_MAX_SIZE : TEMPLATE MAX SIZE: it is the maximum template dimension of an analytical document, expressed in bytes; the default value is 5MB;
  • SPAGOBI.DATASET_FILE_MAX_SIZE : DATASET FILE MAX SIZE: it is the maximum dimension of a file used as a dataset, expressed in bytes; the default value is 10MB;
  • SPAGOBI.DOCUMENTS.MAX_PREVIEW_IMAGE_SIZE : Max preview image size: it is the maximum dimension of an image used as document preview (in the document browser, for instance), expressed in bytes; the default is 1MB;
  • IMAGE_GALLERY.MAX_IMAGE_SIZE_KB : Max image size in Kb: it is the maximum size of the images that can be used in a cockpit creation; the default is 1MB;

Date format

Knowage allows the user to visualize the date time in a format that depends on the selected language. To change the visualization of such formats, the user must enter Knowage as administrator and access the “Server Settings“ section and, consequently, the ”Configuration management“. Then finally select ”DATE-FORMAT“.

installation-guide/media/image29.png

Date format configuration.

For each available language there are two parameters:

  • SPAGOBI.DATE-FORMAT-<lingua>_<nazione>.format: it rules the back-end role;
  • SPAGOBI.DATE-FORMAT-<lingua>_<nazione>.extJsFormat: it rules the front-end role.

We suggest to set the parameters in compliance with each other, according to a local data.

The parameters SPAGOBI.DATE-FORMAT-SERVER.format and SPAGOBI.DATE-FORMAT-SERVER.extJsFormat control the link between back-end and front-end. The adjustment of these parameters do not affect the web GUI.

Language

Knowage manages the multi-language. The list of all languages is manageable from the “Server Settings” section. Go to “Configuration management“ and select the LANGUAGE_SUPPORTED category. Here there are two properties:

  • SPAGOBI.LANGUAGE_SUPPORTED.LANGUAGES: the list of all supported languages underneath this formalism are: [it,IT],[en,US],[fr,FR],[es,ES];
  • SPAGOBI.LANGUAGE_SUPPORTED.LANGUAGE.default: the default value is [en,US].

Adding new languages

To add more languages to the list (if not provided) a few steps are required:

  • Inside the “Configuration Management” add the language as required in previous chapter. If you don’t know the languages and country code you can get them from this language code table
  • Inside the “Domain Management” add the language as language ISO code as in the following image.
../_images/image355.png

domain management example.

  • Add inside the project folder Knowage-Server/knowage/src/main/webapp/js/lib/angular-localization/ the desired locale file from the angular locales and rename it with the lang code from language code table
  • Add inside the project folder Knowage-Server/knowage/src/main/webapp/js/src/messages/ the translations file. The name should be messages_country_LANGUAGE.properties. Ie: messages_country_sw_se.properties.

Warning: use the last step only if no zanata translations are available. Using Zanata should be the primary translations source.

Password constraints settings

User password constraints can be set configuring parameters below:

  • changepwdmodule.len_min: minimum number of character for the password;
  • changepwdmodule.special_char: set of allowed special characters;
  • changepwdmodule.upper_char: if active, the password must contain at least one of the uppercase characters set in the value;
  • changepwdmodule.lower_char: if active, the password must contain at least one of the lowercase characters set in the value;
  • changepwdmodule.number: if active, the password must contain at least one of the digit set in the value;
  • changepwdmodule.alphabetical: if active, the password must contain at least one alphabetical set in the value;
  • changepwdmodule.change: if true, new password must be different from the latest;
  • changepwd.change_first: if true, password must be changed at first login;
  • changepwd.disactivation_time: number of months before deactivation;
  • changepwd.expired_time: number of days for the expiration.
../_images/image318.png

Advanced configuration - password constraints settings.

By default, all above configurations are disabled.

Login security settings

Login security configurations can be set filling fields below:

  • internal.security.login.checkForMaxFailedLoginAttempts: if active and set to true, users will only be able to access Knowage if they have not reached the maximum number of failed login attempts;
  • internal.security.login.maxFailedLoginAttempts: the maximum number of failed login attempts.
../_images/image3211.png

Advanced configuration - login security settings.

Resource export folder cleaning settings

Resource export folder cleaning configurations can be set filling fields below:

  • KNOWAGE.RESOURCE.EXPORT.FOLDER.CLEANING_PERCENTAGE: if active, the cleaning procedure will delete the files contained in the export resource folder leaving this percentage of free space (0 - 100). Default 30;
  • KNOWAGE.RESOURCE.EXPORT.FOLDER.MAX_FOLDER_SIZE: if active, cleaning procedure will start only if the resource export folder will reach this size (byte). Default 10737418240.

Import / Export

Users

Specific configurations for users import procedure:

  • IMPORTEXPORT.USER.DEFAULT_PASSWORD: password set for all users imported by the import procedure.

Changing the secret key for password encryption

The secret password encryption key must be set during the installation and must never be changed. In case that the secret key is lost you must create a new one and update database passwords. For this reason Knowage provides you a tool to find out the new encrypted value.

This tool requires:

  • knowage-utils-<major.minor.patch>.jar (e.g. knowage-utils-8.0.1.jar) library to be added to the classpath
  • the password encryption secret file name with complete path
  • password value (plaintext)

Below is an example of invoking the tool using biadmin as plaintext password.

1
java -cp "TOMCAT_HOME/webapps/knowage/WEB-INF/lib/knowage-utils-<major.minor.patch>.jar" it.eng.spagobi.security.utils.PasswordEncryptionToolMain password/encryption/secret/file/name/with/complete/path biadmin

The output value will be the second argument passed in input encrypted with the key present in the file. This procedure must be repeated for all users.

Configure data decryption

At the moment there is two ways to support data decryption in datasets:

Watch out that the list of supported encryption algorithms strongly depends from JVM producer/version and the list of the installed JCE providers: please read the official documentation from your JVM.

Second, only password-based encryption algorithms are supported.

An example of supported algorithms in OpenJDK 8 is:

  • PBEWithHmacSHA1AndAES_128
  • PBEWithHmacSHA1AndAES_256
  • PBEWithHmacSHA224AndAES_128
  • PBEWithHmacSHA224AndAES_256
  • PBEWithHmacSHA256AndAES_128
  • PBEWithHmacSHA256AndAES_256
  • PBEWithHmacSHA384AndAES_128
  • PBEWithHmacSHA384AndAES_256
  • PBEWithHmacSHA512AndAES_128
  • PBEWithHmacSHA512AndAES_256
  • PBEWithMD5AndDES
  • PBEWithMD5AndTripleDES
  • PBEWithSHA1AndDESede
  • PBEWithSHA1AndRC2_128
  • PBEWithSHA1AndRC2_40
  • PBEWithSHA1AndRC4_128
  • PBEWithSHA1AndRC4_40

Generic decryption

Generic decryption is set via Java system properties encryption.algorithm and encryption.password: see the official Apache Tomcat documentation on how to do this.

We suggest to use CATALINA_OPTS environment variable via TOMCAT_HOME\bin\setenv.bat on Windows installations, or TOMCAT_HOME/bin/setenv.sh in Unix/Linux installations:

1
2
3
4
5
# In TOMCAT_HOME\\bin\\setenv.bat
set "CATALINA_OPTS=%CATALINA_OPTS% -Dencryption.algorithm=PBEWithMD5AndDES -Dencryption.password=knowage"

# In TOMCAT_HOME/bin/setenv.sh
export CATALINA_OPTS="$CATALINA_OPTS -Dencryption.algorithm=PBEWithMD5AndDES -Dencryption.password=knowage"

Privacy Manager by Engineering Ingegneria Informatica S.p.a.

The Privacy Manager is a web app reachable via an URL. To the access the web abb KNOWAGE requires an account, as username, password and application ID, provided by the administrator. KNOWAGE will get the decryption password from the Privacy Manager automatically.

Privacy Manager is set via Java system properties pm.url, pm.user, pm.password, pm.application and pm.algorithm: see the official Apache Tomcat documentation on how to do this.

We suggest to use CATALINA_OPTS environment variable via TOMCAT_HOME\bin\setenv.bat on Windows installations, or TOMCAT_HOME/bin/setenv.sh in Unix/Linux installations:

1
2
3
4
5
# In TOMCAT_HOME\\bin\\setenv.bat
set "CATALINA_OPTS=%CATALINA_OPTS% -Dpm.url=https://pm.local/ -Dpm.user=myuser -Dpm.password=mypwd -Dpm.application=KNOWAGE -Dpm.algorithm=PBEWithMD5AndDES"

# In TOMCAT_HOME/bin/setenv.sh
export CATALINA_OPTS="$CATALINA_OPTS -Dpm.url=https://pm.local/ -Dpm.user=myuser -Dpm.password=mypwd -Dpm.application=KNOWAGE -Dpm.algorithm=PBEWithMD5AndDES"