Protege Client Server RMI

From Protege Wiki
Jump to: navigation, search

How Does RMI Work?

This page is part of the Protege client-server tutorial.

First a disclaimer. I am not an expert on the RMI protocol. The following is based on observations of how the RMI protocol behaves and debugging problems that can happen in ordinary practice. This behavior is further confirmed by the "black magic" tricks (running an rmi server through NAT and tunneling a connection to an rmi server) that we describe in this section. I enthusiastically encourage others to correct or improve these pages.

This page discusses the interaction of a server, rmi registry and a client. The simplest case is shown in the figure below.


The steps in the protocol are:

  1. The server registers (Registry.bind) a remote object with the RMI registry giving it a name. Inside the remote object is the hostname of the server. It turns out that this hostname comes from the -Djava.rmi.server.hostname=... jvm parameter.
  2. The client goes to the RMI registry to get the remote object bound to a particular name.
  3. The client invokes the remote object and contacts the server.
Even just this bit of information can be helpful debugging problems. For example, occasionally - often due to a system misconfiguration, the line

from the script will provide the wrong information. In particular sometimes the hostname command simply returns localhost. This means that the remote object registered in the RMI registry and therefore the object given to the client will indicate that it can be found on localhost. This will not work unless the client is on the same host as the server.

For the two examples below we will assume the configuration
   -Dprotege.rmi.server.port=5200 -Dprotege.rmi.registry.port=5300

In addition the rmiregistry needs to be running on the right port

    rmiregistry 5300.

Black Magic Trick #1: Tunneling RMI out of a private network

Please note: The approach documented here is an advanced technique. My primary purpose in documenting this was to illustrate an understanding of how the rmi protocol works though this technique can be used to get practical results. Anybody implementing this should have read the description of how rmi works (above) and should have a good understanding of networks including ssh and tunneling.

Note that this example is not as well motivated as the next one but it is a little less dangerous. If you do this technique then you should make sure that you understand the security implications. Also I only currently know how to set this up on unix machines (including osx). I am sure that this works on Windows but there is one step where I don't know the magic incantation.

Sometimes you will have permission to access a private network but will be temporarily working outside the private network. The simplest way to gain access to the servers on the private network is to use a VPN. The Cisco VPN seems to be very popular. But VPN's have disadvantages. They often come with policies that make work difficult and they are not always available. An alternative that is occasionally useful is to use a tool such as ssh to tunnel the connection from your machine to the private network.

If you have ssh access then it is not difficult to set up the tunnels. Suppose that the machine you are connecting to is called and the Protege server listens on port 5200 and the rmi registry is listening on port 5300. A command like

     ssh -L 5300:localhost:5300 -L 5200:localhost:5200

will do the trick. Then when you connect in the Protege client, you specify the machine as localhost:5300. Protege will then tunnel straight to the RMI registry and the RMI registry successfully returns the server object to you. However, unless you do something more, this technique still won't succeed. What happens is shown in the figure below.


The problem is that when the server registers the server object with the rmiregistry, the hostname specified in the server object is The client successfully connects to the registry through the tunnel but when it gets the server object it tries to access it through We some how need to convince the client to use localhost:5200 instead of

This is where the magic unix incantation comes in. As root, you can edit the /etc/hosts file and add a line

What this does is to falsely convince the client that the address refers to is located at Now the client goes to when accessing the server object and the behavior is as shown below.



Black Magic Trick #2: Exporting RMI from a NAT'd server

Please note: The approach documented here is an advanced technique. A preferred mode for any server is that it have a dedicated public ip address. My primary purpose in documenting this was to illustrate an understanding of how the rmi protocol works though this technique can be used to get practical results. Anybody implementing this should have read the description of how rmi works (above) and should have a expert understanding of networks including an understanding of the NAT protocol. In addition, it will take extra effort (involving configuring a DNS server) to get this approach to work equally inside and outside the LAN. Configuring DNS servers is outside the scope of what the Protege team will support.

If you are not sure that your machine is living inside a NAT'd LAN then you probably should not be trying these instructions out. However an easy way to determine that you are on a NAT'd LAN is to go to this site and see if the returned ip address is the same as your ip address. If they are different then you are probably working in the NAT case.

In this case you must be the adminstrator of a private network which has a server that you want to expose. Unfortunately the private network is protected by NAT so that the server host inside the network is not visible outside the private network. But you can still win!

This technique is more likely to be useful than the previous trick but it requires a bit more care. When changing the settings on a router you run the risk of breaking the router functionality and causing the network to fail. Of course, if you know how to set the router up, at a last resort you can always reset the router and reconfigure it. When I first started playing with settings on my router I came to a phase where I grew over-confident. I would tunnel to my network remotely and access the router settings. Once the router was misconfigured, I couldn't access it remotely - I had to wait until I was on-site. It only took a couple of misconfigurations for me to realize that I needed to be a bit more careful.

One thing that you can sometimes do before configuring a router is to save the router settings first. For example, the Linksys router has a place to save the configuration under Administration->Manage Configurations. I have seen this configuration in other routers also (Netgear I think).


For this example, we will assume that the server and the rmiregistry are running on the host with the address This is a typical address for machines that are not directly available on the internet. It is clear that exposing the server will only succeed if the router at the boundry of your network forwards requests to your server and your RMI registry. So you need to access the router configuration and set up some forwarding requests.


The collab1 and collab2 entries are the ones that I needed. I was a little surprised to see the vnc line but at least it was not enabled. Hmm... More bluntly put, I am telling anybody who is new to this to be careful. If you ever set up a web server on the internet and watch your logs you will see exactly how quickly infected machines find an open port.

However as before, the problem is that the object that the server registers with the server says it can be found on the host This address makes no sense to the client and the protocol fails.

But this is easy to fix. We simply change the hostname line in the script as follows:


Now the server object registered with the rmiregistry will say it can be found at Note that this will break access to the server inside the private network. But outside the private network, when the client tries to access this it goes to the router who redirects the request to the server.

At this point what you are hoping for is the behavior below.