This topic describes how to set up an XperienCentral installation in a Linux production environment. The result is that all requests for static content (images, style sheets, etc.) are handled through the web server and requests for dynamic content (XperienCentral’s HTML) are forwarded by the web server to XperienCentral which processes the requests. In this topic, an environment will be created with two host names:

External host name: www.mywebsite.com

Internal host name: edit.mywebsite.com

In This Topic

The Directory Structure

After installing XperienCentral, a directory structure is created. You are free to choose your own structure, but GX Software recommends the following:

`/vol/www/server/`	Apache Tomcat web server location
`/vol/www/tomcat-mywebsite/deploy`	Tomcat directory
`/vol/www/mywebsite/configuration/`	Contains the `configuration.xml` file
`/streaming/`	♦ Website downloads
`/system/`	♦ System files
`/web-docs/cfg/`	♦ Flash element configuration
`/toolbar/`	Poll element files
`/upload/`	Page images
`/upload_mm/`	Content Repository images
`/wm/`	Standard XperienCentral files
`/work/cache/`	Cache for plugins and pages
`/deploy/`	Plugins
`/edition-bundles/`	♦ Source files for XperienCentral plugins
`/formupload/`	Binaries of sent forms
`/jcr/`	JCR-related files
`/osgi/`	Cache for OSGi framework files
`/undo/`	Cache for the undo/redo functionality

You can create all or part of this directory structure before starting the entire installation process. Create the directories marked with ♦ before starting the installation. The others will be created later in this topic.

Back to top

Java Development Kit

XperienCentral uses the Java SE Development Kit (JDK) which can be downloaded from: http://www.oracle.com/technetwork/java/javase/downloads.

Use Java version 17.
Use the 64-bit version of Java if possible.

Download and install the JDK for your platform.

cd /usr
mkdir java
cd java
chmod 700 /tmp/jdk-8-linux-i586-rpm
/tmp/jdk-8-linux-i586-rpm
rm -f /tmp/jdk-8-linux-i586-rpm
ln -sf /usr/java/jdk8 /usr/java/jdk1.8

Verify that the new JDK is being used: After entering java –version, the Java version number is displayed. If it is not the correct version, modify the PATH variable and point it to the correct version.

Setting environment variables is best done in the startup script of the shell being used (~/.profile or ~/.cshrc for example). This adds the variable permanently so you do not have to enter the export command multiple times.

Back to top

Apache Maven

To install XperienCentral, use the Maven build tool. This tool can be downloaded from: http://maven.apache.org/. Download and install version 3.6.xx. For example:

cd /usr/local/
tar zxf /tmp/apache-maven-3.6.xx-bin.tar.gz
rm -rf /tmp/apache-maven-3.6.xx*
ln -sf apache-maven-3.6.xx

After the installation, Maven will still have to be recorded in the PATH variable and the M2_HOME variable will need to be set. For example:

export PATH=/usr/java/jdk1.8/bin:$PATH
export PATH=/usr/local/maven/bin:$PATH
export M2_HOME=/usr/local/maven/
export JAVA_HOME=/usr/java/jdk1.8/

Verify that the new version of Maven is being used. After entering mvn –version, the Maven version number is displayed. If an older version is indicated, remove the Maven version already on the system.

Back to top

The Database

XperienCentral works with the following databases:

Oracle
MSSQL
MySQL

For the exact versions of the above listed databases, see the XperienCentral hardware and software requirements. Install one of the databases and create a username and password for someone with permission to create and fill a table. The following are example UNIX commands for MySQL in a Red Hat Enterprise Linux environment:

cd /tmp
rpm -i MySQL-server-community-5.0.45-0.rhel4.i386.rpm
rpm -i MySQL-client-community-5.0.45-0.rhel4.i386.rpm
rpm -i MySQL-shared-community-5.0.45-0.rhel4.i386.rpm
/usr/bin/mysqladmin -u root password '<myDBpassword>'

The default MySQL settings need to be adjusted to make it work smoothly with XperienCentral. Create the file my.cnf and place it in the directory /etc. The initial contents of this file should be:

[mysqld]
max_allowed_packet=512M
innodb_buffer_pool_size=256M
[mysqldump]
max_allowed_packet=512M

For MySQL versions 5.7 and higher, add the following to the [mysqld] section:

optimizer_switch = derived_merge=off

Restart MySQL after you have changed the /etc/my.cnf file.

Back to top

The Application Server (Tomcat or JBoss)

XperienCentral runs within an application server. Install either Tomcat or Jboss (not both).

Tomcat

Download the latest version of Apache Tomcat from http://tomcat.apache.org/) and unpack it in the /vol/www/ directory. Rename the created directory tomcat-mywebsite. For example:

cd /vol/www/
tar zxf /tmp/apache-tomcat-x.tar.gz
mv apache-tomcat-x tomcat-mywebsite
rm -f /tmp/apache-tomcat-x.tar.gz
# Also add the directories for the expanded XperienCentral files
cd tomcat-mywebsite
mkdir deploy
mkdir deploy/appBase

Add the following lines to /vol/www/tomcat-mywebsite/bin/catalina.sh, directly under the first block of comment lines:

CATALINA_HOME=/vol/www/tomcat-mywebsite
JAVA_HOME=/usr/java/jdk11
JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.server.gcInterval=600000"
JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.client.gcInterval=600000"
JAVA_OPTS="${JAVA_OPTS} -Duser.language=en -Duser.country=US"
JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC"
JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
JAVA_OPTS="${JAVA_OPTS} -Dwebmanager.clustering.readonly=false"
JAVA_OPTS="${JAVA_OPTS} -Dsun.net.inetaddr.ttl=300"
JAVA_OPTS="${JAVA_OPTS} -Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"
JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -Xms512M"
JAVA_OPTS="${JAVA_OPTS} -Dorg.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false"
JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x"
JAVA_OPTS="${JAVA_OPTS} -Djava.net.preferIPv4Stack=true"

The settings used in the above example are good defaults and need no adjusting. The only parameter that might need adjusting is the Xmx parameter. The number in the Xmx parameter determines the maximum RAM allowed for the Java process in which XperienCentral runs. In this example, the RAM is set at 1024 MB (1 GB). The higher this number is set, the smoother XperienCentral will run.

Add the following options in your setenv.sh file of tomcat:

For JAVA_OPTS:

-Djava.locale.providers=COMPAT,CLDR

For Catalina add:

--illegal-access=warn --add-opens java.base/java.net=ALL-UNNAMED

In a clustered environment, substitute the x in JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x with a unique name for each node in the cluster (GX Software recommends using the name of the server for the clustering ID). For a read-only node one setting has to be adjusted: set the property webmanager.clustering.readonly to true. See Distributed XperienCentral (Linux) for complete information about setting up a clustered environment.

See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS settings.

Avoiding Clogged Logfiles

With the default settings, the log file will be quickly filled with messages, (INFO, WARNING, and ERROR). GX Software recommends adjusting the logging.properties file in Tomcat in order to reduce the number of messages that are logged. Proceed as follows:

Open the /vol/www/tomcat-mywebsite/conf/logging.properties file.
Replace the line with the handler definition (first uncommented line starting with "handlers = ") with the following:
```
handlers = 1catalina.org.apache.juli.AsyncFileHandler, 5gxsecuritylogging.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
```
This removes unused logfiles localhost.<date>.log, host-manager.<date>.log and manager.<date>.log and adds a special handler for GX security logging.
Do not adjust the line starting with .handlers =.

At the end of the file, add the following lines:

############################################################
# GX WebManager specific properties.
# Provides for GX WebManager logging.
############################################################
nl.gx.level = WARNING
org.apache.felix.level = WARNING
org.apache.jackrabbit.level = WARNING
org.apache.solr.level = WARNING
org.quartz.level = WARNING
org.springframework.level = WARNING

nl.gx.webmanager.startup.level = INFO
# Upgrade bundle logging
nl.gx.webmanager.services.upgrade.impl.level = INFO

#OpenID
org.verisign.joid.level = WARNING

##
# Logging of sensitive events to separate log file
##
5gxsecuritylogging.org.apache.juli.FileHandler.level = INFO
5gxsecuritylogging.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
5gxsecuritylogging.org.apache.juli.FileHandler.prefix = audit.

nl.gx.webmanager.services.securitylogging.level=INFO
nl.gx.webmanager.services.securitylogging.handlers=5gxsecuritylogging.org.apache.juli.FileHandler
nl.gx.webmanager.services.jaxrs.search.bulkactions.impl.BulkActionJob.level = INFO

JBoss

Download JBoss EAP 7.2.0 (https://developers.redhat.com/products/eap/download) and unpack it in the /vol/www/ directory. Rename the created directory jboss-mywebsite. Add the following lines to /vol/www/jboss-mywebsite/bin/standalone.conf, directly under the first block of commented lines:

JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.server.gcInterval=600000"
JAVA_OPTS="${JAVA_OPTS} -Dsun.rmi.dgc.client.gcInterval=600000"
JAVA_OPTS="${JAVA_OPTS} -Duser.language=en -Duser.country=US"
JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC"
JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
JAVA_OPTS="${JAVA_OPTS} -Dwebmanager.clustering.readonly=false"
JAVA_OPTS="${JAVA_OPTS} -Dsun.net.inetaddr.ttl=300"
JAVA_OPTS="${JAVA_OPTS} -Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"
JAVA_OPTS="${JAVA_OPTS} -Xmx1024M -Xms512M"
JAVA_OPTS="${JAVA_OPTS} -Dorg.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false"
JAVA_OPTS="${JAVA_OPTS} –Dwebmanager.clustering.id=x"
JAVA_OPTS="${JAVA_OPTS}  -Djboss.modules.policy-permissions=true"

By default, the settings in the above example need no further adjusting. The only parameter that you might have to change is the Xmx parameter. The value of the Xmx parameter determines the maximum amount of RAM allowed for the Java process in which XperienCentral runs. In the above example, the maximum amount of RAM is set to 1024 MB (1 GB). The higher this number is set, the better the performance you will have.

Add the following option to the standalone.conf file of your JBoss installation when using Java 11 for XperienCentral:

# Use the default JRE JAX parsers instead of Xerces. Xerces 1.12.0-SP02 is on the classpath of JBoss 7.2 by default
JAVA_OPTS="${JAVA_OPTS} -Djavax.xml.transform.TransformerFactory=com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl -Djavax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl"
# Set the locale providers for Java >= 9
JAVA_OPTS="${JAVA_OPTS} -Djava.locale.providers=COMPAT,CLDR"

See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS settings.

The above settings are OK for a standalone setup of XperienCentral and the setup of a read/write node in a clustered environment. For a read-only node one setting has to be adjusted: set the property webmanager.clustering.readonly to true.

Avoiding Clogged Logfiles

With the default settings, the log file will be quickly filled with messages, (INFO, WARNING, and ERROR). To reduce the number of messages that are logged, adjust the (JBoss)/JBoss-My Website/standalone/configuration/standalone.xml file and add the following loggers where the other logger tags are located in the jboss.domain.logging subsystem:

<logger category="org.apache.felix">
   <level name="WARN"/>
</logger>
<logger category="org.apache.jackrabbit">
   <level name="WARN"/>
</logger>
<logger category="org.apache.solr">
   <level name="WARN"/>
</logger>
<logger category="org.quartz">
   <level name="WARN"/>
</logger>
<logger category="org.springframework">
   <level name="WARN"/>
</logger>
<logger category="nl.gx.webmanager.startup">
   <level name="INFO"/>
</logger>
<logger category="nl.gx.webmanager.services.upgrade.impl">
   <level name="INFO"/>
</logger>

Back to top

Apache Web Server

Download the latest version of the Apache web server (http://httpd.apache.org/download.cgi) and install it. How to compile Apache is explained in the examples below. It is also possible to use the Apache included in the package.

Because new versions are regularly relased, it is recommended that you configure Apache according to the package standards by including configuration files containing your specific configuration parameters instead of modifying httpd.conf itself. Doing so ensures that you do not lose custom configuration settings during an update.

Configuration of httpd.conf

For the httpd.conf file, XperienCentral requires at a minimum the following extra modules:

mod_proxy.so
mod_proxy_http.so
mod_proxy_ajp.so
mod_headers.so
mod_expires.so
mod_security2.so

The httpd-vhosts.conf file also needs to be read. Locate vhosts in the httpd.conf and delete the # at the beginning of the line:

Include conf/extra/httpd-vhosts.conf

Configuration of httpd-vhosts.conf

The httpd-vhosts.conf file is located in the /vol/www/server/conf/extra directory of Apache. The configurations for VirtualHosts of the frontend and backend are located here.

<VirtualHost *:80>
   ServerName www.mywebsite.com
   DocumentRoot "/vol/www/mywebsite/web-docs/"
   ErrorLog logs/www.mywebsite.com_error.log
   CustomLog logs/www.mywebsite.com_custom.log common
   <Directory "/vol/www/mywebsite/web-docs/">
      Options +FollowSymLinks +includesnoexec
      AllowOverride All
      Require all granted
   </Directory>
   ProxyPass /web/ ajp://localhost:8009/web/ ttl=600
   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteCond %{REQUEST_URI} !^/web/
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher 
    </IfModule>
</VirtualHost>

The following is the minimal setup of the virtual host for the internal environment of XperienCentral (HTTP):

<VirtualHost *:80>
   ServerName edit.mywebsite.com
   DocumentRoot "/vol/www/mywebsite/web-docs/"
   ErrorLog logs/edit.mywebsite.com_error.log
   CustomLog logs/edit.mywebsite.com_custom.log common
   <Directory "/vol/www/mywebsite/web-docs/">
      Options +FollowSymLinks +includesnoexec
      AllowOverride All
      Require all granted
   </Directory>
   <Directory "/vol/www/mywebsite/web-docs/wm/b/">
      ExpiresActive ON
      ExpiresDefault "now plus 10 minutes"
      Header set Cache-Control "max-age=600"
   </Directory>
   ProxyPass /web/ ajp://localhost:8009/web/ ttl=600
   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteCond %{REQUEST_URI} !^/web/  RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
</VirtualHost>

Backend Configuration of httpd-vhosts.conf for a Redirect to HTTPS

The following is the minimal setup of the virtual host for the internal environment of XperienCentral (HTTPS):

<VirtualHost *:80>
   ServerName www.mywebsite.com
   DocumentRoot "/vol/www/mywebsite/web-docs/"
   ErrorLog logs/www.mywebsite.com_error.log
   CustomLog logs/www.mywebsite.com_custom.log common
   <Directory "/vol/www/mywebsite/web-docs/">
      Options +FollowSymLinks +includesnoexec
      AllowOverride All
      Require all granted
   </Directory>
   ProxyPass /web/ ajp://localhost:8009/web/ ttl=600
   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
# Rewrite external requests to https
   <IfModule mod_rewrite.c>
      RewriteEngine On
      LogLevel emerg
      RewriteCond %{HTTPS} off
      RewriteCond %{REMOTE_HOST} !###\###\###\###$ (substitute the #s with the IP address of the backend server)
      RewriteCond %{REMOTE_HOST} !127\.0\.0\.1$
      RewriteCond %{REMOTE_HOST} !localhost$
      RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L]
      RewriteRule ^/wm.* - [L]
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
</VirtualHost>

Frontend Configuration of httpd-vhosts.conf for an HTTPS Redirect

The following is the minimal setup of the virtual host for an external frontend environment of XperienCentral that redirects to HTTPS:

<VirtualHost *:80>
   ServerName www.mywebsite.com
   DocumentRoot "/vol/www/mywebsite/web-docs/"
   ErrorLog logs/www.mywebsite.com_error.log
   CustomLog logs/www.mywebsite.com_custom.log common
   <Directory "/vol/www/mywebsite/web-docs/">
      Options +FollowSymLinks +includesnoexec
      AllowOverride All
      Require all granted
   </Directory>
   ProxyPass /web/ ajp://localhost:8009/web/ ttl=600
   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
# Rewrite external requests to https
   <IfModule mod_rewrite.c>
      RewriteEngine On
      LogLevel emerg
      RewriteCond %{HTTPS} off
      RewriteCond %{REMOTE_HOST} !###\###\###\###$ (substitute the #s with the IP address of the frontend server)
      RewriteCond %{REMOTE_HOST} !127\.0\.0\.1$
      RewriteCond %{REMOTE_HOST} !localhost$
      RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L]
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
</VirtualHost>

Backend Configuration of httpd-vhosts.conf for HTTPS

The following is the minimal setup of the virtual host for an external backend HTTPS environment of XperienCentral:

<VirtualHost *:443>
   ServerName   <server name>
   ServerAdmin  <admin e-mail address>
   DocumentRoot  /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x
   ErrorLog      /vol/httpd/logs/errors-edit-ssl
   CustomLog     /vol//httpd/logs/access-edit-ssl combined

   #############
   # SSL
   SSLEngine On
   SSLProxyEngine On
   SSLProtocol +TLSv1
   ## See https://mozilla.github.io/server-side-tls/ssl-config-generator
   ## for information on other rules you should add here for the version
   ## of Apache you are using.


   SSLCertificateFile /vol/httpd/ssl/nolaa.crt
   SSLCertificateKeyFile /vol/httpd/ssl/nolaa.key

   SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
   # CustomLog /vol/www/server/logs/ssl/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

   <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x>
      Options +FollowSymLinks +includesnoexec
      AllowOverride All
      Require all granted
   </Directory>

   <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x/wm/b/toolbar/>
      ExpiresActive ON
      ExpiresDefault "now plus 10 minutes"
      Header set Cache-Control "max-age=600"
   </Directory>
   <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x/wm/b/domapi/>
      ExpiresActive ON
      ExpiresDefault "now plus 10 minutes"
      Header set Cache-Control "max-age=600"
   </Directory>

   ProxyPass         /web/ ajp://localhost:19200/web/ttl=600
   ProxyPassReverse  /web/ ajp://localhost:19200/web/
 
   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteLogLevel 0
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  
   </IfModule>
   
   Alias /systemlogs /vol/webmanager/apache-tomcat-8.5.31/logs
      <Location /systemlogs>
         <IfModule mod_deflate.c>
            SetOutputFilter DEFLATE
         </IfModule>
         AuthUserFile /vol/httpd/htpasswd
         AuthName ""
         AuthType Basic

         Options +Indexes
         IndexOptions FancyIndexing

         Order Deny,Allow
         Allow from all
         Allow from localhost
         Allow from <IP address>
   </Location>

   ScriptAlias /cgi-bin "/vol/www/server/cgi-bin"
</VirtualHost>

</IfDefine>

For HTTPS support, you also need to add the –D SSL flag to the Options="" line of the /etc/sysconfig/httpd to enable SSL for the Apache web server.

Frontend Configuration of httpd-vhosts.conf for HTTPS

The following is the minimal setup of the virtual host for an external frontend HTTPS environment of XperienCentral:

<VirtualHost *:443>
   ServerName        <server name>
   ServerAdmin       <admin e-mail address>
   DocumentRoot      /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x
   ErrorLog          /vol/httpd/logs/errors-frontend-ssl
   CustomLog         /vol/httpd/logs/access-frontend-ssl combined

   #################
   # SSL

   SSLEngine On
   SSLProxyEngine On
   SSLProtocol +TLSv1
   ## See https://mozilla.github.io/server-side-tls/ssl-config-generator
   ## for information on other rules you should add here for the version
   ## of Apache you are using.

   SSLCipherSuite HIGH:MEDIUM

   SSLCertificateFile /vol/httpd/ssl/<certificate>.crt
   SSLCertificateKeyFile /vol/httpd/ssl/<certificate>.key

   SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0

   ### CustomLog /vol/www/server/logs/ssl/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

#  Test: Recognize this VirtualHost
   Alias /systemlogs2 /vol/webmanager/apache-tomcat-8.5.31/logs
   <Location /systemlogs2>
      <IfModule mod_deflate.c>
         SetOutputFilter DEFLATE
      </IfModule>
      AuthUserFile /vol/httpd/htpasswd
      AuthName ""
      AuthType Basic

      Options +Indexes
      IndexOptions FancyIndexing
      Order Deny,Allow
      Allow from all
      Allow from localhost
      Allow from <IP address>
   </Location>

   <Directory /vol/webmanager/webmanager-webapps/webmanager-static-webapp/target/webmanager-static-webapp-10.x.x>
      Options +FollowSymLinks +includesnoexec
        AllowOverride All
      Require all granted
   </Directory>

ProxyPass         /web/ajp://localhost:19200/web/ ttl=600
ProxyPassReverse  /web/ajp://localhost:19200/web/

   <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteLogLevel 0

      # Give not found on /web/admin/* on frontend url.
      RewriteCond %{REQUEST_URI}^/web/admin
      RewriteRule ^/web/admin - [R=404]
      RewriteRule ^/(.*)\.htm$ /web/$1.htm [PT,L] //xperiencentral versions r35 and lower
	  RewriteRule ^/(.*)\.htm$ /web/seo/$1.htm [PT,L] //xperiencentral versions r36 and higher  

   </IfModule>
</VirtualHost>

The .htaccess File

The .htaccess file is needed to also set a CSP policy on static assets that are typically served from disk by Apache httpd. Configure the .htaccess file (if your deployment requires it). See https://httpd.apache.org/docs/2.4/howto/htaccess.html for complete information.

Remove Server Header Configuration

In order to prevent Apache from idenitfying itself, add the following content to /etc/httpd/conf.d/remove-server-header.conf. This configuration step is optional.

<IfModule security2_module>
SecRuleEngine on
SecServerSignature " "
</IfModule>

Handling Uploaded Files

The following applies to XperienCentral versions 10.29.3 and higher.

In order to prevent uploaded files from being be opened inside the browser, you need to add a rule that specifies which uploaded files should be treated as an attachment. Add the following rule to one of the Apache httpd.conf include files:

<Location ~ "(/upload|/upload_mm)">
Header set Content-Disposition "attachment"
</Location>

HTTP/2 Support

Beginning with Apache Web server version 2.4.17, the HTTP/2 protocol is supported. Starting with version 10.12.0, XperienCentral is also tested on HTTP/2 over TLS. In principle, earlier 10.x versions of XperienCentral should also work over HTTP/2 but they have not been tested by GX Software.

Apache states on its website that the configuration of HTTP/2 is still an evolving process and that the mod_http2 module will continue to undergo improvements and tweaks and will change from version to version much more than the established modules. Keep this in mind when upgrading your Apache Web server.

In order to support HTTP/2, the Apache module mod_http2 must be loaded. HTTP/2 support is enabled by the following rule within mod_http2:

# HTTP/2
Protocols h2 http/1.1

For more information on the mod_http2 module, see https://httpd.apache.org/docs/2.4/mod/mod_http2.html.

X-Frame Options

The following applies to XperienCentral versions 10.16.1 and higher.

Browsers can restrict or deny the loading of a web page inside a frame, iframe or other object by reacting to the HTTP response header X-Frame-Options associated with that page. Setting this property correctly can prevent click-jacking attacks (https://en.wikipedia.org/wiki/Clickjacking).

This property has three options:

DENY - The page may never be loaded inside another page.
SAMEORIGIN - The page may only be loaded inside another page if it has the same origin.
ALLOW-FROM <origin> - The page may only be loaded inside another page if it is from the indicated origin (www.mywebsite.com, for example).

The option ALLOW-FROM is not recommended because it is not universally supported by all browsers.

In general you are advised to use this property with the option SAMEORIGIN in order to prevent click-jacking attacks. For the frontend environment you can also choose the DENY option, but be aware that with this option pages can no longer be embedded in frames, iframes or other objects.

Configuring the Apache HTTP server for X-Frame-Options is effective for pages served both by XperienCentral and external static pages.

Frontend Environment

Add the header for X-Frame-Options to the frontend environment (add in your .conf file):

<VirtualHost *:80>
   ServerName www.mywebsite.com
   ...
   Header always set X-Frame-Options SAMEORIGIN
   ...
</VirtualHost>

Instead of SAMEORIGIN you can also specify DENY which will disable all embedding of pages into iframes, frames and other objects.

Backend Environment

Add the header for X-Frame-Options to the backend environment (internal edit environment of XperienCentral) (add in your .conf file):

<VirtualHost *:80>
   ServerName edit.mywebsite.com
   ...
   Header always set X-Frame-Options SAMEORIGIN
   ...
</VirtualHost>

For the backend environment you cannot use DENY because XperienCentral itself uses frames.

X-Content-Type-Options and X-XSS-Protection

The following applies to XperienCentral versions 10.17 and higher.

GX Software strongly recommends that you consult with us before implementing the X-Content-Type-Options and/or X-XSS-Protection configuration(s) described below in order to ensure that either or both are appropriate for your XperienCentral implementation.

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed. The HTTP X-XSS-Protection response header is a feature of Internet Explorer, Chrome and Safari that stops pages from loading when they detect reflected cross-site scripting (XSS) attacks.

Frontend Environment

Add the headers to the frontend environment (add in your .conf file):

<VirtualHost *:80>
   ServerName www.mywebsite.com
   ...
   Header always set X-Content-Type-Options nosniff
   Header always set X-XSS-Protection "1; mode=block"  
   Header always edit Set-Cookie (.*) "$1; SameSite=strict"
   Header always set Strict-Transport-Security "max-age=63072000" env=HTTPS
   Header always set Content-Security-Policy "default-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src 'self'; worker-src 'self'; img-src 'self' data:; script-src 'self' 'unsafe-inline' 'unsafe-eval' data: https: wss:"
   ... 

</VirtualHost>

In the example above, the Content-Security-Policy declarations are set to a very strict level and will, among other things, prevent the embedding of external content using, for example, Oembed. If you want to allow the embedding of external content in the frontend environment or use less strict security, you need to relax one or more of these rules. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy for more information.

If you want to include an additional rule to set the HttpOnly flag on cookies, make sure to exclude the X-CSRF-Token cookie from that rule because the anti-CSRF protection in XperienCentral is based on the fact that a browser does not allow JavaScript code to read from cookies from another domain and setting the HttpOnly flag disables access to the cookie from all JavaScript code. For example:

# Set HttpOnly and Secure flag on all cookies except for X-CSRF-Token cookie (required for submitting any sort of form in R33 and higher).
Header edit Set-Cookie ^((?!X-CSRF-Token=).*)$ $1;HttpOnly;Secure env=object_is_secure

Backend Environment

Add the headers to the backend environment (internal edit environment of XperienCentral) (add in your .conf file):

<VirtualHost *:80>
   ServerName edit.mywebsite.com
   ...
   Header always set X-Content-Type-Options nosniff
   Header always set X-XSS-Protection "1; mode=block"
   Header always edit Set-Cookie (.*) "$1; SameSite=strict"
   Header always set Strict-Transport-Security "max-age=63072000" env=HTTPS
   Header always set Content-Security-Policy "default-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src 'self'; worker-src 'self'; img-src 'self' data:; script-src 'self' 'unsafe-inline' 'unsafe-eval' data: https: wss:"
   ...
</VirtualHost>

In the example above, the declarations are set to a very strict level and will, among other things, prevent the embedding of external content using, for example, Oembed. If you want to allow the embedding of external content in the backend environment or use less strict security, you need to relax one or more of these rules. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy for more information.

If you want to include an additional rule to set the HttpOnly flag on cookies, make sure to exclude the X-CSRF-Token cookie from that rule, because the anti-CSRF protection in XperienCentral is based on the fact that a browser does not allow Javascript code from reading cookies from another domain and setting the HttpOnly flag disables access to the cookie from all Javascript code. For example:

# Set HttpOnly and Secure flag on all cookies except for X-CSRF-Token cookie (required for submitting any sort of form in R33 and higher).
Header edit Set-Cookie ^((?!X-CSRF-Token=).*)$ $1;HttpOnly;Secure env=object_is_secure

Content-Security-Policy

In order to add extra security to the XperienCentral environment, it is necessary to add the Content-Security-Policy to the response headers. In the two virtual host (backend and frontend) lists previously mentioned, the header is already added. The value of the header is not a general value, but rather site specific. The value of the Content-Security-Header can be used, but it might block content from the client website be careful when implementing it. There will be a add-on for XperienCentral in the future where the header's value can be generated and altered within XperienCentral itself.

Enable OCSP Stapling on your Server

See https://www.digicert.com/enabling-ocsp-stapling.htm.

Cache-Control and Pragma

It is important to set the cache headers for security reasons. The Pragma header is not used in current browsers - it is a fallback for older implementations. The Pragma header is replaced in the HTTP standard by the Cache-Control header. The Cache-Control header is set for static files like images, CSS, JavaScript files as well as dumped XperienCentral pages. To ensure that dumped content has also a cache header, add the following to the virtualhost setting:

  <LocationMatch "\.html$">
    Header merge Cache-Control "max-age=300"
    Header merge Pragma "no-cache"
  </LocationMatch>

This will set the caching for dumped content to five minutes (300 seconds).

The following configuration disables browser and proxy caching for pages in order to avoid the caching of personalized pages:

setenvif Request_URI "^/(.*)\.htm$" object_is_dynamic=true
setenvif Request_URI "^/web/" object_is_dynamic=true
Header merge Cache-Control "no-cache" env=object_is_dynamic
Header merge Cache-Control "no-store" env=object_is_dynamic
Header merge Cache-Control "private" env=object_is_dynamic
Header merge Pragma "no-cache" env=object_is_dynamic

Back to top

Unpacking the XperienCentral Release

Before XperienCentral can be configured, the release has to be unpacked. To unpack the XperienCentral release, proceed as follows:

cd /vol/www/
mkdir webmanager-mywebsite
cd webmanager-mywebsite
unzip /tmp/GX_WebManager_x.x.x_SDK.zip

Back to top

Modifying settings.xml

The XperienCentral configuration is set in settings.xml. This file is located in the root of the unpacked XperienCentral release (/vol/www/webmanager-mywebsite/). See JAVA_OPTS Parameters for more details and explanations on the JAVA_OPTS settings..

Back to top

Creating the Database(s)

XperienCentral data is stored in a relational database (MSSQL, MySQL, or Oracle). Create the databases desired for this installation. A complete XperienCentral installation requires only one database. In certain cases (performance/security), it is possible to save specific items in separate databases. A separate database can be created for the following components:

XperienCentral core (JCR repository storage)
XperienCentral other (externaldb)

The database for MySQL and MSSQL can be created with one single command and filled with the necessary tables. To create databases and the standard tables for Oracle, you have to use the standard Oracle tools (SQL Plus can be used, for instance). The initial scripts for all databases are: /vol/www/webmanager-mywebsite/webmanager-sqlscripts/.

Actions for MySQL

cd /vol/www/webmanager-mywebsite
mvn -s settings.xml -P create-mysql-db
# If the content of JCR should be stored in another DB, then run:
# mysqladmin create wm9mywebsite_jcr -u root -p

Actions for MSSQL

cd /vol/www/webmanager-mywebsite
mvn -s settings.xml -P create-mssql-db
# If the content of JCR should be stored in another DB, then
# create the DB using the Enterprise Manager

Actions for Oracle

cd /vol/www/webmanager-mywebsite
mvn -s settings.xml -P create-oracle-db
# If the content of JCR should be stored in another DB, then
# create the DB using the Enterprise Manager

Back to top

Installing the XperienCentral Release

The basic server setup is now complete. To install the release, proceed as follows:

cd /vol/www/webmanager-mywebsite
mvn -s settings.xml -P configure-jcr-repository
mvn -s settings.xml -P build-project
cd /vol/www/mywebsite/
mkdir web-docs
cd web-docs
unzip /vol/www/webmanager-mywebsite/webmanager-webapps/\
webmanager-static-webapp/target/\
webmanager-static-webapp-1.0-SNAPSHOT.war
# For JBoss use:
#  /vol/users/product/jboss/jboss-mywebsite/standalone/deployments
cd /vol/www/tomcat-mywebsite/deploy
cp /vol/www/webmanager-mywebsite/webmanager-webapps/\
webmanager-backend-webapp/target/\
webmanager-backend-webapp-1.0-SNAPSHOT.war .
cd /vol/www/mywebsite/work/edition-bundles
cp /vol/www/webmanager-mywebsite/edition-bundles/*.jar .
cd /vol/www/mywebsite/system/
cp /vol/www/webmanager-mywebsite/settings.xml .
cp /vol/www/webmanager-mywebsite/webmanager-cleansite/target/\
webmanager-cleansite-1.0-SNAPSHOT.jar .
rm /tmp/GX_WebManager_10.x.x_SDK.zip

Back to top

Configuring Tomcat

For Tomcat, two files need to be created. Place these files in the /vol/www/tomcat-mywebsite/conf directory.

The conf/server.xml for HTTP

<Server port="8005" shutdown="SHUTDOWN">
   <GlobalNamingResources>
      <!-- Userdatabase is used to secure admin pages! Make sure the path is ok otherwise the admin jsps will not work -->
   <Resource name="WMUserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="XperienCentral user database" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="/vol/www/tomcat-mywebsite/deploy/admin-users.xml" />
   </GlobalNamingResources>
   <Service name="WebManager">
   <Connector port="8009" enableLookups="false" redirectPort="8443" debug="1" protocol="AJP/1.3" secretRequired="false" URIEncoding="UTF-8" connectionTimeout="600000" />
   <Engine name="WebManager" defaultHost="localhost">
      <Realm className="org.apache.catalina.realm.LockOutRealm" >
         <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="WMUserDatabase"/>
         </Realm>
         <Host name="localhost" unpackWARs="true" autoDeploy="false" deployOnStartup="false" appBase="/vol/www/tomcat-mywebsite/deploy">
            <Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="true" showServerInfo="false" /> 
            <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
            <Context path="/web" docBase="webmanager-backend-webapp-1.0-SNAPSHOT.war">
               <Valve className="org.apache.catalina.authenticator.DigestAuthenticator" cache="true" />
            </Context>
         </Host>
      </Engine>
   </Service>
</Server>

The conf/server.xml for HTTPS

<Server port="8005" shutdown="SHUTDOWN">
   <GlobalNamingResources>
      <!-- Userdatabase is used to secure admin pages! Make sure the path is ok otherwise the admin jsps will not work -->
      <Resource name="WMUserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="XperienCentral user database" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="/vol/www/tomcat-mywebsite/deploy/admin-users.xml" />
   </GlobalNamingResources>
   <Service name="WebManager">
      <Connector port="8009" enableLookups="false" debug="1" protocol="AJP/1.3" URIEncoding="UTF-8" secretRequired="false" connectionTimeout="600000" />
      <Engine name="WebManager" defaultHost="localhost">
         <Realm className="org.apache.catalina.realm.LockOutRealm" >
            <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="WMUserDatabase"/>
         </Realm>
         <Host name="localhost" unpackWARs="true" autoDeploy="false" deployOnStartup="false" appBase="/vol/www/tomcat-mywebsite/deploy">
            <Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="true" showServerInfo="false" />
            <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
            <Context path="/web" docBase="webmanager-backend-webapp-1.0-SNAPSHOT.war">
               <Valve className="org.apache.catalina.authenticator.DigestAuthenticator" cache="true" />
            </Context>
         </Host>
      </Engine>
   </Service>
</Server>

The LockOutRealm is used to block users who have tried to authenticate but failed too many times. The default value of the realm is 5 attempts - after 5 incorrect authentications the user is locked out. The lock is active for 5 minutes and does not allow any new login attempts. After 5 minutes the user is unlocked and the user may again attempt a new login. See LockoutRealm for more information.

Apache Tomcat Error Page Configuration

Add the following to the server.xml if you want to ensure that Tomcat displays its own 404 error page in case you don't configure your own in XperienCentral:

<Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false" />

The conf/admin-users.xml

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
   <role rolename="wmadmin"/>
   <user username="wmadmin_user" password="MyPassword" roles="wmadmin"/>
</tomcat-users>

The conf/context.xml

<?xml version="1.0" encoding="UTF-8"?>
<Context sessionCookiePath="/">
   <WatchedResource>WEB-INF/web.xml</WatchedResource>
   <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" sameSiteCookies="strict" />
</Context>

Important

If you use integrated functionality such as SAML for single sign-on or a platform like DigiD, eHerkenning or iDeal that redirects visitors to an external system and then back to XperienCentral, or if Interactive Forms are included on external websites, the sameSiteCookies property in the context.xml as shown above should be set to "none":

sameSiteCookies="none"

The JDBC Drivers

The JDBC Drivers have to be copied to the /vol/www/tomcat-mywebsite/lib directory:

cd /vol/www/tomcat-mywebsite/lib
cp /vol/www/webmanager-mywebsite/ext/mssql-jdbc-7.0.0.jre8.jar .
cp /vol/www/webmanager-mywebsite/ext/oraclejdbcdriver-11.2.0.2.0 .

In XperienCentral versions 10.19.1 and earlier, the mysql-connector-java-5.1.23 driver was available in the SDK in the /ext and /maven-repository directories. This library has been removed from the 10.20.0 and later SDKs, therefore you must manually download and install the driver in the /vol/www/tomcat-mywebsite/lib directory if you want to use the MySQL database:

cp /vol/www/webmanager-mywebsite/ext/mysql-connector-java-5.1.23 .

in XperienCentral 10.24.1 oracle 12.2 is supported. The jdbc oracle driver 12.2 can be used when oracle 12.2 database is available.

Server.xml Configuration

For the supported databases, you must add the JDBC resource to the XperienCentral server.xml:

Oracle

<!-- ORACLE -->
   <Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="oracle.jdbc.driver.OracleDriver" url="jdbc:oracle:thin:@SERVERNAME:PORTNR:INSTANCE" maxTotal="100" maxIdle="10" maxWaitMillis="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandonedOnBorrow="false" removeAbandonedOnMaintenance="false" removeAbandonedTimeout="30" logAbandoned="true" validationQuery="SELECT 1 FROM DUAL"/>

MSSQL

<!-- MSSQL -->
<Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://SERVERNAME:PORTNR;databaseName=INSTANCE" maxTotal="100" maxIdle="10" maxWaitMillis="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandonedOnBorrow="false" removeAbandonedOnMaintenance="false" removeAbandonedTimeout="30" logAbandoned="true" poolPreparedStatements="true" validationQuery="select 1" />

MySQL

<!-- MYSQL -->
   <Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="CHANGEME" password="CHANGEME" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://SERVERNAME:PORTNR/INSTANCE?autoReconnect=true" maxTotal="100" maxIdle="10" maxWaitMillis="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandonedOnBorrow="false" removeAbandonedOnMaintenance="false" removeAbandonedTimeout="30" logAbandoned="true" maxOpenPreparedStatements="100" validationQuery="SELECT 1" />

Support for Special Characters

If you use special characters in file names, add the following to setenv.sh:

export LANG=en_US.utf8

Backend Container Authentication

XperienCentral supports the trusting of the authentication of users in a backend container which in turn means that they do not have to supply a username/password combination when they log in to XperienCentral. See Backend Container-based Authentication for complete information.

Back to top

Configuring JBoss

Configuring JBoss can be done manually or automaticaly if you prefer. To manually configure JBoss, follow the steps below. If you want to configure JBoss automatically, use the maven command mvn -Pconfigure-jboss.

Make the Database Driver Available

Obtain a copy of the database driver from the Maven repository. Copy the driver for your database to the directory jboss-mywebsite/modules/system/layers/base. Use the following JAR files for the following databases:

For MSSQL, copy mssql-jdbc-7.0.0.jre8.jar to com/microsoft/sqlserver/mssql-jdbc/main.
For Oracle, copy oraclejdbcdriver-12.1.0.2.jar to oracle/oraclejdbcdriver/main.

For MySQL, you must download the connector JAR yourself — the jar is not available by default in the Maven repository.

For MySQL, copy mysql-connector-java-x.x.x.jar to com/mysql/main.

In the "main" directory (not the root), create a file named module.xml with the following content:

MSSQL

<?xml version="1.0" encoding="UTF-8"?>
<module name="com.microsoft.sqlserver.mssql-jdbc" xmlns="urn:jboss:module:1.1">
  <resources>
    <resource-root path="mssql-jdbc-7.0.0.jre8.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

MySQL

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
   <resources>
      <resource-root path="mysql-connector-java-x.x.x.jar"/>
   </resources>
   <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
   </dependencies>
</module>

Oracle

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="oracle.oraclejdbcdriver">
   <resources>
      <resource-root path="oraclejdbcdriver-12.1.0.2.jar"/>
   </resources>
   <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
   </dependencies>
</module>

Reference the database driver in standalone/configuration/standalone.xml within the jboss:domain:datasources subsystem:

For MSSQL

<driver name="mssql" module="com.microsoft.sqlserver.mssql-jdbc">
   <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
</driver>

For MySQL

<driver name="MYSQL" module="com.mysql">
   <driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>

For Oracle

<driver name="ORACLE" module="oracle.oraclejdbcdriver">
   <driver-class>oracle.jdbc.OracleDriver</driver-class>
</driver>

Add All Relevant Data Sources to standalone.xml within the jboss:domain:datasources Subsystem

<datasource jndi-name="java:jboss/jdbc/WebManagerDb" pool-name="WebManagerDb" enabled="true" use-java-context="true">
   <connection-url>{connectionurl}</connection-url>
   <driver>{drivername}</driver>
   <security>
      <user-name>{username}</user-name>
      <password>{password}</password>
   </security>
</datasource>

In the XML above, replace {connectionurl}, {username}, and {password} with the appropriate values. The driver name must be either JTDS, MYSQL, or ORACLE (the value of the name attribute of the driver reference). Example connection URLs:

MSSQL: jdbc:sqlserver://mydomain:2433;databaseName=webmanager9181;useLOBs=false

MySQL: jdbc:mysql://mydomain:3306/webmanager9181?autoReconnect=true

Oracle: jdbc:oracle:thin:@mydomain:1521:xe

Disable the Default Welcome Root Web (Undertow) Application

In standalone.xml, delete the following two lines in the jboss:domain:undertow subsystem to disable the default welcome content:

<subsystem xmlns="urn:jboss:domain:undertow:7.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
	<server name="default-server">
		...
		<host name="default-host" alias="${webmanager.backendservername},${webmanager.frontendservername}">
			<location name="/" handler="welcome-content"/> !DELETE THIS LINE!
			<http-invoker security-realm="ApplicationRealm"/>
		</host>
	</server>
	...
	<handlers>
		<file name="welcome-content" path="${jboss.home.dir}/welcome-content"/> !DELETE THIS LINE!
	</handlers>
</subsystem>

Add Aliases for Hostnames

In standalone.xml, add the aliases for the hostnames you are using:

<server name="default-server">
	<host name="default-host" alias="mydomain.mycompany.com,alias">
	</host>
</server>

Enable the AJP Connector

<server name="default-server">
	<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
	<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
	<ajp-listener name="ajp" socket-binding="ajp" scheme="http"/>
</server>

Enable the wmadmin Login

In standalone.xml, add the XperienCentral security domain. This is necessary because the XperienCentral file jboss-web.xml references the XperienCentral security domain

<security-domain name="GX-WebManager" cache-type="default">
   <authentication>
      <login-module code="UsersRoles" flag="required">
         <module-option name="usersProperties" value="${jboss.server.config.dir}/users.properties"/>
         <module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/>
         <module-option name="hashAlgorithm" value="MD5"/>
         <module-option name="hashEncoding" value="RFC2617"/>
         <module-option name="hashUserPassword" value="false"/>
         <module-option name="hashStorePassword" value="true"/>
         <module-option name="passwordIsA1Hash" value="true"/>
         <module-option name="storeDigestCallback" value="org.jboss.security.auth.callback.RFC2617Digest"/>
      </login-module>
   </authentication>
</security-domain>

Adjust the Deployment Timeout

In standalone.xml, add the deployment timeout tag to the deployment-scanner path:

<subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0">
	<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" deployment-timeout="1000" runtime-failure-causes-rollback="${jboss.deployment.scanner.rollback.on.failure:false}"/>
</subsystem>

Generate and Store the JBoss 7.2.0 EAP Application Server Hash

cd /vol/www/jboss-cleansite/modules/system/layers/base/org/picketbox/main
/usr/local/java11/bin/java -cp picketbox-5.0.3.Final-redhat-3.jar org.jboss.security.auth.callback.RFC2617Digest wmadmin "XperienCentral" <password>

Store the generated hash:

echo "wmadmin=<generated_hash>" > jboss-mywebsite/standalone/configuration/users.properties
echo "wmadmin=wmadmin" > jboss-mywebsite/standalone/configuration/roles.properties

Backend Container Authentication

XperienCentral supports the trusting of the authentication of users in a backend container which in turn means that they do not have to supply a username/password combination when they log in to XperienCentral. See Backend Container Authentication for complete information.

Back to top

Placing the configuration.xml

Place configuration.xml in the /vol/www/mywebsite/configuration/ directory.

Back to top

Setting Permissions Correctly

During installation, the root account is used. After installation, it is recommended that you attach permissions to certain directories, for example, Tomcat runs under the user/group tomcat/www and Apache runs under the user/group apache/www. New users can be created with the adduser command. New groups can be created with the groupadd command. Assuming the above directory structure, users, and groups, the following UNIX commands can be used:

# Change the permissions for the Tomcat directory
cd /vol/www/tomcat-mywebsite
chown -R tomcat:www deploy logs work temp
chmod -R guo+r .
# Modify the webdirectory’s settings
cd /vol/www/mywebsite
chown -R tomcat:www .
chmod -R guo+r .

Back to top

Make the Hostnames Resolvable

The server on which XperienCentral is installed needs to be able to resolve the hostnames that are used for the edit environment and the external environment of XperienCentral. In the example the hostnames are www.mywebsite.com and edit.mywebsite.com. Add the used hostnames to the file /etc/hosts if the used hostnames don’t resolve to the right IP address on the server.

Back to top

Setting up rc Scripts

All files are now ready and configured correctly: the application server (Tomcat or JBoss) and Apache can be started. Make sure that the GX search engine (if necessary), database, application server, and Apache automatically start after a system reboot. Make sure that in the rc scripts for the application server the directories are being removed that are temporary for the application server before XperienCentral is started.

In the case of Tomcat, these directories are:

Tomcat’s work directory
The osgi directory
The deploy/appBase directory
Tomcat’s temp directory

For JBoss, empty the following folder before each start:

The /vol/www/mywebsite/work/osgi directory

To start a JBoss Enterprise Application Platform 6 Standalone Server (a single server instance), use the command:

/vol/www/jboss-mywebsite/bin/standalone.sh –b edit.mywebsite.com –c webmanager

To start a JBoss Enterprise Application Platform 6 Managed Domain, which allows control and management of multiple instances, use the command:

/vol/www/jboss-mywebsite/bin/domain.sh –b edit.mywebsite.com –c webmanager

Back to top

Configure the Apache PDFBox Cache Directory

XperienCentral uses the Apache PDFBox library for working with PDF documents. In order for the library to function correctly, you need to configure the directory it uses for caching. To do so set the pdfbox.fontcache system property to use the Java tmp directory. Be sure that XperienCentral has sufficient rights to write to the tmp directory. Normally this will be added to the setenv.sh. with the setting

JAVA_OPTS="$JAVA_OPTS -Dpdfbox.fontcache=${CATALINA_HOME}/temp/"

Back to top

Controlling the Startup Block Mechanism

By default, XperienCentral blocks login requests from the frontend and backend while it is starting up. If XperienCentral receives a request for a page from either the frontend or backend during the startup sequence between the time that the log messages Server startup in <x> ms and XperienCentral started successfully in <x> ms appear, the following message will appear in the browser:

To block this message, add the following JAVA_OPTS property to the beginning of the XperienCentral block:

-Dwebmanager.startupblock.skip=true

For example:

set JAVA_OPTS=%JAVA_OPTS% -Dwebmanager.startupblock.skip=true -Djava.awt.headless=true -Dwebmanager.jcr.filemirror=true -Dwebmanager.clustering.readonly=false -Xms512m -Xmx512m –Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

When blocking is turned off, requests from the frontend will return a cached version of the requested page or a white page with no content when XperienCentral has not finished the startup process. Requests from the backend will show the XperienCentral login screen, however you will not be able to log in.

To turn blocking back on, change the ‘true’ declaration to false. For example:

-Dwebmanager.startupblock.skip=false

Back to top

Security Enhancements

GX Software constantly performs penetration tests using third parties in order to protect you from the latest security threats. The security tips listed below are frequently updated and added to based on our findings. Please review each tip in order to ensure that your XperienCentral environment is protected from the latest security vulnerabilities.

You should install an active virus scanner in the environment where XperienCentral is running. Because files (images, downloads, etc.) can be uploaded to XperienCentral, it is unwise to rely on the client's virus scanner to detect viruses. The installation of the virus scanner is out of scope for the XperienCentral documentation, therefore only this general recommendation is given.
To enhance security on a DNS level, a DNSSEC (Domain Name Systems Security Extensions) and a CAA (Certification Authority Authorization) should be configured on the domain of each client's website. This must be configured by the hosting company with whom the domain is registered. Verify that this is activated for the corresponding website domain.
The XperienCentral environment (including Tomcat/Apache) should be isolated (from a security and performance perspective) from other software installations if they reside on the same server. This prevents unauthorized access between applications. When using a dedicated (virtual) server for the XperienCentral installation, this requirement is automatically fulfilled. This ensures that no access is given to other applications on the same server as XperienCentral, and if the website goes down because of performance issues, the other application(s) are not affected.
When HTTPS is used in an XperienCentral environment, make sure that the Cipher Suites that the server presents to the browser belonging to the SSL protocol has no weak suites available. Weak suites are a security risk and should not be delivered by the server. You can test the Cipher Suite weaknesses in your environment at ssllabs.com. You can view some examples of an Apache configuration for SSL Cipher Suites at https://ssl-config.mozilla.org/. One such example is:
```
# intermediate configuration - tweak to your own needs
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
```
When HTTPS is used, Expect-CT should be added to the response header in order to optimize the security of the SSL connection. This header forces the browser to check the SSL certificate for Certificate Transparency. If the SSL certificate is not transparent, the browser refuses the connection (the enforce option). Add the following header to your Apache configuration in order to enable Expect-CT headers:

Expect-CT: max-age=86400, enforce
To prevent the malicious use of browser API functions, you should add the response header Feature-Policy to your Apache configuration. This header sets restrictions on the browser API functions. For example, when the browser on a mobile device receives a header with the option camera 'none' then the camera can't be used on that device. The default setting for this header disables all API functions but can of course be customized. GX Software recommends that you add the following header to your default configuration:
```
Feature-Policy: vibrate 'none'; geolocation 'none'; accelerometer 'none'; ambient-light-sensor 'none'; autoplay 'none'; camera 'none'; encrypted-media 'none'; fullscreen 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'; midi 'none'; payment 'none'; picture-in-picture 'none'; speaker 'none'; usb 'none'; vibrate 'none'; vr 'none';
```
The full list of options can be found at OWASP Feature Policy

Back to top

GraphQL Rate Limiter Configuration

Using the GraphQL Rate Limiter behind a Proxy

When using the GraphQL Rate Limiter behind a proxy, it will detect the IP address of the proxy instead of the IP address of the individual sending the request when using the standard configuration. To avoid this, a small change must be made to the web server configuration. This change will correctly set the remote address of the request to the address provided by the X-Forwarded-For header. You define the behavior of the GraphQL service in XperienCentral on the General tab of the Setup Tool (graphqlservice).

Tomcat Web Servers

When using Tomcat, you have to add the RemoteIpValve to the server.xml file under the "Host" section. The RemoteIpValve will return the last IP address provided by the X-Forwarded-For header that is not marked as an internal or trusted proxy. If you are using remote proxies you have to provide the trustedProxies parameter to the RemoteIpValve with a regex that matches all the IPs of your remote proxies. IP addresses in the ranges 10/8, 192.168/16, 169.254/16, 127/8, 100.64/10, 172.16/12, and ::1 are automatically detected as internal proxies. You can override this using the internalProxies parameter which also takes a regex value.

Below is a sample configuration having 4.4.4.4 and 3.3.3/24 as remote proxies and 127/8 as an internal proxy:

<Valve className="org.apache.catalina.valves.RemoteIpValve"
   trustedProxies="4\.4\.4\.4|3\.3\.3\.\d{1,3}"
   internalProxies="127\.\d{1,3}\.\d{1,3}\.\d{1,3}"
   remoteIpHeader="x-forwarded-for"
   proxiesHeader="x-forwarded-by"
   protocolHeader="x-forwarded-proto" />

JBoss Web Servers

On a JBoss web server, enable the ProxyPeerAddressHandler filter. This filter will set the remote address to the first address provided by the X-Forwarded-For header. This address should always be the original address that sends the request. To enable the ProxyPeerAddressHandler filter, open the configuration file of your Jboss server (usually named standalone.xml) and look for the undertow subsystem. Now add the filter to the subsystem as follows:

<filters>
   <filter name="proxy-peer-address" class-name="io.undertow.server.handlers.ProxyPeerAddressHandler" module="io.undertow.core"/>
</filters>

Be sure to also add a filter reference to the host set in the same subsystem:

<filter-ref name="proxy-peer-address"/>

You can always consult our default configuration for JBoss in which GX Software has provided the configuration for this filter but it is commented out.

Browser not supported