Configuration

How to start the Engine Configuration application

There are several possibilities to launch the Axon.ivy Engine Configuration application:

Note

Note, that the configuration procedure implies sufficient administration and access rights. For example on a Windows Server 2008, you have to run the Engine Configuration tool with the "Run as Administrator" option.

Launch from Control Center

After starting the ControlCenter, select a server entry from the server list on the left side and press the Server button in the configuration area to start the configuration program.

Windows: Start the ControlCenter.exe program in the bin directory of the Axon.ivy Engine installation directory.

Linux: Start the ControlCenter program in the bin directory of the Axon.ivy Engine installation directory to start the ControlCenter program.

Direct Launch

You can start the Axon.ivy Engine Configuration program directly.

Windows: Start the AxonIvyEngineConfig.exe program in the bin directory of the Axon.ivy Engine installation directory.

Linux: Start the AxonIvyEngineConfig program in the bin directory of the Axon.ivy Engine installation directory.

Launch in Headless Mode

You can start the Axon.ivy Engine Configuration with the option -headless to start the program in the headless mode. Headless mode is useful if you operate in a non-graphical user interface environment. If you start the program with the -headless option, a rich dialog application engine is started. Once the engine is up and running, it prints out a URL to the console. You can now use another computer, to start a web browser and type in the provided URL to start the Axon.ivy Engine Configuration user interface. You can use it to configure the Axon.ivy Engine as explained in this chapter. When you are finished with the configuration, switch back to your server and press a key in your console to stop the rich dialog application engine.

Windows: Use the AxonIvyEngineConfigC.exe program in the bin directory of the Axon.ivy Engine installation directory with the option -headless to start the Axon.ivy Engine Configuration in headless mode.

Linux: Use the AxonIvyEngineConfig program in the bin directory of the Axon.ivy Engine installation directory with the option -headless to start the Axon.ivy Engine Configuration in headless mode.

Engine Configuration

The Axon.ivy Engine Configuration application's user interface is divided into tabs. On the Licence tab you can upload a licence. On the System Database tab the system database can be configured, created or converted. On the Administrators tab system administrators can be registered. This tab is only enabled if a valid system database is configured. On the Web Server tab the web server protocols and ports can be configure. This tab is also only enabled if a valid system database is configured.

Click Save to store the modified data on all tabs. Hit Discard Changes to reload the configuration from the filesystem and database. The Cluster tab is only visible if you have installed an Enterprise Edition Licence.

Note

The changes that you make with the Engine Configuration do not become active unless you restart the engine.

Licence

On the Licence tab you have to upload a valid licence:

Axon.ivy Engine Configuration Licence Tab

Figure 4.1. Axon.ivy Engine Configuration Licence Tab


Use the Upload Licence button to open the file browser and select the licence which should be used.

Note

It is possible to configure the engine without a valid licence, but the engine will always start in the demo mode if you do not have a valid licence and therefore does not use your configuration.

System Database

On the System Database tab the Axon.ivy Engine system database can be configured, created and converted:

Axon.ivy Engine Configuration System Database Tab

Figure 4.2. Axon.ivy Engine Configuration System Database Tab


First choose the database system and the JDBC driver you want to use. At the moment the Axon.ivy Engine supports the following database systems:

The choice of the second step depends on the database system and JDBC driver you have chosen in the first section. Click on the database system links above to find information about how to configure the connection settings. The applied db user needs the following privileges:

  • CREATE DATABASE (to create the system database out of the Engine Configuration)

  • CREATE, ALTER, DROP Tables, Views, Indexes, Triggers (to update the Axon.ivy Engine)

  • INSERT, SELECT, UPDATE, DELETE data

In a third step you can configure additional connection properties. When clicking on the Additional Propertiesbutton a dialog will show, where you can add, edit or delete the properties. See database system specific chapter (links above) to find information which additional connection properties are available for the database system that you have chosen.

At the top of the page the state of the connection is visible. Use the button on the right to try to connect to the system database.

Create new System Database

If the system database does not exist, use the create button at the bottom to create a new system database. During the creation of a new database the configured connection parameters are used. For some database system additional information is necessary. It must be provided in a pop-up dialog before the new database can be created. See database system specific chapter (links above) to find what additional information is necessary for the chosen database system.

Note

You can previously create an empty database/schema. In this case the server configuration tool will only create the necessary tables into the given database/schema. If the database/schema doesn't exist already, the server configuration tool creates it with a best practice configuration. In this case the applied db user needs the following privileges:

  • CREATE, ALTER, DROP Tables, Views, Indexes, Triggers (to update the Axon.ivy Engine)

  • INSERT, SELECT, UPDATE, DELETE data

The best practice configurations are documented in chapter System Database.

Convert an old System Database

Warning

We strongly recommend to backup your database before you convert it to a newer version. Be sure that you have enough disk/table space on your database server. Most conversions add new fields to existing database tables which will enlarge the used database space.

If the system database has an older version, use the convert button at the bottom to convert it to the latest version.

Warning

Depending on the conversion steps and your database system it may be necessary to cut all connections to the system database to avoid problems. If you have problems with the conversion, please disconnect all other database management tools, clients or other tools that has a connection to the system database and try again.

System Administrators

On the Administrators tab you can configure users that have the right to administrate the Axon.ivy Engine:

Axon.ivy Engine Configuration Administrator Tab

Figure 4.3. Axon.ivy Engine Configuration Administrator Tab


Warning

This tab is only enabled if you have configured a connection to a valid system database.

Web Server Ports

On the Web Server tab you can configure which protocols the internal web server of Axon.ivy Engine should support and on which IP ports the web server is listening:

Axon.ivy Engine Configuration WebServer Tab

Figure 4.4. Axon.ivy Engine Configuration WebServer Tab


The following protocols are supported:

ProtocolDescription
HTTPHTTP protocol .
HTTPSHTTP protocol over secure socket layer (SSL).
AJPApache Jakarta Protocol. This protocol is used for the communication of the embedded Servlet Engine with external WebServers like IIS or Apache.

Table 4.1. Web Server Protocols


Warning

This tab is only enabled if you have configured a connection to a valid system database.

Note

In case you disable HTTP port, then the specified port will still opened by the engine for internal purposes. Even though the engine will refuse connections from remote hosts.

Cluster

Note

This tab is only visible if you have installed an Axon.ivy Enterprise Edition licence.

On the Cluster tab you have to configure some information according the local cluster node:

Axon.ivy Engine Configuration Cluster Tab

Figure 4.5. Axon.ivy Engine Configuration Cluster Tab


Use the Add local node button to add this installation as a new Engine cluster node to the list of cluster nodes in your Axon.ivy Engine Enterprise Edition. You have to configure an IP Address and an IP Port that will be used by the cluster to communicate with this node.

Note

An Engine cluster node is uniquely identify by the host it is running on and a local identifier. The local identifier is a unique number that identifies nodes running on the same host (machine). Both values are provided by the installed licence. Therefore, every Engine cluster node needs its own licence file.

Control Center

The Control Center integrates all tools to configure the engine, the (Windows) service and to start/stop the installed Axon.ivy Engine.

To open the Control Center application, go to your Axon.ivy Engine installation directory and launch the ControlCenter.exe or the ControlCenter program located in the bin folder.

Start / Stop

To start the Axon.ivy Engine, simply choose the Axon.ivy Engine in the list on the left side and then press the green start button.

Alternatively, you can choose the Axon.ivy Engine [Console] from the list to start the engine within a console to which some information about the engine is logged. Please note that closing this console window will terminate the Axon.ivy Engine without shutting it down properly.

To stop the engine, click the red stop button.

The Control Center

Figure 4.6. The Control Center


Configuring Windows Service (Windows only)

If you've installed the Axon.ivy Engine under a Windows operating system, you can register it as a Windows service. To do so, select the entry Axon.ivy Engine [Windows Service] from the list on the left and press the button Windows Service on the right. A dialog will open, prompting you for additional configuration data:

Configuring Axon.ivy Engine as Windows service

Figure 4.7. Configuring Axon.ivy Engine as Windows service


First of all press Register Service to register the service and to enable the rest of the configuration sections.

Tip

Service operations (register, unregister, start, stop) may fail because the current user does not own the necessary rights. In this case close the Control Center and start it again by right clicking on the ControlCenter.exe and choose the command Run as administrator from the context menu. After that, the service operation should work.

Now you may configure the user under which the service (and therefore the Axon.ivy Engine) will be executed. This can be either the system user or any other user with sufficient rights to start services and access the Axon.ivy Engine installation directory (read and write).

By default, the service start kind is Manually. To start the engine each time Windows is booted, choose the setting Automatically

The last thing that can be configured are the services that the Axon.ivy Engine depends on. This might be the database management system on which the system database is located or the web server in which Axon.ivy is integrated (IIS or Apache). All the services that you add in this list will be started before Axon.ivy and if any of these services fail to start, Axon.ivy won't start too.

After you have finished the configuration, click Ok. Now you will be able to start the engine from the control center or you may also use the Windows Service Management Console.

Testing the Engine

Once you've started the Axon.ivy Engine, try to open the following address in your preferred web browser: http://ServerName:Port/ivy. If a web page with the Axon.ivy logo appears, the installation and configuration of the Axon.ivy Engine was successful and you may continue with the next chapter.

Server List Configuration

The list with the engine types on the right may be extended by users. You may add other Axon.ivy Engine installations and you even can integrate other third party tools to start them from the Control Center.

Note

The indication whether the program behind an entry in the server list is running or not is only shown for the Axon.ivy Engine binaries of the installation the Control Center belongs to and for any Windows services (including the Axon.ivy Engine services). This applies too for the show console setting because only Axon.ivy Engine binaries can be started in a console (third party applications cannot).

Add opens a dialog to choose the type for the new entry. For integration of another Axon.ivy Engine binary or a third party tool, choose the first option (ivyTeam based Server), if you intend to integrate an Axon.ivy Engine as a Windows service or any other Windows service, then choose the second option (Windows Service based server.

Create a new server in the server list

Figure 4.8. Create a new server in the server list


In the configuration dialog for a normal application you can set the base name and/or refine with the instance name (in the server list the instance name is printed in brackets after the name). Add the server binary (or your third party tool) in the server start executable and the configuration utility in the field configuration program (or the configuration program of your third party application). If and only if you choose the console based binaries (the ones with "C" at the end of the file name, e.g. AxonIvyEngineC.exe) then tick the check box Show console. It has no effect on all other binaries.

Create a new service in the server list

Figure 4.9. Create a new service in the server list


In the configuration dialog for adding/editing a service entry, you can choose an already existing service from the combo box or set the service name when you did not already register the service. Set the configuration program and the service binary similarly to the description above. For simply starting/stopping existing services from the Control Center, it is not necessary to define the service binary

Note

The name in this dialog must be exactly the same name that is used to register the service. Otherwise the lookup will not work.

Remove removes the selected entry from the list and Edit allows to edit the configuration for the selected entry in the server list.

Configure Tomcat

The directory webapps/ivy/WEB-INF/ contains the web.xml file which is the webapp configuration file of the embedded Tomcat application server. See the Apache Tomcat documentation for more information.

Warning

Be very careful when changing the contents of this file. A wrong configuration or an invalid syntax in the file may harm the stability and correctness of your Axon.ivy Engine installation.

Note

After a change in the web.xml a restart of the Engine is required to apply the new configuration.

Below is a description of settings often adjusted in an ivy web.xml

Session Timeout

In the web.xml you can set the timeout for the session. If a session (i.e. a user interaction with an application) is inactive for this amount of time, then the session will be closed. To adapt the default value look for the section below in the web.xml file and change the value accordingly:

<session-config>
<session-timeout>30</session-timeout>
</session-config>

Error Pages

It is possible to defined customized error pages, see chapter Custom Error Pages.

Security Headers

The ivy Engine comes with predefined HTTP Security headers for the /ivy web application. These Security Headers are added on the HTTP Responses to the Client Browser.

These security headers can be switched off or modified in the web.xml.

Header nameValue
X-Frame-OptionsSAMEORIGIN
X-XSS-Protection1; mode=block
X-Content-Type-Optionsnosniff

Table 4.2. Default Values of the Security Headers


Note

Not all Security Headers are supported by all Web browsers.

If the Engine is accessed over HTTPS only (strongly recommended). The cookie should only be transported over HTTPS. To enable this behavior (or disable the transport over HTTP) uncomment following lines in the session-config part of the web.xml:

<cookie-config>
  <secure>true</secure>
</cookie-config>       

Valves and Realms

The directory webapps/ivy/META-INF/ contains the context.xml file which is the context configuration file of the embedded Tomcat application server. See the Apache Tomcat context documentation for more information. In there you can add realms and valves, see the Apache Tomcat documentation about realms or valves for more information.

The following valves are provided by Axon.ivy Engine:

ClassDocumented in Chapter
ch.ivyteam.ivy.webserver.internal.PerformanceLogValve“Request/Performance Logging”
ch.ivyteam.ivy.webserver.security.SingleSignOnValve“Single Sign On”

Table 4.3. Valves provided by Axon.ivy Engine


Warning

Be very careful when changing the contents of this file. A wrong configuration or an invalid syntax in the file may harm the stability and correctness of your Axon.ivy Engine installation.

Custom Valve

You can configure any third party valve or even your own implementation of a valve. A custom valve implementation can only be loaded by the Axon.ivy Engine if its classes are accessible by the engines OSGi environment. This can be reached as follows:

  1. The valve JAR must be implemented as OSGi bundle. This means that the standard JAR manifest (META-INF/MANIFEST.MF) must also contain headers to declare the id, name and version of this bundle. These headers will be set automatically if the bundle is created within the Axon.ivy Designer via File > New > Other... > Plug-in Project

  2. Your bundle must require the bundle with the id ch.ivyteam.tomcat of the Axon.ivy Engine.

  3. Your bundle must register itself as buddy of the tomcat bundle by setting the MANIFEST.MF header: Eclipse-RegisterBuddy: ch.ivyteam.tomcat

  4. The package that contains the custom valve must be exported in the MANIFEST.

  5. Export the bundle as JAR: Menu Export > Deployable Plug-ins and Fragments.

  6. The custom bundle must be copied into the dropins directory of the Axon.ivy Engine.

    Troubleshooting: If your valve is not working as expected, consult the dropins/README.html.

Sample META-INF/MANIFEST.MF:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: ProcessingValve
Bundle-SymbolicName: com.acme.ProcessingValve;singleton:=true
Bundle-Version: 1.0.0.qualifier
Require-Bundle: ch.ivyteam.tomcat
Eclipse-RegisterBuddy: ch.ivyteam.tomcat
Export-Package: com.acme.valve

Tip

A full valve sample implementation can be found on GitHub: https://github.com/ivy-samples/tomcatValve

Additional Security Configuration

Additional Security Headers

Following additional security headers are recommended. Preferably set them on the Front-End Server (e.g. IIS, nginx, Apache).

Header nameDescription
Strict-Transport-SecuritySet this header if the Engine should only be accessed over HTTPS (strongly recommended). For more information, see: Strict-Transport-Security
Content-Security-PolicySet this header if you want to reduce the risk of having an exploitable Cross-site scripting (XSS) vulnerability. With a Content-Security-Policy you can define from which locations external resources can be loaded and if scripts embedded in HTML can be executed. For more information, see: Content Security Policy (CSP)
Referrer-PolicySet this header if you want to control how or if the referrer is disclosed to other sites. For more information, see: Referrer-Policy

Table 4.4. Additional Security Headers


Error Handling

When an error occurs while processing a user request an error screen is displayed to the user.

Show Error Details to End Users

By default, stacktraces, detailed error reports, etc. are not shown to end users because of security concerns when a application is running on the Engine. Instead only a unique Error Id is shown. In development or pre-production environments this behaviour is unnecessary. By changing the System Property Errors.ShowDetailsToEndUser to true this behaviour could be changed, so that all information are displayed to the user, like on the Designer.

Error Id

When 'Show Error Details to End Users' is deactivated then an error screen with an unique Error Id is shown to the user. This Error Id can be used to find the error in the log files.

Custom Error Page

An error page is used to display information about the error to the user. The content and appearance of the ivy error page can be customized. To do so, you can adjust the existing error page webapps/ivy/ivy-error-page.xhtml and its resources.

You are free to create your own error page(s), place them into webapps/ivy/ and add them to web.xml as follows:

<error-page>
	<location>/custom-error-page.xhtml</location>
</error-page>

By adding the <exception-type> tag to the <error-page> configuration it is also possible to configure a specific error page for status codes or kind of exceptions as described in Servlet 3.0 JSR in chapter 10.9.2 Error Pages.

<error-page>
	<exception-type>java.lang.Throwable</exception-type>
	<location>/custom-exception-error-page.xhtml</location>
</error-page>
<error-page>
	<error-code>404</error-code>
	<location>/custom-404-error-page.xhtml</location>
</error-page>

Tip

To retrieve information about the thrown exception and the environment during the request the Public API of ch.ivyteam.ivy.webserver.ErrorPageMBean could be used. An instance will be available as managed bean on the error page. Check the default error page ivy-error-page.xhtml for an example usage.

Error Report

On a error screen it is possible to generate an error report. This report contains information about the error, the system environment and the current state of the Engine.

Tip

To create a report without an explicit error navigate to the following URL http://{server}:{port}/ivy/error.

IIS Error Handling

If the engine is running behind an IIS web server and an error occurs on the Engine the IIS shows its own error page and hides the error page coming from the Engine. This is the default IIS configuration.

Since Axon.ivy 5.1 the IIS integration script configures the IIS to show the detailed error page of the Engine (see Step 'Configure Error Page' of the IIS integration chapter). With the following steps the setting could be reset the default IIS behavior. This could make sense to hide error details because of security concerns:

  1. Open the IIS manager

  2. Select the virtual directory ivy and on its Features View, double click on Error Pages

  3. Right click and select the Edit Feature Settings... or select the same from the Actions pane (in the right hand side)

  4. Select the “Detailed errors for local requests ...” radio button and click on OK.

GC Optimization

The GC (Garbage Collection) of Java cleans up the unused memory of the JRE. Normally the GC completes in a few milliseconds. If it takes longer (and leads to serious issues for running applications) the optimization below can help to optimize the GC time.

Default GC configuration

By default, the GC strategy is optimized for RIA Applications and an explicit full concurrent GC runs every 10 minutes.

Note

Why a periodical GC is required for RIA Applications?

Normally a GC is triggered in the background when a considerable amount (e.g. 80%) of the available memory is used. Then the GC cleans up all unused memory so that the application can always address new memory as required.

Now comes RIA into play. A RIA application creates each UI widget on server- and client-side to share the UI-state on both sides. To clean this up on both sides the widget must be cleaned first on server-side before it can be cleaned on the client-side. But with the default GC configuration the memory on server-side will not be cleaned until a considerable amount of the available memory is used. But the available memory on server-side is usually considerably higher than on client-side, so this can lead to low memory problems on client side (OutOfMemoryException).

To prevent this situation Axon.ivy Engine triggers a full concurrent GC every 10 minutes. This cleans up the memory on server-side and allows the client-side to clean up its memory too.

Optimization for JSF

In JSF applications you only need a Browser on client side. Therefore, no periodical full concurrent GC is required and you can optimize the GC on low latency.

To change the GC accordingly comment out the following line in the corresponding ilc-file or AxonIvyEngine.conf for Linux:

# * GC optimized for JSF
ivy.garbage.collector.options=-XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+CMSParallelRemarkEnabled -XX:+CMSClassUnloadingEnabled -XX:+DisableExplicitGC
			

System Database Encryption

User passwords are stored encrypted in the system database. Passwords of Axon.ivy users are hashed by using the bcrypt algorithm. Passwords of technical users that are used to communicate with external systems are encrypted using the AES algorithm. The secret key for the AES algorithm is by default created automatically by using a secure random generator. However, it is possible to provide an own secret key as follows:

  1. Create your own AES secret key and store it in a key store file by using the Java keytool:

    keytool -genseckey -alias aes -keyalg AES -keysize 128 -storepass changeit -storetype JCEKS -keystore keystore.jceks
  2. Configure the following Java system properties in the launcher configuration:

    Java System PropertyDescription
    ch.ivyteam.ivy.persistence.keystore.fileThe path to the key store that holds the AES secret key. E.g. keystore.jceks.
    ch.ivyteam.ivy.persistence.keystore.passwordThe password needed to read the key store file. Default value changeit.
    ch.ivyteam.ivy.persistence.keystore.aliasThe name of the key to read from the key store file. Default value aes.
    ch.ivyteam.ivy.persistence.keystore.typeThe type of the key store. Default value JCEKS.

    Table 4.5. AES Secret Key System Properties


Warning

If you configure to use an own AES secret key after you have already stored technical passwords for external system then those passwords can no longer be decrypted and are useless. You have to reconfigure all those passwords again!