Before Starting the Installation

Service Endpoints

Before you start the installation, each service can have previously configured, dedicated URL endpoints. These are examples of service endpoints, comprising a service name and a domain name:

3dlicencing.mydomain.com

3dpassport.mydomain.com

3ddashboard.mydomain.com

untrusted.3ddashboard.mydomain.com

3dsearch.mydomain.com

3dspace.mydomain.com

3dspace.mydomain.com/{webapp_name}

fcs.3dspace.mydomain.com

3dswym.mydomain.com

HTTPS and Certificates

To be accepted by the 3DEXPERIENCE platform servers, the certificate CN must be equal to the full server URL (i.e. 3dpassport.mydomain.com) or to a domain with a wildcard (i.e. *.mydomain.com). The certificate expiry date must also of course be in the future.

The certificate comprises two parts:

• the (public) certificate itself, needed to be understood by all clients and servers of the platform
• and the (private) key, which is needed only for the reverse proxy.

Certificates can be obtained from any certificate creation public authority, or, if you have your own authority, generated and signed by this authority. Do not use self signed certificates. Firefox (since version 55) and Chrome-based browsers (since version 80), block them.

You can generate certificate requests and transmit them to your administrator or provider. For more information see Set Up Certificates of each service installation guide.

If you are deploying 3DSpace on an application server which relies on its native java, you must import certificates on the native java as well.

Reverse Proxy and Load Balancers

Connection to all 3DEXPERIENCE platform services is done via https protocol for security reasons. In order for the application to be contacted by its clients, a set comprising reverse proxy (for ending https calls) and load balancer (for high availability) should be cascaded between the client and the application server for the service. These two functions may be achieved by the same component.

The reverse proxy, apart from securing the communication between the client (or other servers) and the application, also sets some headers to allow CORS capabilities between elements of the platform. Configurations for apache2.4 are built during the service installation process and can be found at:

<install_dir>/<os>/templates/<service_name>_http_fragment.conf[.txt]

They can easily be translated into configurations for other reverse proxy technologies.

All load balancers should be configured to conserve the sessions using cookies and a parameter value (see examples given for some load balancers). See the installation documentation for each service for more details.

There are several different possibilities:

• all the different services may be installed either on different machines, or on the same machine
• you can have a different reverse proxy for each service, but all the different services may also use the same reverse proxy
• all the different services may use different HTTPS ports, or the same port.
  Note: Typical examples are the case of a DMZ setup, or security limitations on open ports.

The case where the services are set up using the same virtual host, on the same / uri (without a different path for each service) is not possible in a single httpd.conf configuration file with only one domain.

Note that the fragments for each service are isolated in a location container, allowing them to be used on the same Apache HTTPD server on the same port.

Add all templates into one HTTPD configuration file within a single correctly configured ssl Virtualhost. For more information, see the section "Configuring the Reverse Proxy" in each service installation guide.

Machines

Physical or virtual machines can be used except for licensing using the DS License Server (DSLS) which needs physical machines unless you use the following specific implementations:

• Managed Licensing Service: For Licensing, you can also adopt the Managed Licensing Service which is a highly available license server managed by Dassault Systèmes. Dassault Systèmes performs all mandatory license server administration tasks (for example, license key enrollment), but certain operations are still authorized using the locally installed license administration tool.
• you can run Managed Licensing Service administration tasks using the licensing service administration web user interface
• Setting Up a Virtualized DS License Server Failover Cluster Using Hyper-V on Windows Server 2016: The Hyper-V role in Windows Server lets you create a virtualized computing environment where you can create and manage virtual machines. It can be used to create and run a virtualized DS License Server.

On Linux make sure /usr/tmp folder exists in write access before launching the 3DSpace installer.

Internet Access

Internet access is mandatory in the following cases:

• on all machines if the Managed Licensing Service is used, since the service is stored on the Dassault Systèmes site.
• on all 3DDashboard machines to enable certain apps (such as Feed Reader, Run your app) to access external data.

Firewall settings

The TCP (HTTPS) protocol must be allowed from all machines to the DS License Server typically on port 4085, or another port number if the DS License Server is configured to listen to a non-default port number.

We recommend that you update firewall settings to accommodate non-default ports, if chosen for all services.

Shared Directory

Almost all services need a shared directory to store data:

• always keep the data directories in a common path managed by mount (generally used Linux), NAS (Network Attached Storage) or shared directory (in Windows) having read/write/execute access.
• this method is particularly useful when large amounts of data need to be saved, and also facilitates management of a load balanced environment.

Configuration information shared between services

Configuration information is also shared between services.

We also recommended that you set up a shared configuration directory in a common path managed by mount (generally used Linux), NAS (Network Attached Storage) or shared directory (in Windows) having read/write/execute access for all services including reverse proxies and load balancers.

It should contain the following elements:

• certificates (.cer (or .crt))
• cypher key for 3DPassport
• TNSNames.ora directory.

Databases

For each service, refer to Microsoft documentation for connecting with encryption to SQL Server.

For more information, see the Preparing the installation section of each service.

Application Servers

Note that EACH SERVICE requires a dedicated, separate application server: the services cannot share the same application server. If the embedded Server JRE is not selected at installation, the setenv.bat/.sh file must be updated with the variable JAVA_HOME for each application server.

User IDs

Throughout the installation, whenever you are prompted to create users, all userids must be created in lowercase. This limitation does not apply to other user information in user profiles such as first and last names, addresses, etc.

Furthermore, spaces are NOT allowed in userids.

Users should be created in both 3DPassport and 3DSpace, in that order, with the same userid that should never be changed, and then synchronized with the rest of the platform. So it is critical that all services be up and running when a new user is created.

There are two methods for creating users:

• without LDAP: a user can create an account directly using the 3DPassport service. There is no security risk as the user has, at that moment, no access to any service or application (beyond managing the account information).
• with an Enterprise Information System such as LDAP.

admin_platform must be the administrator of the 3DSpace server. The admin_platform user is created when installing 3DSpace, and also has administration rights.

If you are migrating from V6R2014x or earlier, users should be created with user IDs with the same case as 3DSpace user IDs.

Migrate Existing Users Created in an Earlier Release explains how to import these users in batch mode.

Timezone

For all servers, set the time zone to UTC (Coordinated Universal Time).

On Windows, configure the system date and time to use UTC (Coordinated Universal Time) as the time zone.

On Linux, configure the system time zone to UTC. To do so, run for instance the following command:

ln -s /usr/share/zoneinfo/UTC /etc/localtime

Clock synchronization

You must ensure that all clocks on all servers are synchronized using technology such as NTP synchronization.

Mail Server Configuration

Certain service instances require a local mail server to send mail to users. Consequently, you must configure each mail server.

A mail sender name is required for each service for the following reasons:

• 3DPassport: password recovery (not available for user passwords if connected to enterprise SSO/LDAP), notifications on security (if activated)
• 3DDashboard: sharing of dashboards (invitation/copy), tabs (copy) and widgets (copy)
• 3DSpace: sends invitations to members to join the platform (and creates users if not performed by the administrator in batch mode)
• 3DSwym: social notifications.

Batch Authentification

Certain internal services do not support 3DPassport CAS authentication, consequently they must be configured with a NO-CAS authentication on a dedicated TomEE application server on the 3DSpace side, set with a dedicated mxEnv.sh configuration file (for more details, see the dedicated section in the 3DSpace administration documentation).

List of services communicating with DSLS Server

Service	Communication to DSLS Server	Roles
3DPassport	No	NA
3DSpace (MCS)	Yes	Collaborative Business Innovator (IFW) is the minimal license needed to use the 3DEXPERIENCE platform. The 3DSpace apps are available within the Collaborative Industry Innovator (CSV) role, CSV is the pre-requisite for all the Governance & Engineering related roles. The administrator created by the installation (admin_platform) is granted automatically an IFW and an CSV license.
3DSpace File Collaboration Server(FCS)	No	NA
3DSpace Index (File Converter)	No	NA
3DSearch (Federated Search)	No	NA
3DSpace Index	No	CV (Cloud View) licensing is managed with a file delivered with the installer. No DSLS specific license is required in that case.
3DIndex Server (only build 2D/3D thumbnails)	No	NA
3DDashboard	Yes	IFW is required on DSLS Server.
3DComment	Yes	IFW is required on DSLS Server.
3DSwym Foundation	Yes	IFW is required on DSLS Server.
3DSwym Video Converter	No	NA
3DSwym Index + EXALEADCloudView	Yes	IFW is required on DSLS server for 3DSwym Index. CV (Cloud View) licensing is managed with a file delivered with the installer. No DSLS specific license is required in that case.
3DNotification	Yes	IFW is required on DSLS Server.

Load Balancing Recommendations

Load balancing multiple instances of each 3DEXPERIENCE platform service is recommended for production environments, for availability, scalability and performance.

All services supporting access through load balancing must comply with the following constraints:

• Session affinity is performed through cookie injection (a cookie is set for each client, identifying the affected node and reading this cookie value will enable traffic to be directed to the same node), and per URL.
• For calls that do not have Cookies:
  • For OPTION call: do not set any Cookie (just set CORS headers and return 200, see reverse proxy configuration for content)
  • For all other calls: Set the cookie with the Node ID, and set the x-dsp-client-node header with the same Node ID
• Health-checking through HTTP calls.

Standard First request:

OPTION request:

Standard other request (not OPTION, not first):

In compliance with these constraints, here is an example of a load balancing configuration using haproxy (behind an independent reverse proxy).

global
  log 127.0.0.1 syslog notice
  option httplog        
  maxconn 4000

defaults
  log global
  option tcplog
  option forwardfor 
  timeout connect 5000
  timeout client 50000
  timeout server 50000
  option http-server-close

frontend http-in  
  bind *:{inbound port}  
  mode http  
  capture cookie SERVERID len 100
  default_backend Service_All

backend Service_All  
  balance roundrobin  
  mode http  
  cookie SERVERID insert indirect nocache secure httponly 
 #for all services except 3DSpace :  
  option httpchk OPTIONS /{Service uri}//healthcheck/ HTTP/1.0 
 #for 3DSpace : 
 # option httpchk OPTIONS /enovia/ HTTP/1.0  
  http-send-name-header x-dsp-client-node         
 # List of servers  
  server Front_0 {server0 IP}:{tomee port} cookie Front_0 check  
  server Front_1 {server1 IP}:{tomee port} cookie Front_1 check

For the configuration of HAProxy specific to 3DDashboard, the following line should be added:

option httpchk OPTIONS /<3DDashboardUri>/ HTTP/1.0\r\nHOST:\ <3DDashboardHostname>

If you add an URL for 3DDashboard like this: https://domain.com/custom3dd in the URL dialog box, the values are:

<3DDashboardUri>: custom3dd
<3DDashboardHostname>: domain.com

If you add an URL for 3DDashboard like this: https://domain.com in the URL dialog box, the values are:

<3DDashboardUri>: 3ddashboard
<3DDashboardHostname>: domain.com

Another example: For hardware load balancer BigIP from F5, an iRule can be designed to set the x-dsp-client-node header, beside a Cookie-based configuration. An example of the part of this iRule setting the header could be:

when LB_SELECTED {
     #following 3 lines could determine persistence cookie name being
       used if not manually set in the RULE_INIT section
     #if {not [info exists cookie_name]} { 
     #    if { [set cookie_name [PROFILE::persist mode cookie
      cookie_name]] eq "" } { set $cookie_name
     "no_cookie_persist_but_nevermind" } 
     #}
     #Next function is here to forge the persistence cookie value when
      it doesn't exist yet (because it's the first hit)
             if { [set COOKIE [HTTP::cookie value $cookie_name]] == "" } {
                 scan [LB::server addr] {%d.%d.%d.%d} a b c d 
                 #Forging the cookie value based on sol6917  
                 set ADDR [expr { $a + $b * 256 + $c * 65536 + $d * 16777216 }]
                 set PORT [ntohs [LB::server port]] 
                 set COOKIE "${ADDR}.${PORT}.0000"
                 #log local0. "$cookie_name = $COOKIE created for [HTTP::uri]"
                 unset a b c d ADDR PORT 
             } 
             HTTP::header insert "x-dsp-client-node" $COOKIE
} 

Native Apps (CATIA) use headers. Here is the list of headers to be kept on the RP / LB chain. During Operations like CATIA open, xmql queries are sent to the server with:

with Accept-Encoding: SIDL, gzip, deflate
with Content-Encoding: application/octet-stream

Certain load balancers are configured to modify these headers leading to errors.

The diagram below explains session affinity in more detail.

X-Forwarded-proto transfers data about the protocol used upstream from the load balancer, HTTPS in this case. This rebuilds dynamically the URL of the service called, to be later provided to 3DPassport when redirecting to the login page or validation ticket.

The X-Forwarded-proto header does not need to be set on the 3DPassport side, only on the services side. Setting it now does not cause any problems, above all if the same rule is used for all and the load balancer is shared by all the services, including 3DPassport.

Load request filter load balancing

Follow this procedure to enable session affinity required for callbacks sent by 3DPassport to the other services of the 3DEXPERIENCE platform.

1. Configure Apache HTTPD.

   For example, for 3DSpace:

   ProxyHCExpr is_ok {hc('body') =~ /ok/}
   ProxyHCExpr hcx200 {%{REQUEST_STATUS} =~ /^[2]/}
   ProxyHCTemplate hctSpace hcmethod=GET hcinterval=5 hcpasses=1 hcfails=1 hcuri=servlet/fcs/ping hcexpr=hcx200
   
   <Proxy "balancer://spaceCluster">
           BalancerMember "http://rdy2space.dsone.3ds.com:9080/3dspace" route=space1 timeout=5 connectionTimeout=3 hctemplate=hctSpace
           BalancerMember "http://rdy2space.dsone.3ds.com:9180/3dspace" route=space2 timeout=5 connectionTimeout=3 hctemplate=hctSpace
           BalancerMember "http://rdy2space.dsone.3ds.com:9280/3dspace" route=space3 timeout=5 connectionTimeout=3 hctemplate=hctSpace
           ProxySet stickysession=SERVERID
   </Proxy>
   <Location "/3dspace">
           RequestHeader set X-Forwarded-Proto "https"
           RequestHeader set X-Forwarded-Port "443"
           RequestHeader set x-forwarded-contextpath /3dspace
           Header add Set-Cookie "SERVERID=SPACE.%{BALANCER_WORKER_ROUTE}e; path=/3dspace" env=BALANCER_ROUTE_CHANGED
           ProxyPass "balancer://spaceCluster" nofailover=on
           ProxyPassReverse "balancer://spaceCluster"
   </Location>        
   

   For example, for Federated Search balancerMember:

   BalancerMember http://rdy2search.dsone.3ds.com:8080/federated route=fed1 timeout=5 connectionTimeout=3 hcmethod=OPTIONS hcuri=manager?query=monitoring hcexpr=hcx200 hcinterval=5

2. Enable NodeRequestFilter:

   Modify the WEB-INF/web.xml of 3DSpace/FedSearch/… to declare the new filter.

   <filter>
   	<filter-name>NodeRequestFilter</filter-name>
   	<filter-class>com.dassault_systemes.apache.util.NodeRequestFilter</filter-class>
   	<!-- <init-param>
   		<param-name>jvmRoute</param-name>
   		<param-value>fed1</param-value>
   	</init-param>
   	<init-param>
   		<param-name>cookieName</param-name>
   		<param-value>SERVERID</param-value>
   	</init-param> 
   	<init-param>
   		<param-name>stickySessionSep</param-name>
   		<param-value>.</param-value>
   	</init-param> -->
   </filter>
   <filter-mapping>
   	<filter-name>NodeRequestFilter</filter-name>
   	<url-pattern>/*</url-pattern> 
   </filter-mapping>
   

   Note: NodeRequestFilter must be added BEFORE existing CAS filters (Authentication, Validation, etc.)
3. Specify NodeRequestFilter parameters.
   Note: The only required parameter is jvmRoute. Failure to provide jvmRoute will prevent service start-up (throws servlet exception).

   All parameter values can be supplied by either:

   • Filter init-param
   • Environment variables
   • –D or conf/catalina.properties
   • conf/server.xml - Engine jvmRoute attribute.
   jvmRoute=”${jvmRoute}” will use either –D or property with same name.

   Default parameter values:

   • cookieName = SERVERID
   • stickySessionSep =
   Note: cookieName and stickySessionSep values can be changed by any method except for server.xml change.

   Preference for which parameter values are used by Filter (as currently written):

   • server.xml Engine jvmRoute attribute takes precedence
   • –D or properties file
   • Environment variables
   • Filter parameters.
   jvmRoute value must match the Apache BalancerMember route= VALUE for the specific 3DEXPERIENCE service.

4. Enforce testing failures in the load balanced environment (negative testing):
   • Set all nodes to the same jvmRoute (e.g. jvmRoute=(null)). Using (null) is equivalent to existing Apache recommended directives for setting x-dsp-client-node value on initial service requests.

     or

   • Set one of the 3dspace nodes as jvmRoute=FAIL
5. Log in using logback.xml:

   <appender name="NodeFilter" class="ch.qos.logback.core.ConsoleAppender">
       <encoder>
         <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
       </encoder>
     </appender>
   
      <logger name="com.dassault_systemes.apache.util" level="DEBUG">
           <appender-ref ref="NodeFilter" />
       </logger>
   

Service healthcheck

You can check services status by opening the following URLs in your browser.

• 3DPassport: https://<hostname>:<port>/<URI>/healthcheck
• 3DDashboard: https://<hostname>:<port>/<URI>/test-alive
• 3DSearch: https://<hostname>:<port>/federated/manager?query=monitoring
• 3DSpace: https://<hostname>:<port>/<URI>/servlet/fcs/ping
• 3DCompass: https://<hostname>:<port>/<URI>/servlet/fcs/ping
• 6WTags: https://<hostname>:<port>/<URI>/servlet/fcs/ping
• 3DComment: https://<hostname>:<port>/<URI>/monitoring/healthcheck
• 3DNotification: https://<hostname>:<port>/<URI>/healthcheck
• 3DSwym: https://<hostname>:<port>/<URI>/monitoring/healthcheck
• FileCollaboration: https://<hostname>:<port>/<URI>/servlet/fcs/about