The obvious point to note here is that the number of requests processed per second does not necessarily relate to the load on the target system (whatever that may be);for example a search request with broad parameters that returns a huge amount of data will consume more resources on the service provider system than an update that contains a unique identifier for a record and a couple of values. The ability to restrict the number of concurrently processing, high cost requests should be considered as important as controlling the rate of incoming requests. Failing to provide this type of protection for mission critical services has seriously undesirable side-effects.

In this post I’ll give an example of how a gateway can be used to provide protection from system overload (at an operation level) and discuss the various approaches to managing this in an HA (High Availability) and dual site configuration.

First off let’s be clear about in-flight requests and concurrent transactions….

Assuming the target service is exposed to external consumers in the classic service virtualisation pattern above, an “in-flight” request is considered to have a lifetime that begins as soon as the request leaves the gateway (forwarded to the service) and that ends once the response from the service is received by the gateway. For longer running requests (in the order of 2 to 5 seconds or more) the effect of concurrent processing is exaggerated. To clarify, the requests do not need to be concurrent – it is the overlap of  the lifetime of in-flight requests that constitutes a “concurrent transaction” in the context of MCT (Maximum Concurrent Transaction) throttling.

In the diagram above, (green dots representing requests) if a limit of 2 MCT had been applied to the service, then subsequent requests would be rejected until such time as one of the requests currently being processed completes and returns.

Clearly the objective here is to manage a count, applying a one-in one-out restriction when the maximum number of allowed transactions currently being processed by the target server is reached… sounds pretty easy, and in a single gateway in-line configuration it is.

Using either the service name, operation name (or a combination of both) or even the URI of the incoming request to provide the key for the increment allows the restriction of the number of concurrently executing requests on the target server.

The challenge here is how to scale, simply dividing the maximum limit by the number of gateways behind a load balancer is notoriously unreliable and could easily result in a loss of transaction capacity if the load balancer has any bias at all. The only real solution is to maintain an atomic transaction count across 1..n gateways.

I spent some time looking at the different options for achieving this, and whilst there are a few that are satisfactory from a functionality point of view, they all came with a cost (usually a performance hit).

The silver bullet was actually handed to me on plate by David Cooke at Oracle (thanks David), who introduced me to Oracle Coherence, a very cool piece of tech. The key to it all is providing a non-blocking lock on the count – allowing multiple gateways to read, increment and decrement the count for a given service/operation. The simple policy shown below is all that is required to implement service level MCT throttling (in its most basic form)

If the gateway fails to acquire a lock on a transaction a custom error message is returned back to the client. The fault handler (in blue) for this circuit also releases the lock – to prevent orphaned transactions. In this example the connection to the target service is also load balanced (by the gateways) to multiple hosts.

As a solution this is highly scalable (multiple gateways, 300+ services/operations) and also self healing; one or more gateways can be removed from the architecture without impacting the availability or the transaction count, as long as there is one gateway up and running. Orphaned transaction locks from a terminated gateway are automatically cleaned up and freed for use by the remaining gateways.

The load balancing performed by the gateway will also mitigate downstream server failure – by removing an unresponsive host from the available pool and adding it back in when it becomes operational and available again.

If that wasn’t enough, the transaction restrictions can be applied even in a dual / multi site (DR) scenario – although performance may vary depending on the inter-site connectivity.

The MCT throttling limits can be implemented as “hard” and “soft” limits with alerting (as described in the previous request throttling – and the concurrency can be tracked against almost any facet of the interaction service/operation/user/client IP address etc… Limits can be stored externally (abstracted to a directory/database / IdM solution) allowing the administration.

Mark assumes you have a degree of familiarity with either the Vordel Gateway or Oracle Enterprise Gateway, if you don’t then take a look at my earlier “hello world” entries

What I’d like to do in this post is focus a little deeper on request throttling, and show how the gateway can help avoid partners and service consumers from overloading your services not just by blocking requests that exceed a certain threshold, but by giving advanced warning of erroneous excessive service consumption.

It is worth taking a few paragraphs to explain the very real value of request throttling, and perhaps to make a brief comparison with SLA management, quota management, traffic shaping and concurrent transaction processing limits.

In the context of gateways being used to virtualise services for external consumption, throttling is primarily concerned with the number of requests made by consumers to the target services. Restrictions take the form of a message count that is incremented and measured over a specific time period. The Vordel gateway provides both coarse and fine grained control of request counts and perhaps more importantly can track the request count based on virtually any index.

  The throttling filter provides a variety of options for measuring and tracking request counts – the time period unit ranges from seconds, minute, hour, day, and week meaning that it can used to implement quota management as part of a pay-per-use solution.

The number of messages, period and period unit can also specified by parameter substitution – enabling complete decoupling of the throttling limits which could be managed in an external provisioning system or database.

Key to the successful implementation of a request throttling solution of enterprise scale is the ability to maintain a consistent count across multiple gateways in an HA / HA-DR deployment – achieved quite simply here by the use of the gateway’s caching mechanism.

Pay special attention to the “Track per key” setting that allows the request count to be applied to different contexts. In the screen shot above, the wildcard attribute of ${http.request.clientaddr} is being used – fairly obviously this will apply the request count restrictions based on unique IP address value of the calling client. The ability to control the “key” with attributes gives enormous flexibility, and because multiple throttling filters can be linked together in a policy (or circuit) limits can be applied to an incredibly low level. You could for example apply a global request rate limit across all services (good practice for mitigating DoS attacks). Legacy applications that have been “service enabled” may be a little fragile (having never been designed for web volumes) – it would make sense to apply a service wide limit in addition to the global restriction, but independent of the calling client – you could even be operation specific. Most of us are also familiar with the pattern that allows restricted service usage for “free”, and a tiered allowance for those signing up to the “pro” version – a good example of metered service consumption by role. Then there is the hard core application – of quota management by identity (which could be at individual user level or partner organisation).

For the record, throttling should not be confused with SLA (Service Level Agreement) monitoring and management. It may be sensible to offer an SLA within restricted bounds (of request volume) but SLA is more concerned with response times, number of failures (typically non 2xx response codes) etc…

The value here is pretty obvious, by implementing a well considered throttling strategy (which incidentally can be designed once and applied globally) you get the following

• Protection from request volume based DoS attacks
• Shielding of vulnerable servers, services (and even specific operations)
• Service Consumption Metering (billable pay per use services)
• Optional and conditional routing of excess traffic (maybe expanding into the cloud at peek times
• Pro-active non-blocking alerting that allows action to be taken before critical limits are reached with built in alert storm protection
• boundary volumes for tightening SLA agreements

Using externally set parameters means that limits can be changed an applied dynamically (or in extreme cases even scripted!!) you could for example automate the increase of a limit on receipt of payment for a particular partner / customer.

The wealth of functionality in just one filter component is impressive in its own right, and… there’s more… Mark’s blog describes a relatively simple design…. once you reach the throttling limit for the service then future requests are “rejected” until such time as the rate calculation falls below the specified threshold. By introducing a soft limit we have the capability to provide non-blocking alerts that give prior warning of an impending breech .

Working through an example….

1. Basic service throttling

The figure above shows rudimentary service throttling (at 100 requests per second is used as an example only). If the number of requests to the service exceed this, then a soap fault will be returned by the gateway and the request is not sent to the target service (blocking).

If we introduce another throttling filter (different key for tracking!) with a lower limit, we can provide an alert to an appropriate party (operations / partner administration contact / account manager or all)

2. Setting a “soft” limit

In this example I’ve chosen to set the warning level at 80 requests per second – and changed the key to track by to avoid a double increment with the hard limit filter.

At first glance, it looks a little odd – basically we don’t change the policy execution path when we exceed the SOFT limit. This will however show in trace files, real time monitoring and the new Traffic Monitor

3. Take some action on exceeding the SOFT limit

a) For demonstration purposes I’ll use a syslog alert, but it should be obvious at this point that the conditional processing that occurs as a result of a SOFT limit breach is not restricted to syslog alerting – or alerting at all! – setting up an alert

Having set up an alert target, it can now be used to flag a soft limit breach… n.b. the alert filter is found in the Monitoring category

The actual alert configuration is outside the scope of what I want to discuss here, I’ll perhaps cover it in greater detail in a different post

So from the top down …..

If the request being processed causes the 80/s count to be exceeded we follow the failure path (the red line) to the “Alert” filter – my alert is configured to send a message to syslog with details of the service soft limit breech.

In the above policy I have chosen not to put the alert on the critical path, in real terms this means that even if the alert fails then message processing will continue. Then the policy checks the HARD limit which is where we started at step 1… meaning that if the request is over the soft limit but below the hard limit then the alert is sent and the request is processed as desired, only when the hard limit is exceeded are requests blocked.

** The brighter readers of this might observe that this means you could have 20 alerts in a second for each request that is >79 but less than 100 ** essentially an alert storm. Fortunately the alerting filter provides the ability to prevent this by configuring a limit for the number of alerts that can be sent in a given time period…. the clever guys at Vordel think of almost everything

I

So far we have used the set message filter to set the message value to some arbitrary text, and then used the reflect filter to bounce this back to the requestor with an http response code of 200.

To add some simple authentication, the first thing we will need is a User.

1. Creating the user

Select the users section on the configuration navigation panel on the left hand side.

Then click on the Users node of the User Store

Click Add – and enter some details for your user (I have used ‘joe’ with a password of ‘joe’)

Note the option to assign an X509 cert here – this can be used for crypto operations and mutual SSL – which are topics for a later post.

Notice also the attributes tab, click this and add an attribute

I’m going to set an age attribute with a value of 30

Add a couple more if you feel like experimenting – just the one will serve for the purpose of this post – remember – pretty much everything is CASE SENSITIVE by default.

Click OK and now you have your user “joe” in the built in user store

2. Adding authentication to the policy

Now we have a user to work with, lets put some authentication requirements on our Hello World policy – starting with http basic. Navigate to the Hello world policy (select the policies section on the left hand navigation panel and click on the policy in the tree node, or if it is already there select it from the list of tabs in the design panel (central panel by default).

Type “authentication” into the filter text box at the top of the pallet – you should be getting used to where things are by now… and expand the Authentication category.

In the authentication category you will see many options for providing authentication to services – some of which enable out of the box integration with third party IdM products –  we won’t be looking at these in the blog but feel free to submit a comment if you need assistance with something specific like Tivoli, RSA, CA, ADFS etc…

Remember that each of the filters here will have a context based dialogue that allows you to enter the parameters required to integrate – NO CODE REQUIRED.

For those of you not familiar with how  Mutual SSL authentication (or Client certificate authentication) don’t expect to be able to use this just yet, as we haven’t set up an https interface … so it’s not possible just yet …. have patience

Anyone wanting to play with kerberos – feel free but I’m not a big fan so won’t be covering it here unless someone forces me too

Left click, hold and drag the filter onto the design canvas – it is best to drop it on to an “empty” part of the canvas – dropping filters on top of each other or directly on to connectors has a different effect which we will cover later.

Configure the filter with the following settings:

and click Finish – you should have something like this.

Remember any filter that is not the start filter, and is not connected to it by a downstream path is not part of the policy.

Obviously it makes sense here for http basic authentication to be the first step we perform in the policy – it may seem trivial right now, but we don’t want to waste processing power performing tasks for an un-authenticated user!

There are a couple of ways of achieving this, and it’s basically down to personal preference – either set the filter as the start filter (right click – set as start) and then join the others, or use the to link the http basic filter to the set message filter… then set it as start – I typically do the later.

There are no RED warnings – so all attribute requirements are satisfied – all that remains to be done is deploy the update policy to the gateway

to deploy the configuration hit the F6 function key, or click the deploy icon – changes to policy do not affect the running [active] gateway until they are deployed.

In a browser of your choice – load up your hello world uri

http://localhost:8080/blog/tutorial01/helloworld

– you should be challenged for a user name and password

Enter the credentials for the user you added in the first step of this tutorial – in my case – ‘joe’ and ‘joe’

and you should be granted access to the hello world page

** There are a couple of things to keep in mind when it comes to using browsers as a test client; they tend to cache authorisation headers – so if you got your username and password wrong here then to try again you may have to shut down ALL browser sessions before you can try again – or even clear your browsing history – ultimately it is better to use a testing tool like Vordel SOAP Box that will all0w you to send a variety of requests at the gateway (including http GETs) without the browser functionality getting in the way of you testing – we’ll take a look at SOAP Box in the next couple of blogs – and its a free download with no “pro-version” limitations **

So we have layered  http basic authentication over the hello world service – now that we have a user identity established as part of the policy we can add some personalisation – let’s start by changing the welcome message.

Go back to the hello world policy and double click on the set message filter –

edit the text to say Hello $

Notice that as soon as you press the ‘$’ key a scrollable list of attributes is presented for auto insertion – continue to type “authentication” and then select the “authentication.subject.id” attribute and hit enter. Your message text should now look like this.

Hello ${authentication.subject.id}

Click finish.

This is the general syntax for attribute insertion (or substitution) – the authentication.subject.id attribute is populated by way of the http basic authentication filter we inserted earlier. You can see what attributes are generated, required and consumed by right clicking on the design canvas and selecting the “show all attributes” menu item.

There are other attributes available (populated by default as part of handling an http request – http.request.uri and http.client.addr for example that are not shown in this list – all the attributes are documented in detail in the gateway documentation. available at http://localhost:8090/docs/

Deploy [F6 function key, or click the deploy] your updated policy and browse to the url http://localhost:8080/blog/tutorial01/helloworld

for fun you could then try setting your message to something like this.

Hello ${authentication.subject.id}
You are on ip address ${http.request.clientaddr}
and accessing the relative path ${http.request.uri}
via the HTTP method: ${http.request.verb}

Next we will look at retrieving joe’s age from the user store.

In the filter textbox on the pallet – type attributes and expand the attributes section

Again there is a wealth of functionality that deals with attributes of all kinds, shapes and sizes – scrolling down you will find the filter we need for this example

Remember you can customise the filters that are shown or hidden, and add your most frequently used filters to the Favourites (Favorites for you folks in the US) category.

If you fancy a change and don’t want to drag and drop then you could right click on the canvas and select add filter, then select the retrieve from user store filter.

Configure the filter to use the authentication.subject.id as the User ID, – the authentication.subject.id will be used to uniquely identify the user whose attributes we wish to retrieve. – you can add individual attributes to selectively retrieve, or leave the attribute list empty to return ALL attributes for the user from the built in store

Now wire in the retrieve from user store filter. Logically it would not make sense to retrieve attributes before we have identified the user – so you should be able to figure out where this one should go – again there are different ways to rewire the policy – by preference I connect the filter I have just added using the success connector to the filter that should follow it, then move the end of the path that should connect above it like this.

Connect the retrieve from user store filter to the set message filter

click the success path joining the http basic filter and the set message filter then drag the arrow end to the retrieve from user store filter

click the arrow head and drag it onto the retrieve from user store filter and release

Now we have a nice visual representation of the flow –
1. authenticate
2. get attributes from user store
3. set the personalised message
4. return the message to the requestor

we just need to update the message to include our ‘age’ attribute

change the message text in the set message filter to

Hello ${authentication.subject.id} you are ${user.age} years old

Notice that the age attribute is prefixed with “user.” this is because the attribute belongs to the user, and NOT the message – distinguishing between user attributes and message attributes becomes more important later when inserting SAML assertions amongst other things.

Deploy the updated policy and check it out….

You can change “joe’s age” by modifying the age attribute value for joe in the user store – remember to re-deploy before you test again.

Notice that the Set Message filter is now RED – warning that one or more required attributes may not be available at run-time – this is because we used the retrieve filter to return ALL the values – therefore the GUI cannot confirm with any certainty that the “age” attribute will ALWAYS be available. If you show all attributes you will see it is the user.age attribute that is the cause for concern.

What you should have learnt

• How to add a user (with attributes) to the local user repository
• How to configure http basic authentication against the local user repository
• How to insert a filter (rather than just add) into an existing circuit
• How to retrieve user attributes from the local user repository
• How to substitute retrieved attributes using the wildcard syntax into the set message filter
• Where to access the list of available attributes (in the product docs!!)
• How to detect attribute dependencies in policies
• How to navigate between the different configuration sections – policies, services, users

Fundamentals

• User attributes are prefixed with “user.”
• selecting a success or failure “arrow” allows the arrow head to be dragged and reconnected to change the flow of the policy
• ALL changes need to be deployed – even updating user attributes
• Changing the starting filter affects the whole policy – there is more than one way to achieve the desired flow through the policy / filter circuit

Up next….

Fault handling and policy shortcuts… a short introduction on how to create re-usable policies that can be invoked from multiple “parent” policies, and how this helps to keep a clean and clear visual representation of gateway policies; and how to create policies that handle errors and failures.

Having said that, it is helpful to know which end of the proverbial oar to use before starting to paddle so here is the express tour of the main Policy Studio design window.

The main policy studio window has two sections – the section on the left is for configuration navigation and is split into 5 separate viewing perspectives

• Services – For configuring inbound channels e.g. http listeners, jms and pop3 consumers
• Policies – Viewing and managing policies – we will explore this in more detail later
• External Connections – external databases and repositories, AuthN and AuthZ / IdM Provider integration, SMTP, JMS etc…
• Users – A built in user repository that can be used to apply AuthN and AuthZ without requiring a 3rd Party User Repository or IdM product
• Certificates – self explanatory – contains functionality for managing certificates and keys

Selecting the different sections on the bottom left hand container changes the explorer tree node view.

left clicking on any of the node items changes the contents of the tabbed central panel to a context sensitive display

If you are anything like me then you’ll probably have tried clicking, double clicking and right clicking on just about everything that looks clickable by now (I’m every IT trainers worst nightmare). Hopefully you managed to cancel out out of everything you weren’t sure of and tried deleting anything you thought you understood to get back to ground zero…. if you didn’t then don’t worry about it simply close the top level gateway configuration tab, choose to discard your changes and then click “edit active configuration again” and phew…you’re back!…

Next fire up your browser and navigate to http://localhost:8080/healthcheck – you should get a little message back saying “OK” – depending on your browser it may or may not be rendered as XML

Use your browsers view source facility to take a look at what is actually sent back by the gateway

the gateway URIs are case sensative http://localhost:8080/HealthCheck will give you a totally different result (again this can be overridden but is out of the scope of this post)

If you haven’t already fired it up and had a look around already then check out the traffic monitor and real time monitoring tools at http://localhost:8090/

the traffic monitor is a really useful tool for development and diagnostics…. and shows policy execution, trace and payload information, we will take a look as part of the first policy exercise.

So now we have the basics in place, and we can navigate the different configuration sections we can go right ahead and develop our first policy.

The gateway is often used in the context of a reverse proxy for web, xml and ReST services, in the case of Web Services we can use an import wizard to load up a WSDL and auto-generate a policy framework that virtualises the service. Ironically this makes more sense when you know more about how the gateway actually works. So instead of plumping for the standard StockQuote Service (which I promise to cover in a later post) I’m going to take a step back and work through setting up an “echo” style service on the gateway – no SOAP, no WSDL, no XSD just an http request and response.

Start by creating a new Policy Container under the Policies node in the node tree on the left hand configuration explorer pane

You can also add a sub container if you like, containers are essentially just folders that help you keep your policies organised – this is particularly important for separation of concerns and for re-usable “utility policies”.

Once you have the containers configured as you want them then add a policy to the appropriate container.

Policies appear in alpha numeric order (so as a tip – start with at least one leading zero :-) – you can rename them later if you need to.

When you click ‘OK’ the blank design canvas will load up into the central tabbed panel along with the filter pallet on the right hand side

Remember to use the text lookup box at the top to help you find the filter components you need to build the policy – You can also customize the pallet to show and hide individual filters and categories

Under the “Conversion” section you will see the “Set Message” filter – we are going to use it to build our “Hello World” message that will be sent to the calling client.

The “Conversion” category contains a whole bunch of filters that are used to manipulate messages; XML, SOAP, Attachments, text, binary, pretty much anything.

The “Set Message” filter can be used to create a template message of a particular mime-type which can then be populated with information drawn from other sources – SAML Assertions, LDAP repositories, Databases, message headers or protocol information.

Learning what each of the filters does, and how to combine them is the essence of good policy design – if you are resorting to using the scripting and extensibility features of the design environment then the chances are you haven’t thoroughly explored what’s available or not thought through what exactly is involved in achieving the desired result; as with all “development” there is no real substitute for a good design document and a few flow / sequence diagrams to help you get it right.

I would start by adding the “set message” filter to my favourites though.

Left click on the filter in the categories list and DRAG it onto the design canvas for your hello world policy – then let go. You will be prompted with a dialogue to configure the set message filter …. do something like this…

Notice that the content-type has been set to text/plain – this means we don’t have to go writing html or xml and the message will render ok in a browser without issue – if you want to put some XML or HTML then feel free to give it a go, just be sure to use the appropriate content type (text/xml or text/html as appropriate)

Notice the “Next” button at the bottom – pretty much every configuration dialogue has one of these and it opens up the logging options for each filter – again feel free to take a look, but I’ll cover this off in a different post.

Click finish

Now you have a “greyed” out set message filter on your canvas.

Every policy must have at least ONE filter and ONE START; A Policy MAY have just ONE filter that IS the START

As it is our policy doesn’t have a start point, we just dragged on a filter and configured it. To set our set message filter to be the start filter we need to

Right click on the filter on the design canvas and chose “set as start”.

The filter now shows as both Start and End

So far so good…. but we need to “bounce” or “reflect” this back to the calling client – for http/https requests we use the “reflect” filter from the utilities section to do this.

type reflect in the pallet lookup text box and expand the “Utility” Section

Click and drag the filter onto the canvas and click Finish

You will see that the reflect message filter is not joined to the set message filter which is our starting filter – and so at the moment it is inactive to make it part of the policy we need to connect it with one of the connectors.

Almost every filter in the pallet has two possible outcomes SUCCESS and obviously  

Policies are constructed by building logical trees (Binary decision trees) of filter execution – so in “pseudo-speak”… when the message has been set successfully we want to reflect the result.

To link our Set Message filter to the newly added reflect filter click on the in the pallet on the right hand side – this puts the mouse into “success connector mode”

Left click *and release* on the set message filter – then left click on the Reflect filter

Note: success and failure paths are not dragged from the pallet.

To exit “Connector” mode either hit the escape key or click on the component in the pallet.

The reflect message filter SHOULD turn RED this is to warn us that the filter may not have enough information to execute properly – to see what the problem is hover over the filter

To execute properly the reflect filter needs http headers (i.e. it needs to be part of an http request response pair – the http headers will be provided by an incoming request to the gateway that invokes our hello world policy – So all that is left for us to do is wire the policy up to a suitable URI to expose our hello world service.

Select the services category on the left hand configuration explorer panel and expand the nodes down to the “default services” node.

Right clicking on the Defualt Services node gives us an option to add a “relative path” – or you can do this by selecting the “Default Services” node and using the link in the design panel

Chose a meaningful path –  /blog/tutorial01/helloworld

and then select the hello world policy as the “Path Specific Policy”

Again, the audit settings aren’t what this post is about, but feel free to have a look around -

click Ok and navigate back to your hello world policy (use the tab at the top of the central pane or the “browser back” button from the toolbar menu at the top left.

The reflect message filter now has the required http.headers attribute (that will be populated by the http request) so there are no “red” warnings.

To deploy your configuration (as we haven’t actually made any changes to our gateway yet) hit the F6 (function key) or click the Deploy icon in the toolbar menu at the top.

** Notice the status bar at the bottom **   

Now we can test our policy using the browser –

The default http listener that we added our relative path to was on port 8080 – so to test our policy we combine the protocol (http) the host name (localhost) the port number (8080) and the relative path (/blog/turorial01/helloworld) to give us our uri.

http://localhost:8080/blog/tutorial01/helloworld

What you should have learnt ….

• How to start up the gateway and connect policy studio
• How to navigate the primary sections of policy studio
• How to create containers to organise your policies
• How to use the filter lookup text box to search for the filters you need
• How to create a basic policy using the drag and drop filter components
• How to link filters with the success connector
• How to add a relative path to a service node and map it to a policy
• How to deploy your configuration to your gateway
• How to detect when a filter doesn’t have enough information available to execute

Fundamentals

A policy must have at least one filter, and at least one of the filters must be set as the start point for the policy.

A policy that has only one filter which is set as the start filter can be valid

Any filter not linked directly or indirectly downstream of the start filter will be inactive – inactive filters are shown greyed out

Up Next

Hello Joe – the hello world policy gets a little more personal as we explore some basic authentication, failure paths and using “attributes”.

When we are sure that we are on the right road there is no need to plan our journey too far ahead. No need to burden ourselves with doubts and fears as to the obstacles that may bar our progress. We cannot take more than one step at a time.

Orison Swett Marden (1850-1924)

What you will need:

Apart from coffee, and a machine (Win/Linux/Solaris … oh and Mac too if you can run a VM), you will need

Vordel Gateway – available for OS as above and Virtual Image
Vordel Policy Studio – design tool for the gateway
Vordel SOAPBox – neat service testing tool – all the usual stuff supported (http/s SOAP XML attachments encryption etc…)
Probably a good idea to have a browser with the latest flash plugin installed

Later I might dip into centralised management for distributed gateways provided by Vordel Director and the various reports,  and stats that can be extracted with Vordel Reporter… so you may as well get those while you’re at it…

If you can’t download and install then it is possible you’d be better suited to a career in sales… but seriously….contact me via this blog or the guys at vordel … sales@vordel.com, and just tell them I sent you

Once you’ve installed, then your good to go … you could even design your first policy on the train…

So let’s start at the very beginning, and the first thing to do is get everything fired up and connected. For the purposes of this blog I’ll be using the Windows 7 version of the Vordel Gateway and Policy Studio if you need info or assistance with different a different OS then either contact me directly or post a comment on the blog.

I could just say RTM, but if you’re anything like me that will be one of the last things you want to do…. far easier if someone just showed you right? My gravestone will probably read “Here lies Ian…. who should have read the manual”. So if you can’t find the manual, or the dog ate it, this is how we get started … assuming you managed to run the installer (or extract the tar.gz) and that you have a valid licence …. if you don’t have a licence or aren’t sure what to do with the one you have STOP and see this separate post on getting a licence

Step 1: Start the Vordel Gateway

Open a command prompt (no really you can do this without a picture)

Change to the bin directory cd C:\gateway_install\Win32\bin

run the command vordelgateway.bat

n.b. if you have installed as a windows service – you can use the program files menu to start / stop the gateway. the advantage of running in a command or terminal window is that you can see the gateway trace without having to tail or open the trace file. You can just double click the .bat file in an explorer window, but if there is a problem (like you forgot to get and install a licence key) the window will terminate without giving you any clue as to what happened.

Notice that the gateway by default starts up using 2 different ports – 8080 and 8090. You can browse to http://localhost:8080/healthcheck to see if your gateway is behaving as it should.

You should also open up http://localhost:8090/ and login to see the gateway “home page” that gives you access to trace files, real-time monitoring and other cool stuff that we will play with later. The user name and password defaults are admin and changeme

Step 2: Starting Vordel Policy Studio

For windows users this is easy – either use the start menu, programs, vordel, policy studio link or

double click the policystudio.exe in the installation folder (you could of course do this from the command line too if you like)… either way you should see something like this

Assuming you haven’t messed with anything you should be able to go right ahead and click on the link to “Gateway – localhost”

The user name and password defaults again are admin and changeme and you’re in

Hit the shortcut to edit active configuration or double click on the Vordel Gateway in the process list and you can take a look at the gateway configuration as it comes out of the box.

When you are prompted for a “passphrase” just click ok.

“So what does a gateway do anyway?”

Many think of it just as a piece of security infrastructure that “secures web services and XML traffic”, and yes it does that (too). Others perceive it as a transformation engine converting between disparate data formats and protocols, they too would be correct. There are a few SOA fanatics that recognise a gateway as providing a point of enterprise wide control, monitoring and reporting – and as a key architectural component for both design time and runtime governance. In fact the Vordel Gateway provides all of these features and more.

I have been involved in countless gateway implementations across all market verticals and whilst I have seen similarities in designs and some common requirements for gateway functionality, I can honestly say that no two implementations are the same. One of the greatest strengths of the gateway is flexibility. It could and often is considered a network Swiss Army knife, the real challenge being to know which blades to use for what.

The purpose of this and future posts is to share a little of what I know the gateway can do, and perhaps draw attention to some of those that require a little lateral thinking, a few “How Tos” and “Why Tos” and hopefully comments from readers that will prompt a little health debate.

I’ve listed a few topics that I intend to cover below, but I’m happy to go ‘off road’ and take a steer on what ground to cover from any comments that are posted.

• Pop3 to SOAP/ReST API
• Controlling services at runtime
• Selective Tracing (runtime debugging)
• Service throttling – in-line and abstracted
• ReST [style] Façade for Services – no code required!
• Why SSL May Not Be Enough – data at rest and message level encryption
• Detecting Client Certificate Expiry [before the event]
• Using Active Directory Group membership for Authorisation
• Service/Operation based User, Rate and Quota Provisioning – with database integration.

In addition to the above list I’ll be covering high availability and gateway scaling in general. If what is here isn’t enough, there is a whole host of valuable information, tips and tricks, videos and more from CEO Mark O’Neill http://www.soatothecloud.com/ and also various contributions from the Vordel Solution Architecture Team at http://xmlgateway.blogspot.com