Crossing a Firewall Using HTTP Tunneling for 3d com

	Introduction
	The solution exposed in this document is based on HTTP-tunneling technique. HTTP tunneling consists in wrapping application layers (here IIOP messages) in HTTP requests and responses. The main advantage of this technique is that most firewalls may be configured to accept HTTP messages. Unlike the "port redirection only" solution, the provided HTTP-tunneling components imply some performance overhead due to the additional handling of the HTTP protocol semantics. Though, the solution still has no impact on application code and remains easy to deploy and administrate. The proposed global solution is made of four parts (one of which is optional): 1. A tunnel client process that runs on each client host. 2. A specific server-side configuration that will be applied to each client application process to activate the port redirection. 3. A tunnel server process that runs on each server host. 4. An optional genuine HTTP proxy forward or genuine HTTP reverse proxy server
	As far as the server network is concerned, besides the port 80, dedicated to the HTTP protocol by standard, an additional port will be used and must be open on the firewall. By default, this is port 12872, but it can be customized. On this server side, both direct and HTTP-tunneled connections are allowed with the same Orbix daemon. All servers and clients lying inside the firewall can connect to all other servers without HTTP tunneling. On the client side, network security, and especially user authentication, is still managed by the corporate firewall and/or a HTTP proxy server, that enforce rules controlling which client can connect to which server on which port. In particular, the tunnel client component is able to handle authentication challenges from the HTTP proxy server (only base-64 "Basic" authentication is currently supported).
	The HTTP and HTTPS (SSL) Tunneling solutions can now be totally integrated in a traditional Web-oriented network infrastructure. On the server side, this kind of network infrastructure is generally composed of a De-Militarized Zone (DMZ), protected by a first firewall, that hosts servers (Web servers, DNS servers, ...) directly accessible from the Internet. Then a second firewall protects the internal network that hosts back-end servers accessible only from the DMZ. Generally only HTTP port 80 and HTTPS port 443 will be open on the firewalls, hence the need for tunneling non HTTP traffic. As far as Web servers are concerned, in much cases the Web server itself is not present in the DMZ but is located in the internal network and is represented in the DMZ by a Reverse Proxy server. A Reverse Proxy server is the server-side equivalent of a Proxy server: its role is to represent the server from the client point of view just like the Proxy server represents the client from the server point of view. This kind of infrastructure is much more secure and allows features such as load balancing. We will base all the following deployment on the most common and general Web-oriented network infrastructure that may exist on a site wishing to share its servers with the external network. Here is a logical representation of this assumed network topology: As can be seen, we consider three different network domains: the external domain of the client applications, the domain of the DMZ (hosting a Reverse Proxy server in particular), and the internal domain of the server applications. The internal domain cannot be seen from the external domain, only the DMZ domain can. Notice that on the client side, a Proxy server can be deployed but its role does not change the preceding considerations about the network. It is just an optional representative of a client host. We suppose also that each domain comes with its own Domain Name Service (DNS) allowing to locate a network host in this domain from its fully qualified domain name (FQDN). The Reverse Proxy server can be secured or not, that is, be listening on open port 80 and/or 443. If it is secured, SSL protocol requires that it has a valid certificate to be presented to the SSL clients for acceptance. The Reverse Proxy server can in turn connect to the back-end servers using secure protocol or not. In the first case, the back-end servers must have a valid certificate to be presented to the Reverse Proxy server for acceptance. Though this kind of configuration is supported by the current SSL Tunneling solution, we will not deal with it in our example. We will make the simple assumption that the Reverse Proxy server connects to the back-end servers using open HTTP port 80. This avoids managing SSL intricacies on the back end, performance overhead, and so on.
	Client-side deployment The starter process Each client host has to act as a gateway (see CATProxyGateway variable in the server-side section). Actually, the HTTP-tunneling gateway process named "CATHttpTunnelClient" is started by a dedicated process named "CATTunnelStartup." The role of this process is to start and control the lifecycle of the HTTP-tunneling gateway process which is in charge of alternatively wrapping all outgoing IIOP requests into HTTP requests and unwrapping all incoming HTTP responses back to IIOP responses. The process CATTunnelStartup is launched if and only if a configuration variable is properly set on the server side to enable HTTP tunneling (see TunnelingMode variable in the server-side section). The download and launching of the needed components are automatically done when starting 3dcom portal. Hence the deployment of the HTTP-tunneling solution on the client side is almost transparent. However the end user has to be aware that two additional processes will be running on the client machine (i.e. CATTunnelStartup and CATHttpTunnelClient) and eventually the user will have to kill them if something goes wrong with the application (unusual message boxes will appear to the user's attention in such cases).
	Server-side deployment The dedicated Web Server An important thing to note is that, if the tunnel server process is to be running on port 80 instead of the Web server, then the Web server dedicated to the download of 3d com client code must run on any other suitable port. In this case, you have to apply the 3d com administration guide item : "Modifying the HTTP Server Port Default Parameter." Enabling port redirection on the client side For 3d com clients to be able to initiate HTTP tunneling, three variables must be set on the server side in the file corbaProxy.properties located in the directory where the Web server gets the 3d com client code, i.e. <Install Path>/docs/java. The 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): `CATProxify=my3dcomserver` The tunnel server process is to be contacted on port 12872 on a host named "my3dcomserver." This port has to be open on the firewall. The 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 the port number where the tunnel client process will be running (see client-side deployment). Since a tunnel client process must be running on each client host, whose name is not known by the server side, <gateway host> must always be set to "localhost." (Note: "localhost" is a common machine name alias declared by the operating system that always represents the local machine.) Default port is set to 18271 and we recommend to use it to avoid client-side deployment problems (clients will not have to matter about this port when the CATTunnelStartup process will start the tunnel client process with the default arguments) : `CATProxyGateway=localhost:18271` This means that all messages will be redirected to the local client machine on port 18271. In the same file, to avoid the redirection of the true HTTP messages between the clients and the dedicated Web server, a third variable named CATNoProxify has to be valuated to the port the HTTP server is listening to (typically 80): `CATNoProxify=80` Activating the starter process on the client side On the client side, the process CATTunnelStartup is automatically launched if and only if the following variable is properly set in the file config.properties located in the directory <Install Path>/docs/webstarter : `TunnelingMode=http` Configuring the HTTP-tunneling gateway process for the client side The file config.properties also lists the commands that can be launched by the starter process CATTunnelStartup. The tuning of the HTTP-tunneling gateway process itself can be made in the file config.properties. The configuration of the tunneling gateway process itself is made in a dedicated file. 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 eno3dcom001, using this switch, the URL will be /eno3dcom001/cgi-bin/CATHttpTunnelHandler instead of simply /cgi-bin/CATHttpTunnelHandler. Default value=false (no prefix). An example of a customized CATTunnelClient.conf file is given in the summary section.
	The 3d com Server The starter process On all server hosts, 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 tunnel server process which is specifically in charge of alternatively wrapping all outgoing IIOP responses in HTTP responses and unwrapping all incoming HTTP requests back to 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 purpose. 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 SSL 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 SSL 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 SSL server process and have to be customized. There are two kinds of parameters in this file: the general parameters and the security parameters. For HTTP tunneling only general parameters are useful. 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 SSL 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 SSL server process (the default is a HTTP server hosted by the same machine and listening to port 80).IMPORTANT NOTE: these HTTP requests are not to be confused with the regular 3d com application related HTTP requests. `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). An example of a customized CATTunnelServer.conf file is given in the summary section.
	Summary of the overall deployment Example of the overall deployment without any proxy servers Configuring the server host Let's suppose a host named eno3dcom001 located in the internal network of the oem company, with operating system IBM AIX. On this machine, 3dcom 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 3dcom 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. This supposes also that a Web server is installed and configured to work with 3dcom applications, and is running on port 80. Let's say that the 3dcom installation is located in the directory <InstallPath>, which could be something like: `/usr/DassaultSystemes/eno3dcom/aix_a` HTTP Tunneling server process configuration Edit the file <InstallPath>/docs/javaserver/CATTunnelServer.conf to configure the HTTP Tunneling server process. Verify: `secured=false` (Note: you can also adapt the forwardPorts parameter to match the actual port range of the 3dcom servers declared in the Orbix configuration.) 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` Launch the starter process CATTunnelStartup with the following command line: `<InstallPath>/code/command/catstart -run CATTunnelStartup` Check that the Java process is running. HTTP Tunneling client process configuration Edit the file <InstallPath>/docs/java/CATTunnelClient.conf to configure the HTTP Tunneling client process. Verify: `relaySecured=false` Edit the file: `<InstallPath>/docs/java/corbaProxy.properties` to enable port redirection on the client side and set: `CATProxify=eno3dcom001.dmz.com:80 CATProxyGateway=localhost CATNoProxify=80` Edit the file: `<InstallPath>/docs/indexHTTPTunneling.html` and change line: `document.writeln('<param name="portalparam.hostName" value="'+getPortalServerHostname()+'">');` to: `document.writeln('<param name="portalparam.hostName" value="eno3dcom001.dmz.com:1570">');` and line: `document.writeln('<param name="portalparam.codebase" value="http://'+window.location.host+':443'+popdir(window.location.pathname)+'java/">');` to: `document.writeln('<param name="portalparam.codebase" value="http://'+window.location.host+popdir(window.location.pathname)+'java/">');` 3dcom Web server configuration The 3dcom Web server has to act also as a Reverse Proxy server to separate the HTTP messages (intended to itself) from the IIOP over HTTP messages (intended to the HTTP Tunneling server process). The separation is based on the URL of the HTTP messages. We assume that the 3dcom Web server is an Apache server version 1.3.29 or superior installed in directory /usr/local/apache. Make sure that the Web server is compiled with the proxy module enabled: cd /usr/local/apache ./configure --prefix=/usr/local/apache --enable-module=rewrite --enable-shared=rewrite --enable-module=proxy --enable-shared=proxy make make install Then add the following lines in the httpd.conf configuration file: `<IfModule mod_proxy.c> ProxyRequests Off <Directory proxy:> Allow from all </Directory> ProxyPass /cgi-bin/CATHttpTunnelHandler http://eno3dcom001:12872/cgi-bin/CATHttpTunnelHandler ProxyPassReverse /cgi-bin/CATHttpTunnelHandler http://eno3dcom001:12872/cgi-bin/CATHttpTunnelHandler </IfModule>` Finally restart the Apache Web server to account for these new configuration properties. This step ends the configuration of the server host. Configuring the client hosts We suppose that the client machines have Windows for operating system. 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. The HTTP Tunneling client process inherits from the settings of the Web browser as far as Proxy settings are concerned, be this configured manually, or by .ins or *.pac files. However, the user ID and password are not inherited: the user will have to type them twice (for the Web browser first, for 3dcom next). Starting URL configuration To begin a 3dcom client session through a Web browser using HTTP Tunneling, the user has to type the URL: `http://www.dmz.com/enovia_portal/indexHTTPTunneling.html` The Web browser should then ask the user to type his/her Internet user Id and password (to pass the Proxy server), and eventually to type a secondary Internet user Id and password (to pass the Reverse Proxy server). The CATTunnelStartup process will be automatically started by the applet and will control the HTTP Tunneling client process (on Windows, a command console should appear and be minimized in the tool bar: DO NOT CLOSE THIS CONSOLE). The user will have to type his/her 3dcom user ID and password in the logon CATlet, his/her Internet user ID and password again (to pass the Proxy server), and eventually to type his/her secondary Internet user Id and password again (to pass the Reverse Proxy server). From now on, everything should be transparent from the user's point of view.
	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: supplier domain: `enoclient001 192.168.4.3 proxy 192.168.4.2`  oem public domain: `www 192.168.2.2` oem private domain: `eno3dcom001 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. eno3dcom001.oem.com) can only be resolved from the internal network itself and from the DMZ. To permit the client hosts to contact the 3dcom 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 eno3dcom001 192.168.2.2` It is mandatory that the Reverse Proxy and 3dcom servers share the same 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 3dcom messages (both HTTP and IIOP) using the HTTP Tunneling solution: Three network hosts are represented along with the running processes of interest: 1. the client host (running a Web browser, the 3dcom client application, the HTTP Tunneling client process); 2. the bastion host (running a Reverse Proxy server); 3. the server host (running a Web server, the 3dcom server applications, the HTTP Tunneling server process). The Web browser and the HTTP Tunneling client process are speaking to the Reverse Proxy server in HTTP. 3dcom HTTP and 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 back-end Web server in HTTP. All HTTP and IIOP over HTTP messages are sent to this Web server, whatever their URL is. Finally, the Web server plays the role of a Reverse Proxy server: IIOP over HTTP messages (differing from other HTTP messages by their URL) are redirected to the HTTP Tunneling server process which dispatch 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 eno3dcom001 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 eno3dcom001.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 eno3dcom001.dmz.com. On this machine, 3dcom 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 3dcom 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. This supposes also that a Web server is installed and configured to work with 3dcom applications, and is running on port 80. Let's say that the 3dcom installation is located in the directory <InstallPath>, which could be something like: `/usr/DassaultSystemes/eno3dcom/aix_a` Orbix daemon configuration 1. To support that 3dcom 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 = "eno3dcom001";` and in file: `<InstallPath>/startup/orbix/Orbix.cfg` `IT_LOCAL_DOMAIN dmz.com IT_LOCAL_NAME eno3dcom001` Then edit the file /etc/hosts and add eno3dcom001.dmz.com at the end of the server host's IP address line, so that `192.168.1.1 eno3dcom001` should now read: `192.168.1.1 eno3dcom001 eno3dcom001.dmz.com` The Orbix daemon must be restarted to account for its new configuration. Important Notes: 1. This step is not required if the 3dcom 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. 2. This change to the Orbix configuration prevents 3dcom clients located in the internal network to connect to the 3dcom servers. Only external access is possible. HTTP Tunneling server process configuration Edit the file <InstallPath>/docs/javaserver/CATTunnelServer.conf to configure the HTTP Tunneling server process. Change: `secured=true` into: `secured=false` (Note: you can also adapt the forwardPorts parameter to match the actual port range of the 3dcom servers declared in the Orbix configuration.) 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` Launch the starter process CATTunnelStartup with the following command line: `<InstallPath>/code/command/catstart -run CATTunnelStartup` Check that the Java process is running. HTTP Tunneling client process configuration Edit the file <InstallPath>/docs/java/CATTunnelClient.conf to configure the HTTP Tunneling client process. Change: `relaySecured=true` to: `relaySecured=false` Add the lines: `noCONNECT=true relayNoCONNECT=true (for completeness; useless when CATNoProxify=80)` Edit the file: `<InstallPath>/docs/java/corbaProxy.properties` to enable port redirection on the client side and set: `CATProxify=eno3dcom001.dmz.com:80 CATProxyGateway=localhost CATNoProxify=80` Edit the file: `<InstallPath>/docs/indexHTTPTunneling.html` and change line: `document.writeln('<param name="portalparam.hostName" value="'+getPortalServerHostname()+'">');` to: `document.writeln('<param name="portalparam.hostName" value="eno3dcom001.dmz.com:1570">');` and line: `document.writeln('<param name="portalparam.codebase" value="http://'+window.location.host+':443'+popdir(window.location.pathname)+'java/">');` to: `document.writeln('<param name="portalparam.codebase" value="http://'+window.location.host+popdir(window.location.pathname)+'java/">');` 3dcom Web server configuration The 3dcom Web server has to act also as a Reverse Proxy server to separate the HTTP messages (intended to itself) from the IIOP over HTTP messages (intended to the HTTP Tunneling server process). The separation is based on the URL of the HTTP messages. We assume that the 3dcom Web server is an Apache server version 1.3.29 or superior installed in directory /usr/local/apache. Make sure that the Web server is compiled with the proxy module enabled: cd /usr/local/apache ./configure --prefix=/usr/local/apache --enable-module=rewrite --enable-shared=rewrite --enable-module=proxy --enable-shared=proxy make make install Then add the following lines in the httpd.conf configuration file: `<IfModule mod_proxy.c> ProxyRequests Off <Directory proxy:> Allow from all </Directory> ProxyPass /cgi-bin/CATHttpTunnelHandler http://eno3dcom001:12872/cgi-bin/CATHttpTunnelHandler ProxyPassReverse /cgi-bin/CATHttpTunnelHandler http://eno3dcom001:12872/cgi-bin/CATHttpTunnelHandler </IfModule>` Finally restart the Apache Web server to account for these new configuration properties. 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 for anyone. Make sure GZip and Perl are installed and accessible through the commands gzip and perl. Put the following zipped file in directory /usr/src (this software is freely available on the Internet): `apache_1.3.29.tar.gz` Extract in directory /usr/src the required package: `gzip -d -c apache_1.3.29.tar.gz \| tar xvf -` 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 ..` 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 eno3dcom001.dmz.com ErrorLog logs/eno3dcom001.dmz.com-error_log CustomLog logs/eno3dcom001.dmz.com-access_log common <Directory proxy:*> Order deny, allow Allow from all </Directory> ProxyPass / http://eno3dcom001.oem.com/ ProxyPassReverse / http://eno3dcom001.oem.com/ </VirtualHost>` 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 for anyone. Make sure GZip and Perl are installed and accessible through the commands gzip and perl. Put the following zipped file in directory /usr/src: `apache_1.3.29.tar.gz` Extract in directory /usr/src the required package: `gzip -d -c apache_1.3.29.tar.gz \| tar xvf -` 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` 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>` 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 turn into false the related parameters of file <InstallPath>/docs/java/CATTunnelClient.conf that configures the HTTP Tunneling client process: `noCONNECT=false relayNoCONNECT=false` This will significantly increase network performance since the Proxy server will be transparent as far as HTTP protocol is concerned. 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 two or three 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 3dcom 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. 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. The HTTP Tunneling client process inherits from the settings of the Web browser as far as Proxy settings are concerned, be this configured manually, or by .ins or .pac files. However, the user ID and password are not inherited: the user will have to type them twice (for the Web browser first, for 3dcom next). Java configuration Normally a Java Runtime Environment 1.3 is already present on the client host, as well as a Java Plug-in for the Web browser. Refer to the product documentation to learn about these software requirements. We suppose Java is installed in C:\jdk1.3.1_08. Starting URL configuration To begin a 3dcom client session through a Web browser using HTTP Tunneling, the user has to type the URL: `http://www.dmz.com/enovia_portal/indexHTTPTunneling.html` The Web browser should then ask the user to type his/her Internet user Id and password (to pass the Proxy server), and eventually to type a secondary Internet user Id and password (to pass the Reverse Proxy server). The CATTunnelStartup process will be automatically started by the applet and will control the HTTP Tunneling client process (on Windows, a command console should appear and be minimized in the tool bar: DO NOT CLOSE THIS CONSOLE). The user will have to type his/her 3dcom user ID and password in the logon CATlet, his/her Internet user ID and password again (to pass the Proxy server), and eventually to type his/her secondary Internet user Id and password again (to pass the Reverse Proxy server). From now on, everything should be transparent from the user's point of view.