Configuration
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.
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.
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.
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.
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.
On the Licence tab you have to upload a valid licence:
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.
On the System Database tab the Axon.ivy Engine system database can be configured, created and converted:
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.
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.
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. The best practice configurations are documented in chapter 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.
On the Administrators tab you can configure users that have the right to administrate the Axon.ivy Engine:
Warning
This tab is only enabled if you have configured a connection to a valid system database.
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:
The following protocols are supported:
| Protocol | Description |
|---|---|
| HTTP | HTTP protocol . |
| HTTPS | HTTP protocol over secure socket layer (SSL). |
| AJP | Apache 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.
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:
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.
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.
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.
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:
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.
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.
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.
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.
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.
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
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>
It is possible to defined customized error pages, see chapter Custom Error Pages.
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 name | Value |
|---|---|
| X-Frame-Options | SAMEORIGIN |
| X-XSS-Protection | 1; mode=block |
| X-Content-Type-Options | nosniff |
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>
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:
| Class | Documented 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.
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:
-
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
-
Your bundle must require the bundle with the id
ch.ivyteam.tomcatof the Axon.ivy Engine. -
Your bundle must register itself as buddy of the tomcat bundle by setting the MANIFEST.MF header:
Eclipse-RegisterBuddy: ch.ivyteam.tomcat -
The package that contains the custom valve must be exported in the MANIFEST.
-
Export the bundle as JAR: Menu Export > Deployable Plug-ins and Fragments.
-
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
Following additional security headers are recommended. Preferably set them on the Front-End Server (e.g. IIS, nginx, Apache).
| Header name | Description |
|---|---|
| Strict-Transport-Security | Set this header if the Engine should only be accessed over HTTPS (strongly recommended). For more information, see: Strict-Transport-Security |
| Content-Security-Policy | Set 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-Policy | Set 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
When an error occurs while processing a user request an error screen is displayed to the user.
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.
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.
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.
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.
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:
-
Open the IIS manager
-
Select the virtual directory
ivyand on itsFeatures View, double click onError Pages -
Right click and select the
Edit Feature Settings...or select the same from theActionspane (in the right hand side) -
Select the “Detailed errors for local requests ...” radio button and click on OK.
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.
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.
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
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:
-
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
-
Configure the following Java system properties in the launcher configuration:
Java System Property Description ch.ivyteam.ivy.persistence.keystore.file The path to the key store that holds the AES secret key. E.g. keystore.jceks.ch.ivyteam.ivy.persistence.keystore.password The password needed to read the key store file. Default value changeit.ch.ivyteam.ivy.persistence.keystore.alias The name of the key to read from the key store file. Default value aes.ch.ivyteam.ivy.persistence.keystore.type The 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!