Iteraplan Documentation

Transcript

iteraplan Amazing Enterprise Architecture Management Release 5.5, February 2017 Table of Contents Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tomcat Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Database Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iteraplan installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZIP file contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-in User Authentication (iTurm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Authentication via LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Username & Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single Sign On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X.509 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iteraplan config files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iTURM config files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Configuration Options and Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrade Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrade Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 5 9 9 9 10 10 10 11 20 20 20 20 20 21 35 36 36 38 38 42 45 Installation Guide Corporate Edition only! The entire Installation Guide refers to the iteraplan Corporate Edition only. Lite Edition users should follow the instructions in the bundled README.txt file. This installation guide describes how to install and run iteraplan and the light-weight identity management system iTURM. Audience This installation guide is intended for people who want to install and run iteraplan. Scope The iteraplan application is designed to be able to connect with your existing identity management solution. However, if you do not have a solution already installed, you can use iTURM for managing users, roles and rights. User management is done via the application itself, so this subject is not dealt with in this manual. For more information about managing users and roles, please refer to the iteraplan User Guide . Conventions This manual uses the following typographical conventions: Bold: Bold type designates elements of the user interface. Monospace: File names, URL addresses are shown in non-proportional (monospace) type. Installation Prerequisites iteraplan is a client/server application. This chapter describes the requirements on both the client and the server side. Overview of Required Infrastructure iteraplan is a web application which runs on a central server. On the client side, the application requires a web browser; on the server side, it requires a Java servlet engine, which provides the runtime environment for the application, plus a relational database in which the application data can be stored. Client Requirements On the client side, iteraplan only requires a web browser. We recommend using the latest version of Mozilla Firefox. 3 iteraplan Classic Client iteraplan Interactive Client Microsoft Internet Explorer 9, 10, 11 Microsoft Internet Explorer 10, 11 latest Version of Mozilla Firefox latest Version of Mozilla Firefox latest version of Chrome The browsers data privacy settings must be configured to accept cookies and JavaScript. Server Requirements Overview Type Minimum Requirement Recommended Value CPU 1 GHz Dual Core more is better RAM 2 GB (with large models: more needed) 4 GB, more is better Disk space 250 MB (excluding DB and OS) 1 GB of free space (excluding DB and OS) Operating System any OS supported by Java 7 or 8 (64 Bit) Runtime Environment Java SE Runtime Environment version 7 (Update 25) or version 8 (Update 65) (always 64bit) by Oracle/SUN latest update of Java SE 7 or 8 (64bit) by Oracle/SUN (http://www.java.com) Application Server Apache Tomcat 7.0.37 or 8.0.37 latest Apache Tomcat 8.0.x or 7.0.x Database System MySQL 5.x, Oracle 10/11/12c* or MS SQL Server 2012 latest update/patch level of MySQL 5.x, Oracle 10/11/12c or MS SQL Server 2012 JDBC Connector, MySQL JDBC Connector 5.x latest JDBC driver for your database vendor of choice see also Database drivers, Oracle JDBC 6 (ojdbc6) according to your DB System Microsoft JDBC Drivers 4.0 Database Storage 10 MB (with large models: more needed) 100-200 MB * Oracle 12c is only supported with the bug fix/patch No. 18430870 applied to the database. Without the patch iteraplan will not work correctly. We recommend to apply all patches available for Oracle 12c. With Oracle 12c there are defects similar to the one leading to the known problem with iteraplan, even if no specific iteraplan problems have been reported so far. Whenever it is not possible to install the patch, please consult the Knowledge Base Article Search Index creation fails. Details iteraplan is an application based on Java server pages/ Java servlets and therefore requires a servlet engine. The server with this engine must be connected to the local network and be able to respond to requests submitted with HTTP/HTTPS. Please verify that a supported version of Apache Tomcat is installed, and that the CATALINA_HOME environment variable references the Tomcat installation folder. CATALINA_HOME must be created as a system wide environment variable. Please refer to your operating system manual for instructions on creating system wide environment variables. For Windows systems, Microsoft provides information in knowledge base entry KB31 0519. Some Tomcat configuration options must be changed in order to run iteraplan successfully. Please follow these instructions. Also make sure that you have write access to the subfolder webapps of the Tomcat installation folder, as the iteraplan installer will write to this folder later on. A relational database is required for storing the application data. Make sure that one of the supported database products is installed. The procedure for creating the database schemas is described on a separate page. Before installing the application with the iteraplan Installer utility, you must first install a compatible Java runtime environment (JRE). The JRE is also a prerequisite for running the Tomcat servlet engine. The application supports the Java runtime environments by Oracle. JREs from other vendors are not tested and not supported, although they might work. Please verify that the Java /bin folder is included in the PATH environment variable (or Path - environment variables are not case sensitive in Windows). In addition, the environment variable JRE_HOME (alternatively: JAVA_HOME) must be set to the installation folder of the Java runtime or development environment. You can check the current environment variable values by running set in a command line window. 4 Performance Considerations The performance of iteraplan depends on many different parameters. Therefore there are neither general established numbers for precise hardware requirements nor a set of rules for iteraplan configuration. When considering iteraplan's performance the following hints might be helpful nevertheless: On the server side more memory is more important than more CPU power in most cases. On the client side more CPU power is more important than more memory in most cases. The iteraplan interactive client heavyly relies on JavaScript. Any anti virus software (or similiar) interfering with web browser execution or with loading JavaScript files from the server can severely affect iteraplan's performance. In some cases iteraplan might become practically unusuable. Tomcat Configuration Before starting iteraplan you have to make a few configuration adjustments to your Tomcat application server. Tomcat Host Configuration Tomcat Connector Configuration Encoding Configuration Limit Maximum Number of Request-processing Threads HTTP header size SSL Example Connector configurations Classic Client support Memory Settings Tomcat 8 only Tomcat 7 and 8 Tomcat in headless mode for terminal-only Unix/Linux systems Tomcat Host Configuration In the file $TOMCAT_HOME/conf/server.xml, the name of the host and the base location of the web applications is configured in the e lement. It is best to leave this configuration unchanged at Tomcat default values. Most important is that the attribute unpackWARs is set to true: ... possible further settings ... Tomcat Connector Configuration Encoding Configuration iteraplan's pages are consistently encoded in UTF-8, as to allow for representation of non-latin characters. It is necessary to adjust Tomcat's configuration, so that it uses UTF-8 for interpreting incoming requests as well. Failure to adjust that setting may result in corrupted data when non-English characters (such as German umlauts) are involved. In the file $TOMCAT_HOME/conf/server.xml, find all active occurrences of the tag and add the attribute URIEncoding="UTF-8 " to all of these tags. For instance, the HTTP connector might look as follows, where the last attribute has been added: Typically, there are between one and three active connectors configured in Tomcat. Be sure to add the attribute to all of them. Please be aware that this option applies to all applications which are deployed on your Tomcat. Under rare circumstances, this setting might break character encoding of non-English characters in other applications on that Tomcat instance. Should you experience such problems, please contact the iteraplan support in order to find a solution. 5 Limit Maximum Number of Request-processing Threads If the Tomcat on which iteraplan is deployed is not expected to run under heavy load and/or iteraplan is the only application deployed on it, we recommend you to limit the number of Tomcat threads that process requests to 20. In order to do this, the $TOMCAT_HOME/conf/server.xml h as to be modified. First, you have to define an Executor with the name iteraplanThreadPool within the Service Catalina (after the line ), if it does not already exist. It should look like this: Then, you have to change the connectors to use the given thread pool. Normally, these are any or all of the connectors for the AJP (8009), HTTP (8080) and HTTPS (8443) protocols. Please note that, while the settings for these connectors may vary depending on your personal system's configuration, the executor attribute has to be set and the connectors themselves must not specify any of the attributes maxThreads or minSpareThreads to avoid conflicts. This causes all requests to be handled by tomcat with a maximum of 20 threads. The purpose of this is to avoid a possible deadlock in one of the database access libraries used by iteraplan. Such a situation may occur when there are more threads writing concurrently to the database than database connections are available. The standard configuration for iteraplan's database connection pool is 21, to ensure that there is always at least one more database connection available and to avoid this problem. If, for some reason, your Tomcat needs to be able to handle requests on these ports in more threads, we still recommend that you configure it as described above, but change the value of the maxThreads attribute to a more appropriate value. It is strongly recommended though, that the maximum number of database connections is updated accordingly, such that it is always higher than the maximum number of threads. This can be done by changing the value of the properties database.pool.maxIdle and database.pool.maxActive in iteraplan/WEB-INF/cl asses/iteraplan-db.properties. Please contact your database admin to find out which number of connections is acceptable for your database. HTTP header size The Tomcat connector attribute maxHttpHeaderSize defines the maximum size of the request and response HTTP header, specified in bytes. If not specified, this attribute is set to 8192 (8 KB). In some cases this may be insufficient, particularly when larger data on the HTTP header are transmitted. If you have any problems with the header size, add a maxHttpHeaderSize = "65536" to increase enlarge from the default maximum of 8K to 64K. SSL Information to set up Tomcat for SSL can be found in the official Tomcat documentation: Tomcat 7: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html Tomcat 8: https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html An example configuration for a Tomcat SSL connector can be found below. More information about setting up iteraplan for SSL can be found here: Other Configuration Options and Notes 6 Example Connector configurations Here are examples how the different Tomcat Connectors could be configured, based on the instructions above. AJP connector: HTTP connector: HTTPS connector: Classic Client support For some of the diagrams in the classic client a special Java setting regarding sorting is necessary. Without this setting, entries in the diagram legend might be in the wrong order. Add the following setting to the Java options of the Tomcat instance: -Djava.util.Arrays.useLegacyMergeSort=true See the Memory Settings section below for the exact place where to add this option. 7 Memory Settings Tomcat 8 only In the default configuration the caching of Tomcat 8 is set to "false". When starting the service some warnings appear: "insufficient free space available after evicting expired cache entries". Add the following line in the file $TOMCAT_HOME/conf/server.xml. After this change the warnings disappear. Tomcat 7 and 8 In the default configuration, Apache Tomcat uses only up to 64 MB of memory for all the applications installed on it. You have to increase this value to make sure that iteraplan can run reliably. If you installed Tomcat as a Windows service, the Tomcat service properties tool allows you to adjust these memory settings. On Unix systems and for the standalone Windows version (unpacked zip file), you need to adjust some environment variables, as described below. You can open the service management tool for Tomcat from the Tray icon (right-click and Configure) or from the Start menu entry. If neither of these is available, you can launch the tray icon by running these commands on the command line (adjust paths to your machine and Tomcat version): cd \Program Files\Apache\Tomcat X.Y.ZZ\bin tomcat7w.exe //MS// In this properties dialog, you can adjust the memory options on the Java tab. We recommend to set at least 2048 MB for the Maximum memory pool and to append the the line -Djava.util.Arrays.useLegacyMergeSort=true (see above for details about this option) in the Java Options field. When using Java 7 also add the option -XX:MaxPermSize=256m. Do not add this option when using Java 8. Important: The entries need to be on separate lines. If you are running Tomcat on a Unix system or with Windows batch scripts, you need to set the environment variable CATALINA_OPTS. Create a file setenv.sh (or setenv.bat on Windows) in the Tomcat bin directory and enter the following line: 8 (Unix): export CATALINA_OPTS="-Xmx2048m -XX:MaxPermSize=256m -Djava.util.Arrays.useLegacyMergeSort=true -Djava.awt.headless=true" (Windows): set CATALINA_OPTS=-Xmx2048m -XX:MaxPermSize=256m -Djava.util.Arrays.useLegacyMergeSort=true Please note, that other applications running on the same tomcat are also affected by this global option. This approach does not work if Tomcat is run as a Windows service! The Windows service will ignore the values that you defined in setenv.bat. Instead, you need to use the configuration utility as shown above. Tomcat in headless mode for terminal-only Unix/Linux systems In order to run iteraplan on a headless (terminal only) Unix/Linux system, you need to add the following option to the CATALINA_OPTS: -Djava.awt.headless=true Database drivers To run iteraplan, a JDBC connector driver appropriate for your database vendor needs to be installed if not present already. The driver must be compliant with the JDBC 4 specifiaction. To install the driver, copy the driver file (a jar file) into the library directory of your Apache Tomcat installation. The directory usually is one of the following, with TOMCAT_HOME referring to the installation directory of Apache Tomcat: TOMCAT_HOME/lib TOMCAT_HOME/common/lib TOMCAT_HOME/server/lib If one of the above directories already exists, simply place the driver there. If not, consult the Tomcat documentation for the appropriate location. That JDBC driver is also needed if the initialization of the iteraplan database is chosen during the installation of iteraplan. In that case, the installer will ask for the directory the driver is placed in. The JDBC connector jar files can be downloaded from following locations free of charge: MySQL: http://dev.mysql.com/downloads/connector/j/ (best choose platform independent download) Oracle Database: http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html Microsoft SQL Server: https://www.microsoft.com/en-us/download/details.aspx?id=11774 Creating the Database Schemas iteraplan requires a relational database with support for transactions. To initialise the database with the structure and data required for iteraplan, use the iteraplan Installer. MySQL iteraplan requires InnoDB as database engine. Starting from version MySQL 5.5.5, the InnoDB is the default Storage Engine. For MySQL Versions earlier than 5.5.5 If a MySQL Version earlier than 5.5.5 is installed, you can use the following SQL command to show the configuration of the database: show variables; The variable "storage_engine" holds the current database engine. If the value is not set to INNODB, you can change the engine in the file my.ini in the MySQL installation folder. Check the following entry and edit if necessary: default-storage-engine=INNODB Additionally to ease the support (usage of scripts/exchange of DB dumps/Switch between MySQL installations on different Operating Systems etc.) we recommend to set: 9 lower_case_table_names=1 Please note, that other databases hosted on the same DBMS are affected by this global configuration as well. When creating an iteraplan database, you must ensure the right settings are made for character set and collation, enabling text in German and English each to be stored correctly. You should therefore create the iteraplan database with the following SQL command: CREATE DATABASE databasename CHARACTER SET utf8 COLLATE utf8_general_ci; You then have to create a new database user with full access privileges for the iteraplan database. The following SQL commands are required to give this user both local and remote access to the database: GRANT ALL PRIVILEGES ON databasename.* TO 'username'@'localhost' IDENTIFIED BY 'userpassword'; If the user in question does not already exist, executing these commands will automatically create a new user. If you are planning to use the iTURM identity management solution which ships with iteraplan, repeat above steps to create a second database which will hold the authentication and authorization information. Oracle A database user schema with the following properties is required when using an Oracle database system. Ask your Oracle DBA to create a schema accordingly: Default character set: WE8ISO8859P1 (or a superset like AL32UTF8) Country specific character set: AL16UTF16 Roles of the database user: CONNECT Rights of the database user: CREATE SEQUENCE CREATE TABLE Tablespace/Quota: Minimum of 10MB, we recommend 100-200MB. Adequate quota for this user on the assigned table space. To provide an unlimited quota, adapt and execute this command: ALTER USER QUOTA UNLIMITED ON ; If you are planning to use the iTURM identity management solution which ships with iteraplan, repeat above steps to create a second database schema which will hold the authentication and authorization information. Microsoft SQL Server The SQL Server instance must allow Server Authentication with username and password. The Windows Authentication method alone is not suifficient, because it is not supported by iteraplan. The Authentication Mode, which allows both methods ("Windows Authentication" cannot be disabled), is called "mixed mode". Please refer to the following chapter in the SQL Server 2012 documentation: Choose an Authentication Mode Your SQL Server has to be configured using a DNS hostname or IP address (not a Windows network ressource path / UNC) and must use a static port, to which the iteraplan application can connect. Currently, only the usage of Latin1 (ISO/IEC 8859-1) characters will work properly in iteraplan. It is recommended to setup the database with the standard collation Latin1_General_CI_AS. The server login used for iteraplan must have sufficient privileges to create and alter tables insert, update, delete data Please ensure that you run the installer and migration/initialization/repair scripts with the login that you configured for the iteraplan application. This is necessary, because the login user's default schema must be the same schema which contains the tables for iteraplan. If you are planning to use the iTURM identity management solution which ships with iteraplan, you can setup another database and/or login for the iTURM application. Technically, you could use the same database and/or login for both applications, but it is a cleaner approach to separate the two applications. 10 Installation iteraplan installer Corporate Edition only! The installation procedure described here applies to iteraplan Corporate Edition only. Lite Edition users should follow the instructions in the bundled README.txt file. The distribution package comes with the installation utility iteraplanInstaller.jar. You can use this to create application packages (.WAR file) for both iteraplan and iTURM. Both files are configured to the values you enter in the Installer, and can be used for operation in a servlet engine. If necessary, the Installer also creates the data required for running the application – such as an initial user account for administration – in the relevant databases. Launch the iteraplanInstaller with the following command in a command line window: java -jar iteraplanInstaller.jar Under Windows, you can also launch the tool by double-clicking the file name in Windows Explorer. After initialization, you will the see the welcome screen. iteraplan Installer welcome screen (via Windows Explorer) The tool features both a graphical and text-based interface and you are automatically presented with the appropriate interface for your environment. 11 Text-based interface of the installation tool In the graphical version of iteraplanInstaller you proceed to the next screen form by clicking the Next button. If you are working with the text-based version, please follow the instructions on the screen. You accept the default values – stated in square brackets – by pressing return. The next section explains the installation process in detail. First, you can choose a customization for the authentification mechanism of iteraplan. Auth customization screen If LDAP + SSO option was selected, the (default) principal request header can be modified. If this header name was changed in your IIS, you must set in the next window the new name. Principal request header screen When doing an installation with LDAP, the next step is the configuration of the LDAP connection. 12 LDAP configuration screen Optional you can adapt the user search filter, if it does not reflect your directory schema. You can also adapt the role membership filter, if your directory uses an attribute other than 'member' to store role members. Next, if any LDAP authentication is used, there is no need for installing iTurm. If you choose iTurm authentication, you can install both applications, iteraplan and iTurm. Selection of deployable web applications Creating the iteraplan and/or iTURM WAR File(s) The first step is to configure the name of the application. With the name of the application you can specify the URI path, from which the application can be addressed in the servlet container. With the default settings and default name "iteraplan", the application will be accessible under http://:/iteraplan. You will also be prompted to name your iTURM installation, if you are installing iTURM as well. 13 Form for entering the application name You then have to specify the database vendor and parameter, where the application data will be stored, as it is illustrated in the figure below. Before the Installer tool takes you to the next page, it checks whether it is able to establish a database connection or not. Please make sure the local firewall does not block this connection. The option Microsoft SQL Server is just available with the SQL Server customized installer version. Specify database vendor 14 Form for entering the iteraplan database parameters. The choice between "ServiceName" and "SID" is only there, when Oracle was selected as database (see hint below). Only for Oracle Databases: When connecting to a Oracle database, "User name for the DB" represents the "Schema" (as this is the same in Oracle DB). One can either use the Oracle Service Name or the Oracle SID for the database connection. Depending on what is entered in the field "ServiceName or SID", the correct radio button has to be selected below the field. If you install iTurm, you must specify the database connection for iTurm in a seperate screen. Next, you specify the folder in which the iteraplan technical log file should be stored. If you leave this field blank, the files are stored in the temp folder of the Tomcat installation. Please note, that these files may be lost if you change the Tomcat installation at a later date. Make sure the servlet engine has read & write access to these paths. If you are also installing iTURM, you will be prompted for its log file path as well. Specifying the path for the technical log file Standard installation of Tomcat 6 on Ubuntu activates Java Security per default. In this case iteraplan can write its log files only within Tomcat's directories without running into access problems. If you require iteraplan's log files outside of Tomcat's directories, please 15 de-activate Java Security. In the next step you can adjust the path where iteraplan will store its search index. The Hibernate Search index contains a full-text index of all data entered into iteraplan, in order to make searching efficient. Make sure that the servlet engine has read & write access to the directory you specify here. Form for specifiying the search index storage directory of iteraplan In the following form you can enable Last Modification Logging. With this option enabled, all building blocks in the database are tagged with the login name of the last user who modified the record and the modification time. This information will be visible to all iteraplan users in the GUI. Form for enabling GUI display of the last change to business data records Next, you have the option of initializing the database. This procedure populates the database with essential data. If you would like to install a newer version of iteraplan using an existing database, please skip this step by leaving the default option No, I will do that at a later time. However, bear in mind that the existing database schemas may have to be adjusted using a special migration script. The individual migration scripts of the according installer can be found within the installer package in the folder "upgrade". If you are installing iteraplan for the first time and only have a fresh iteraplan database schema as described in (see Creating the Database Schemas), your next step is to initialize it. To do this, activate the option Yes, initialize the database. Please bear in mind that this re-initialized the 16 database and any data already in the database will be irrevocably lost. All tables in the database are deleted, created afresh, and re-initialized with data. The database initialization process also creates the administrative role iteraplan_Supervisor and a couple of sample user roles. User with the administrative role iteraplan_Supervisor have comprehensive access privileges in iteraplan. You will have to use iTURM or LDAP in order to manage individual users and password and their role memberships. If you are also installing iTURM, you will also be asked whether you wish to initialize its database. Form for choosing whether to initialise the database If you chose to initialize the database, you are then asked to enter the location of the appropriate JDBC driver (see also Database drivers). Form for entering the JDBC connector driver location The next step is to specify a destination folder into which the iteraplan Installer will copy the generated iteraplan .WAR file. If the CATALINA_HOME environment variable is configured, the Installer suggests the webapps subfolder of the Tomcat installation. Hence, Tomcat will deploy iteraplan automatically. 17 Form for selecting where to store the WAR file On the next dialog page, you have to select the required access protocol for iteraplan users. You can choose between HTTP and HTTPS security, as it is shown in the screenshot below. If you choose HTTPS, all connection attempts to iteraplan will be redirected to a secured HTTPS/SSL connection. This requires that your Tomcat servlet engine accepts HTTPS connections and has an appropriate SSL certificate installed. Please refer to Other Configuration Options and Notes and to the Tomcat documentation for configuration instructions http://tomcat.apache.org/tomcat-6. 0-doc/ssl-howto.html. By choosing HTTP, iteraplan will accept both unsecured and secured connections. If your Tomcat has a HTTPS connector configured, iteraplan will work with HTTP and HTTPS simultaneously. Security level selection If you selected one of the LDAP configurations, the next screen offers the option to specify a group of your LDAP system to which supervisor privileges for iteraplan will be granted. 18 Supervisor group Note: If you are doing a new installation (including database setup), you must specify a group that has full access to iteraplan. If you don't do that, you will not be able to access any feature of the application. Members of this supervisor group can configure all privileges for other users or groups within iteraplan. Also the privileges of the choosen supervisor group can be restricted in the application. Please ensure that the specified LDAP-group is written exactly the same (with upper and lower case)! On the next page a email address for the iteraplan administrator (who has superuser privileges) can be configured. This setting can be changed in "iteraplan.properties" file ("admin.email=..."). This email address is used to give iteraplan users the option to send problem report links to their iteraplan administrator. Administrator Email Address On the last page, use the Execute button to create the .WAR file and – depending on your settings in the form – initialise the database. Show Details -> Output shows the log output of this process; Show Details -> Errors shows any errors that occurred. 19 When initializing a database, the Installer first attempts to delete existing tables from the database. If a new schema is being created for the database (meaning no tables as yet exist for iteraplan), the Installer issues an error message stating that it is unable to locate the tables to delete. You can safely ignore this message here. Once generated, the .WAR file is located in the folder you previously specified. When Tomcat is launched, the file is automatically unpacked and the application can then be accessed in the browser. With the default setting, the application can be accessed at http://*servername*:8080/iteraplan/. If you use iTURM for user management, the initial administrator user has the login name system and the password password. For security reasons we strongly recommend to change the default password after installation. If the license have not been validated yet, please enter lincense-key provided by e-mail on the page $iteraplanRoot$/licensing/update.do. For details see here. ZIP file contents iteraplan is provided as one package in the ZIP file format. Once unpacked, the folder contains the following subfolders and files: lib/ contains the jar files for antinstaller and log4j licenses_3rd-party/ contains all used third party libraries' license texts modified_3rd-party_sources/ contains source files for modifications of third party libraries prerequisites/ contains files and other components for running iteraplan. .keystore: server certificate for secure access via the HTTPS protocol. vbaCert.cer: certificate for running macros in Microsoft Visio. upgrade/ contains SQL scripts and the upgrade guides for the last few versions up to the current one The file iteraplanInstaller.jar is the installer for configuring and creating the application and for setting up the database structure. The file buildenv.properties contains information about the build. Readme file README.txt with current information on the distribution. File RELEASE_x_y.txt containing the current release notes . The file 3RD-PARTY_LICENSE.txt contains a listing of used third party libraries and their licenses. User Authentication Users in iteraplan can be authenticated via a built-in method (iTurm) or using an external LDAP connection. Built-in User Authentication (iTurm) Users in iteraplan can be authenticated via the built-in user management tool iTurm. When running the iteraplan installer select iTurm as authentication mechanism. You can either initialise a new iTurm database or use an existing one. After installation you can login in iTurm and configure role assignments as well as users and passwords. Please see iTURM chapter for further details. User Authentication via LDAP The following chapters describe the setup of iteraplan with an LDAP connection. Different variants of authentication are available. Please note that the steps described in Username & Password are also required for the other two variants. Username & Password To authenticate users using LDAP and username & password, install iteraplan Corporate Edition version with LDAP connection. Follow the configuration steps below to configure the parameters according to your LDAP directory specific details. 1. Use the iteraplan LDAP installer version to perform the basic configuration, initialize the database (if necessary) and generate a WAR file. 2. After you have deployed the final WAR file in Tomcat and it has been extracted by Tomcat, you might need to customize some files. In the following we assume your WAR file is called iteraplan-ldap.war and the relevant files are located in $TOMCAT_HOME/webapps /iteraplan-ldap/WEB-INF. 3. Optional: Some LDAP servers offer secured communication over SSL. In order to active LDAP-over-SSL, specify your server with an lda ps:// URL and import the respective CA certificate that is required to verify the LDAP server certificate. Obtain the certificate of the CA that issued the SSL certificate of the LDAP server. It is best if the certificate file is in PEM format. Import the certificate into the Java key management. Do this on the command line with the following command (all on one line). You may have to adjust the path and name of the certificate file. C:\Programme\Java\jre6\bin\keytool -importcert -file ca.crt -keystore C:\Programme\Java\jre6\lib\security\cacerts -storepass changeit -alias LdapCA 20 If you have installed iteraplan with LDAP authentication correctly, you should be able to login with a user of the chosen supervisor group in iteraplan, after a restart of Tomcat. If the login does not work, then a higher log level is very useful for diagnosis. Add the following four lines to the file $TOMCAT_HOME\webapps\it eraplan-ldap\WEB-INF\classes\log4j.properties, within the section "Spring logging" in that file: log4j.logger.org.springframework.security.ldap=DEBUG log4j.logger.org.springframework.security.ui.webapp=DEBUG log4j.logger.org.springframework.security.web.authentication=DEBUG log4j.logger.org.springframework.ldap=DEBUG Near the end of this file you can also see into which file iteraplan is logging. Additionally, $TOMCAT_HOME\logs\catalina-YYYY-MM-DD.log and $TOMCAT_HOME\logs\localhost-YYYY-MM-DD.log can be useful for a diagnosis. If you have increased the log level, be sure to reduce it again by removing the relevant lines! Single Sign On iteraplan's view of SSO scenarios Installation Prerequisites Overview diagrams Example installation Additional configuration Debugging help User Authentication with Active Directory Single-Sign-On iteraplan can be set up to authenticate users via Single-Sign-On (SSO), provided that they are logged in to a Windows Active Directory. This sub chapter describes how to configure iteraplan and how a possible sample solution for the rest of the required environment might look like. The installer includes the option to install with Single-Sign-On configuration, as described in Username & Password. When trying to set-up the sample solution described below your mileage may vary. Please understand that even with support contracts iteratec can not offer support for systems and set-ups other than iteraplan itself as the number of combinations of systems and versions of software is simply too big. Other set-ups than the one described below might also work. Should you have another solution up and running and are willing to share it with other iteraplan users, simply send it to us. We would be glad to publish it here. iteraplan's view of SSO scenarios In SSO scenarios, the iteraplan web application doesn't handle user authentication itself, but expects the information about a pre-authenticated principal from an external system (in this case the IIS). This is realized by a request header "logon-user", which contains the pre-authenticated principal information as plain username without domain or as username in the format "DOMAIN\user" (without quotes). iteraplan trusts the provided information, which is why the Tomcat's configuration should deny such requests from untrusted sources, for example by restricting the IP range or the hostname(s) for the AJP connector. The header name "logon-user" can be configured during the installation process. It is also possible to manually set the parameter "principalRequestHeader" in the bean "preauthAuthenticationFilter" of iteraplan's Spring configuration file "WEB-INF/applicationContext-spring-security.xml". After iteraplan got the principal information, it looks up the groups (= iteraplan roles) in the ActiveDirectory's LDAP for this principal to perform authorization. Installation Prerequisites For the sample solution the following should be available: An Active Directory where all relevant Client Computers are members Windows Server 2008 or 2012 Must be Member in the same Active Directory as iteraplan user are With Web Server Role (IIS) .NET Framework 3.5 or newer Boncode AJP Connector (see below for details) iteraplan 3.3 or later with working LDAP configuration parameters May be installed on the same Windows Server, but can also run on a different server (even on an non-Windows Operating System) 21 Deployed in a Tomcat Server with active AJP Connector Optional: SSL certificate for configuring HTTPS connectivity Overview diagrams We know of two possible deployment variants where iteraplan and IIS are installed, as shown in following diagrams. Note that the database is not shown in these diagrams, as it does not matter for authentication. You are free to install iteraplan on the same server where the database runs or on a separate server. Deployment Variant "All in one Server" 22 Deployment Variant "Separate Servers" If you want to run more than one iteraplan installation, this is possible with still just one IIS server. You need to configure different IIS Sites and have each forward to a different iteraplan installation. This case is not considered in further detail in this documentation. Please refer to the Boncode connector documentation for help. Example installation Step-by-Step: Installing the SSO-enabled iteraplan version Since iteraplan version 3.4 the LDAP with SSO option is available within the premium Installer. Use the iteraplan installer with LDAP + SSO option to perform the basic configuration, initialize the database (if necessary) and generate a WAR file. Copy your working LDAP configuration file to $TOMCAT_HOME/webapps/iteraplan-sso/WEB-INF. This assumes that you named the WAR file iteraplan-sso.war during installation. Edit the Tomcat configuration file $TOMCAT_HOME/conf/server.xml. and make sure it contains the following Connector entry: If IIS and Tomcat run on the same server, you may also add the attribute address="localhost" to make sure that Tomcat accepts only local connections, not from other servers. Edit the same file so that any other entry is removed or commented out. This is required to avoid that unauthenticated requests can reach Tomcat. (iteraplan would block such unauthenticated requests, but it would be confusing for any user.) Step-by-Step: Installing IIS8 on the Windows Server Assumptions: Windows 2008/ 2012 is installed (optional/ recommended: 64 Bit version) This documentation focusses on Windows Server 2012 with IIS 8 Start Server Manager Pick Add Roles and Features 23 Select Role-based or Feature-based Installation and pick the current server: 24 Then select the role Webserver (IIS) and confirm that IIS Management Tools are installed as well: In the next step, no additional features are needed. Just click Next. The next step shows explanations what the Webserver role comprises. Click Next to proceed to the step Role Services. Here, make sure that the option Windows authentication in the Security section is enabled. Also, be sure to enable .NET extensibility 3.5 in section Application development. This is needed for the Boncode connection to integrate with IIS. Confirm that required other features will be enabled as well. 25 The next page lists all selected Features. Confirm that they are correct and click Install. After the installation process completed, confirm and close the wizard. Return the Server Manager Window. There you will see a new left-hand side entry for IIS which offers some diagnostic information. Click the top-right Tools button and select IIS Manager. 26 Click your way through the left-hand side configuration tree down to the Default Web Site. After you clicked on that, the right-hand side task panel offers a command to Browse the Website. A Web Browser will open and show the IIS welcome page. You have now verified that IIS has been installed and is able to service HTTP requests. 27 Optional steps (not documented here): Configure IIS with an SSL certificate to provide HTTPS connectivity Step-by-Step: Install the Boncode IIS-to-Tomcat connector Download the connector installation package from http://www.boncode.net/boncode-connector and extract the ZIP file to the server Launch the Boncode installer Proceed through the installation wizard and enter the connection information for your Tomcat. Leave the default settings as proposed by the wizard: 28 Depending on your IIS setup, you may have to choose a specific site into which the connector should be installed. Otherwise, we recommend to install it into All IIS Sites: Modify the default handler mappings in the next step if needed for other purposes. For iteraplan, they are fine. Be sure to leave IIS Sub Configuration enabled: 29 After installation has finished, go back to the IIS Manager. Step-by-Step: Configuring IIS to forward to iteraplan Within the desired IIS site, add an application by right-clicking the site icon. As Alias enter the name of the iteraplan application in your Tomcat as entered by you during iteraplan's installation, and select a suitable physical path on the server, where IIS can store its settings. After that, open the Handler Mappings configuration dialog for that application alias. 30 Add a Managed Handler to that application alias as follows. The wildcard in the request path field indicates that all requests should be forwarded to the Boncode connector, and hence to Tomcat and iteraplan. You can find the complete string to be entered into the Type field in the file BonCodeFullHandlerName.txt within the Boncode ZIP download. In that same dialog, click the Request Restrictions button. Uncheck the option Invoke handler only if request is mapped to on the Ma pping tab (first dialog tab), and check that all verbs are handled (second dialog tab) and access permissions are set to Script level. 31 Confirm all dialogs for the handler mapping and return to the application alias configuration. Open the Authentication dialog. Choose Windows Authentication and enable it. Choose Anonymous Authentication and disable it. You can perform advanced configuration of the Windows authentication feature if needed. 32 Optional: Step-by-Step: Enable HTTP Basic authentication for iteraplan's REST API Add a sub-application API as a child of the iteraplan application you just created. For the field Physical Path it is recommended to create an empty subdirectory within the iteraplan application folder on your hard drive. Leave all other settings with their default values. Open the Authentication dialog for that sub-application and enable Anonymous Authentication. All other authentication mechanism must be disabled. Note that choosing anonymous authentication here does not mean everyone could access the REST API, but that authentication is not performed by IIS, but instead by iteraplan itself. Iteraplan will authenticate credentials provided via HTTP Basic against the Active Directory via LDAP. 33 Additional configuration Enable SSO for Firefox The NTLM Authentification required for SSO is enabled in IE by default, but disabled in Firefox. To enable it in Firefox, enter "about:config " (without quotes) into the address bar and search for "network.automatic-ntlm-auth." (without quotes). Double-click on the entry "network.automatic-ntlm-auth.trusted-uris" and enter the URL(s ) that are allowed to automatically authenticate via NTLM, like "example.com". For details please refer to the Mozilla documentation. Increase the packet size In most cases the default packet size for the SSO token might not be big enough. You have to increase the value to an equal byte size in the Boncode AJP connector configuration and in the Tomcat AJP connector configuration. A value of 16384 bytes should be sufficient. Boncode AJP connector: make sure, that the "BonCodeAJP13.settings" file has an option like "16384". For details please refer to the Boncode documentation. Tomcat AJP connector: In the "conf/server.xml" file, look for the AJP -tag and make sure that it contains an attribute like packetSize="16384". For details please refer to the Tomcat documentation. Tomcat security When the token is sent from a different machine as the Tomcat server, then you can restrict the remote machines by adding a RemoteAddressaFilter-Valve or a RemoteHostFilter to the Tomcat configuration. For details please refer to the Tomcat documentation for Valves. Debugging help There should be a file BonCodeAJP13.settings in the windows directory of your server. You can add two lines to that settings file to enable additional logging, see the entries LogDir and LogLevel in the following example: 34 localhost 8009 True True False False C:\logs\Boncode 4 This will create logfiles containing information about the requests forwarded by the Boncode connector. The files will be saved in the given directory with a name prefix BonCodeAJP13Connection_. X.509 Authentication with X.509-Client Certificates and LDAP Some organizations have a public-key infrastructure (PKI) deployed, which allows users to prove their identify with a certificate instead of username & password. Regardless of the identify proof, role assignments need to be retrieved separately. A variant of iteraplan is available that can authenticate with client certificates and access an LDAP directory to retrieve the respective roles for a user. Login with username and password is completely disabled, in turn. The basic setup is as follows: iteraplan is installed on a Tomcat server. The Tomcat does not handle HTTP or HTTPS connections itself. Instead, an Apache httpd server must be set up to proxy all incoming HTTPS requests via AJP to Tomcat. The Apache server has to be configured for SSL-secured connections (typically with the server module mod_ssl) and is responsible for verifying client certificates on incoming requests. The authentication framework used by iteraplan relies on the web server to perform full certificate verification, including signature checks, expiration checks, revocation checks etc. Only authenticated requests must be forwarded to the Tomcat, and eventually iteraplan. It is necessary for the certificate to be forwarded to the Tomcat as well. When a properly authenticated request comes in, iteraplan extracts the user name from the presented certificate and looks up any additional user information via an LDAP search operation. Only if a user object is found, access to the application is eventually granted. The user's roles are also extracted from LDAP in this moment. User roles subsequently define which permissions a user receives. Installation The option for an installation with X.509 configuration is included in the installer. The first part of the required installation steps are described in Us ername & Password. X.509 Configuration steps After you completed the installation routine, you should have a properly initialized iteraplan database and an iteraplan WAR file. Please deploy the file to your Tomcat (if not already done) and configure the Apache httpd to make the iteraplan URL available. In this stage, iteraplan will most probably fail to start. This is normal and should not cause any concerns. Before you can log in for the first time, you have to modify the authentication settings. 1. Optional: Some LDAP servers offer secured communication over SSL. In order to activate LDAP-over-SSL, specify your server with an ldaps:// URL and import the respective CA certificate that is required to verify the LDAP server certificate. Follow these steps to import the 35 1. CA certificate.With default settings, iteraplan assumes that the user name is directly given in the CN field of any certificate. If that is not true in your environment, please adapt the regular expression that is set with the configuration key x509.extractUsernameFromDN.regex. a. Get the CA certificate that issued the SSL certificate of your LDAP(S) server. It works best if you get the certificate file in PEM encoding, which you can identify by this line in the file: ----BEGIN CERTIFICATE---- b. You have to import that certificate into the Java key management in order to be establish SSL-secured connections to your LDAP server. Run the following command to import the certificate (everything on one line!). You may have to adapt the paths and file names to your specific environment. C:\Programme\Java\jre6\bin\keytool -importcert -file ca.crt -keystore C:\Programme\Java\jre6\lib\security\cacerts -storepass changeit -alias LdapCA 2. Configure Apache httpd for SSL client authentication (or verify the settings). There are many ways how you can structure your httpd configuration files. Therefore, it is hard to give precise instructions where you have to set what option. However, the following hints may be helpful to you. For other problems, please refer to one of the many HOWTOs on the Internet for setting up mod_ssl a. Make sure that you have a directive SSLCACertificateFile, pointing to a file that contains the certificates of those CAs which issue acceptable user certificates. b. Include a directive SSLCARevocationFile, pointing to a CRL file that you CAs issued. c. Include a directive SSLVerifyClient and set its value to optional or require, depending on your requirements. d. To forward the certificate to the Tomcat along with an authenticated request, include a directive SSLOptions +ExportCertData 3. Restart Tomcat and httpd to make sure that your configuration changes become effective. iteraplan should now start without any error messages (check its log file and the Tomcat logs catalina.out and localhost.log). Try to open iteraplan in a browser that has a suitable certificate.As soon as you got the authentication mechanisms working, every user with a valid certificate will be able to login, but will not receive any permissions. For that reason, the left-hand side menu will remain almost empty. You will also have to configure httpd for proxying this installation, before you can login. a. If the browser cannot connect, your configuration of Apache httpd and its SSL options is incorrect. b. If you can connect, but only see an iteraplan error message in the browser, there are still errors in the iteraplan configuration. In this case, please enable additional logging options as follows: c. Add the following lines to the text file $TOMCAT_HOME/webapps/iteraplan-certificates/WEB-INF/classes/log4j.properties in the section "Spring logging" and restart Tomcat: log4j.logger.org.springframework.security.ldap=DEBUG log4j.logger.org.springframework.security.ui.webapp=DEBUG log4j.logger.org.springframework.security.web.authentication=DEB UG log4j.logger.org.springframework.ldap=DEBUG d. Inspect the log file after attempting to authenticate once. iteraplan support can help you analyse the log messages and make appropriate corrections. Configuration Files You can influence behaviour of iteraplan through a number of configuration files. The iteraplanInstaller adjusts these files initially with your given configuration, but in some cases you may need to tweak these configuration files later on. These configuration files are stored in sub-directories of Tomcat's webapps directory, i.e. the place where you typically store the iteraplan .WAR file. If your file is named iteraplan.war (the default value), its contents were unpacked to a corresponding directory 'iteraplan' by Tomcat. In the following, [iteraplan Server Context] refers to that directory. Whenever you change these configuration files, the new settings will only become effective after Tomcat has been restarted. iteraplan config files The iteraplan .WAR file contains the following important configuration files [iteraplan Server Context]/WEB-INF/classes/iteraplan_local.properties This property file is initially empty. It can be used to overwrite properites from the following config files. 36 Property values should primarily be set via this file. Other iteraplan property files might remain unchanged. After installation, this file is empty. When property values are set here, they will overwrite the values in the original files. When upgrading to a new iteraplan release, this file can simply be copied into the new instance. [iteraplan Server Context]/WEB-INF/classes/iteraplan.properties The iteraplan general configuration file contains the settings for "last modification logging", "audit logging", "buildingblock default view" and reporting. Most graphical reports as well as the mass update functionality have upper limits on the number of building blocks they process at once. This is intended to prevent overly large memory consumption or long processing times. In this file, you may increase these limits if your server has the necessary hardware resources available. Please Note: Other modifications to iteraplan.properties should only be made in consultation with the iteraplan team. [iteraplan Server Context]/WEB-INF/classes/iteraplan-db.properties This configuration file contains connection information about the database used with iteraplan. The database must have the schema defined by ite raplan. Please note that different versions of iteraplan will generally have different database schemas, though exceptions are possible. Be aware that some of the settings require a syntax specific to the database product you are using. Before changing these settings, make sure you understand their syntax. [iteraplan Server Context]/WEB-INF/classes/iteraplan-gui.properties This configuration file contains the colour values for graphical report configuration. For all diagram types that iteraplan can generate, you can specify seven colour values (in hexadecimal RGB notation, like in HTML). [iteraplan Server Context]/WEB-INF/classes/iteraplan-auth.properties This config file contains settings regarding the password expiry. [iteraplan Server Context]/WEB-INF/classes/log4j.properties Technical logging and audit logging are configured here. Log file names and paths are also set here. The following config files should be left unchanged [iteraplan Server Context]/WEB-INF/applicationContext-spring-security.xml This file configures authentication with the Spring Security component. The last section is of particular interest: this section describes fetching of user and role data from a JNDI-connected database. With the inital settings, access is configured to a database schema corresponding to the iTURM Schema. If you would like to connect iteraplan to your own identity management (e.g. LDAP), please contact iteraplan support for details how to do so. [iteraplan Server Context]/META-INF/context.xml The configuration file for the iteraplan context contains information such as the connection details for a JNDI-connected iTURM database which the Spring Security component uses for authentication. If you use LDAP or another mechanism for authentication, there is no need to change anything here. The database schema is expected to be present as described in the iTURM configuration documentation. The first time the application is deployed, the file is copied to the directory conf/Catalina/localhost in the Tomcat installation folder under the name of the application (e.g. iteraplan.xml). Translations of graphical user interface [iteraplan Server Context]/WEB-INF/classes/de/iteratec/iteraplan/presentation/resources The folder contains ressource files with the translation of iteraplan GUI in English and German. The files are named as follows: ApplicationRe sources_[language abbreviation].properties (e.g. ApplicationResources_de.properties). To support other languages as the two default ones or more than two languages, just put a correctly named translation file in [iteraplan Server 37 Context]/WEB-INF/classes/de/iteratec/iteraplan/presentation/resources and restart Tomcat. You might want to use one of the supplied files as a basis for your translation. Please Note: Localization ressource files should be named as described above. Otherwise they won't be used correctly by iteraplan. ApplicationResources.properties is the english localization of all iteraplan messages, which is used by default. iTURM config files The iTURM configuration files are: [iturm Server Context]/WEB-INF/applicationContext-spring-security.xml As with iteraplan, authentication for iTURM is done by the Spring Security component. Here too, the login and password are checked against the database which must be provided via JNDI. Typically, you need not change this file. [iturm Server Context]/META-INF/context.xml The database expected by the Spring Security component is defined here. This database is the default for authentication and for storing the data managed by iTURM. [iturm Server Context]/WEB-INF/classes/turm.properties This configuration file contains the JNDI name of the database in which the data managed by iTURM is stored. This file can also contain definitions of minimum password lengths and password patterns (if any have been specified). Each of the configuration options is explained within this file. [iturm Server Context]/WEB-INF/classes/log4j.properties The Log4j Framework configuration file contains the settings for log file names and paths. This is the data model of iTURM: iTURM data model Other Configuration Options and Notes Authentication Authentication of iteraplan users is carried out using the Spring Security component of the Spring Framework. This permits connection of various data sources. With the default setting, users are authenticated by means of the iTURM database, which is made available by Tomcat via JNDI. 38 You should therefore make sure that the right JDBC driver (for the database containing the authentication information) is located in the lib subdirectory of your Tomcat installation folder. If you want to use an existing LDAP directory (such as Active Directory) for authenticating users, refer to the detailed setup instructions. Access via HTTPS Protocol For reasons of security and data privacy, iteraplan should be configured to enforce access with the secure HTTPS protocol. The iteraplan installer offers you a choice which level of security you want to enforce. The use of the HTTP protocol is inadvisable. There are two ways of setting up HTTPS access that you can choose from. First, a web server such as Apache httpd can do the job of processing HTTPS requests and forwarding the decrypted requests to Tomcat. Please refer to the Apache httpd documentation for HTTPS/SSL configuration instructions, and to the Apache Tomcat documentation on the AJP connector for connecting Tomcat to Apache httpd. Second, Tomcat also offers SSL-secured connections, i.e. HTTPS itself. In order to use HTTPS it is necessary to install a server certificate (certificate keyfile) for the web server. The servlet engine also has to be configured for this protocol. iteraplan ships with the requisite server certificate – this is located in the folder prerequisites. If you do not intend to use existing certificates, you can create one with the keytool utility provided with Java. You run this utility as follows: keytool -genkey -alias -keypass -keystore .keystore -storepass -dname "CN=, OU=, O=, L=, ST=, C=" The resulting file .keystore then has to be copied to the conf folder in the Tomcat installation folder. To instruct Tomcat to process HTTPS requests, you have to enter a connector in the file server.xml, which is located in the conf folder of your Tomcat installation folder. An example configuration is shown below: If you would like to use the .keystore file provided, enter the password iteraplan in the field keystorePass. Further information to set up Tomcat for SSL can be found in the official Tomcat documentation: Tomcat 7: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html Tomcat 8: https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html Access via HTTP Protocol If access via HTTP protocol is required, you have to make a small change to the iteraplan configuration: Open the file [iteraplan Server Context]/WEB-INF/web.xml and replace the section ... with the following: 39 Secured Area /* NONE In order to revert to the previous behaviour, replace NONE with CONFIDENTIAL. Visual Basic Certificate iteraplan offers you to export landscape data to Microsoft Visio format. To ensure the exported data will be presented correctly in Visio, the supplied Visual Basic macro has to be permitted to execute whenever one of these files is opened. If no adjustment is made to the configuration, users will be required – for security reasons – to confirm macro execution each time a file opens. The certificate vbaCert.cer, signed by iteratec, makes it possible to suppress this confirmation request and open the files directly. The certificate, which is stored in the folder prerequisites, is displayed in Windows by double-clicking the file name and can then be installed. You must also ensure you are running Microsoft Visio with the current Service Pack (at present this is Service Pack 3 for MS Visio 2003 and Service Pack 1 for MS Visio 2007). Database cache To improve the performance of the iteraplan application caches are used (via Hibernate and Ehcache). If the database has been modified outside of iteraplan, e.g. when a database dump was imported, the database and cache will be out of synchronisation. If this occurs, the cache must be cleared or the iteraplan application must be restarted. To fine-tune performance you can adjust the time-to-live of elements in the cache configuration, see [iteraplan Server Context]/WEB-INF/classes/ehcache.xml Connection Pooling Connection pooling is a powerful way to improve performance. The default parameters work fine in most situations, but servers with a higher than normal workload may require additional tuning. At the moment iteraplan uses a DBCP connection pool, configured via a org.apache.commons.dbcp.BasicDataSource object. The configuration is made in the file [iteraplan Server Context]/WEB-INF/classes/iteraplan-db.properties. Here is a summary of the most important configuration options: database.pool.autoCommit: specifies whether SQL statements should be auto committed by default (default: false) database.pool.transactionIsolation: sets the default isolation level of the transactions database.pool.initialSize: sets the initial number of connections to be created by the pool (default: 0) database.pool.maxActive: limits the maximum number of active connections in the pool (default: 8) database.pool.maxIdle / database.pool.minIdle: specifies the maximum/minimum number of idle connections permitted in the pool (default: 8/0) Use a different logo instead of the iteraplan logo Some companies want to adapt iteraplan to look more similar to their Corporate Identity. iteraplan displays the logo in the top-left corner of each page. The image can be found in [iteraplan Server Context]/images/iteraplanLogo200x49.gif. You can overwrite that file with our own logo. Try to make sure that replacement image file is also 49px high, otherwise the page layout might break. The iteraplan logo on the login page references the same file. As an alternative to replacing the image file, you may also modify the HTML template files to reference another image file. For the login page, search for the tag in [iteraplan Server Context]/jsp/login.jsp, and for the main page logo, search for the tag in [iteraplan Server Context]/jsp/layouts/standard.jsp. 40 Redirect to the Classic Client after login Whenever the following option is set to "true", all users will be redirected to the Classic Client start screen after login, unless some other redirect is used. ################################################################# # Redirect to Classic Client after login # ################################################################# ic.afterloginoldclient.enabled=true When user is already logged in, this option also specifies which homepage is shown (Classic or New Interactive Client) when the base URL is entered. If you want to enable this feature, add this property to the configuration file [iteraplan Server Context]/WEB-INF/classes/iteraplan.properties or [iteraplan Server Context]/WEB-INF/classes/iteraplan-local.properties: Audit Logging With audit logging enabled, details of changes made by users are stored in a file which can be downloaded from the iteraplan GUI. Audit logging makes the application slower, so you should only enable it, if you really need the feature. To enable audit logging, copy following lines into $iterplan_Home$/WEB-INF/classes/iteraplan_local.properties: ################################################################# # Audit log configuration # ################################################################# audit.logging.enabled=true and adjust the AuditLogger log level in section # iteraplan audit logging in the file $iterplan_Home$/WEB-INF/classes/log4j.properties to DEBUG, as shown below. # iteraplan audit logging # ####################### log4j.logger.de.iteratec.iteraplan.businesslogic.common.AuditLogger=DEBUG, auditlogfile log4j.additivity.de.iteratec.iteraplan.businesslogic.common.AuditLogger=false In order to specify the path where the iteraplan audit log file should be stored, additionally adjust the value for the key log4j.appender.aud itlogfile.File in the file $iterplan_Home$/WEB-INF/classes/log4j.properties. An example is shown below. Please make sure that the Tomcat has read & write access to this folder. If the setting is not changed, the same folder as for general logging will be used. ############################################################### #FileAppender "auditlogfile" ############################################################### log4j.appender.auditlogfile=org.apache.log4j.DailyRollingFileAppender log4j.appender.auditlogfile.File=D:/iteraplan/auditlogs/iteraplan-5.0-audit.log Speed up initial client load time When accessing the interactive client for the first time, it takes some time until data loading has finished. This is due to the amount of data to be transferred between iteraplan and the client. To speed up the initial load of the new iteraplan client (among other operations) we recommend to enable compression in the Tomcat connector. 41 Should you want to enable compression, add the following two settings to the connector entry in the Tomcat server.xml file: compression="on" compressableMimeType="application/json,text/html,text/xml,text/plain,text/css,text/javascript,application/j avascript" Upgrade Guide 1 Verify System Requirements Before starting with the upgrade, please verify that you have the required software packages installed and upgraded to the required version. See here for details: Installation Prerequisites 2 Preparation This guide provides instructions to upgrade iteraplan from release 5.4 to release 5.5. Please note that this guide is only applicable to these versions of iteraplan. For prior versions, please follow the appropriate iteraplan upgrade guides in order to upgrade to iteraplan 5.4 first. The upgrade steps only need to be carried out once. However, they must be repeated for every installed instance of iteraplan (if applicable). The upgrade process is not intended to be reversible, i.e. after performing the upgrade there is no standard way to revert to the previously installed version of iteraplan. For that reason, we strongly recommend to create a complete backup of your entire iteraplan database and the application files. To help you carry out the upgrade our checklist might prove useful. 2.1 Conventions and Assumptions In the scope of this guide, it is assumed that iteraplan is deployed on an Apache Tomcat web server. The Tomcat installation directory is hereafter referred to as $TOMCAT_HOME, regardless of the underlying operating system. Furthermore, it is assumed that the iteraplan application is deployed under $TOMCAT_HOME/webapps/iteraplan. If you have deployed the application under a different name, replace iteraplan in the provided path as appropriate. The Java Runtime Environment (JRE) or Java Developlent Kit (JDK) installation directory is denoted as $JAVA_HOME. This guide uses Unix conventions for path names. For Windows, replace slashes (/) with back-slashes (\) and include drive letters where necessary. 3 Upgrade 3.1 Upgrade the database structure Be sure that you have shut down iteraplan or the entire Tomcat instance. To shut down Tomcat on Windows, use the Computer Management Console to stop the Tomcat Service. Alternatively, run the batch script shutdown.bat in the $TOMCAT_HOME/bin directory. On Unix-like systems, use the normal daemon control mechanism, i.e. /etc/init.d/tomcat stop, or run the shutdown.sh shell script in the $TOMCAT_HOME/bi n directory. All database upgrade scripts are encoded with UTF-8. Please ensure that you use this encoding. Depending on whether you use MySQL, Oracle or SQLServer, use the SQL script for the respective database vendor. The script will perform all necessary modifications of your database. In the directory upgrade/v5.4To5.5/ three files are provided: migration_iteraplan_540_to_550_[database].sql Replace the placeholder [database] with the database you use. To execute the scripts, use a database management tool appropriate for your system. Because of the wide variety of tools, detailed instructions are omitted in this guide. 3.2 Migrate history data 42 If the history function has never been active in the past or you already migrated the history data when upgrading to the release 5.4 or you do not want to keep the history data, skip this chapter completely and proceed with chapter 3.3. If you want to migrate your history data from previous version, please proceed with the following steps. CAUTION The history migration will take several hours. Our internal test show times from 5 up to 20 and more hours. We strongly recommend to run this long-running job over night and/or on a weekend. During this job iteraplan needs to be shut down to prevent data inconsistency. This migration needs to be run only once. iteraplan 5.4 and later comes with a reworked implementation of its historization functionality. If the history functionality has been enabled in older iteraplan versions and you want to migrate that history data to be used in iteraplan 5.5, the provided history migration tool has to be executed once. To run the history migration tool, proceed as follows: 1. Backup your iteraplan database, if not already done. 2. Extract the provided historyMigrationTool.zip file into a folder. The folder has to be located on the same computer or virtual machine like iteraplan is running on. After extraction of the zip-file, the folder should contain the following files: historyMigrationTool.jar migrateHistory.bat (for Windows systems) migrateHistory.sh (for Unix systems) 3. Copy the following files from your old iteraplan installation to the folder with the migration tool: a. from the $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes folder: iteraplan.properties, iteraplan-db.pr operties and iteraplan_local.properties b. from $TOMCAT_HOME/lib: The jdbc driver jar file corresponding to your database: for MS SQL Server: sqljdbc[version].jar (for example sqljdbc4.jar) for Oracle: ojdbc[version].jar (for example ojdbc6.jar) for MySQL: mysql-connector-java-[version].jar (for example mysql-connector-java-5.1.3 1.jar) If more than one of those files exists, only copy the file for the database you use with iteraplan. 4. Make sure the environment variable JAVA_HOME is set correctly. 5. Run the shell script appropriate for your operating system: migrateHistory.sh on Linux systems or migrateHistory.bat on Windows systems. During the migration the history migration tool uses two different log-files. In the file "migration.log" the progress of the tool is tracked. It contains one entry for each element that is migrated. The file "iteraplan.log" contains eventual exceptions. If it is not possible to migrate a single change set, this is logged in both files. The migration of other changesets is not affected in this case. If there is an error during the migration, please contact the iteraplan customer support. 3.3 Configure the new installation Before iteraplan 5.5 is set up, the previous installation of iteraplan should be completely undeployed from the Tomcat instance. In particular, the following files and directories should be deleted from the Tomcat installation directory: $TOMCAT_HOME/conf/Catalina/localhost/iteraplan.xml $TOMCAT_HOME/webapps/iteraplan.war $TOMCAT_HOME/webapps/iteraplan If your old iteraplan installation is deployed simultaneously with iteraplan 5.5, unexpected side effects may occur due to competing database and file access. Launch iteraplan installer Run the installer by launching the iteraplanInstaller.jar file and follow the instructions. Depending on your system configuration, double-clicking the jar file might not work. If this is the case, the file can be launched from the command line by executing 43 java jar iteraplanInstaller.jar or by explicitly stating the JRE to use: $JAVA_HOME/bin/java jar iteraplanInstaller.jar Enter database connection parameters During the installation process, the installer will request you to provide database connection parameters. The parameters to use are the same as the ones used for the installation of previous versions of iteraplan. If you are not sure, you can look up the settings in the following two files of your old version’s backup: $TOMCATBACKUP/webapps/iteraplan/WEBINF/classes/iteraplandb.properties for the iteraplan database and $TOMCATBACKUP/conf/Catalina/localhost/iteraplan.xml for the iTURM database with authentication information. Important: Make sure to disable database initialization. Otherwise, your current database contents will be deleted completely and you will need to resort to the data you have backed up. Enter full-text search index storage directory In a subsequent step, you will be requested to specify a directory where the files of the search index are to be stored. It is recommended to use a new empty subdirectory of the Tomcat installation directory, for example $TOMCAT_HOME/indexes. In case several instances of iteraplan are deployed with different database configurations, it is important to use different search index directories. Empty Tomcat’s temporary work directory Tomcat’s temporary work directory probably contains files of a previously installed version of iteraplan, even after installing the new version. This might cause problems. Therefore delete the following folder: $TOMCAT_HOME/work/Catalina/localhost/[iteraplan] This forces Tomcat to recompile at start up. Deployment on Tomcat and fine-tuning the configuration After iteraplan 5.5 has been successfully configured by the installer, the generated WAR-file should be automatically copied into the Tomcat webapps directory ($TOMCAT_HOME/webapps). Then you can start Tomcat in order to deploy iteraplan 5.5. During deployment, a directory $TOMCAT_HOME/webapps/iteraplan (corresponding to the name of the WAR-file), in which the iteraplan installation resides, will be generated. In case you made any customizations to your old installation’s configuration options, make sure to transfer the modifications analogously, for example to the the properties in $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes/iteraplan.p roperties file or to any other *.properties file in $TOMCAT_HOME/webapps/iteraplan/WEB-INF/classes Copy document templates iteraplan allows to store document templates for some report types on the server. Copy those template files from your old installation’s backup to the new iteraplan 5.5 installation. To do that, go through all sub-directories in $TOMCAT_BACKUP/webapps/iteraplan/WEBINF/classes/te mplates and copy all files from the old installation which do not yet exist in the new installation’s corresponding directory. That is, you should not overwrite existing files, e.g. .../templates/elasticExcel/ExcelWorkbook.xlsx. It’s okay if no files are to be copied. Copy Graphics Reactor Contents The iteraplan Graphics Reactor stores all input and output files in the file system. Copy the contects of $TOMCAT_BACKUP/webapps/iterapla n/WEB-INF/classes/reactor from the backup to the corresponding directory in the new installation. It’s okay if no files are to be copied. Copy Plugin API Scripts The iteraplan Plugin API scripts are stored in the file system. Copy the contects of $TOMCAT_BACKUP/webapps/iteraplan/WEB-INF/class 44 es/scripts from the backup to the corresponding directory in the new installation. It’s okay if no files are to be copied. Enable Compression within Tomcat To speed up the initial page load of the new iteraplan client (amongst other operations) we recommend to enable compression in the Tomcat connector. This is not mandatory, but generally a good idea. If you want to enable compression, add the following two settings to the connector entry in the Tomcat server.xml file: compression="on" compressableMimeType="application/json,text/html,text/xml, text/plain,text/css,text/javascript,application/javascript" Your connector entry might then look like this: Transfer LDAP authentication settings If iteraplan was installed with LDAP authentication enabled, simply copy the iteraplan-auth.properties file from your old installation’s backup to the $TOMCAT_HOME/webapps /iteraplan/WEB-INF/classes/ directory. The contents of the file do not need to be adjusted. Final restart As a final step, restart Tomcat to make sure that any modifications to the iteraplan configuration become active. 3.4 Notes After the upgrade, some users might report that iteraplan does no longer work as expected. Possible observations might include that buttons have wrong titles or that the client freezes when performing certain tasks. In this case users should clear their local browser cache and re-login into iteraplan. Upgrade Checklist Upgrade from iteraplan version 5.4 to 5.5 Preparation 45 Task Comment Stop iteraplan Through Tomcat Manager, or by stopping the entire Tomcat instance Done Backup database(s) MySQL: mysqldump; Oracle: exp or expdb Backup Tomcat installation directory $TOMCAT_HOME and its contents. Verify system and software requirements and upgrade if neccessary See online documentation for details. Upgrade Task Comment Database migration History data migration Only needed, if the history function has been enabled in the past and history data has not already been migrated with a previous iteraplan upgrade Undeploy previous installation Install iteraplan 5.5 Use the installer provided within the ZIP file. Empty Tomcat work directory 46 Review Configuration Transfer custom settings from the old iteraplan.properties file. If LDAP is used for authentication, copy iteraplan-auth.properties. Transfer document templates Copy all document templates (Visio and Excel files) from your old installation‘s backup Transfer Plugin API contents Copy all files in the scripts directory Transfer Graphics Reactor contents Copy all files in the reactor directory Done