Finding out the VisiBroker configurations and analysing the logs are the routine tasks when troubleshooting VisiBroker application issues. Unfortunately, many users are unable to provide this information quickly and accurately due to their unfamiliarity with VisiBroker and their own application’s implementation. This usually leads to unnecessary delays in understanding the runtime environment and scenario that may have caused the problem.

VBUtility is a tool designed to help you troubleshoot VisiBroker for Java and C applications. Its two main functions are:

1. To facilitate the extraction of the VisiBroker configurations from your application.
2. To change VisiBroker log levels dynamically without restarting your application.

To use VBUtility Tool, you just need to plug in VBUtility to your existing VisiBroker for Java or C application. There is no need to rewrite/rebuild your application. A VBUtility Console is provided to enable you to interact with the VBUtility Plug-in to extract the VisiBroker configurations and control the log levels.

Please contact Micro Focus SupportLine to get a copy of the VBUtility Tool. Some Demos are provided to teach you how to use it.

As a prerequisite, you must have the proper VisiBroker 8.5 installation, license and runtime environment in order to run VBUtility Tool and the Demos.

Frequently Asked Questions:

1. What VisiBroker configurations can be extracted by VBUtility?

2. What logging operations can be performed?

3. How to plug in VBUtility to a Java Application?

4. How to plug in VBUtility to a C Application?

5. Pre-configuring the Logger in your VisiBroker Application

6. How to start VBUtility Console?

7. How to specify the Server which you want to troubleshoot?

8. How to plug in VBUtility to a Security enabled Java Application?

9. How to plug in VBUtility to a Security enabled C Application?

10. How to connect VBUtility Console to a Security enabled Application?

11. How to plug in VBUtility to a specific Server Engine in a multiple Server Engines configuration?

12. What are the Platforms available?

13. How to get a copy of VBUtility Tool?

14. Disclaimer

1. What VisiBroker configurations can be extracted by VBUtility?

The following VisiBroker configurations can be extracted by VBUtility Console:

1. VisiBroker properties set by the application

2. Operating System Environment Variables

3. JVM System Properties (VBJ only)

4. POAs' Policies set in each POA

5. ORB Level Policies

6. Version number of the VisiBroker libraries used by the application

• • “vbsec.jar” and “vbjorb.jar” for VBJ.
  • The various shared libraries for VBC .

7. Connections and Worker Threads usage in each Server Engine (VBJ only)

8. Connections usage in the Client Engine (VBJ only)

The VisiBroker configurations are printed to the Console and also written to the VBUtility Console log file specified by the property “vbroker.debugger.console.logFile”. The default file name is "vbdebugger.log". You should attach this log file when reporting a VisiBroker Support Incident so that the Support Engineer knows the VisiBroker configurations in your environment.

2. What logging operations can be performed?

Using the VBUtility Console, you can perform the following logging operations dynamically without restarting the application:

1. Enable and disable logging globally and also for individual log filter anytime.
2. Change the log level globally and also for individual log filter anytime.

The VisiBroker logs are printed to the VBJ and VBC application’s console or rolling log files. You can attach these log files to the Support Incident as it may help the Support Engineer understand the runtime events leading to the problem.

3. How to plug in VBUtility to a Java Application?

The VBUtility Java Plug-in implementation is in “vbdebug.jar”.

Assume currently you are starting your VBJ Server application with the following command:

vbj -DORBpropStorage=visibroker_server.properties Server

To plug in the VBUtility to your VBJ Server, you need to ensure “vbdebug.jar” is present in the Java CLASSPATH. You can start your Server with the following command:

vbj -classpath <VBUtility Install>/lib/vbdebug.jar -Dvbroker.orb.dynamicLibs=com.inprise.vbroker.debugger.Init -DORBpropStorage=visibroker_server.properties Server

The VBUtility's IOR is written to a file specified by "vbroker.debugger.iorFile". The default VBUtility IOR filename for a VBJ Server is "vbdebugj.ior". You may set this IOR file in the Console to connect to the VBUtility. Other ways of connecting to VBUtility is documented in FAQ 7.

Please refer to the Java example in “demo/bank_agent” for more information.

4. How to plug in VBUtility to a C Application?

The VBUtility C Plug-in implementation is in the shared libraries “DebugContainerInit.so” (Security disabled) and “DebugContainerInitSec.so” (Security enabled).

Assume currently you are starting your VBC Server application (without Security) with the following command:

Server -DORBpropStorage=visibroker_server.properties

To plug in the C VBUtility to your VBC Server, you can start your application with the following command:

Server -Dvbroker.orb.dynamicLibs=<VBUtility Install>/lib/DebugContainerInit.so -DORBpropStorage=visibroker_server.properties

Notes:

• The file extension of the VBUtility libraries for Windows platform is “.dll” and for Unix/Linux platforms is “.so”.
• You must plug in the C VBUtility from the same platform and bit size as your VBC application.

The VBUtility's IOR is written to a file specified by "vbroker.debugger.iorFile". The default VBUtility IOR filename for a VBC Server is "vbdebugc.ior". You may set this IOR file in the Console to connect to the VBUtility. Other ways of connecting to VBUtility is documented in FAQ 7.

Please refer to the C example in “demo/bank_agent” for more information.

5. Pre-configuring the Logger in your VisiBroker Application

The VisiBroker properties file (e.g. visibroker_server.properties in the above examples) contains the necessary properties used to configure the VisiBroker ORB. On top of that, you should pre-configure the logger filters and rolling log files in the properties file before starting the application.

For example:

vbroker.log.enable=false
vbroker.log.logLevel=info
vbroker.log.default.filter.all.enable=true
vbroker.log.default.filter.register=cdr,connection,agent,se,server,orb,client
vbroker.log.default.filter.cdr.enable=true
vbroker.log.default.filter.cdr.logLevel=info
vbroker.log.default.filter.connection.enable=true
vbroker.log.default.filter.connection.logLevel=info
vbroker.log.default.filter.agent.enable=true
vbroker.log.default.filter.agent.logLevel=info
vbroker.log.default.filter.se.enable=true
vbroker.log.default.filter.se.logLevel=info
vbroker.log.default.filter.server.enable=true
vbroker.log.default.filter.server.logLevel=info
vbroker.log.default.filter.orb.enable=true
vbroker.log.default.filter.orb.logLevel=info
vbroker.log.default.filter.client.enable=true
vbroker.log.default.filter.client.logLevel=info
vbroker.log.default.appenders=rolling
vbroker.log.default.appender.rolling.appenderType=rolling
vbroker.log.default.appender.rolling.maxFileSize=10
vbroker.log.default.appender.rolling.maxBackupIndex=50
vbroker.log.default.appender.rolling.logDir=./
vbroker.log.default.appender.rolling.fileName=visibroker_server.log

Please refer to the Demos for more examples.

6. How to start VBUtility Console?

The VBUtility Console is a regular VBJ Client and its implementation is in “vbdebugcli.jar”. Hence you need to ensure that “vbdebugcli.jar” is present in the Java CLASSPATH. You can start the VBUtility Console with the following command:

vbj -classpath <VBUtility Install>/lib/vbdebugcli.jar com.inprise.vbroker.debugger.VBDebuggerClient

Please refer to the Demos for more examples.

7. How to specify the Server which you want to troubleshoot?

If multiple Servers (with VBUtility plug-in) are deployed in your environment, how do you identify and specify the target Server, which you want to troubleshoot, inside the VBUtility Console?

There are 5 available options in the VBUtility Console to specify the target Server:

1. By Naming Service
2. By IOR file
3. By IOR String, corbaloc or corbaname
4. By Osagent Bind Support by POA
5. By Osagent Bind Support by Instance

The most suitable option depends on how the Server Object Reference is advertised and how the Clients obtain the Server Object Reference.

The following are some recommendations:

If the VBUtility IOR file of the target Server is accessible by VBUtility Console.

• When the VBUtility is plugged in successfully to the Server, it's IOR is written to a file specified by "vbroker.debugger.iorFile". The default VBUtilityIOR filename for a VBJ Server is "vbdebugj.ior" and for a VBC Server is "vbdebugc.ior".
• Choose option “2. By IOR file” and specify the file system path of the VBUtility IOR file. For example, “/home/java_server/vbdebugj.ior” or “/home/cpp_server/vbdebugc.ior”.

If the target Server Object Reference IOR file is accessible by VBUtility Console.

• Choose option “2. By IOR file” and specify the file system path of the IOR file. For example, “/home/bank/manager.ior”.

If you know the Hostname/IP address and IIOP listener port of the target Server.

• Choose option “3. By IOR String, corbaloc or corbaname” and specify the corbaloc of the VBUtility plug-in. For example, “corbaloc::Host:port/VBDebugger”.
• Note that this option does not support SSL listener port.

If you know the target Server Object Reference IOR string, corbaloc or corbaname.

• Choose option “3. By IOR String, corbaloc or corbaname” and specify the IOR String, corbaloc or corbaname of the target Server Object.
• For Examples:

• IOR:000000000000002b49444c3a6f6d672e6f72672f436f734e616d6 . . .
• corbaloc::Host:port/key_string
• corbaname::NamingServiceHost:port#Java.Lang/BankManager.Role

If the Server Object is bound to Naming Service, and you know its full Naming Context.

• Bootstrapped the Naming Service when starting the VBUtility Console. For example, vbj -DORBInitRef=NameService=file:./ns.ior  ...  com.inprise.vbroker.debugger.VBDebuggerClient
• Choose option “1. By Naming Service” and specify the full Naming Context of the target Server Object. For example, "Java.Lang/BankManager.Role".

If the Server Object is registered to the osagent by POA, and you know its “POA Name” and “Object Id”.

• Choose option “4. By Osagent Bind Support by POA” and specify the “POA Name” and “Object Id”, such as "/bank_agent_poa" and "BankManager" respectively.
• You may specify the optional HostName/IP Address which the Server is running on.

If the Server Object is registered to the osagent by Instance, and you know its “Repository Id” and “Instance Name”.

• Choose option “5. By Osagent Bind Support by Instance” and specify its “Repository Id” and “Instance Name”, such as "IDL:Bank/AccountManager:1.0" and "BankManager" respectively.
• You may specify the optional Hostname/IP Address which the Server is running on.

Please refer to the Demos for more information.

8. How to plug in VBUtility to a Security enabled Java Application?

You must set the additional property “vbroker.debugger.security.disable=false” to enable Security for the VBUtility Plug-in. The default value is “true”, which means Security is disabled.

You should also configure the additional Java Security log filter source name, i.e. “secure”.

Please refer to the Java example in “demo/bank_ssl” for more details.

9. How to plug in VBUtility to a Security enabled C Application?

You must set the additional property “vbroker.debugger.security.disable=false” to enable Security for the VBUtility Plug-in. The default value is “true”, which means Security is disabled.

You must set the shared library “DebugContainerInitSec.so” to the “vbroker.orb.dynamicLibs” property. Note that the file extension of the VBUtility libraries for Windows platform is “.dll” and for Unix/Linux platforms is “.so”.

You should also configure the additional C Security log filter source names, i.e. “v_secauthn”, “v_secauthz”, “v_secssl”, “v_seccsiv2”and “v_secmisc”.

Please refer to the C example in “demo/bank_ssl” for more details.

10. How to connect VBUtility Console to a Security enabled Application?

The VBUtility Console is just a regular VBJ Client Application. So VisiBroker Security properties can be used to configure its Security credentials (such as certificates, trustpoints, peer authentication mode, etc.) so that it can establish a secured SSL connection to the Server.

Please refer to the “demo/bank_ssl” for more details.

11. How to plug in VBUtility to a specific Server Engine in a multiple Server Engines configuration?

Your current application may already be configured with multiple Server Engines in a multi-homed machine so that each Server Engine listens on a different IP address and has different level of Security protection. You can plug in VBUtility to a specific Server Engine by setting the “vbroker.debugger.seName” property.

For example, if the current Server Engine names are “SE_A” and “SE_B” which service requests from Network A and Network B respectively. If you felt that it is more convenient to perform administrative tasks (such as troubleshooting) in Network A, you can plug in VBUtility in “SE_A” by setting “vbroker.debugger.seName=SE_A”.

Please refer to the “demo/hybrid_secure” for a working example.

12. What are the Platforms available?

The following platforms are currently available for VisiBroker 8.5:

• SUSE 32-bits
• SUSE 64-bits
• Redhat 32-bits
• Redhat 64-bits
• Solaris Sparc 32-bits
• Solaris Sparc 64 bits
• Solaris Intel 32-bits
• Solaris Intel 64-bits
• Windows 32-bits (Visual Studio 2008 SP1)
• Windows 64-bits (Visual Studio 2008 SP1)
• AIX (Java-Only)
• HPUX-IA (Java-Only)

If you need a platform not listed above, please raise a Support Incident at http://supportline.microfocus.com.

13. How to get a copy of VBUtility Tool?

Please raise a Support Incident at http://supportline.microfocus.com to get a copy the VBUtility Tool. Please state the platform required. We will get back to you as soon as possible.

The latest version of VBUtility Tool is 1.6.0.

14. Disclaimer

This software is provided "as is" without warranty of any kind. Micro Focus disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall Micro Focus or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Micro Focus or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages so the foregoing limitation may not apply.

Micro Focus is a registered trademark.

Copyright (C) Micro Focus 2015. All rights reserved.