Executive Summary
When working with multiple IBM DataPower Gateway devices in an enterprise infrastructure, the individual devices can begin to look identical. The Web GUI and command line interface are standard components that offer little default customization other than the hostname found in the banner. This is easy to miss and when a miss occurs developers are implementing configuration changes on the wrong device. This can cause projects in unrelated environments to be impacted by the rogue change.
The solution is to create a custom user interface file to insert a unique header and footer that represents the device’s environment. This gives the developer a visual clue of the environment and reduces the chance of rogue changes.
Introduction
Out of the box, all DataPower appliances feature an almost identical user interface. The only distinction between appliances is the hostname. In the Web GUI, this hostname is found in the header. In the command line interface (CLI), it won’t be displayed at all. Most DataPower infrastructures have multiple devices representing development through to production. If a developer is not careful, they can land up changing configuration on the wrong device. Worse, they may not even realize the mistake until a platform consumer notices that a service no longer works. This negatively affects the trust between projects and the infrastructure they are deployed on.
In order to minimize this situation, DataPower provides a small customization hook called the customer user interface file.
The Custom User Interface File
The custom user interface file is XML that can enable:
- An HTML banner in the Web GUI
- A text banner for the Command Line Interface (CLI)
- A modification to the CLI’s command prompt that will add the System Setting’s Appliance Name
The format of the file is defined in the DataPower Knowledge Center and the XSD representing the format can be found on the appliance at: store://schemas/dp-user-interface.xsd.
Markup Banners
Markup Banners are shown when using the Web GUI. The banner can be configured to appear pre-login, post-login or as a constantly visible system banner. It can appear as a header and/or footer in the browser window. The banner supports a very small subset of HTML tags: ’em’, ‘strong’, ‘tt’ (monospaced font) and ‘p’. The banner only supports static content so introspection of the DataPower device is not allowed. Foreground and background text can be used but only a small set of colours: Red, Orange, Yellow, Blue, Green and Black are supported.
Example
This is a sample user interface file that can be uploaded to your datapower device.
|
1 2 3 4 5 6 7 8 9 |
<User-Interface xmlns="http://www.datapower.com/schemas/user-interface/1.0"> <CustomPrompt>%s</CustomPrompt> <MarkupBanner type="system-banner" location="both" foreground-color="none" background-color="red"> <tt>This is the <strong> DEVELOPMENT </strong>; environment. </tt> </MarkupBanner> <TextBanner type="pre-login">This is the DEVELOPMENT environment.</TextBanner> </User-Interface> |
Setting the custom user interface file for an appliance is configured via the System Settings object in the default domain.
Recommendation – Markup Banner
The WebGUI is the easiest place to lose track of the device as most developers work with multiple tabs and may not notice the URL in the address bar. I recommend that the banner be enabled on both the top and bottom, to provide a visual frame that encloses the DataPower configuration. A unique background colour should be assigned to the environment for the device. For example:
- Red – Production
- Orange – Pre-producion
- Yellow – Business Acceptance Test
- Green – System Integration Test
- Blue – Development
- Black – Other low priority environments
The text in the banner should also contain the name of the environment.
I’m not a fan of pre and post login warnings as most people are conditioned to dismiss pop-ups without absorbing information. Remember, that we’re trying to make the device’s environment obvious over a period of time. This could be hours after initial log in. Pre/post login notification are better suited for implementing legal requirements about how the device contains confidential information and unauthorized users should immediately disconnect.
Recommendation – Text Banner
When working in the command line interface, it is slightly more difficult to lose track of the system as most SSH clients don’t support tabs. This means there is less of a need to create the in-your-face banner system as above.
There are two good times to notify the developer of the environment they are connecting to: When they first connect to the server and from the command prompt (next section). I recommend creating a pre-login notification that contains the environment of the device. A system-banner is overkill as it will appear before every single command, cluttering the scroll back log and driving the developers crazy.
Recommendation – Custom Prompt
A custom prompt will update the command prompt on the Command Line Interface. By default the prompt will only contain the appliance type:
|
1 |
xi52#: |
This is not very informative. Setting the customer prompt to ‘%s’ (the only value that is allowed for this element) will cause the prompt to include the value of the Appliance Name field in the System Settings.
My recommendation is that the Appliance Name use the following pattern:
- <Environment>@<hostname>
|
1 |
DEV@dp322-02:xi52#: |
This will ensure that the user knows exactly what appliance and environment of the device they are connected to in a non-intrusive way.
Conclusion
While the custom user interface hook in DataPower is limited in customization, it can be used to remind developers of the environment the device represents. The configuration file itself is very small and this feature can be enabled in a few minutes.
The custom user interface is a quick win that can reduce changes made to the wrong device.
About the Author
Share this Post