In this document you will discover how to manage a Server supporting Collaborative Modeling features.
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. |
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.
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.
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.
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" .../> -->
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 :
<ldap or ldaps>://<IP_address or domain_name>:<port>
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.
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
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:
# 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
# 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
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.
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>
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.
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>
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> ^
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>
Keytool can be used to create and manage certificates and stores. This tool is provided with the JDK and its documentation is available here.
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.
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
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.
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.
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.
This is the recommended configuration to work with several projects.
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:
Hypothesis: the server is added to a just installed version, by default it will only contain the default repository “repoCapella”.
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).
You have three ways to reinitialize data in a database.
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:
!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).
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:
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
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.
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.