The provided HTTP-tunneling component implies some performance overhead due to the additional handling of the HTTP protocol semantics. Though, it still has no impact on application code and remains easy to deploy and administrate.
Activating this solutions involves the following operations:
- client-side deployment
- a tunnel client process that runs on each client hosts
- a tunnel server process that runs on each server hosts.
Client-side Deployment
Enabling HTTP tunneling
A first variable named CATProxify has to be valuated to a comma-separated list of <hostname>:<tunneling port> to reference all the servers to be contacted behind the firewall through some specified tunneling port numbers. By default, all messages are redirected to port 12872 (not 80).
Examples:
CATProxify=LCA,Vault:12345
ENOVIA V5 VPM and Vault servers are to be contacted respectively on ports 12872 and 12345. These ports have to be open on the firewalls.
CATProxify=LCA:80,Vault:80
ENOVIA V5 VPM and Vault servers are both to be contacted on port 80, which is a commonly open port on firewalls.
In addition, a second variable named CATProxyGateway has to be valuated with a single host / port couple as <gateway host>:<gateway port> to reference the host name and port number where the tunnel client process is running (see below). We strongly recommend that a tunnel client process runs on each client host, so that <gateway host> be always set to "localhost" (this is in particular mandatory to impose individual HTTP proxy authentication). Default port is set to 18271.
Example:
CATProxyGateway=localhost:2222
Means that all messages will be redirected to the local machine on port 2222.
Note: "localhost" is a common machine name alias declared by the operating system to represent the local machine.
According to the client application, two methods exist to set these two variables. For CATIA clients for interoperability, they have to be added to the CATIA runtime environment file using the Environment Editor. For clients, they have to be set in the file corbaProxy.properties located in the directory <Install Path>/docs/java.
The starter process
Each client host has to act as a gateway (see CATProxyGateway variable). Actually, the tunneling gateway process is started by a dedicated process named "CATTunnelStartup." The role of this process is to start and control the lifecycle of the tunneling gateway process which is in charge of alternatively wrapping all outgoing IIOP requests into HTTP requests and unwrapping all incoming HTTP responses back into IIOP responses.
CATTunnelStartup is automatically launched if and only if the following variables are properly set in the runtime environment of the client process:
- CATTunnelingMode=http
- CATTunnelingPropertiesFileName=CATTunnelStartupClient.conf
- CATTunnelingPropertiesFilePath=<Install Path>/docs/java
Note that the file name and the file path properties can be customized and be different from the above default values. However it is mandatory that the file name at least contains the string "Client".
The file name and file path properties point to the provided file CATTunnelStartupClient.conf located in <Install Path>/docs/java. The role of this file is to list the commands to be launched by the starter process CATTunnelStartup.
Configuring the HTTP-tunneling gateway process
The configuration of the tunneling gateway process itself is made in a dedicated file. That's why the command line is not to be modified except to set extra properties specific to the JVM.
The file to configure the HTTP tunneling process is pointed to by two environment variables to set its name and its location on the file system. Both variables are optional. Their default values are listed below:
1. CATProxyPropertiesFileName=CATTunnelClient.conf 2.
CATProxyPropertiesFilePath=<Install Path>/docs/java
The file CATTunnelClient.conf is provided and is located in <Install Path>/docs/java. The content of this file is a series of properties that set the behavior of the HTTP tunneling process and have to be customized. There are two kinds of parameters in this file : the general parameters and the security parameters.
General parameters
We here detail all the general parameters that can be set in the HTTP client process configuration file. You can open it to follow the explanations and to customize it:
<Install Path>/docs/java/CATTunnelClient.conf
listenPort: sets the port the process will be
listening to (default is 18271).
proxyHost and proxyPort: used to
specify the host name and port of the HTTP proxy server if, and only if, it
exists (default is no HTTP proxy server).
proxyAuthorization: provides a credential used to
handle the "Basic" HTTP proxy server authorization challenge. The expected
value is user:password typed in clear. Note that setting this parameter is
not recommended for obvious security reasons. To avoid using this
parameter, a GUI component dedicated to the handling of proxy challenge is
provided. It is automatically started as soon as the user clicks OK in the
logon CATlet. When the tunneling gateway contacts the HTTP proxy server for
the first time, the user is prompted for his / her internet id and password
to safely pass through the HTTP proxy server. This challenge reappears
unless the credentials are validated by the HTTP proxy server. Once the
user has been authorized by the HTTP proxy server, no more challenge occurs
during the login session.
noCONNECT: to be set to true when the HTTP CONNECT
method is not allowed on port set for tunneling by the Proxy server.
Default value: false.
forwardHost and forwardPort:
used to specify the host name and port of the machine hosting the HTTP
server process if, and only if, it is different from the machine hosting
the ENOVIA servers. The default recommendation assumes that the ENOVIA
servers and the HTTP server processes are running on the same machine.
retry and delay: used to specify
the number of tentative reconnections and the delay in seconds between two
tries (default is 10 every 1 second). This parameter can be useful when the
HTTP proxy server is temporarily unavailable.
acceptTimeout: Maximum time in millisecond between
the end of the client application and the end of the Tunneling client
process. Default value=10000.
threadNb: Number of threads started at the beginning
in the pool and also minimum number of threads present at any time in the
pool. Default value=5 (resp. 10).
threadNbMax: Maximum number of threads present in
the pool. Above this limit the jobs are queued waiting for a busy thread to
be freed. Default value=10 (resp. 20).
threadIdleTimeout: Time in millisecond between the
moment at which a busy thread is freed and the moment at which this thread
will be removed from the pool (applicable when there are more than threadNb
threads in the pool). Default value=60000 (resp. 60000).
prefixURL: Tells whether (value=true) or not
(value=false) the URL built by the Tunneling client process should be
prefixed by the name of the back-end server host or not. This feature can
be useful when several servers are to be accessed: based on the value of
the URL, the messages can be directed to the right server host. For example
if we consider a server host named enolca001, using this switch, the URL
will be /enolca001/cgi-bin/CATHttpTunnelHandler instead of
simply /cgi-bin/CATHttpTunnelHandler. Default value=false (no
prefix).
Server-side Deployment
The starter process
On all server hosts where ENOVIA servers are running, a starter process named "CATTunnelStartup" needs to be running. Its role is exactly reciprocal to the role of the client starter process: start and control the HTTP server process which is specifically in charge of alternatively encoding all outgoing IIOP responses and decoding all incoming IIOP requests.
The following variables must be properly set in the environment of the starter process. These variables can be exported in the server environment file whose name is given in <Install Path>/EnvName.txt and location is given in <Install Path>/EnvDir.txt.
- CATTunnelingMode=http
- CATTunnelingPropertiesFileName=CATTunnelStartupServer.conf
- CATTunnelingPropertiesFilePath=<Install Path>/docs/javaserver
Note that the name and the location properties of the file to configure the starter process can be customized and be different from the above default values. However it is mandatory that the file name at least contains the string "Server".
The file CATTunnelStartupServer.conf provided in <Install
Path>/docs/javaserver lists all the commands that can launch the
process CATTunnelStartup. Each command line is solution specific (i.e. iiop,
http). The customer has the possibility to change each command line for
tuning or tracing purposes. However, as far as HTTP is concerned, the
appropriate command line is not to be modified except for eventually
setting up the BOOTCLASSPATH to point to the JSSE implementation (see
client section for an example).
When the environment variables are set, the process CATTunnelStartup have to be started with the "catstart" command such as:
<Install Path>/code/command/catstart -run
CATTunnelStartup
The HTTP server process
The configuration of the HTTP server process itself is made in a dedicated file. That's why the command line is not to be modified except to set extra properties specific to the JVM.
The file to configure the HTTP server process is pointed to by two environment variables to set its name and its location on the file system. Both variables are optional. Their default values are listed below:
1. CATProxyPropertiesFileName=CATTunnelServer.conf
2. CATProxyPropertiesFilePath=<Install Path>/docs/javaserver
The file CATTunnelServer.conf is provided and is located in
<Install Path>/docs/javaserver. The content of this file is a
series of properties that set the behavior of the HTTP server process and
have to be customized. Only one kind of parameters is concerned by http :
the general parameters.
General parameters
We here detail all the general parameters that can be set in the HTTP server configuration file (you can open it to follow the explanations and customize it).
listenPort: sets the port the process
will be listening to (default is 12872).
forwardHost: used to specify the ENOVIA
server host name. This property is optional and blank is recommended since
the ENOVIA servers and the HTTP server processes are running on the same
host.
forwardPorts: used to specify the range
of allowed ports on which the client can contact the ENOVIA servers
(default is the Orbix default range of ports).
webHost and webPort:
used to specify the host name and port of a HTTP server that will handle
any true HTTP requests eventually arriving to the HTTP server process (the
default is a HTTP server hosted by the same machine and listening to port
80).
retry and delay : used to specify the number of tentative reconnections and
the delay in seconds between two tries (default is 10 every 1 second). This
parameter is useful during initialization when ENOVIA servers are not yet
ready to be accessed by their clients.
threadNb: Number of threads started at the beginning in the pool and also
minimum number of threads present at any time in the pool. Default value=5
(resp. 10).
threadNbMax: Maximum number of threads
present in the pool. Above this limit the jobs are queued waiting for a
busy thread to be freed. Default value=10 (resp. 20).
threadIdleTimeout: Time in millisecond
between the moment at which a busy thread is freed and the moment at which
this thread will be removed from the pool (applicable when there are more
than threadNb threads in the pool). Default value=60000 (resp. 60000).
Summary of the Overall Deployment without Proxy
To sum-up the preceding points here is now an example of a typical deployment, going from the server to the client.
Local network
Let's suppose there are two hosts, named "S1" and "S2", and having private IP addresses "IP1" and "IP2" respectively on the local network. On "S1" a ENOVIA V5 VPM server will be running, with Orbix daemon port 1570 and a range of IIOP ports from 1590 to 1790. The logical name "LCA" is given to this server in the Orbix configuration file. On "S2" a Vault server will be running, with Orbix daemon port 2570 and a range of IIOP ports from 2590 to 2790. The logical name "Vault" is given to this server.
Each server environment file is updated to configure the process CATTunnelStartup for the server side (name from <Install Path>/EnvName.txt and location from <Install Path>/EnvDir.txt):
1. CATTunnelingMode=http
2. CATTunnelingPropertiesFileName=CATTunnelStartupServer.conf
3. CATTunnelingPropertiesFilePath=<Install Path>/docs/javaserver
On each host the starter process is launched like this:
ENOVIA V5 VPM:
<Install Path>/code/command/catstart -run CATTunnelStartup
Vault:
<Install Path>/code/command/catstart -run CATTunnelStartup
The files CATTunnelServer.conf are updated to start the process with the following arguments:
ENOVIA V5 VPM:
listenPort=80forwardHost=forwardPorts=1570,1590-1790webHost=webPort=retry=10delay=1secured=false
Vault:
listenPort=80forwardHost=forwardPorts=2570,2590-2790webHost=webPort=retry=10delay=1secured=false
Clients
On the client network, suppose a HTTP proxy server running on a host named "MyHttpProxy," on typical port 8080. This proxy is configured to let go out only authorized users. Moreover it is configured to authorize the CONNECT method on port 80 between the internal network (or a part of it) and IP address "IP0" (this is almost MANDATORY).
For the ENOVIA VPM Product Editor client application, the corbaProxy.properties file is updated like this:
CATProxify=LCA:80,Vault:80
CATProxyGateway=localhost
For the CATIA application, the same variables are exported in the runtime environment. On each client host, before running any application, the process "CATHttpTunnelClient" is configured like this by editing the file CATTunnelClient.conf :
listenPort=18271proxyHost=MyHttpProxyproxyPort=8080secured=false
When beginning an ENOVIA VPM Product Editor client session, besides userID and password, the user types the following server name: "LCA:1570." Moreover, in the VaultClient.properties file, the Vault server host name and daemon port have been set to "Vault" and "2570", respectively.
From now on, everything should be transparent from the client point of view, except for the HTTP proxy server authorization panel, that appears for the user to enter his / her Internet id and password just after login.
Example of the overall deployment with Internet proxy and reverse proxy servers
To make clear the new deployment of the HTTP Tunneling solution, an example of a typical deployment is presented and explained step by step, going from the server side to the client side.
Our purpose is to go from the back end to the front end and see at each step what is required to deploy the HTTP Tunneling solution successfully.
General DNS configuration
Three domains are present on the network:
1. .supplier.com: public domain of the supplier company, managed by a DNS
server in the supplier public network
2. .dmz.com: public domain of the oem company, managed by a DNS server in
the oem public network.
3. .oem.com: private domain of the oem company, managed by a DNS server in
the oem internal network
Here is what could be found in the DNS records of the:
1. supplier domain:
enoclient001 192.168.4.3
proxy 192.168.4.2
2. oem public domain:
www 192.168.2.2
3. oem private domain:
enolca001 192.168.1.1
(We use private addresses 192.168.x.x for illustration purpose only. Of course they are irrelevant in the context of Internet.) FQDN of hosts pertaining to the oem public domain (e.g. www.dmz.com) can be resolved from anywhere in the network. On the contrary, FQDN of hosts pertaining to the oem internal network (e.g. enolca001.oem.com) can only be resolved from the internal network itself and from the DMZ.
To permit the client hosts to contact the ENOVIA V5 VPM servers, the FQDN of the machine hosting the servers MUST be resolvable from the client network. Hence a record has to be added to the public DNS server of the oem company:
- oem public domain:
www 192.168.2.2
enolca001 192.168.2.2
It is mandatory that the Reverse Proxy and
ENOVIA V5 VPM servers share the same
public IP address for the HTTP Tunneling solution to work.
We have added two routers to filter the traffic between the different
networks, hence to play the role of the corporate firewalls. They are not
mandatory for our example: they only ensure that non authorized / direct
traffic occurs between the separated networks. Since there is a lot of
commercial routers, each coming with its own configuration procedure, we
won't delve into the details of their setup. This task is left to the
network administrator.
Overview of the solution
Here follows a schematic representation of what happens to the ENOVIA V5 VPM messages using the HTTP Tunneling solution:
Three network hosts are represented along with the running processes of interest:
1. the client host (running the
ENOVIA VPM Product Editor client application, the HTTP
Tunneling client process);
2. the bastion host (running a Reverse Proxy server);
3. the server host (running the
ENOVIA V5 VPM server applications, the HTTP Tunneling
server process).
The HTTP Tunneling client process is speaking to the Reverse Proxy server in HTTP. ENOVIA V5 VPM IIOP messages are redirected to the HTTP Tunneling client process that eventually handles:
- the Proxy server authentication challenge (optional)
- the Reverse Proxy server authentication challenge (optional)
Then the Reverse Proxy server is speaking to the HTTP Tunneling server process which finally dispatches them to the right applicative server process (in IIOP). We will now detail the configuration of each box.
Configuring the server host
Let's suppose a host named enolca001 located in the internal network of the oem company, with operating system IBM AIX.
This host has a private IP address that can be resolved from the internal network and the DMZ using a DNS lookup on the FQDN enolca001.oem.com. However, as seen in the DNS configuration setup, from a client point of view, this host has also a public IP address (the one of the bastion host) that can be resolved from anywhere using a DNS lookup on the FQDN enolca001.dmz.com.
On this machine, ENOVIA V5 VPM servers will be running: the Orbix daemon will be listening on port 1570 and each applicative server on a port ranging from 1590 to 1789. Hence we start the HTTP Tunneling configuration after a standard ENOVIA V5 VPM installation has been done as explained in the dedicated product documentation. This supposes in particular that a JRE 1.3 be present and correctly installed on the machine.
Let's say that the ENOVIA V5 VPM installation is located in the directory <InstallPath>, which could be something like:
/usr/DassaultSystemes/enoLCA/aix_a
Orbix daemon configuration
1. To support that ENOVIA V5 VPM servers and Reverse Proxy server belong to two distinct domain names, the Orbix configuration has to be modified.
Change the following Orbix parameters in file <InstallPath>/startup/orbix/config/common.cfg:
IT_LOCAL_DOMAIN = "dmz.com";
IT_LOCAL_NAME = "enolca001";
and in the file <InstallPath>/startup/orbix/Orbix.cfg:
IT_LOCAL_DOMAIN dmz.com
IT_LOCAL_NAME enolca001
Then edit the file /etc/hosts and add enolca001.dmz.com at the end of the server host's IP address line, so that:
192.168.1.1 enolca001
should now read:
192.168.1.1 enolca001 enolca001.dmz.com
The Orbix daemon must be restarted to account for its new configuration.
Important Notes:
- This step is not required if the ENOVIA V5 VPM servers and the Reverse Proxy server share the same domain name, for example oem.com. The Orbix configuration set up during a standard installation is sufficient in that case.
- This change to the Orbix configuration prevents ENOVIA VPM Product Editor clients located in the internal network to connect to the ENOVIA V5 VPM servers. Only external access is possible.
HTTP Tunneling server process configuration
2. Edit the file <InstallPath>/docs/javaserver/CATTunnelServer.conf to configure the HTTP Tunneling server process.
Change:
listenPort=12872
to:
listenPort=80
(Note: you can also adapt the forwardPorts parameter to match the actual port range of the ENOVIA V5 VPM servers declared in the Orbix configuration.)
3. Set the three environment variables CATTunnelingMode, CATTunnelingPropertiesFileName, and CATTunnelingPropertiesFilePath in the file whose name is given in <InstallPath>/EnvName.txt and location is given in <InstallPath>/EnvDir.txt:
CATTunnelingMode=http
CATTunnelingPropertiesFileName=CATTunnelStartupServer.conf
CATTunnelingPropertiesFilePath=<InstallPath>/docs/javaserver
4. Launch the starter process CATTunnelStartup with the following command line:
<InstallPath>/code/command/catstart -run CATTunnelStartup
Check that the Java process is running.
This step ends the configuration of the server host.
Configuring the bastion host
In this section we illustrate the installation and the configuration of a Reverse Proxy server. We assume that this server is an Apache server. As already stated, these steps are intended to anyone
1. Make sure GZip and Perl are installed and accessible through the
commands gzip and perl.
2. Put the following zipped file in directory /usr/src (this software is
freely available on the Internet)
apache_1.3.29.tar.gz
3. Extract in directory /usr/src the required package:
gzip -d -c apache_1.3.29.tar.gz | tar xvf -
4. Build the Apache Web server:
1. cd apache_1.3.29
2. ./configure --prefix=/usr/local/apache --enable-module=rewrite --enable-shared=rewrite --enable-module=proxy --enable-shared=proxy
3. make
4. make install
5. cd ..
5. Configure the Apache Web server with the virtual host feature.
Edit the Apache configuration file /usr/local/apache/httpd.conf and add the following lines:
<VirtualHost *:80>
ServerAlias enolca001.dmz.com
ErrorLog logs/enolca001.dmz.com-error_log
CustomLog logs/enolca001.dmz.com-access_log common
<Directory proxy:*>
Order deny, allow
Allow from all
</Directory>
ProxyPass / http://enolca001.oem.com/
ProxyPassReverse / http://enolca001.oem.com/
</VirtualHost>
6. Restart the Apache Web server:
/usr/local/apache/bin/apachectl restart
Note: the Reverse Proxy server can be configured to issue an authentication challenge to the end user using HTTP code 401. In that case, the HTTP Tunneling client process will prompt the user for an ID and password (the so-called Basic authentication is the only supported scheme).
This step ends the configuration of the bastion host.
Configuring a Forward Proxy server (optional)
In most companies, Proxy servers are present to allow end users to go outside the internal network. We illustrate here the installation and the configuration of a Proxy server. It will be configured to issue an authentication challenge to the end user using HTTP code 407. In that case, the HTTP Tunneling client process will prompt the user for an ID and password (the so-called Basic authentication is the only supported scheme). We assume that this server is an Apache server. As already stated, these optional steps are primarily intended to anyone
1. Make sure GZip and Perl are installed and accessible through the
commands gzip and perl.
2. Put the following zipped file in directory /usr/src:
apache_1.3.29.tar.gz
3. Extract in directory /usr/src the required package:
gzip -d -c apache_1.3.29.tar.gz | tar xvf -
4. Build the Apache Web server:
1. cd apache_1.3.29
2. ./configure --prefix=/usr/local/apache --enable-module=rewrite --enable-shared=rewrite --enable-module=proxy --enable-shared=proxy
3. make
4. make install
5. Generate user ID and password for Basic authentication (replace <UserID> and <UserPwd> with actual values):
1. mkdir passwd
2. cd bin
3. ./htpasswd -c /usr/local/apache/passwd/passwords <UserID>
htpasswd will ask for a password, and ask it twice for confirmation:New password: <UserPwd>
Re-type new password: <UserPwd>
6. Configure Apache Web server with authentication and cache features:
Edit the Apache configuration file /usr/local/apache/httpd.conf and edit / add the following lines:
ServerName proxy.supplier.com
<IfModule mod_proxy.c>
ProxyRequests on
ProxyVia On
<Directory proxy:*>
Order deny, allow
Allow from all
AuthType Basic
AuthName "My supplier realm"
AuthUserFile /usr/local/apache/passwd/passwords
require valid-user
</Directory>
</IfModule>
CacheRoot "/usr/local/apache/proxy"
CacheSize 5
CacheGcInterval 4
CacheMaxExpire 24
CacheLastModifiedFactor 0.1
CacheDefaultExpire 1
Note: if the HTTP CONNECT method is to be allowed on port 80 (using the Apache directive AllowCONNECT 80 in the above httpd.conf file) then you can set to false the related parameter of file <InstallPath>\docs\java\CATTunnelClient.conf that configures the HTTP Tunneling client process (see Configuring the client hosts section below):
noCONNECT=false
This will significantly increase network performance since the Proxy server will be transparent as far as HTTP protocol is concerned.
7. Restart the Apache Web server:
/usr/local/apache/bin/apachectl restart
This step ends the configuration of the optional Proxy server host.
Important Note: To reduce the overhead introduced by HTTP protocol, HTTP Tunneling uses the Keep-Alive feature of HTTP/1.1, that is it reuses the same TCP connection to send several messages. But as seen in the current deployment of the solution, on the path from the client host to the server host, there can be at least one or two Web servers. These Web servers can be configured to restrict the number of messages that can be send on the same TCP connection before closing it (for Apache Web server the parameter to tune is MaxKeepAliveRequests). In some scenarios (when downloading huge or numerous models for example), it is possible that the number of messages exceeds this limit and the tunnel gets broken. Hence be sure that MaxKeepAliveRequests or equivalent be as high as possible on each traversed Web server to avoid such a shortcoming. Alternatively, the packet size of the ENOVIA V5 VPM messages can be increased so that:
sizeof( all data to download at once ) / (packet size) <= min( all
traversed MaxKeepAliveRequests )
Configuring the client hosts
We suppose that the client machines have Windows for operating system. We start the HTTP Tunneling configuration after a standard ENOVIA V5 VPM installation as explained in the dedicated product documentation. Let's say that the ENOVIA V5 VPM installation is located in the directory <InstallPath>, which could be something like:
C:\Program Files\Dassault Systemes\enoLCA\intel_a
C:\Program Files\Dassault Systemes\enoLCA\win_b64
Proxy configuration
On the client network, we suppose that the Proxy server described above is running on a host named proxy and is listening to port 8080. This Proxy server is configured to let go out only authorized users with valid user ID and password.
HTTP Tunneling client process configuration
1. Edit the file <InstallPath>\docs\java\CATTunnelClient.conf to configure the HTTP Tunneling client process. Add the lines:
noCONNECT=true
proxyHost=proxy.supplier.com
proxyPort=8080
2. Set the three environment variables CATTunnelingMode, CATTunnelingPropertiesFileName, and CATTunnelingPropertiesFilePath in the file whose name is given in <InstallPath>\EnvName.txt and location is given in <InstallPath>\EnvDir.txt:
CATTunnelingMode=http
CATTunnelingPropertiesFileName=CATTunnelStartupClient.conf
CATTunnelingPropertiesFilePath=<InstallPath>\docs\java
3. Edit the file <InstallPath>\docs\java\corbaProxy.properties to enable port redirection on the client side and set:
CATProxify=enolca001.dmz.com:80
CATProxyGateway=localhost
When beginning a ENOVIA VPM Product Editor client session, the user has to type the server name and port as:
enolca001.dmz.com:1570
The CATTunnelStartup process will be automatically started by the ENOVIA VPM Product Editor client application and will control the HTTP Tunneling client process. The user will have to type his/her ENOVIA V5 VPM user ID and password in the logon CATlet, his/her Internet user ID and password (to pass the Proxy server), and eventually to type his/her secondary Internet user Id and password (to pass the Reverse Proxy server). From now on, everything should be transparent from the user's point of view.
