BladeLogic Command Line Interface (BLCLI)

Table of Contents
Table of Contents.......................................................................................................................................... 1
1. Introduction ........................................................................................................................................... 2
1.1. Overview ..................................................................................................................................... 2
2. Best Practice........................................................................................................................................... 3
2.1. Before We Begin ......................................................................................................................... 3
2.1.1. A Brief Overview of the BLCLI............................................................................................. 3
2.1.2. How is the BLCLI useful? ...................................................................................................... 3
2.1.3. How do I read the BLCLI API?.............................................................................................. 3
2.1.4. Common Uses of the BLCLI.................................................................................................. 4
2.2. Caching Credentials .................................................................................................................... 4
2.2.1. Encoded .dat File .................................................................................................................... 4
2.2.2. BLTray Utility ........................................................................................................................ 5
2.3. Server / Proxy Mode.................................................................................................................... 5
2.3.1. blcli2.exe ................................................................................................................................ 6
2.3.2. Without blcli2.exe .................................................................................................................. 6
2.4. Other Possibilities for Increasing Speed of the BLCLI ............................................................... 8
2.4.1. Using the Subshell .................................................................................................................. 8
2.4.2. Experimental: Using Jython ................................................................................................... 8
2.5. Options and Recommendations for Production Implementation................................................. 9
2.5.1. Starting Server from Within Script......................................................................................... 9
2.5.2. Running Server as Service...................................................................................................... 9
3. Behind the Scenes .................................................................................................................................. 9
3.1. How the BLCLI works ................................................................................................................ 9
3.1.1. Released / Unreleased Commands........................................................................................ 10
3.1.2. Context and the Target Object .............................................................................................. 10
3.1.3. API Commands..................................................................................................................... 11
3.1.4. Load Commands................................................................................................................... 11
3.1.5. Save Commands ................................................................................................................... 11
3.1.6. Procedure Commands........................................................................................................... 11
3.2. Complex Commands ................................................................................................................. 12
3.2.1. Complex Commands – Piece by Piece ................................................................................. 12
3.2.2. SmartServerGroup createNewGroup Explained................................................................... 14
4. Appendices ........................................................................................................................................... 17
4.1. BLCLI Usage and Flags ............................................................................................................ 17
4.2. Troubleshooting the BLCLI ...................................................................................................... 17
4.3. Compiling Unreleased API Documentation .............................................................................. 17

1 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
1. Introduction
1.1. Overview
The goal of this document is to discuss the Best Practices for using the
BladeLogic Command Line Interface, better known as the BLCLI. In its present
form, this document is intended to remain internal to BladeLogic Professional
Services, as it will explore some aspects of the BLCLI functionality not yet
completely available to our customers. There is a trimmed-down version of this
document available for our clients.

We will begin with an introduction of the BLCLI, a discussion of why it is useful

and how it works, and then will explain how to read the API documentation
before moving on to more complicated concepts. The paper continues to discuss
cached credentials and the BLCLI server / proxy mode. This paper next reviews
possibilities for increasing execution speed of the BLCLI before making
recommendations regarding production implementation.

The next section provides an in depth look at how the BLCLI works, unreleased
commands, session context, and command types. This section also explains each
section of a complex command, in detail, before explaining in detail a specific
example command, SmartServerGroup createNewGroup.

Finally, the appendices discuss usage details of the BLCLI. Next, the paper looks
at how to troubleshoot building BLCLI Complex commands, before finally
explaining how to compile the API documentation for unreleased BLCLI
commands.

2 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
2. Best Practice
2.1. Before We Begin
2.1.1. A Brief Overview of the BLCLI
The BladeLogic Command Line Interface is a Java-based command line tool,
hence its name, for accessing BladeLogic API operations. Though released
functionality remains somewhat limited, a sufficiently sophisticated user could
conceivably use the BLCLI to complete any operations through the command line
that would traditionally be only accessible via the BladeLogic GUI. The BLCLI
tool accepts input from the command line, parses that input, and processes that
input against XML-formatted commands to become the user’s bridge to the
BladeLogic API.

The BLCLI is not a shell. It is its own application command line interface, as
every command line execution requires the BLCLI to startup and shutdown. As
each instance of a BLCLI execution requires the Java Virtual Machine (JVM) to
start and for the BLCLI to authenticate against the Application Server, by default,
each BLCLI command takes a significant amount of time to execute. There are
ways to get around this, and we will discuss them in more detail later in this
document.

Each BLCLI command is broken down into three parts, Namespace, Command,
and Arguments. These are defined in the XML command descriptor files that the
BLCLI uses to know how to execute each command. The BLCLI commands
should take the following format:

blcli NameSpace commandName <Argument1> … <ArgumentN>

The argument number and data type(s) depend on the command and are explained
in the API documentation available in the Doc directory of each Operations
Manager installation. BLCLI commands can be scripted using Network Shell,
Perl Scripts, Batch Jobs, or other languages that can execute system calls.

2.1.2. How is the BLCLI useful?

Before the BLCLI, there was no way to automate functions within the BladeLogic
GUI. The BLCLI allows a user more functionality than merely accessing the GUI
operations programmatically; it allows us to script it using any native system or
installed scripting language that can make system-level calls, as BLCLI calls are
usually called from within a shell.

2.1.3. How do I read the BLCLI API?

The BLCLI Help and API documentation are installed with each installation of
Operations Manager, whether the Application Server or just the Configuration
Manager. This documentation is installed to
<blinstall_dir>/Doc/cli/index.html. Available from this page is a short
Help screen, explaining some BLCLI basics for new users.

3 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 The BLCLI API is a set of HTML files organized into 3 frames. The left top
frame is the list of namespaces, with the commands for the selected namespace in
the frame below that. The namespace commands appear in the main frame along
with descriptions, return types, and argument lists. The argument lists are in a
table but, of course, should be passed as command line arguments when executing
the BLCLI. Arguments as String data types require quotes if the value has any
white space.

2.1.4. Common Uses of the BLCLI

The BLCLI becomes more and more useful every day. BladeLogic Professional
Services now includes Network Shell scripts calling BLCLI commands in every
implementation to populate custom server properties based on data
programmatically acquired via Network Shell commands. These custom
properties are then used in our standard custom inventory reports accessible from
BladeLogic Reports.

The BLCLI can be used to load bulk data into the BladeLogic system via a script.
Using BLCLI extended functionality, we can write a script to parse a formatted
data file and pre-load virtually any data into the BladeLogic system with BLCLI
commands during the initial implementation.

We can use the BLCLI command to sidestep issues. One recent use involved
setting up a NSH script job to call a script that would retrieve information from
BladeLogic, use that information to compile a SQL statement, and execute that
SQL statement against the BladeLogic database. This solves a problem of setting
BlPackage ownership, a construct that does not presently exist within the
BladeLogic code base.

2.2. Caching Credentials

As each execution of the BLCLI requires authentication against the BladeLogic
Application Server, a user must provide login information each time the BLCLI is
called. Executing scripts with BLCLI commands necessitates a way to cache
credentials, so the BLCLI does not actively request input from the user. We can
accomplish this credential caching in multiple different ways: generating an
encoded data file, the BLTray tool, and with the BLCLI server. The first two will
be discussed in this section, but the Server / Proxy mode is saved for the next
section.

2.2.1. Encoded .dat File

A user can cache credentials in a file generated by the
<blinstall_dir>/br/bl_gen_blcli_user_info.bat file. This script will
cache a user’s username, password, and chosen role in encoded format. There are
two ways of using this file. One may execute the BLCLI with a –i flag,
specifying which encoded file to use as a user’s cached credentials. As a second
option, a user may save the file as user_info.dat, and copy the file to the
<user_home>/Application Data/BladeLogic/user/ directory on Windows,
or to the <user_home>/.bladelogic/.user on UNIX/Linux. The <user_home>
directory on Windows is the user’s username directory within /Documents and
Settings.
4 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 When running a NSH script with BLCLI commands as a NSH Script Job by the
Application Server, the user_info.dat file must be saved in the <user_home>
directory on the server of the user as whom the server is running. On Windows,
the BladeLogic server runs as LocalSystem. It is not always obvious which path
leads us to the LocalSystem <user_home> directory, but we can perform a quick
trick to discover this path.

Ensure that the Windows ‘Task Scheduler’ service is running. From a

command line (cmd) Window, type at <time+> /interactive cmd.exe, where
<time+> is some HH:MM formatted time some minutes in the future. Because the
‘Task Scheduler’ service runs as the LocalSystem account, the cmd.exe window
that opens when the specified scheduled time arrives will inherit LocalSystem
privileges with the Windows Id ‘SYSTEM’. Once in here, you may type ‘echo
%USERPROFILE%’, though this may not work on all Windows releases. Because
Network Shell must be installed on the Application Server, start Network Shell
(nsh) and ‘echo $USERPROFILE’ will return the LocalSystem account’s
<user_home>.

On UNIX, the task is much simpler. The BladeLogic server runs as bladmin and
the <user_home> directory can be determined either by running sudo –u
bladmin echo $HOME as root or as a user with root privileges or by becoming
the bladmin user and running cd ~; pwd.

2.2.2. BLTray Utility

The BLTray is a tool found in the <blinstall_dir>/bin/ directory, using
Stanford University’s Open-Source Secure Remote Password (SRP) protocol with
which, while running, will cache login information in memory on the workstation
running the BLTray. There is no communication between the BLTray and the
BladeLogic server.

To execute the BLTray, go to a command prompt in the above mentioned folder

and type ./bltray.exe –srp. A window will appear asking for the username,
password, and role with which you would like to authenticate against the
BladeLogic Application Server. Once this is active, it will appear as an icon in
your taskbar tray, to the left of your system clock. While active, you will be able
to execute BLCLI commands without authenticating. When you are finished, you
may right-click on the BLTray icon to exit.

2.3. Server / Proxy Mode

The BLCLI provides users with the capability to proxy commands through a
BLCLI Server. In server mode, the BLCLI authenticates once against the
BladeLogic Application Server and waits, listening on a specific port as a Server.
Another call to the BLCLI can proxy through this server, thereby piggybacking
on the already authenticated persistent connection. One thing to note is that, in
server mode, the BLCLI only accepts proxy connections from localhost. We can
use the experimental Windows executable (blcli2.exe) to achieve this
functionality or, if this option is unavailable, we can create batch or script files to
do this. These methods are addressed in the following two sections.
5 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
2.3.1. blcli2.exe
With the release of BladeLogic version 6.2, there exists an experimental version
of the BLCLI executable, blcli2.exe. This executable will allow greater
manipulation of the BLCLI without modifying batch files. With this, we may
easily instantiate a BLCLI Server and use the BLCLI proxy through that server.

Presently, this experimental version only exists for Windows implementations,

but you will see in the next section that we can implement this same functionality
on UNIX and on Windows versions prior to 6.2. The blcli2 executable is a
wrapper around the Java executable, expanded from the standard blcli
executable. The blcli2 allows us to pass a single –D Java Properties argument to
the JVM upon execution, as well as accepting a –c flag to connect to a specific
port with the BLCLI proxy.

In order to instantiate the BLCLI server with blcli2, execute the following
command from within Network Shell:

blcli2 –Dcom.bladelogic.cli.port=<port#> –m server

Where <port#> is port on which the server should listen, and –m server starts the
BLCLI in server mode. The port most often used is 5555. This process will open
a listening port on the specified port number that will listen for BLCLI commands
to be sent from the client.

Either authenticate when asked or use cached credentials to authenticate

automatically. If using cached credentials, you can execute the command with an
‘&’ at the end, sending the BLCLI process into the background.

To utilize the BLCLI proxy using blcli2, call blcli2 with the following
command from Network Shell:

blcli2 –c <port#> <NameSpace> <command> <argument1> …

<argumentN>

Where <port#> is the same port specified in the instantiation of the server, telling
the BLCLI through which port to connect to proxy.

Implemented in a script with multiple blcli commands, this will significantly

decrease the total time it takes to complete execution of the script.

2.3.2. Without blcli2.exe

The blcli2 executable is still experimental, and so has not been implemented
into full production. In addition, for anyone still using versions prior to v6.2, the
blcli2 executable does not exist. The blcli2 is merely a wrapper around the
Java executable, so we can write .nsh scripts and .bat files to implement this all
in a manual manner.

6 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 In Windows, assuming that a user has installed Operations Manager in the default
C:\Program Files\BladeLogic directory, the following batch files will
instantiate the server mode and the proxy client.
Windows:
blcliserver.bat
@echo off
clear

SET PATH=C:\Program Files\BladeLogic\OM\jre\bin;C:\Program Files\BladeLogic\OM\bin;C:\Program

Files\BladeLogic\OM\br\stdlib;
SET CLASSPATH="C:\Program Files\BladeLogic\OM\jre\lib\rt.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib";"C:\Program Files\BladeLogic\OM\br\stdlib\log4j-
1.2.4.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\activation.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\jaxp.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mailapi.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\parser.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mysql.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\xerces.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\xml-
writer.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\oracle.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msbase.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mssqlserver.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msutil.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\smtp.jar";"C:\Program Files\BladeLogic\OM\br";"C:\Program
Files\BladeLogic\OM\br\bladelogic.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\looks-
1.1.2.jar";"C:\Program Files\BladeLogic\OM\bin";"C:\Program
Files\BladeLogic\OM\br\stdlib\rbachelp.jar"
set JAVA_PROPERTIES=-Xmx512M -Xss2m -Dblx.rootdir="C:\Program Files\BladeLogic\OM" -
Dblx.cmrootdir="C:\Program Files\BladeLogic\OM\br" -Dcom.bladelogic.cli.xmldir="C:\Program
Files\BladeLogic\OM\br\xml\cli"
set MAIN_CLASS=com.bladelogic.cli.CLIMain

set PORT=-Dcom.bladelogic.cli.port=5555

echo BladeLogic CLI server connected to application server %srvr% on port %portnum%.
echo Press CTRL+C to exit.

java %JAVA_PROPERTIES% %PORT% -classpath %CLASSPATH% %MAIN_CLASS% -m server

blcliproxy.bat
@echo off

SET PATH=C:\Program Files\BladeLogic\OM\jre\bin;C:\Program Files\BladeLogic\OM\bin;C:\Program

Files\BladeLogic\OM\br\stdlib;
SET CLASSPATH="C:\Program Files\BladeLogic\OM\jre\lib\rt.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib";"C:\Program Files\BladeLogic\OM\br\stdlib\log4j-
1.2.4.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\activation.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\jaxp.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mailapi.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\parser.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mysql.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\xerces.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\xml-
writer.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\oracle.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msbase.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mssqlserver.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msutil.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\smtp.jar";"C:\Program Files\BladeLogic\OM\br";"C:\Program
Files\BladeLogic\OM\br\bladelogic.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\looks-
1.1.2.jar";"C:\Program Files\BladeLogic\OM\bin";"C:\Program
Files\BladeLogic\OM\br\stdlib\rbachelp.jar"
set MAIN_CLASS=com.bladelogic.cli.CLIClient
set JAVA_PROPERTIES=-Dcom.bladelogic.cli.port=5555

java %JAVA_PROPERTIES% -classpath %CLASSPATH% %MAIN_CLASS%%ARGS%

UNIX:
Blcliserver
#!/bin/sh
BLADELOGIC_HOME=/usr/nsh
JAVA_HOME=/usr/nsh/br/java
BLDEPLOY=$BLADELOGIC_HOME/br
STDLIB=$BLDEPLOY/stdlib
CLASSPATH=$BLADELOGIC_HOME/br:$BLADELOGIC_HOME/br/bladelogic.jar:
$JAVA_HOME/jre/lib/rt.jar:$STDLIB:$STDLIB/activation.jar:$STDLIB/jaxp.jar:
$STDLIB/log4j-1.2.4.jar:$STDLIB/looks-1.1.2.jar:$STDLIB/mailapi.jar:$STDLIB/msbase.jar:
7 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
$STDLIB/mssqlserver.jar:$STDLIB/msutil.jar:$STDLIB/mysql.jar:$STDLIB/oracle.jar:
$STDLIB/parser.jar:$STDLIB/smtp.jar:$STDLIB/xerces.jar:$STDLIB/xml-writer.jar
PATH=/usr/nsh/bin:/usr/nsh/sbin:$PATH
LD_LIBRARY_PATH=${LD_LIBRARY_PATH:=}${LD_LIBRARY_PATH:+:}$BLADELOGIC_HOME/lib
export JAVA_HOME CLASSPATH LD_LIBRARY_PATH PATH

$JAVA_HOME/bin/java -Dblx.cmrootdir=$BLADELOGIC_HOME/br \
-Dcom.bladelogic.cli.xmldir=$BLADELOGIC_HOME/br/xml/cli \
-Dcom.bladelogic.cli.port=5555 \
com.bladelogic.cli.CLIMain "${@}" -m server

Blcliproxy
#!/bin/sh
BLADELOGIC_HOME=/usr/nsh
JAVA_HOME=/usr/nsh/br/java
BLDEPLOY=$BLADELOGIC_HOME/br
STDLIB=$BLDEPLOY/stdlib
CLASSPATH=$BLADELOGIC_HOME/br:$BLADELOGIC_HOME/br/bladelogic.jar:$JAVA_HOME/jre/lib/rt.jar:
$STDLIB:$STDLIB/activation.jar:$STDLIB/jaxp.jar:$STDLIB/log4j-1.2.4.jar:$STDLIB/looks-1.1.2.jar:
$STDLIB/mailapi.jar:$STDLIB/msbase.jar:$STDLIB/mssqlserver.jar:$STDLIB/msutil.jar:$STDLIB/mysql.jar:
$STDLIB/oracle.jar:$STDLIB/parser.jar:$STDLIB/smtp.jar:$STDLIB/xerces.jar:$STDLIB/xml-writer.jar
PATH=/usr/nsh/bin:/usr/nsh/sbin:$PATH
LD_LIBRARY_PATH=${LD_LIBRARY_PATH:=}${LD_LIBRARY_PATH:+:}$BLADELOGIC_HOME/lib
export JAVA_HOME CLASSPATH LD_LIBRARY_PATH PATH

$JAVA_HOME/bin/java -Dblx.cmrootdir=$BLADELOGIC_HOME/br \
-Dcom.bladelogic.cli.xmldir=$BLADELOGIC_HOME/br/xml/cli \
-Dcom.bladelogic.cli.port=5555 \
com.bladelogic.cli.CLIClient "${@}"

2.4. Other Possibilities for Increasing Speed of the BLCLI

2.4.1. Using the Subshell
The –m flag enables two separate modes, one is the aforementioned server, the
other the subshell. The subshell is so called because it is not a full-featured shell,
but rather a limited shell-like access to the BLCLI. Once in the subshell
environment, there are no environment variables, just command prompts and
return values. Those return values can be automatically passed to the next
command, without retyping them. This functionalty works because of a topic to
be covered later in this documentation, BLCLI context. Refer to section 3.1.2 for
more information on context.

If there are many BLCLI commands to be executed at once, the results of which
do not rely on one another, then one can pass them to the subshell by running cat
against a file full of BLCLI namespaces and commands, and piping it to blcli –
m subshell.

2.4.2. Experimental: Using Jython

We have recently begun using a new scripting tool. This tool utilizes the present
Java construct of the BLCLI, but changes the scripting environment from
Network Shell, replacing it with a Java interpreter of Python, commonly called
Jython.

This tool allows scripting in Jython, with all BLCLI calls made directly through
the Java classes, due to Jython’s native interoperability with Java. With this
approach, the Jython code imports the Java libraries, authenticates against the
Application Server, and makes BLCLI calls directly via the Jython interface with
Java. This best-of-all-worlds hybrid solution combines the speed of the BLCLI
8 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 server with the scripting capabilities of Network Shell or Perl. Because the
Jython tool makes a single connection and then runs all commands through Java,
essentially, we are scripting the BLCLI subshell.

As a future initiative, Python’s support of XML parsing may afford us the

opportunity to make initial PS implementations post-scoping more standards-
compliant. We are presently working on an installation and usage guide of
Jython, a.k.a. the JLI when using the BLCLI. If installed properly on the
BladeLogic Application Server, we can use the JLI as an NSH Script Job, making
enormous gains in speed over standard NSH scripts.

2.5. Options and Recommendations for Production

Implementation
The current implementation of the BLCLI offers command-line manipulation of
the BladeLogic environment. Utilizing BLCLI functionality may leave the more
security-conscious users concerned about security implications. We have
developed a number of methods to circumvent possible security implications.

2.5.1. Starting Server from Within Script

While the user_info.dat file still must remain in the <user_home> directory, we
can conceivably start and kill the BLCLI server from within a NSH script. Begin
the script with the BLCLI command to instantiate the server and, when all BLCLI
commands are completed, execute a kill -9 %1 to kill the job with the
background number of 1.

2.5.2. Running Server as Service

While not recommended, it is possible to run the BLCLI server as a service. In
Windows, one may download an application like Fire Daemon that can be
installed as a service and set to run batch files on Windows startup. In UNIX, one
may desire to write a startup script to be placed in /etc/init.d/ with start and stop
parameters.

3. Behind the Scenes

Behind the scenes, the BLCLI is contained in a set of Java classes, with the
package name com.bladelogic.cli. These Java classes load the XML files in
the <blinstall_dir>/br/xml/cli/ directory into memory and these files tell
the BLCLI how to access the BladeLogic API. We will discuss how these files
work in section 3.1 before moving on how to construct complex commands in
section 3.2. Additionally, we should have a BladeLogic Best Practice document
for constructing BLCLI Complex Commands.

3.1. How the BLCLI works

The BLCLI parses and loads into memory all the XML files in the /br/xml/cli
directory. These files contain commands and hooks into the API. The file
naming convention for these XML files is NameSpace-CommandTypes.xml. The
‘Additional’ command type usually indicates Complex commands written by
the BLCLI developers to provide more streamlined BLCLI functionality. These
commands represent the majority of the released commands. BladeLogic
9 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
Professional Services, at present, saves custom command files as NameSpace-
PSAdditional.xml.

Each command to the BLCLI coincides with a namespace and an XML

command. Each XML command can be released or unreleased and contains one
or more other BLCLI commands. There are different types of commands, such as
API, Load, Save, and Procedure commands. These will all be addressed in the
following subsections. Complex commands are addressed in section 3.2 and
consist of multiple types of commands.

3.1.1. Released / Unreleased Commands

The API that is installed with Operations Manager documents all the released
commands, commands executable by default from the command line. As there
remain still many unreleased commands, this API is a trimmed down version of
the BLCLI API documentation that is released to clients. To release the full API
documentation, please refer to the Appendix of this document, Section 4.3. This
will provide access to the extended functionality of the BLCLI. This
documentation is generated automatically from the Java code’s Javadoc but will
not generate API documentation for custom-written XML descriptor files.

3.1.2. Context and the Target Object

The BLCLI API consists of various namespaces, each with various commands.

The BLCLI operates in sessions, whether in the execution of a command from the
command line or in subshell mode. For each instance of a BLCLI session,
execution of these commands is linear, and data passes between them via the
BLCLI’s concept of context. Context is persistent from when a session begins
until the session ends. The context is NULL when a session begins, and any
attempt to access the context will result in a thrown Java exception.

When a Load command is executed, the resulting object is loaded into memory as
the context, and any API command can be executed against that without explicitly
requiring an argument. Strings, integers, and boolean values cannot be stored in
context, but “Model Objects” can. When returning strings, integers, or boolean
data in a complex command, we can save into the BLCLIs session memory, into a
list of what are called Named Objects. This will make more sense as we discuss
Load and Complex commands.

Once an object handle is loaded into the context via a Load command, it becomes
known as the Target Object. It remains the BLCLI target object for the duration
of the execution of that BLCLI command until it is overridden by the loading of
another object into context, or until a different target object is explicitly set within
the code. An API command may return a handle to an object, but it will not set
the Target Object because it is not a Load command. If an API command returns
an object handle, we call ‘Utility setTargetObject’ to complete the loading
of the object handle into context.

As an example, consider the command DepotGroup groupNameToId

</group/name>. From the user’s perspective, a command is called, a group name

10 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
is passed and the user is returned the group Id. What really happens is that a
command is run to find that group by name and load the object into context.
Then, another command is run without taking any explicit arguments to get that
group’s Id and return it as the result value. Instead of an explicit argument, it
looks to the BLCLI context.

3.1.3. API Commands

The commands contained in the XML files for the BLCLI all eventually terminate
at a point containing an API call. These API calls are the direct calls to the
BladeLogic Java framework. API commands are those that operate on the context
object.

In the documentation, a command is an API command if it retrieves data directly

from the database. In the XML code, however, there is a distinction. Commands
that are API commands in the documentation, are those commands in the code
that invoke BLCLI commands with API calls. For all API BLCLI commands in
the XML code, there is an analogous Load command in the code, and this is the
command that one sees in the documentation.

While most API commands will require a Target Object to be set, some may
operate without a Target Object, creating and setting their own. This applies to
some Load commands (referenced below) and to Factory methods that create new
instances of objects.

3.1.4. Load Commands

The BLCLI needs an interface through which it can retrieve object information.
Load commands provide that interface. A Load command does not necessarily
have ‘load’ in the name, but instead will often be named something like ‘get’ or
‘find’. Load commands return handles to BladeLogic objects, and save them into
the BLCLI context. These handles cannot be passed explicitly as data to other
BLCLI commands, but can be used with API commands that do not require
command line arguments. The arguments these commands use are the objects in
the document context.

3.1.5. Save Commands

When making changes to an object loaded into context, or creating a new object
via the BLCLI, we need to save the changes to it. This is done simply with a Save
command. Save commands may not exist for all objects, but they will exist for
their abstract class, such as Group would be the abstract class of DepotGroup or
SmartServerGroup. In this way, when we create a SmartServerGroup in our
code, we create an object, make it a group of the type SmartServerGroup, give it
a name, and then call ‘Group save’, because SmartServerGroup is an
abstraction of the Group class. Save commands take the Target Object and save it
to the database.

3.1.6. Procedure Commands

Procedure commands are unique, in that these are commands that are multi-step
procedures built into the code. All Procedure commands are in the Utility

11 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 namespace, and do not have corresponding XML commands in the xml/cli
directory.

3.2. Complex Commands

When we talk about creating custom BLCLI commands, we are talking about
Complex commands. Complex commands are merely a linear succession of
BLCLI commands of all different types. Within a complex command, we can
reference passed arguments, save data results for later use, and call Load, Save,
and other Complex commands. A Complex command contains one or more other
commands. While the name implies some sort of intricacy, it merely refers to the
Complex commands’ extending the functionality of the basic BLCLI commands.

3.2.1. Complex Commands – Piece by Piece

Let us first discuss the structure of complex commands. We will review the
structure of the XML for a Complex command and discuss the details of each
section.

12 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 <command_inventory>
The <command_inventory> tag is the wrapper around all the commands in the
XML file. Every BLCLI XML file needs a <command_inventory> tag at the
beginning (after the <xml> and <doctype> tags) and again at the end to close the
tag.
<name_space name=””>
The <name_space> tag wraps around all the commands for a given namespace.
This namespace becomes the case-sensitive first argument passed before each
BLCLI command. The standard naming convention is that of no spaces, but
where the first letter of each new word is capitalized.
<complex_command release=””>
The <complex_command> tag is the XML wrapper tag around all other elements
in the Complex command. Release takes a value of ‘yes’ or ‘no’, where ‘yes’
indicates that a user can access the command directly from the command line. A
value of ‘no’ for release indicates that this command is only accessible from
within other BLCLI Complex commands.
<name></name>
The <name> tag defines the name of the command, and this becomes the argument
to BLCLI after the namespace. The standard naming convention requires no
spaces, where the first letter of each new word is capitalized, but for one
exception. The first letter of each command is in lower case. Complex
commends are allowed to be overloaded. This means that there can be multiple
complex commands with the same name, so long as they have a different number
of arguments.
<description>
The <description> tag wraps around the <author>, <general_info>, and
<result> commands.
<author></author>
As the first author of a command, one should place one’s name between these two
tags.
<general_info></general_info>
The <general_info> tag is a free form text field, and there can be multiple
<general_info> tags. Here, one should describe what the command does, the
date it was written, and should note any edits one has made to the original
command.
<return_value_info></return_value_info>
The <return_value_info> tag tells us which data type or information to expect
as a result of a successful invocation of the command.
</description>
<argument_list>
This is the wrapper around the list of arguments expected from the command line.
<argument name=”” desc=””></argument>
The <argument> tag, of which there may be more than one, tells the Complex
command which argument types to expect for each argument. The name property
takes as a value the name of the argument, to be referenced later as $argName$
and should follow the same naming conventions as the command name. The
desc property gives a description of the argument’s purpose. Between the
<argument></argument> tags we add the argument type, where valid values are
java.lang.String, int, or boolean.
</argument_list>
<commands_to_execute>

13 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
The <commands_to_execute> tags wrap around the series of
<command_invocation> elements.
<command_invocation>
These <command_invocation> commands each ‘invoke’ a BLCLI command, and
wrap around the command input.
<namespace_ref></namespace_ref>
The <namespace_ref> tags tell each command invocation with which namespace
to associate the command, to come next. This is the same as the first argument
passed to the BLCLI executable.
<name></name>
The <name> tag tells the command invocation which command to execute from
the preceding namespace.
<input></input> [<input/>]
The <input> tags pass the input string to the command invocation. This string
must have the same format as command line input. Any strings that may contain
quotes must be delimited by &quot; special characters. A command that does not
require an input should have either nothing between the input tags or just a single
<input/> tag.
<store_result><name></name><store_result>
Often times, an API command will return a string or integer result necessary to
use later in the command invocation. We store this in the BLCLI context list of
named objects. After the <input> tags, we place these <store_result><name>
tags and place the name of the new named object between them. This variable is
referenced later as NAMED_OBJECT=objectName.
</command_invocation>
</commands_to_execute>

3.2.2. SmartServerGroup createNewGroup Explained

Creating smart server groups was not possible before creating our own Complex
commands. There is a Professional Services XML command descriptor file
named SmartServerGroup. This file contains three commands:
createNewGroup, addConditionToGroup, and setMatchAllOnGroup.
createNewGroup creates a smart server group with no conditions.
addConditionToGroup adds conditions and setMatchAllOnGroup sets the Match-
All / Match-Any via true or false.

This section will investigate the command SmartServerGroup createNewGroup.

We execute this command with two arguments: the fully qualified parent group
name, and the name of the group to be created. Therefore, if we have a static
group named “Servers by OS” which is a first-level server group, and to that we
want to add a smart server group named “Windows 2003”, then we execute the
following command:

blcli SmartServerGroup createNewGroup “/Servers by OS” “Windows

2003”

This creates a group, though it will not yet contain any conditions and therefore
will not actually show Windows 2003 servers. To determine how to add
conditions and to set the Match-All property on the group, see the full
SmartServerGroup-PSAdditional.xml file available in the Professional
Services Knowledge Base.
14 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
The XML on the following page creates a Complex command that is released to
the command line interface. The name of the Complex command is
createNewGroup. The description lists Brad Jacobs as the author and explains
that this Complex command will create a smart server group with no conditions.
The command will return the database Id of the group with type Integer.

The command takes two arguments, both of type String. One is the
parentGroupName and the other is the groupName.

The first command is ‘ServerGroup groupNameToId’ and takes the

$parentGroupName$ argument as input, returning the parent group database Id
and storing that group Id as NAMED_OBJECT=parentGroupId.

Next, we create a Model Object with the Utility command of type

SmartServerGroup. We next set the name of the newly created smart server
group. The command takes as input the $groupName$ variable from the
command line argument, but sets the name on the group object stored in the
BLCLI context.

We use the NAMED_OBJECT that we set in the first command invocation to set the
parent Id of the new smart server group. Because a SmartServerGroup is just an
abstraction of the Group object, we call the ‘Group save’ command next.
Finally, we call SmartServerGroup getGroupId, a command which takes as
input the object in the BLCLI context. As this is the last command in the
Complex command, the result is returned to <STDOUT>.

15 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
 SmartServerGroup createNewGroup
<complex_command release="yes">
<name>createNewGroup</name>
<description>
<author>Brad Jacobs</author>
<general_info>Create Smart Server Group with zero conditions. Need addCondition
command below to add conditions.</general_info>
<return_value_info>Integer of Group Id</return_value_info>
</description>
<argument_list>
<argument name="parentGroupName" desc="Qualified name of parent
group.">java.lang.String</argument>
<argument name="groupName" desc="Name of Smart Server
Group.">java.lang.String</argument>
</argument_list>
<commands_to_execute>
<command_invocation>
<namespace_ref>ServerGroup</namespace_ref>
<name>groupNameToId</name>
<input>$parentGroupName$</input>
<store_result><name>parentGroupId</name></store_result>
</command_invocation>
<command_invocation>
<namespace_ref>Utility</namespace_ref>
<name>createModelObject</name>
<input>SmartServerGroup</input>
</command_invocation>
<command_invocation>
<namespace_ref>SmartServerGroup</namespace_ref>
<name>setName</name>
<input>$groupName$</input>
</command_invocation>
<command_invocation>
<namespace_ref>SmartServerGroup</namespace_ref>
<name>setParentGroupId</name>
<input>NAMED_OBJECT=parentGroupId</input>
</command_invocation>
<command_invocation>
<namespace_ref>Group</namespace_ref>
<name>save</name>
<input/>
</command_invocation>
<command_invocation>
<namespace_ref>SmartServerGroup</namespace_ref>
<name>getGroupId</name>
<input/>
</command_invocation>
</commands_to_execute>
</complex_command>

16 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
4. Appendices
4.1. BLCLI Usage and Flags
-D<jvmopt> Pass a single –D flag to the JVM
-X<jvmopt> Pass a single –X flag to the JVM
-a <appserver> Specifies against which Application Server the BLCLI should run.
-c <port> Connect to a BLCLI server listening on the specified port.
-m <mode> Start the BLCLI in server or subshell mode.
-u <user> Assume the specified user upon execution.
-r <role> Assume the specified role upon execution.
-i <user_info.dat> Use the specified user_info.dat file.

4.2. Troubleshooting the BLCLI

The first step in troubleshooting problems with BLCLI commands is to use the
subshell mode. Get your Complex command working in subshell mode, and
repeat those same steps in your Complex command. Using the blcli2.exe, it is
possible to enter subshell mode where all BLCLI commands are released. This
will allow fully interactive testing of any complex command components, if
necessary.

blcli2.exe –Dcom.bladelogic.cli.debug.release-only=”false” –m
subshell

4.3. Compiling Unreleased API Documentation

The batch file below compiles the full API documentation, both released and unreleased commands.
@echo off
setlocal

SET PATH=C:\Program Files\BladeLogic\OM\jre\bin;C:\Program

Files\BladeLogic\OM\bin;C:\Program Files\BladeLogic\OM\br\stdlib;

SET CLASSPATH="C:\Program Files\BladeLogic\OM\jre\lib\rt.jar";"C:\Program

Files\BladeLogic\OM\br\stdlib";"C:\Program Files\BladeLogic\OM\br\stdlib\log4j-
1.2.4.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\activation.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\jaxp.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mailapi.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\parser.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mysql.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\xerces.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\xml-
writer.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\oracle.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msbase.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\mssqlserver.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\msutil.jar";"C:\Program
Files\BladeLogic\OM\br\stdlib\smtp.jar";"C:\Program Files\BladeLogic\OM\br";"C:\Program
Files\BladeLogic\OM\br\bladelogic.jar";"C:\Program Files\BladeLogic\OM\br\stdlib\looks-
1.1.2.jar";"C:\Program Files\BladeLogic\OM\bin";"C:\Program
Files\BladeLogic\OM\br\stdlib\rbachelp.jar"
set JAVA_PROPERTIES=-Dcom.bladelogic.cli.port=5555
set MAIN_CLASS=com.bladelogic.cli.help.HelpGenerator

set XML_COMMANDS_DIRECTORY=C:\progra~1\bladelogic\om\br\xml\cli
set XML_OUTPUT_DIRECTORY=C:\com.bladelogic\cli-docs

java -cp %CLASSPATH% %JAVA_PROPERTIES% %MAIN_CLASS% %XML_COMMANDS_DIRECTORY%

%XML_OUTPUT_DIRECTORY%

17 of 18
©2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary