Server Configuration

In this document you will discover how to manage a Server supporting Collaborative Modeling features.

  1. Server Configuration
    1. Cdo-server.xml File
    2. Authenticated Configuration
    3. User Profiles Configuration
    4. Not Authenticated Configuration
    5. Activate LDAP authentication
      1. Activate LDAP authenticator
      2. Configure LDAP authenticator
      3. Configure LDAP with Active Directory
      4. Configure LDAP with a manager
      5. Use a self-signed or non CA-authentified certificate
    6. Audit mode
    7. Activate SSL connection
      1. Client configuration
      2. Importer configuration
      3. Server configuration
    8. Managing certificate
      1. Generate a keystore
      2. Sign your certificate from a certificate authority(optional)
      3. Export certificate from a keystore
      4. Create a truststore from a certificate
    9. Team for Capella Server Installation Types
      1. Quick Installation (1 Server, 1 Repository)
      2. Configuration with 1 Server, n Repositories, N Models
      3. Configuration with N Servers, N Repositories, N Models (1 Scheduler)
    10. How to Improve Export Performances
    11. Reinitialize database
      1. Restore database from database backup
      2. Restore database from projects backup
    12. How to externalize configuration in a specific folder
    13. How to Change Ports Values
    14. How to Increase the Size of Description and Documentation Columns

Cdo-server.xml File

The main configuration file used by the Team for Capella Server is the cdo-server.xml file.

The Team for Capella Server bundle comes as a standard Eclipse application. In the installed package, locate the Configuration folder and open it.

In this folder, locate the cdo-server.xml file and open it.

Here is a commented extract of the ''‹cdo-server.xml›'' delivered with Team for Capella:

Highlighted elements can be changed to customize the Team for Capella Server.

Note that many repository configuration options can not be changed anymore after the repository has been started the first time or if some data have been exported once to the server. If you need to change something in this configuration afterwards, you should then first delete the database files (files with db extension). A typical example is changing the name of the repository. The only elements you can change in the configuration file afterwards are Type of access control : userManager, securityManager, ldap or none and the acceptor.

Authenticated Configuration

To activate the authenticated server you have to set the line below in the cdo-server.xml file before the <store > tag.
<userManager type="auth" description="usermanager-config.properties"/>

usermanager.properties is a path to the authenticated server configuration file. The path can be absolute or relative to the cdo-server.xml file.

users.file.path=users.properties
# ldap configuration
auth.type=ldap
auth.ldap.url=ldap://127.0.0.1:10389
auth.ldap.dn.pattern=cn={user},ou=people,o=sevenSeas
auth.ldap.filter=
auth.ldap.tls.enabled=false
auth.ldap.truststore.path=
auth.ldap.truststore.passphrase=

users.file.path is the name of the file containing the users. This file has to be copied into the root server installation folder. You can add new users by modifying the users.properties file.
auth.xxx corresponds to the authentication configuration. The properties are prefixed by auth.

The file users.properties contains entries which keys are the logins and values are the passwords. Note that space must be escaped with \ else it will be considered as a key-value separator.
Examples:

admin=admin
			
John\ Doe=secret

Note :
You must not escape spaces in the login field required to connect to remote model (see Connect to remote model section).
The same applies when you create a new user through the "security model" (see Access Control section).

As access control modes are exclusive, other modes must be commented in the cdo-server.xml file:
<!-- <securityManager type="collab" .../> -->
<!-- <authenticator type="ldap" .../> -->

The server must be restarted to take into account the modifications done in the cdo-server.xml file.

User Profiles Configuration

To activate the user profile server you have to set the line below in the cdo-server.xml file before the <store > tag. The user profiles model is created at the first server launch.
Once activated, you must see this during the Team for Capella Server starting:

<securityManager type="collab" realmPath="userprofile-config.properties" />

userprofile-config.properties is a path to the user profile configuration file. The path can be absolute or relative to the cdo-server.xml file.

realm.users.path=users.userprofile
administrators.file.path=administrator.properties
# ldap configuration
auth.type=ldap
auth.ldap.url=ldap://127.0.0.1:10389
auth.ldap.dn.pattern=cn={user},ou=people,o=sevenSeas
auth.ldap.filter=
auth.ldap.tls.enabled=false
auth.ldap.truststore.path=
auth.ldap.truststore.passphrase=

realm.users.path is the name of the resource that contains the user profile model.
administrators.file.path is a path to the administrators file. The path can be absolute or relative to the cdo-server.xml file. This file is only used to initialize administrators in the user profile model during the first start of the repository with the User Profile mode enabled (repository creation for example). It is mandatory because the definition of the user profile can only be done by an administrator.
auth.xxx corresponds to the authentication configuration. The properties are prefixed by auth.

Be aware that once the server has been launched with the User Profile mode enabled, modifications on this file will have no effect. If you want to manage the list of administrators, please have a look at User Pofiles documentation and especially at the Promote a User to Super User section if you want to promote an existing user to administrator. On the other hand, you can also make backups (shared projects and User Profiles model), stop the server, delete the database, modify the administrators files, restart the server and re-export your data.

As access control modes are exclusive, other modes must be commented in the cdo-server.xml file:
<!-- <userManager type="auth" .../> -->
<!-- <authenticator type="ldap" .../> -->

The server must be restarted to take into account the modifications done in the cdo-server.xml file.

Not Authenticated Configuration

This configuration allows to work with a CDO server without authenticating from a client.
Just comment securityManager, userManager and authenticator tags in the cdo-server.xml file:
<!-- <securityManager type="collab" .../> -->
<!-- <userManager type="auth" .../> -->
<!-- <authenticator type="ldap" .../> -->

The server must be restarted to take into account the modifications done in the cdo-server.xml file.

Activate LDAP authentication

Activate LDAP authenticator

You can activate LDAP authentication in three different ways:

The server must be restarted to take into account the modifications done in the cdo-server.xml file.

These ways are excluding themselves.

To activate LDAP authentication, as exclusive authenticator, the following authenticator tag must be added to the repository configuration in cdo-server.xml.

<authenticator type="ldap" description="ldap-config.properties" />

ldap-config.properties is a path to a properties file containing the LDAP authenticator configuration. This path may be relative to the CDO server configuration file or absolute.

As access control modes are exclusive, other modes must be commented in the cdo-server.xml file:
<!-- <userManager type="auth" .../> -->
<!-- <securityManager type="collab" .../> -->

Configure LDAP authenticator

The LDAP authenticator’s configuration file is a properties file whose content could look like the following one:

ldap.url=ldap://127.0.0.1:10389
#ldap.url=ldaps://127.0.0.1:10389
ldap.dn.pattern=cn={user},ou=people,o=sevenSeas
ldap.filter=
ldap.tls.enabled=true
ldap.truststore.path=trusted.ks
ldap.truststore.passphrase=secret

where :

When the LDAP authenticator is used in User Profile or Authenticated configurations, those properties property keys must be prefixed by the auth. and the auth.type=ldap is needed to activate the LDAP authentification.

Important !

Unlike the other two configuration ways (with «user profile server» and «authenticated server»), in the «exclusive authenticator configuration», the properties are not prefixed by auth.

If the LDAP certificate has been signed by an official Certificate Authority it is not required to set the trust store path as the JVM already trusts the CA.

If you need to generate a self-signed certificate or need to create a trust store from an existing certificate please refer to the following section.

Configure LDAP with Active Directory

An LDAP using Active Directory provides a field sAMAccountName that is usually used as a key (like the «cn» field). Users can be identified using this field associated with a domain name after an «@» as separator. This leads to this pattern: sAMAccountName@DomainName. As the user identifies himself by providing only his identifier, not the domain name, the corresponding pattern is: {user}@DomainName.
For instance, if the domain name is «MyCompanyDomain» then the LDAP pattern will be: auth.ldap.dn.pattern={user}@MyCompanyDomain

Configure LDAP with a manager

Some LDAP does not support anonymous binding (if your LDAP server doesn’t even allow a query without authentication), then Capella would have to first authenticate itself against the LDAP server, and Capella does that by sending the «manager» DN and password. Using this specific connection, the user credentials (given by the user in the authentication popup) can be looked for in the LDAP tree.

This manager credentials needs to be provided in the properties file as it will not be asked to the user. These credentials are provided with the following properties:

The search for the user himself in the LDAP is provided with the following properties:

Example of LDAP configuration with a manager

# ldap configuration
ldap.url=ldap://ldap.myCompany.com:389
ldap.user.search.base=dc=myCompany,dc=com
ldap.user.search.filter=(&(objectClass=account)(cn={user}))

# The manager credentials are useful for LDAP requiring authentication to run search filters
ldap.manager.dn=uid=manager,ou=People,dc=myCompany,dc=com
ldap.manager.password=DerfOcDoocs6

ldap.tls.enabled=false

Example of LDAP configuration with a manager and Active Directory

# ldap configuration
ldap.url=ldap://ldap.myCompany.com:389
ldap.user.search.base=dc=myCompany,dc=com
ldap.user.search.filter=(&(objectClass=organizationalPerson)(name={user}))

# The manager credentials are useful for LDAP requiring authentication to run search filters
ldap.manager.dn=manager@myCompany.com
ldap.manager.password=managerPassword

ldap.tls.enabled=false

Use a self-signed or non CA-authentified certificate

In case the certificate is self-signed or the CA used in your certificate is not managed by the jvm, you will need to generate a truststore and reference this truststore from the configuration file.

Follow the Export and TrustStore creation steps to create the trust store.

Audit mode

The Audit mode aims to configure the server so it keeps tracks of all versions of each object in the CDO Server database. It is required for comparing different versions of the model for example.

This is the default mode since Team for Capella 1.3.0.

When using this mode the size of the database might need to be monitored. If the database size grows bigger than 4 GB, the user might need to clear it if he encounters performance issues. That is to say, importing the models from the server, clearing the database and then importing the models back in the new database. Be aware that after doing this operation he will not be able to compare new commits against the commits done before the clearance. Some benchmarks have been done, after 10 000 commits modifying semantic and graphical elements this size have never been reached. In this context, modification and saving model times increase slightly compared to a server that does not have audit mode enabled. However both operations still feel smooth for the user.

Be aware that it is not possible to switch between «Audit» mode and non «Audit» mode on a CDO server that holds models. The switch has to be done on a empty CDO server database.

In order to disable the Audit mode you have to change cdo-server.xml to:

<property name="supportingAudits" value="true"/>
<mappingStrategy type="horizontalNonAuditing"> 
<mappingStrategy type="horizontalNonAuditing">
	...
	<!-- property name="withRanges" value="true"/ -->
</mappingStrategy>

In order to (re-)activate the Audit mode you have to change cdo-server.xml to:

<property name="supportingAudits" value="true"/>
<mappingStrategy type="horizontalAuditingWithRanges"> 
<mappingStrategy type="horizontalAuditingWithRanges">
	...
	<property name="withRanges" value="true"/>
</mappingStrategy>

Activate SSL connection

It is possible to activate a SSL connection between the client and the CDO server.
Both client and server have to be configured accordingly.
On server side a keystore has to be set up and, on client side, a trust store containing the key store public key has to be set up. See chapter Managing certificate to generate keystore and truststore.

Client configuration

Add the following lines in the client eclipse.ini file:

-Dorg.eclipse.net4j.tcp.ssl.passphrase=secret
-Dorg.eclipse.net4j.tcp.ssl.trust=file:///<trusted.ks absolute path>

Importer configuration

When SSL is activated on the server, the importer must be configured accordingly to be successful.
Add the following lines in the client importer.bat file:

-Dorg.eclipse.net4j.tcp.ssl.passphrase=secret ^
-Dorg.eclipse.net4j.tcp.ssl.trust=file:///<trusted.ks absolute path> ^

Server configuration

In the cdo-server.xml configuration file the acceptor has to be configured to accept SSL connections
<acceptor type="ssl" listenAddr="0.0.0.0" port="2036">
Set the acceptor type to ssl.

Add the following lines in the server ini file:

-Dorg.eclipse.net4j.tcp.ssl.passphrase=secret
-Dorg.eclipse.net4j.tcp.ssl.key=file:///<server.ks absolute path>

Managing certificate

Keytool can be used to create and manage certificates and stores. This tool is provided with the JDK and its documentation is available here.

Generate a keystore

The keystore contains certificate information, private and public key. To generate it use the following command:

keytool -genkey -ext SAN=IP:<server IP> -keyalg "RSA" -dname o=sevenSeas -alias keystore_alias -keystore server.ks -storepass secret -validity 730 -keysize 4096

-ext: For example, <server IP> may be the LDAP server for SSL connection between CDO server and LDAP server or may be the CDO Server for SSL connection between client and CDO server.
-dname: optional. It initializes the metadata of your organization.

Sign your certificate from a certificate authority(optional)

This step is optional and you may then proceed with Export certificate from a keystore.
For that step, you have to give your certificate signature request(server.csr) to your certificate authority(CA) which, in return will provide a signed certificate(server.crt).

keytool -certreq  -alias keystore_alias -file server.csr -keystore "server.ks"

The two steps below allow to import root certificate and intermediary certificate.

keytool -import -alias Root_CA -keystore server.ks -file Root_CA.cer
bc. keytool -import -alias Server_CA -keystore server.ks -file Server_CA.cer

Then, import the signed certicated into the server.ks keystore.

keytool -import -alias keystore-signed -keystore server.ks -file server.crt

Export certificate from a keystore

To export a certificate from an existing keystore the following command can be used :

keytool -export -keystore server.ks -alias keystore_alias -file server.cer

This command asks for the store’s passphrase and then create a server.cer file containing the certificate previously created.

Create a truststore from a certificate

It is advised to not export the whole keystore on clients. Creating a truststore containing only the certificate and public key is recommended. This truststore is intended to be deployed on clients which need to connect to the server.

keytool -import -file server.cer -alias keystore_alias -keystore trusted.ks -storepass secret

This command creates a new truststore in file trusted.ks. This truststore contains the server’s public key, it can be copied on client machines and referenced via the truststore.path configuration key.

The truststore is protected with secret as a passphrase.

Team for Capella Server Installation Types

Quick Installation (1 Server, 1 Repository)

Installation process and details are described in the Installation Guide for Team for Capella.

Moreover, do not install any viewpoint except PROPERTIES KEY/VALUES-typed viewpoint. Ask to viewpoint providers whether their viewpoint is compatible with Team for Capella.

If the viewpoint is compatible with Team for Capella, deploy the viewpoint on every Team for Capella client and the importer used by server. Clean and export models again after a viewpoint installation.

Configuration with 1 Server, n Repositories, N Models

Introduction

This is the recommended configuration to work with several projects.

How to Add a New Repository

Hypothesis: the repository is added to a just installed version.

Add a new repository to the Team for Capella Server:

Note the 2 default repositories (content is collapsed in this screenshot),

Notes:

Add a new job to Team for Capella Scheduler (Jenkins) to manage the new repository:

Check the configuration is working: Start the Team for Capella Server using the “Server – Start” job (click on ) and open the TeamForCapella\server\ folder

db and workspace folders should have been created:

Configuration with N Servers, N Repositories, N Models (1 Scheduler)

Introduction

How to Add a New Server

Hypothesis: the server is added to a just installed version, by default it will only contain the default repository “repoCapella”.

  1. Create a new Team for Capella server instance,
    1. Do a copy of the TeamForCapella\server folder to newServer (for example),
    2. Change the server port in the TeamForCapella\newServer\configuration\cdo-server.xml (for example 2037):

  1. Add new jobs to Team for Capella Scheduler (Jenkins),
    1. Launch Jenkins,
    2. Using a web browser, connect to "http://localhost:8036",
    3. The fourth Jobs must be duplicated for the new server,
    4. Create a new job by copying the “Server – Start” job, name it “Start New Server”,
    5. Change the new job’s command:

How to Improve Export Performances

The following line is used to configure the database (in cdo-server.xm):

To improve performances when exporting big models to the repository, change LOG=1 by LOG=0. When exports are done, return to the original value (LOG=1 is useful to avoid database corruptions when the server process is killed).

Reinitialize database

You have three ways to reinitialize data in a database.

Restore database from database backup

The use of the Database – Restore job should be preferred but it is still possible to manually do the same operation.

This operation should be used to restore a database from the file generated by the Database – Backup job (this file has a pattern like: repoCapella.20151105.171109-sql.zip).

The database will be restored in exactly the same state as it was when the backup was performed:

How to manually restore a DB backup

  1. Edit “server.ini” file
  2. Change the vmarg property collab.db.restore to true as follow: -Dcollab.db.restore=true
  3. Specify the backup file location with the -Dcollab.db.restoreFolder parameter (default value is db.restore in the server)
  4. Put the .zip backup file in the specified directory. Example with db.restore:
  1. Stop the server using the Server – Stop job
  2. Start the server using the Server – Start job
  3. If everything went well, you will get a log like the following one in the server’s console:
!ENTRY com.thalesgroup.mde.melody.collab.server.repository.h2 1 0 2020-04-22 18:39:32.409
!MESSAGE Restore repoCapella processing starts.

!ENTRY com.thalesgroup.mde.melody.collab.server.repository.h2 1 0 2020-04-22 18:39:33.977
!MESSAGE Restore repoCapella restored database from : C:\TeamForCapella\server\..\scheduler\jenkins_home\jobs\Database - Backup\builds\7\archive\repoCapella.20200422.182742-sql.zip

!ENTRY com.thalesgroup.mde.melody.collab.server.repository.h2 1 0 2020-04-22 18:39:33.980
!MESSAGE Restore repoCapella processing ends. The file has been moved to C:\TeamForCapella\server\..\scheduler\jenkins_home\jobs\Database - Backup\builds\7\archive\repoCapella.20200422.182742-sql.zip.restored

!ENTRY org.eclipse.emf.cdo.server.db 2 0 2020-04-22 18:39:35.537
!MESSAGE Detected crash of repository repoCapella

!ENTRY org.eclipse.emf.cdo.server.db 1 0 2020-04-22 18:39:35.614
!MESSAGE Repaired crash of repository repoCapella: lastObjectID=OID248, nextLocalObjectID=OID9223372036854775807, lastBranchID=0, lastCommitTime=1 586 948 133 861, lastNonLocalCommitTime=1 586 948 133 86

The .zip backup file will be suffixed by .restored or .error if the restore failed. This behavior can be disabled with the use of -Dcollab.db.restore.rename.source.file=false .

NOTE: Restore process only supports textual script backup with the name that ends with –sql.zip.

If you want to remove restored locking sessions from the database, use the Durable Locks Management view (see the Server Administration part of this documentation).

Restore database from projects backup

This way gives more control on the restoration as you may delete the repository and the repository is restored project by project.
To restore projects in a repository:

How to externalize configuration in a specific folder

Example:

server/server.exe -data C:/data/TeamForCapella/server/workspace

capella/importer.bat -data C:/data/TeamForCapella/server/importer-workspace

capella/command.bat -data C:/data/TeamForCapella/server/command-workspace

Example:

server/server.exe -configuration C:/data/TeamForCapella/server/configuration

capella/importer.bat -configuration C:/data/TeamForCapella/server/configuration

capella/command.bat -configuration C:/data/TeamForCapella/server/configuration

Example:

-vmargs -Dnet4j.config=C:/data/TeamForCapella/server/configuration/cdo-server.xml

Example:

Line 18 : <userManager type=«auth» description="C:/data/TeamForCapella/server/usermanager-config.properties" />

Example:

Line 37 : <dataSource uRL="jdbc:h2:C:/data/TeamForCapella/server/db/h2/capella;LOG=0;CACHE_SIZE=65536;LOCK_MODE=0;UNDO_LOG=0" (…)

Update scheduler/conf/context.xml to change the attribute Environment JENKINS_HOME with the path of the jenkins_home folder :

Example:

-vmargs -Dcollab.db.backupFolder=C:/data/TeamForCapella/server/db.backup

-Dcollab.db.restoreFolder=C:/data/TeamForCapella/server/db.restore

To directly externalize all previous file, you can edit server.ini file

Example: To externalize all files in the folder C:\data\TeamForCapella\server

1) Update server.ini

-console

12036

-data

**C:/data/TeamForCapella/server/workspace **

-configuration

C:/data/TeamForCapella/server/configuration

-vmargs

-Dnet4j.config= C:/data/TeamForCapella/server /configuration

-Dcollab.db.backup=false

-Dcollab.db.restore=false

-Dcollab.db.backupFolder= C:/data/TeamForCapella/server /db.backup

-Dcollab.db.restoreFolder= C:/data/TeamForCapella/server /db.restore

-Dcollab.db.backupFolderMaxSize=1G

-Dcollab.db.backupFrequencyInSeconds=900

-Dosgi.requiredJavaVersion=1.8

-Xms128m

-Xmx2000m

-XX:PermSize=128m

How to Change Ports Values

See Server configuration section → Cdo-server.xml File

See Jenkins configuration section → How to change the port used by scheduler admin site.

By convention we could use 12036 for a server that listens to the port 2036 (defined in cdo-server.xml), 12037 for the server that listens to 2037, 12038 for 2038 etc…

Ex: command.bat localhost 12036 capella_db backup

Ex: command.bat localhost 12036 close

Ex: importer.bat –consoleport 12036 –archivefolder

NOTE: If you have several jobs using the OSGI port value, you can create an environment variable to store it in a single place.

How to Increase the Size of Description and Documentation Columns

When very long text are written in Description or Documentation fields, an error of the following type can occur when saving a remote project or exporting a local project to the server:

[ERROR] org.h2.jdbc.JdbcSQLException: Value too long for column DESCRIPTION VARCHAR

To avoid this problem, change the file server/configuration/cdo-server.xml to use:

<dbAdapter name=”h2-capella” /> instead of <dbAdapter name=”h2” />

Fields description and documentation will be stored in CLOB instead of VARCHAR.

h2-capella is the default value in cdo-server.xml.