Home

5. Protocol Proxy

EME Community Edition 1.1.0


4. Managed File Transfer

Table of Contents

6. EME




5. Protocol Proxy


  • Protocol Proxy has two web front ends, one for adminstrators (http://localhost/proxy-admin) and one for trading partners (http://localhost/proxy-portal)
  • You MUST set JAVA_HOME to be able to start Protocol Proxy
  • Protocol Proxy uses two ports (HTTP:80, FTP:21) that require either Administrator or root access to start properly. You may need to contact your System Administrator to acquire the proper permissions.
  • Protocol Proxy internally is broken down into different parts; all of the log files are in the following location:
      {BIT_EME_CE_HOME}/protocol-proxy-ce-{version}/bin
  • Protocol Proxy is run as a background process, so to shutdown you need to run a script. Please reference the Stop Protocol Proxy section for details.
  • Protocol Proxy runs in the Apache Tomcat container. If you have another default install of Tomcat running on your system, you may have problems with start and stop scripts. It will require you to change some administration ports in one of your Tomcat installs.


5.1. Start Protocol Proxy


  • Verify that you have Administrator privileges, root access or have proper sudo privileges
  • Open a command prompt or terminal and change directories:
      {BIT_EME_CE_HOME}/protocol-proxy-ce-{version}/bin


5.1.1. Windows Command


  • You may receive a security warning about opening ports, make sure you allow access.
      startup.bat


5.1.2. Linux / Unix Command


  • If you are root, type:
      ./startup.sh
  • Otherwise type:
      sudo ./startup.sh


5.2. Stop Protocol Proxy


Protocol Proxy runs as a background process so you must run a shutdown script.

Open a command prompt or terminal and change directories:

    {BIT_EME_CE_HOME}/protocol-proxy-ce-{version}/bin


5.2.1. Windows Command


    shutdown.bat


5.2.2. Linux / Unix Command


    ./shutdown.sh


5.3. Advanced Setup



5.3.1. Public Internet Setup


We do NOT recommend deploying Protocol Proxy in its default state to the DMZ for public access. Protocol Proxy was developed as separate web apps (WARs) that can be deployed in separate containers, so that you can apply strict firewall rules for which ports can be accessed publicly and privately. If everything is deployed in a single web container and the public internet is given access, you risk over-exposure of the internal database and administrative screens. While they are protected by usernames and passwords, you can increase your security by not allowing outside access to them directly.


5.3.1.1. Public Web Apps


- ftp.war: Public FTP Server 
- httpproxy.war: Public HTTP/S REST Web Services
- proxy-portal.war: Public Web Portal for uploading and downloading files
- emailproxy.war: Public HTTP/S Servlet that takes an HTML FORM POST; creates and stores xml
- ROOT.war: Public static web content, such as javascript and images


5.3.1.2. Private Web Apps


- emeproxy.war: Private Admin HTTP/S REST Web Services; Allows EME to push/pull messages for all users
- proxy-admin.war: Private Admin Web Portal, for administering Trading Partners and uploading / downloading messages
- proxy-db.war: Protocol Proxy internal encrypted database used for storing user information and messages


5.3.1.3. Preferred Setup


We suggest installing two Apache Tomcat instances in the DMZ. One should contain the Public Web Apps that runs on port 80 and is exposed via firewall rules for the public. Install the Private Web Apps in the other Tomcat instance running on a non-standard port (ex: 8080), exposed only for traffic originating from inside the corporate firewall.


5.3.1.4. FTP Firewall Rules


Exposing FTP securely requires additional firewall rules. The default communication port for FTP is port 21, however FTP also uses random ports in the Dynamic Port Range for short periods of time for transmitting data. Most modern firewalls have algorithms so you don't have to open all of the whole Dynamic Port Range, and it will only allow traffic on the specific port needed for the short duration that it is used, then close it again. This isn't specific to the Protocol Proxy implementation of FTP; all FTP servers require these rules.


5.3.2. Setup Protocol Proxy SSL


Click here for very thorough documentation on how to set up SSL for Tomcat.

You will need to edit server.xml once you have created a keystore:

{BIT_EME_CE_HOME}/protocol-proxy-ce-{version}/conf/server.xml


5.3.3. Change Protocol Proxy Web Port


The default web port is 80, to change the port you first need to stop Protocol Proxy:

  • edit {BIT_EME_CE_HOME}/protocol-proxy-ce-{VERSION}/conf/server.xml
  • find the section in the xml file that looks like this:
1 <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
2 <Connector port="80" maxHttpHeaderSize="8192"

3            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
4            enableLookups="false" redirectPort="8443" acceptCount="100"

5            connectionTimeout="20000" disableUploadTimeout="true" />
  • change the port attribute from 80 to the new port number
    • Port must be between (1-65535), ports between (1-1023) require Administrator or root access
    • List of TCP ports
  • save the file and restart Protocol Proxy


5.4. Features


Protocol Proxy is compartmentalized into different web applications deployed into a single Apache Tomcat Web Container. The default web port is 80, so it will require Administrator or root privileges to start.

5.4.1. Proxy Admin


Proxy Admin is the Administration Web Portal: http://localhost/proxy-admin

You can add/edit users, upload, download, and delete messages for any Protocol Proxy user.

Default access:

username password
eme password


5.4.2. Proxy Portal


Proxy Portal is the User Web Portal: http://localhost/proxy-portal

It is accessed by the external Trading Partners so they can upload, download, and delete messages for only their Protocol Proxy user.


5.4.3. FTP


FTP is a standards-based FTP Server external Trading Partners can use to upload, download and delete messages for only their Protocol Proxy user. By default it is run on port 21, with data ports being from the dynamic range.

It has been tested with many clients across all operating systems, however that does NOT mean it will work with every client. FTP has been around for a long time and some legacy clients may have issues.

If you find a problem or issue, please go to our Forums and search for your topic in the area for Developers, or enter a new one.

Note: Protocol Proxy requires an FTP client that supports IPV4.

More information about FTP


5.4.4. HTTP/S


There are two HTTP/S REST Web Services available, one for Trading Partners, and one for EME (Internal Applications). The external REST API only allows Protocol Proxy users to upload, download, and delete their own messages. The Administration REST API is used by EME to act upon messages for all Protocol Proxy users.


4. Managed File Transfer

Table of Contents

6. EME