Using ALUI URLMappings, especially for debugging

| | Comments (0)
Often ALUI customers deploy portals accessed through a single URL that doesn't go directly to the portal servers. This may be the URL of an SSL accelerator, a load balancer, or a proxy. Unless the customer deploys their portal with an extra URLMapping or two, then portal administrators or IT staff may find themselves inconvenienced in that they can only access the portal through the single public URL. It can be much easier to debug load balancer problems or troubleshoot an SSL portal if the admins can access the system through administrative URLs. The portal's URLMapping feature can allow this.

This article will explain the URLMapping feature, show a common but limiting configuration with proxies or SSO, and show alternate configurations that are more flexible.

What are URLMappings?
The portal needs to know how to write its HTML so that links go to URLs that make sense to the end user. In the simplest portal configuration, users browse directly to the portal (http://simple/portal/server.pt), and the portal returns a page with links that continue to use http://simple/portal/server.pt. No mapping required. But consider a more advanced configuration that involves a load balancer. Users browse to http://public/portal/server.pt, then the load balancer fowards traffic to http://serverA/portal/server.pt and http://serverB/portal/server.pt. The portals needs to return HTML to the end user with the base of http://public instead of http://serverA. URLMappings instruct the portal how to do this.

How URLMappings Work
URLMappings are configured in \plumtree\settings\portal\portalconfig.xml or \plumtree\ptportal\5.0\settings\config\x_config.xml. You can create as many URLMappings on a system as you'd like. Each mapping has three elements:

  • URLFromRequest is the URL the portal sees in the incoming request. This isn't necessarily what the user typed in, such as when the portal is behind a load balancer or proxy. The portal tries to match the incoming request to the URLFromRequest value, and if it finds a match, then it will map according to the values found in the next two elements. You can look in PTSpy for a message like this one to know what the portal sees: Entering handleRequest: GET http://serverA:80/portal/server.pt.
  • ApplicationURL is the base URL the portal will use to rewrite links for HTTP traffic.
  • SecureApplicationURL0 is the base URL the portal will use to rewrite links for SSL traffic.

The portal evaluates each URLMapping in its config file, and once it finds a matching URLFromRequest, it can rewrite URLs. The portal must find a match though, and so you must make the final URLFromRequest setting an asterisk to handle any case not matched by prior URLMapping rules (an IP address, for example).

Common Configurations
I show examples in the XML format used by 5.x portals since visually its more concise than the 6.x format. The concept is the same in both versions though. By default, the URLMapping section looks like this in 5.x portals:

<URLFromRequest0 value="*" /> 
<ApplicationURL0 value="*" /> 
<SecureApplicationURL0 value="*" /> 
That is essentially a pass-through mapping. Users can go to http://simple/portal/server.pt or https://simple.fully.qualified/portal/server.pt, and the portal will write links to keep them on the same base they first entered.

With a load balancer, the URLMapping section could be as simple as this in the case that the user types in http://public to get to the load balancer, then the load balancer forwards traffic to http://serverA:

<URLFromRequest0 value="*" />  
<ApplicationURL0 value="http://public/portal/server.pt" />  
<SecureApplicationURL0 value="https://public/portal/server.pt" /> 

Advanced Configurations
Many customers don't go further than the above mappings. But lets say you have http://serverA and http://serverB behind your load balancer, and you want to be able to browse to a specific server. You could use the following URL mapping to do this. It tests whether the user requested a specific machine. If they did, they'll stay on that machine. Otherwise, they'll use the load balaner's URL:

<URLFromRequest0 value="http://serverA/portal/server.pt" />  
<ApplicationURL0 value="http://serverA/portal/server.pt" />  
<SecureApplicationURL0 value="https://serverA/portal/server.pt" /> 

<URLFromRequest1 value="http://serverB/portal/server.pt" /> 
<ApplicationURL1 value="http://serverB/portal/server.pt" /> 
<SecureApplicationURL1 value="https://serverB/portal/server.pt" /> 

<URLFromRequest2 value="*" />  
<ApplicationURL2 value="http://public/portal/server.pt" />  
<SecureApplicationURL2 value="https://public/portal/server.pt" /> 
It's also possible that for security purposes, you want to require all traffic to go through an URL protected by an SSO product or through a proxy. How can your system administrator debug, such as when you think a problem is caused by your proxy? You could configure an URLMapping so that when the system administrator logs into the server console, he or she can then access the portal at http://localhost/portal/server.pt:
<URLFromRequest0 value="http://localhost/portal/server.pt" />  
<ApplicationURL0 value="http://localhost/portal/server.pt" />  
<SecureApplicationURL0 value="https://localhost/portal/server.pt" /> 

<URLFromRequest1 value="*" /> 
<ApplicationURL1 value="http://public/portal/server.pt" /> 
<SecureApplicationURL1 value="https://public/portal/server.pt" /> 
There are other ways to put URLMappings to work for you, but this discussion should give you the base understanding required to get started.
And a Bug
[Added July 23, 2007]

It turns out there's a bug. Basically, gatewayed portlet content has URLMapping rules applied to it twice. So let's say initial configuration were this:

URLMapping0: http://internal1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping1: http://internal2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping3: http://internal3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping4: * -> http://everything.else/portal/server.pt

So a user browses to their My Page, and the URL for links to portal infrastructure such as other My Pages or Communities would propertly rewrite from http://internal1/portal/server.pt to http://proxy1/portal/server.pt. But within the gatewayed content of the portlet, a second rewriting would occur. In this case it would rewrite http://proxy1/portal/server.pt (which matches to *) to be http://everything.else/portal/server.pt.

The workaround isn't too hard. All you need to do is have a URL mapping section that matches the external URL and says "when this URL is encountered, leave it alone."

You would add mappings such that:

URLMapping0: http://internal1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping1: http://internal2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping3: http://internal3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping4: http://proxy1/portal/server.pt -> http://proxy1/portal/server.pt
URLMapping5: http://proxy2/portal/server.pt -> http://proxy2/portal/server.pt
URLMapping6: http://proxy3/portal/server.pt -> http://proxy3/portal/server.pt
URLMapping7: * -> http://everything.else/portal/server.pt

Leave a comment