Installation and Configuration Guide

Transcription

1 BiZZdesign Team Server Installation and Configuration Guide

2 Table of contents 1 About the Team Server 3 2 Team Server system requirements 4 3 Contents of the Team Server installation bundle 5 4 Team Server installation Installing the database Configuring network access Installing the Team Server Configuring the Windows firewall (optional) Configuring the Team Server 11 5 Changing Team Server settings Changing the Team Server identification details Changing the Team Server configuration Changing the Team Server database configuration 16 6 Additional configuration options User import from Active Directory and single sign-on Configuring LDAP user import and single sign-on Synchronizing users with Active Directory Deactivating the LDAP user import Limiting user invitations to existing Team Server users 25 Appendix A - Team Server-related issues 27 Appendix B - Using an official HTTPS certificate for the Team Server 29 2

3 1 About the Team Server The Team Server is a component of the Team Platform functionality in Enterprise Studio. The Team Server facilitates working together on model packages, and stores the administration of shared model packages and the participating users. Before model packages can be shared in Enterprise Studio, a Team Server must be installed and configured. After that, users can be registered in the Team Server and model packages can be stored in it and shared. The Team Server also supports importing users from Windows Active Directory using LDAP, to enable logging in to the Team Server with their Windows account and, automatically logging in via single sign-on. Note: This documentation is meant for application administrators who are familiar with installing and configuring software and databases. 3

4 2 Team Server system requirements The Team Server has a general set of software requirements. As resource requirements are largely driven by the usage of Enterprise Studio and the Team Server, the necessary hardware depends on various factors. For a complete overview of the system requirements, please refer to the Enterprise Studio System Requirements (PDF). 4

5 3 Contents of the Team Server installation bundle The Team Server installation bundle contains the following files: File 3rdparty\ service\ license.txt Explanation Legal documents of third party libraries (licenses etc.) Files needed to install Team Server BiZZdesign software license readme.txt - 5

6 4 Team Server installation 4.1 Installing the database 1. Open SQL Server Management Studio and create a new empty database. 2. Create a database user having at least read and write rights for the created database. The user needs the "db_owner" role. 4.2 Configuring network access Enterprise Studio uses the network to connect to a SQL database, even when it is locally installed. The following steps must be performed to successfully connect to the SQL Express database. 1. Open the SQL Server Configuration Manager. 2. In the SQL Server Configuration Manager window, expand the SQL Server Network Configuration and click Protocols for SQLEXPRESS, or something similar if your are using a different SQL. 3. In the list of protocols for SQLEXPRESS, right click TCP/IP and then click Enable. 6

7 4. Right click TCP/IP once again and subsequently click Properties. 5. Click the IP Addresses tab and scroll down to IPALL. Set the TCP Port, for example to In the SQL Server Configuration Manager window, select the SQL Server Services and restart SQL Server (SQLEXPRESS) by right clicking it and then clicking Restart. 7

8 4.3 Installing the Team Server After installing the database, follow the procedure below to install Team Server as a Windows service. 1. Download the Team Server and unzip the file. Choose a location on the hard drive where the Team Server must be installed. This location will be referred to as TeamServerHome. 2. Copy the contents of the \service folder (not the folder itself) into the installation bundle to the TeamServerHome folder. 3. Open the wrapper.conf file (TeamServerHome\conf folder) in a text editor and configure the following parameters. Make sure that each parameter you add is unique. Each parameter has a property name which starts with "wrapper.java.additional.<n>". The "<n>" component is an integer number counting up from 1. By default the numbering should be in sequence without gaps. Update the HTTP port Update the HTTP port under which the server must be running. By default, port 9000 is set. You can choose your own port by editing the port number: wrapper.java.additional.2 = -Dhttp.port=9000 8

9 Optional: Set the JVM memory settings If desired, set your own JVM memory settings. Set the initial size (xms) and max size (xmx). wrapper.java.additional.3 = -Xms=768 Set the initial size to at least 768 MB. wrapper.java.additional.4 = -Xmx=<max size> The max size depends on how much memory you want to allocate. Make sure to leave some memory left for other applications and the OS. Optional: Use HTTPS instead of HTTP If you want to use HTTPS instead of HTTP, please refer to Appendix B and follow the instructions before continuing to the next step. 4. Verify that the Team Server is correctly configured: a. Execute the runconsole.bat file in the TeamServerHome\bat folder. When it's finished, leave the Command prompt open. 9

10 Note: If the text in the Command prompt ends with "Press any key to continue", then an error occurred during the execution. Check the information in the Command prompt, press any key to close the window and fix the reported problem. b. Open your web browser and point locally to Replace <servername> by the name of the computer you are installing the server on, and replace <portnumber> by the specified port number. You should see the Team Server setup page: If the page is not displayed immediately, refresh it. 5. If everything is running correctly, close the web page. Press Ctrl+C in the Command prompt to stop the Team Server, type Y and press Enter to terminate the batch job and close the window. If an error occurs, check if a file RUNNING_PID exists (TeamServerHome\ folder). Delete this file before trying to run a second time. 10

11 6. Install the service by running the Command prompt as administrator, navigating to the TeamServerHome\bat folder, and running the installservice.bat file in this folder. 7. Also in the Command prompt, start the service by navigating to the TeamServerHome\bat folder and running the startservice.bat file in this folder, or go to Control Panel > Administrative Tools > Services and start the service there. The service is called Team Server <version>. Note: If the service does not start properly, and an error message appears, please refer to Appendix A for more information and the solution. 4.4 Configuring the Windows firewall (optional) Verify that the specified port number is open to other users. If not, configure your Windows firewall in order to make it accessible. Use Windows Firewall with Advanced Security to create a new incoming rule for the port by right clicking Inbound Rules and then clicking New Rule. Make sure you clear the Public check box in the list of network profiles while adding the new rule. 4.5 Configuring the Team Server After installing the Team Server, configure the server and create the initial administrator user. 11

12 1. Open your web browser and enter the address the users will use to access the Team Server. Example: The Team Server setup page appears. 2. At step 1. Identity, identify the installed server by entering a display name and specifying its server protocol, hostname and port. 3. At step 2. Database, configure the database connection. Test the connection by clicking Test connection. Optional: Select the Integrated security check box if you want to enable logging in on the Team Server using a Windows account. a. If you are using the JDBC driver, download the sqljdbc_auth.dll file from: Make sure you download the correct version. b. Save this dll file on a location that is accessible in Windows, for example C:\Windows\System32 or..\program Files\Java c. After that, restart the Team Server Service. d. Make sure the login user for the Team Server Service has rights to be able to access the database and Team Server. Per default your service will be added as "local system" account. It might be necessary to change this login for a user who has access to those components. 4. At step 3. , specify the settings for the Team Server. Test the settings by filling out an address that is outside your mail server domain and clicking Send test At step 4. Admin user, create the initial administrator user for the Team Server. 6. Finally, click Finish setup to complete the Team Server setup. 12

13 After completing the setup, users can be added to the Team Server and be invited to model packages and projects. Detailed information about adding users, registering in the Team Server, and inviting users can be found in the Team Platform user documentation (PDF) and the Enterprise Studio online help. 13

14 5 Changing Team Server settings Changes can be made to the configuration settings of an installed Team Server, for example to correct something. The following settings can be changed: identification details: Team Server display name and server protocol, hostname and port configuration database configuration: database password, JDBC URI, and integrated security The identification details and configuration can be changed at the Team Server settings, the database configuration is changed in the Team Server configuration file. 5.1 Changing the Team Server identification details 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > General. 2. On the General Settings page, in Team Server, edit the settings you want to change. 14

15 3. Click Save to save the changes. 5.2 Changing the Team Server configuration 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > On the Settings page, edit the settings you want to change. 15

16 3. In Recipient, fill out an address that is outside your mail server domain, and then click Send test message to test the new settings. 4. Click Save to save the changes. 5.3 Changing the Team Server database configuration The Team Server database configuration can be changed in the teamserver.config.json configuration file. This file is located in the TeamServerHome folder (location where the Team Server is installed). The section of the configuration file that contains the database settings is the following: "database" : { "hostname" : <database hostname (if generateurl=true)>, "port" : <database port (if generateurl=true)>, "name" : <database name (if generateurl=true)>, "url" : "<database connection URI (if generateurl=false)>", "generateurl" : <true or false>, "username" : "<username (if singlesignon=false)>", "password" : "<encrypted password (if singlesignon=false)>", "newpassword" : "<update password>", "singlesignon" : <true or false> To make changes to the database configuration, follow these steps: 16

17 1. Stop the Team Server if it is still running. 2. Open the teamserver.config.json configuration file with a text editor, and edit the settings you want to change: Database password The passwords in the configuration file are encrypted. To change the password of the database, enter a new password in the newpassword property. When restarting the Team Server the value of newpassword is encrypted and will update the previously encrypted password. After that the newpassword property in the configuration file is cleared again. JDBC URI If you want to specify the JDBC URI, set the generateurl property to false, and enter the URI in the url property. Else set the generateurl property to true, and enter the values for the properties hostname, port and name. Integrated security If you want to activate integrated security for connecting to the database, set the singlesignon property to true. The properties username and password will be ignored then. To deactivate integrated security, set the singlesignon property to false, and enter the database credentials in the properties username and password. 3. Save the changes and close the file. 4. Test the new settings by restarting the Team Server and then opening the server location in your web browser. 17

18 6 Additional configuration options 6.1 User import from Active Directory and single sign-on Users are registered in the Team Server to be able to work together on model packages and projects. The BiZZdesign Team Server supports importing users from Windows Active Directory using LDAP, to enable logging in to the Team Server with their Windows account and, automatically logging in via single sign-on. LDAP user import If users that must be registered in the Team Server, are available in an LDAP environment, they can be imported into the Team Server from Windows Active Directory using LDAP. Keeping user data in the Team Server up-to-date can simply be done by periodically synchronizing the users with Active Directory. New users will be added, existing users will be updated, and users that are no longer present in Active Directory will be removed from the Team Server. Single sign-on If users are imported from Active Directory, single sign-on can be enabled for them to log in to the Team Server and add storage places in Enterprise Studio using their Windows account without giving their credentials. For configuring single sign-on, the Kerberos network authentication protocol is used. Note: The settings for configuring the LDAP user import and single sign-on are only available and visible to Team Server administrator users Configuring LDAP user import and single sign-on LDAP user import can be configured on its own, without single sign-on (SSO). Single sign-on can be configured additionally to the LDAP user import. 18

19 Configuring LDAP user import To configure LDAP user import in the Team Server, follow these steps: 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > Directory Integration. 2. On the Active Directory Integration Settings page, next to Synchronization and authentication of users from Active Directory through LDAP, click the switch to activate the LDAP user import feature. 3. In Directory Server, specify the Active Directory server to use and the settings for connecting to this directory server. Server URL: The URL used to connect to the LDAP server. It should start with ldap://. Distinguished name: The Distinguished Name of the user which is used to bind to LDAP. Password: The password of the user entered by Distinguished Name. 4. In User Synchronization, specify the settings for synchronizing the users. 19

20 Base DN: The base from which to search for LDAP users. LDAP query: The LDAP query selects the users that should have access to the Team Server. Use the search filter syntax for Active Directory for this. To preview the results of the filter the Advanced tab of the Custom search functionality of Active Directory can be used. Note that license seats may be claimed for any user that matches the query. If you also want to use single sign-on, proceed with the steps below for configuring single sign-on. If you only want to configure the LDAP user import, you are now ready. To save the settings and synchronize users, click Save and synchronize users. Click Save if you only want to save the settings and synchronize at a later time. Configuring single sign-on To configure single sign-on, follow these steps: 1. In Single Sign-On, next to Use single sign-on, click the switch to activate single sign-on. 2. Set the properties that are needed for single sign-on. 20

21 Principal: The Kerberos principal for the Team Server. This typically has the format Realm: The Kerberos realm in which the Team Server resides. This is typically the same as the domain. 3. Optional: If you want to use a keytab, click the switch next to Use keytab to activate it. Also, name the keytab file teamserver.keytab and place it inside the conf/ directory of the Team Server installation. 4. Optional: If you do not use a keytab, and want to use the principal s password, enter it in Password. 5. Click Save to save the settings. Click Save and synchronize users if you also want to synchronize users. If the settings have already been saved, click Synchronize users Synchronizing users with Active Directory To synchronize users with Active Directory, follow these steps: 21

22 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > Directory Integration. 2. At the bottom of the Active Directory Integration Settings page, click the Synchronize users button. 3. The User Synchronization page shows an overview of the users that will be added, changed, and removed after synchronization. Example: It is the result of the LDAP query. The total number of users that is shown includes users from Active Directory and original Team Server users. If the data look OK, click Synchronize users. Click Cancel if you want to cancel the synchronization. 22

23 Tool license limitations on synchronization The number of users that can be synchronized is bound to the number of seats in your Enterprise Studio tool license. During user synchronization, there is no immediate check on the number of users that you are allowed to synchronize. If the number is exceeded, a notification will only appear a short time later. Therefor you should take the allowed number into account before synchronizing. To find out the number of license seats in your tool license, go to File > About in the Backstage view of Enterprise Studio, and click License Management. After the synchronization Users that are added during the synchronization with Active Directory do not have administrator rights nor have the rights to create model packages. Their rights need to be granted afterward by an administrator user. Additionally, the users do not receive an notification and do not need to register in the Team Server (manually added users do). The user accounts are immediately ready for logging in and can be used directly for model package invites Deactivating the LDAP user import If you do not want to continue the synchronization and authentication of users from Active Directory via LDAP, deactivate the link with Active directory. After deactivating, users synchronized from Active Directory cannot authenticate via Active Directory anymore. If you had also configured single sign-on, it will also be deactivated. When deactivating the link you have the option to remove the synchronized users, or to convert them to original Team Server users. To deactivate the link with Active Directory, follow 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > Directory Integration. 23

24 2. On the Active Directory Integration Settings page, next to Synchronization and authentication of users from Active Directory through LDAP, click the switch to deactivate the link, and then click Save. 3. A message appears offering you the choice to keep or remove the users from Active Directory: Click Keep users to keep the users and convert them to original Team Server users. Click Remove users if you want to remove the users from the Team Server. If the former LDAP users are kept and converted to original Team Server users, they will receive an for setting their password for the Team Server, because the Team Server does not create a password for these users after the conversion. The users can still be invited to model packages and projects. 24

25 6.2 Limiting user invitations to existing Team Server users Users who are registered in the Team Server can invite other people to collaborate on model packages and projects. By default, anyone can be invited. A person's address can be entered and an invitation will be sent. For security reasons, inviting people can be limited to users who already exist in the Team Server. These are people that have been added to the Team Server and have received an invitation to register. They need not have registered yet though. New users can only be added by an administrator user in the Team Server. To limit user invitations, follow these steps: 1. Log in to the Team Server as an administrator user, and in the toolbar click Settings > General. 2. On the General Settings page, in Invitations, click the switch next to Only existing users can be invited to model packages, to activate the limitation. 3. Click Save to save the changes. Once the limitation has been activated, users can only invite other users that already exist in the Team Server. If the address of (one of) the invitee(s) does not belong to an existing Team Server user, the user will see a message indicating that only existing users can be invited. The invitation operation is canceled. 25

26 Canceling the limitation To cancel the limitation to invite only existing users, click the switch again, and then click Save. 26

27 Appendix A - Team Server-related issues Windows service cannot be started during Team Server installation Problem The Windows service does not properly start during the Team Server installation in one of the following situations: The message "Service Team Platform Server NOT started" appears when running startservice.bat in the Command prompt after installing the Windows service. The message "Windows could not start the Team Server v2.0.0 service on Local Computer. Error 1053: The service did not respond to the start or control request in a timely fashion." appears when starting the service via Administrative Tools > Services. Solution Please check the TeamServerHome\logs folder. If no logs are found it is most likely caused by having Java 8 installed alongside an older version of Java. If the logfile TeamServerHome\logs\wrapper.log exists, please check the contents of this file for errors. To fix the problem, follow these steps: 1. Uninstall the Windows service by typing uninstallservice.bat in the Command prompt. 2. Uninstall any older Java versions, or make sure that older versions of java.exe are not found on the PATH. For example, a java.exe could be found in the folder 'C:\Windows\System32'. 27

28 If uninstalling older versions of Java is not desired, the full PATH to the java.exe can be specified in the TeamServerHome\conf\wrapper.conf file, on the line wrapper.java.command=java.exe. 3. Install the service again by typing installservice.bat in the Command prompt. 4. Start the service by typing startservice.bat. 28

29 Appendix B - Using an official HTTPS certificate for the Team Server The Team Server supports working with certificates issued by trusted certificate authorities. BiZZdesign has tested the HTTPS with a JKS and p12/pfx certificate. To ensure your Team Server instance is using a certificate authority issued certificate, the following configuration steps are needed as part of the Team Server configuration. Creating a keystore The Team Server uses Java keystores to configure SSL certificates and keys. Usually, signing authorities provide instructions on how to create a Java keystore. If no such instruction was provided to you, you can find the official Oracle documentation for generating keystores at this website: Once you have successfully created your keystore, you need to configure your Team Server instance to use this keystore. Configuring the HTTPS port To enable HTTPS, open the wrapper.conf file (TeamServerHome\conf folder) in a text editor, locate the section that starts with # Java Additional Parameters, and add the following: Disable the HTTP port by adding the following line: wrapper.java.additional.5 = -Dhttp.port=disabled Choose an HTTPS port you want the Team Server to run on: wrapper.java.additional.6 = -Dhttps.port=443 Specify the path to the keystore containing the private key and certificate, 29

30 if not provided generates a keystore for you. wrapper.java.additional.7 = -Dhttps.keyStore=D://LocationOfCertificate//keystore.jks or wrapper.java.additional.7 = -Dhttps.keyStore=D://LocationOfCertificate//keystore.p12 Enter the password of your certificate: wrapper.java.additional.8 = -Dhttps.keyStorePassword=MyPassword Specify the keystore type. Choose the JKS or PKCS12 certificate: wrapper.java.additional.9 = -Dhttps.keyStoreType=JKS or wrapper.java.additional.9 = -Dhttps.keyStoreType=PKCS12 Save the changes and close the file. Configuring the default baseurl Open the application.conf file (TeamServerHome\conf folder), and replace the default URL by changing the value of to your desired HTTPS URL. For example: application.baseurl=" Save the changes and close the file. 30

31 Contact BiZZdesign Service desk Academy Inside sales Head office Website Customer portal For questions and information regarding service and support. Phone: servicedesk@bizzdesign.com For questions and information regarding training and education. Phone: academy@bizzdesign.com For questions and information regarding commercial conditions, new modules, and prices for use. sales@bizzdesign.com For general questions and information. Phone: info@bizzdesign.com