Thursday Mar 15, 2012

GlassFish Clustering with DCOM on Windows

DCOM - Distributed COM, a Microsoft protocol for communicating with Windows machines.

Why use DCOM?

  • In GlassFish 3.1 SSH is used as the standard way to run commands on remote nodes for clustering.  It is very difficult for users to get SSH configured properly on Windows.  SSH does not come with Windows so we have to depend on third party tools.  And then the user is forced to install and configure these tools -- which can be tricky.
  • DCOM is available on all supported platforms.  It is built-in to Windows.
The idea is to use DCOM to communicate with remote Windows nodes.  This has the huge advantage that the user has to do minimal, if any, configuration
on the Windows nodes.

Implementation Highlights

Two open Source Libraries have been added to GlassFish:
  • Jcifs – a SAMBA implementation in Java
  • J-interop – A Java implementation for making DCOM calls to remote Windows computers.  

Note that any supported platform can use DCOM to work with Windows nodes -- not just Windows.
E.g. you can have a Linux DAS work with Windows remote instances.

All existing SSH commands now have a corresponding DCOM command – except for setup-ssh which isn’t needed for DCOM.  
validate-dcom is an all new command.

New DCOM Commands

  • create-node-dcom
  • delete-node-dcom
  • install-node-dcom
  • list-nodes-dcom
  • ping-node-dcom
  • uninstall-node-dcom
  • update-node-dcom
  • validate-dcom
  • setup-local-dcom (This is only available via Update Center for GlassFish 3.1.2)

These commands are in-place in the trunk (4.0).  And in the branch (3.1.2)

Windows Configuration Challenges

There are an infinite number of possible configurations of Windows if you look at it as a combination of main release, service-pack, special drivers, software, configuration etc.  Later versions of Windows err on the side of tightening security be default.  This means that the Windows host may need to have configuration changes made.
These configuration changes mostly need to be made by the user.  setup-local-dcom will assist you in making required changes to the Windows Registry.  See the reference blogs for details.

The validate-dcom Command

validate-dcom is a crucial command.  It should be run before any other commands.  If it does not run successfully then there is no point in running other commands.
The validate-dcom command must be used from a DAS machine to test a different Windows machine.  
If  validate-dcom runs successfully you can be confident that all the DCOM commands will work.  Conversely, the opposite is also true:  If validate-dcom fails, then no DCOM commands will work.

What validate-dcom does

  1. Verify that the remote host is not the local machine.
  2. Resolves the remote host name
  3. Checks that the remote DCOM port is being listened on (135, 139)
  4. Checks that the remote host’s File Sharing is enabled (port 445)
  5. It copies a file (a script) to the remote host to verify that SAMBA is working and authorization is correct
  6. It runs a script that it copied on-the-fly to the remote host.

Tips and Tricks

The bread and butter commands that use DCOM are existing commands like create-instance, start-instance etc.   All of the commands that have dcom in their name are for dealing with the actual nodes.

The way the software works is to call asadmin.bat on the remote machine and run a command.  This means that you can track these commands easily on the remote machine with the usual tools.  E.g. using AS_LOGFILE, looking at log files, etc.  It’s easy to attach a debugger to the remote asadmin process, “just in time”, if necessary.

How to debug the remote commands:
Edit the asadmin.bat file that is in the glassfish/bin folder.  Use glassfish/lib/nadmin.bat in GlassFish 4.0+
Add these options to the java call:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=1234
  Now if you run, say start-instance on DAS, you can attach your debugger, at your leisure, to the remote machines port 1234.  It will be running start-local-instance and patiently waiting for you to attach.

Thursday Mar 01, 2012

GlassFish DCOM Configuration Utility

Version 3.1.2 of GlassFish adds support for communicating with Windows remote hosts over DCOM.  DCOM is a communications protocol from Microsoft.  All Windows versions that GlassFish supports come with DCOM support built-in.  

In these days of high-security on Windows,  using DCOM may well require a few configuration steps.  One of the more challenging steps is to edit the Windows Registry.

We are using DCOM to run GlassFish processes on the remote Windows machines (we call them nodes).  What we do is the same thing command-line users do -- run asadmin on the remote machine.  Asadmin.bat is a script and in order to remotely run scripts you must have permissions set in the Windows Registry.  In fact you need two Registry entries set to give permission to the Administrators group.  These two are:

  1. WMI - Windows Management Interface
  2. WBEM Scripting

The problem with these 2 registry keys is that in many versions of Windows they are owned by an account named TrustedInstaller.  And by default the Administrators group have no permissions at all.  (Yes , I said the owner of the key -- Registry keys have owners with access control lists exactly analogous to files).  In my humble opinion this is a Windows Bug! 

Setting-up the registry keys correctly is fairly involved.  There are significant complications for 32 bit versus 64 bit Windows.  Windows does automatic redirection of Registry Keys.  You're probably thinking -- "This is just too painful to bear!".  And you are right.  That's why I wrote a C++ Windows program that does all of the registry changes for you.  But that's not all!  I embedded this C++ program inside a jar file that also contains an asadmin extension command.  In order to do the editing of the registry keys you simply need to deploy the extension command and run it one time on each Windows machine.  And then only if you need to run it.

The name of the command is setup-local-dcom.  You can get it from Update Center under contributions.  See my other blog for instructions on exactly how to get it from Update Center.

Instructions for running setup-local-dcom

  • Backup the Registry just in case.
  • Run the command on the Windows machine that will be used as a remote node for GlassFish
  • You need to be logged in to an account that is a member of the Administrators group.
  • run the following to see the manual page:
    asadmin setup-local-dcom --help

  • Run the command to edit the registry keys, if needed.  Use the --verbose option to get a report of what it did.
  • Note that the command makes you type in yes and hit return to give you one last chance to change your mind.  If you find that annoying use the --force option and it will silently run.
  • If the command was successful then go to any other computer that can access it and run the validate-local-dcom command against the machine you just ran setup-local-dcom on.  If validate-local-dcom runs successfully then all clustering commands should work fine in your distributed environment.  If validate-local-dcom fails then see another blog that describes further configuration steps you may need to make on the Windows node.

Example Output of setup-local-dcom --verbose

d:\>asadmin setup-local-dcom -v
Caution: This command might modify the permissions of some keys in the Windows registry.
Before running this command, back up the Windows registry.
The modification allows the Windows user full control over these keys.

Are you sure that you want to edit the Windows registry? If so, type yes in full:  yes
>>>>>>>>>>>>>                          <<<<<<<<<<<<<
>>>>>>>>>>>>>   Set to Verbose Mode    <<<<<<<<<<<<<
>>>>>>>>>>>>>                          <<<<<<<<<<<<<
Administrators group SID: [S-1-5-32-544]
Key: [CLSID\{72C24DD5-D70A-438B-8A42-98424B88AFB8}]  Owner: [S-1-5-32-544]
Key: [CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}]  Owner: [S-1-5-32-544]
Redirected Key: [Wow6432Node\CLSID\{72C24DD5-D70A-438B-8A42-98424B88AFB8}]
Redirected Key: [Wow6432Node\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}]
No need to adjust the Scripting Registry Key.
No need to adjust the WMI Registry Key.
>>>>>>>>>>>>>                          <<<<<<<<<<<<<
>>>>>>>>>>>>>   Set to Verbose Mode    <<<<<<<<<<<<<
>>>>>>>>>>>>>                          <<<<<<<<<<<<<
Administrators group SID: [S-1-5-32-544]
Key: [CLSID\{72C24DD5-D70A-438B-8A42-98424B88AFB8}]  Owner: [S-1-5-32-544]
Key: [CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}]  Owner: [S-1-5-32-544]
Redirected Key: [Wow6432Node\CLSID\{72C24DD5-D70A-438B-8A42-98424B88AFB8}]
Redirected Key: [Wow6432Node\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}]
No need to adjust the Scripting Registry Key.
No need to adjust the WMI Registry Key.

Command setup-local-dcom executed successfully.

Friday Jul 16, 2010

GlassFish V3.1 Offline Configuration

Clustering support is available now in pre-release GlassFish 3.1  In this blog I will show you how to perform Offline Configuration in GlassFish 3.1

I've blogged about  why and how to do Offline Configuration here.

One big difference between GlassFish V2 and GlassFish 3.1 clustering is that node agents are not provided and used in GlassFish 3.1.  Instead ssh is utilized.  Using ssh in GlassFish 3.1 is the subject of a different future blog.  In this blog I'll demonstrate how to setup a distributed GlassFish 3.1 system without node-agents or new ssh features.

The Desired Environment

  • DAS running on improvident
  • One cluster
  • The cluster has one instance
  • DAS and the instance run on different machines


  • The names are just the names of the machines I happened to use.
  • This is as simple a distributed system as possible for demonstration purposes. 
  1. machine1 = samskritam
  2. machine2 = improvident

  • install the same  GlassFish 3.1installation files on each machine. 
  • DAS (domain1) is used on samskritam. 
  • The other machine never runs DAS.
  • improvident has this set in its environment -- This makes it easy to run asadmin commands.
    • AS_ADMIN_HOST=samskritam
  • In the Procedure section I'm using these conventions:
    1. I put the name of the machine where the command is running at the beginning of the line - you wouldn't type that in.
    2. Comments are in italics
    3. Output from asadmin is bold


  1. [samskritam] asadmin start-domain
  2. [samskritam] asadmin create-cluster mycluster
  3. [samskritam] asadmin create-node-config --nodehost improvident imp
  4. [samskritam] asadmin create-instance --cluster mycluster    --node imp mycluster_i1
  5. [improvident] asadmin create-local-instance --node imp mycluster_i1
  6. [improvident] asadmin start-local-instance mycluster_i1


On Samskritam:

samskritam% asadmin start-domain
Waiting for the server to start ....
Successfully started the domain : domain1
domain location: /home/kedar/glassfishv3/glassfish/domains/domain1
Log File: /home/kedar/glassfishv3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
samskritam% asadmin create-cluster mycluster
samskritam% asadmin create-node-config --nodehost improvident imp
samskritam% asadmin create-instance --cluster mycluster    --node imp mycluster_i1
remote failure:
Successfully created instance mycluster_i1 in the DAS configuration, but failed to create the instance files. Please run:

asadmin --host samskritam.SFBay.Sun.COM --port 4848 create-local-instance --node imp mycluster_i1

on improvident to complete the transaction.


On improvident:

~>asadmin create-local-instance --node imp mycluster_i1
Attempting to rendezvous with DAS on host samskritam port 4848
Uptime: 1 minutes, 31 seconds

The instance has rendezvoused with the DAS and will be using host samskritam port 4848 for future communication.

~>asadmin start-local-instance mycluster_i1
Waiting for the server to start ......................................
Successfully started the instance: mycluster_i1
instancelocation: /export/home/bnlocal/glassfishv3/glassfish/nodeagents/improvident/mycluster_i1
Log File: /export/home/bnlocal/glassfishv3/glassfish/nodeagents/improvident/mycluster_i1/logs/server.log
Admin Port: 24848
~>asadmin list-clusters
mycluster running

~>asadmin list-instances --verbose
Instance Name   Host Name     Admin Port   Cluster     Current State
mycluster_i1    improvident      24848      mycluster  Uptime: 15 minutes, 11 seconds

Monday Feb 15, 2010

GlassFish v2 Offline Configuration

Review of Clustering Features in GlassFish v2

A typical GlassFish v2 enterprise installation consists of one administration domain controlled by the Domain Administration Server (DAS) which handles all of the administration duties of the domain.  The  domain provides a common  authentication and administration point for a collection of Java EE server instances.

Each JavaEE server instance gets it's configuration from DAS and has its lifecycle controlled by a Node Agent.  A Node Agent is a very light-weight process that DAS interacts with.  Node Agents and remote Java EE server instances synchronize with DAS during startup to get the latest configuration from the central repository managed by DAS.

GlassFish v2 supports the concept of cluster where multiple Java EE server instances can be grouped for horizontal scalability. Each Java EE server instance in a cluster shares the same set of applications and configuration information.

Typical Configuration

Say you have a running DAS (Domain Administration Server) and you wish to add a cluster, a few instances and a Node Agent running on a separate machine.  Here is how you would do an online configuration:

  1. Login to the new Node Agent machine
  2. asadmin create-node-agent NA-Name
  3. asadmin create-cluster
  4. asadmin create-instance (probably need to run this command a few times)
  5. asadmin start-node-agent

 You can see how if you have a lot of machines this can become a headache.  Note that create-instance has many required parameters that I'm not showing here.

Offline Configuration

Offline Configuration lets you do all of the configuration right from the DAS machine.  On each Node Machine you run two very simple commands:

  • asadmin create-node-agent NA-Name
  • asadmin start-node-agent NA-Name

There are several good reasons for developing scripts for offline configuration of complex GlassFish installations:

  • You can develop scripts that will exactly recreate your system from scratch.  I'm talking about deploying your applications, setting complicated jvm-options, configuring database connections, setting up multiple clusters and instances -- the works!  This is very powerful.  I have a personal website that has been running v2 for 4 years or so.  I can recreate the entire site anytime I like on any new machine that has v2 installed.  It has a ton of applications, a database, etc.
  • You need the complicated configuration information to be used on just one machine, DAS, in a multiple machine installation.
  • You can replace a Node easily at any time
  • No restarts are needed during the creation of the instance, cluster and node-agent configuration since it is all being done offline.  Once ALL of the configuration is complete everything is started at once and no restarts will be needed.  This is a key difference with online configuration.
  • Faster to automate a multi-node GlassFish cluster setup with desired configuration.
  • It works!

Example Offline Configuration Session

Generally one would want to edit a script and run the script.  Here is a an example session to show you how to do it from a command line:

(For clarity the credentials such as --user and --passwordfile are left out of the commands)

  • asadmin start-domain
  • asadmin create-cluster c1
  • asadmin create-node-agent-config na1
  • asadmin create-node-agent-config na2
  • asadmin create-instance --cluster c1 --node-agent na1 i1_1
  • asadmin create-instance --cluster c1 --node-agent na2 i2_1
  • asadmin create-instance --cluster c1 --node-agent na2 i2_2

We didn't start anything.  All of the commands changed the configuration in the domain.xml.  Namely it created 1 new cluster with 2 node agents and a total of 3 instances.

To get everything running we do this:

  • For each machine (in this case 2 separate remote machines with v2 binaries installed)
    • asadmin create-node-agent na1 or na2
    • asadmin start-node-agent na1 or na2
    • note: the Node Agent name must match exactly the name in create-node-agent-config above.  Otherwise you will get a new Node Agent created!

Example Script

Kedar Mhaswade created  the attached example shell script.  The script demonstrates how you can automate building a four-machine Enterprise GlassFish v2 Installation.





« March 2015