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 J ython................................................................................................... 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, Smar t Ser ver Gr oup cr eat eNewGr oup.

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 J ava-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 users 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 J ava Virtual Machine (J VM) 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:

bl cl i NameSpace commandName <Ar gument 1> <Ar gument N>

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 J obs, 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
<bl i nst al l _di r >/ Doc/ cl i / i ndex. ht ml . 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
<bl i nst al l _di r >/ br / bl _gen_bl cl i _user _i nf o. bat file. This script will
cache a users 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 users cached credentials. As a second
option, a user may save the file as user _i nf o. dat , and copy the file to the
<user _home>/ Appl i cat i on Dat a/ Bl adeLogi c/ user / directory on Windows,
or to the <user _home>/ . bl adel ogi c/ . user on UNIX/Linux. The <user _home>
directory on Windows is the users username directory within / Document s and
Set t i ngs.
4 of 18
2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary

When running a NSH script with BLCLI commands as a NSH Script J ob by the
Application Server, the user _i nf o. 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 Local Syst em. It is not always obvious which path
leads us to the Local Syst em<user _home> directory, but we can perform a quick
trick to discover this path.

Ensure that the Windows Task Schedul er service is running. From a
command line (cmd) Window, type at <t i me+> / i nt er act i ve cmd. exe, where
<t i me+> is some HH: MM formatted time some minutes in the future. Because the
Task Scheduler service runs as the Local Syst emaccount, the cmd. exe window
that opens when the specified scheduled time arrives will inherit Local Syst em
privileges with the Windows Id SYSTEM. Once in here, you may type echo
%USERPROFI LE%, 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 $USERPROFI LE will return the Local Syst emaccounts
<user _home>.

On UNIX, the task is much simpler. The BladeLogic server runs as bl admi n and
the <user _home> directory can be determined either by running sudo u
bl admi n echo $HOME as r oot or as a user with root privileges or by becoming
the bl admi n user and running cd ~; pwd.
2.2.2. BLTray Utility
The BLTray is a tool found in the <bl i nst al l _di r >/ bi n/ directory, using
Stanford Universitys 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 . / bl t r ay. exe sr p. 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 (bl cl i 2. 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, bl cl i 2. 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 bl cl i 2 executable is a
wrapper around the J ava executable, expanded from the standard bl cl i
executable. The bl cl i 2 allows us to pass a single D J ava Properties argument to
the J VM 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 bl cl i 2, execute the following
command from within Network Shell:

bl cl i 2 Dcom. bl adel ogi c. cl i . por t =<por t #> mser ver

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 bl cl i 2, call bl cl i 2 with the following
command from Network Shell:

bl cl i 2 c <por t #> <NameSpace> <command> <ar gument 1>
<ar gument N>

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 bl cl i commands, this will significantly
decrease the total time it takes to complete execution of the script.
2.3.2. Without blcli2.exe
The bl cl i 2 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
bl cl i 2 executable does not exist. The bl cl i 2 is merely a wrapper around the
J ava 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: \ Pr ogr amFi l es\ Bl adeLogi c directory, the following batch files will
instantiate the server mode and the proxy client.
Windows:
bl cl i ser ver . bat
@echo of f
cl ear

SET PATH=C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ bi n; C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ bi n; C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b;
SET CLASSPATH=" C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ l i b\ r t . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b" ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l og4j -
1. 2. 4. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ act i vat i on. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ j axp. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mai l api . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ par ser . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mysql . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xer ces. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xml -
wr i t er . j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ or acl e. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msbase. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mssql ser ver . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msut i l . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ smt p. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ bl adel ogi c. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l ooks-
1. 1. 2. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ bi n" ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ r bachel p. j ar "
set J AVA_PROPERTI ES=- Xmx512M - Xss2m- Dbl x. r oot di r =" C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM" -
Dbl x. cmr oot di r =" C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br " - Dcom. bl adel ogi c. cl i . xml di r =" C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ xml \ cl i "
set MAI N_CLASS=com. bl adel ogi c. cl i . CLI Mai n

set PORT=- Dcom. bl adel ogi c. cl i . por t =5555

echo Bl adeLogi c CLI ser ver connect ed t o appl i cat i on ser ver %sr vr %on por t %por t num%.
echo Pr ess CTRL+C t o exi t .

j ava %J AVA_PROPERTI ES%%PORT%- cl asspat h %CLASSPATH%%MAI N_CLASS%- mser ver

bl cl i pr oxy. bat
@echo of f

SET PATH=C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ bi n; C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ bi n; C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b;
SET CLASSPATH=" C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ l i b\ r t . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b" ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l og4j -
1. 2. 4. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ act i vat i on. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ j axp. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mai l api . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ par ser . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mysql . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xer ces. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xml -
wr i t er . j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ or acl e. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msbase. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mssql ser ver . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msut i l . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ smt p. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ bl adel ogi c. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l ooks-
1. 1. 2. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ bi n" ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ r bachel p. j ar "
set MAI N_CLASS=com. bl adel ogi c. cl i . CLI Cl i ent
set J AVA_PROPERTI ES=- Dcom. bl adel ogi c. cl i . por t =5555

j ava %J AVA_PROPERTI ES%- cl asspat h %CLASSPATH%%MAI N_CLASS%%ARGS%
UNIX:
7 of 18
2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
Bl cl i ser ver
#! / bi n/ sh
BLADELOGI C_HOME=/ usr / nsh
J AVA_HOME=/ usr / nsh/ br / j ava
BLDEPLOY=$BLADELOGI C_HOME/ br
STDLI B=$BLDEPLOY/ st dl i b
CLASSPATH=$BLADELOGI C_HOME/ br : $BLADELOGI C_HOME/ br / bl adel ogi c. j ar :
$J AVA_HOME/ j r e/ l i b/ r t . j ar : $STDLI B: $STDLI B/ act i vat i on. j ar : $STDLI B/ j axp. j ar :
$STDLI B/ l og4j - 1. 2. 4. j ar : $STDLI B/ l ooks- 1. 1. 2. j ar : $STDLI B/ mai l api . j ar : $STDLI B/ msbase. j ar :
$STDLI B/ mssql ser ver . j ar : $STDLI B/ msut i l . j ar : $STDLI B/ mysql . j ar : $STDLI B/ or acl e. j ar :
$STDLI B/ par ser . j ar : $STDLI B/ smt p. j ar : $STDLI B/ xer ces. j ar : $STDLI B/ xml - wr i t er . j ar
PATH=/ usr / nsh/ bi n: / usr / nsh/ sbi n: $PATH
LD_LI BRARY_PATH=${LD_LI BRARY_PATH: =}${LD_LI BRARY_PATH: +: }$BLADELOGI C_HOME/ l i b
expor t J AVA_HOME CLASSPATH LD_LI BRARY_PATH PATH

$J AVA_HOME/ bi n/ j ava - Dbl x. cmr oot di r =$BLADELOGI C_HOME/ br \
- Dcom. bl adel ogi c. cl i . xml di r =$BLADELOGI C_HOME/ br / xml / cl i \
- Dcom. bl adel ogi c. cl i . por t =5555 \
com. bl adel ogi c. cl i . CLI Mai n " ${@}" - mser ver

Bl cl i pr oxy
#! / bi n/ sh
BLADELOGI C_HOME=/ usr / nsh
J AVA_HOME=/ usr / nsh/ br / j ava
BLDEPLOY=$BLADELOGI C_HOME/ br
STDLI B=$BLDEPLOY/ st dl i b
CLASSPATH=$BLADELOGI C_HOME/ br : $BLADELOGI C_HOME/ br / bl adel ogi c. j ar : $J AVA_HOME/ j r e/ l i b/ r t . j ar :
$STDLI B: $STDLI B/ act i vat i on. j ar : $STDLI B/ j axp. j ar : $STDLI B/ l og4j - 1. 2. 4. j ar : $STDLI B/ l ooks- 1. 1. 2. j ar :
$STDLI B/ mai l api . j ar : $STDLI B/ msbase. j ar : $STDLI B/ mssql ser ver . j ar : $STDLI B/ msut i l . j ar : $STDLI B/ mysql . j ar :
$STDLI B/ or acl e. j ar : $STDLI B/ par ser . j ar : $STDLI B/ smt p. j ar : $STDLI B/ xer ces. j ar : $STDLI B/ xml - wr i t er . j ar
PATH=/ usr / nsh/ bi n: / usr / nsh/ sbi n: $PATH
LD_LI BRARY_PATH=${LD_LI BRARY_PATH: =}${LD_LI BRARY_PATH: +: }$BLADELOGI C_HOME/ l i b
expor t J AVA_HOME CLASSPATH LD_LI BRARY_PATH PATH

$J AVA_HOME/ bi n/ j ava - Dbl x. cmr oot di r =$BLADELOGI C_HOME/ br \
- Dcom. bl adel ogi c. cl i . xml di r =$BLADELOGI C_HOME/ br / xml / cl i \
- Dcom. bl adel ogi c. cl i . por t =5555 \
com. bl adel ogi c. cl i . CLI Cl i ent " ${@}"

2.4. Other Possibilities for Increasing Speed of the BLCLI
2.4.1. Using the Subshell
The mflag 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 bl cl i
msubshel l .
2.4.2. Experimental: Using Jython
We have recently begun using a new scripting tool. This tool utilizes the present
J ava construct of the BLCLI, but changes the scripting environment from
Network Shell, replacing it with a J ava interpreter of Python, commonly called
J ython.

This tool allows scripting in J ython, with all BLCLI calls made directly through
the J ava classes, due to J ythons native interoperability with J ava. With this
approach, the J ython code imports the J ava libraries, authenticates against the
Application Server, and makes BLCLI calls directly via the J ython interface with
J ava. 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
J ython tool makes a single connection and then runs all commands through J ava,
essentially, we are scripting the BLCLI subshell.

As a future initiative, Pythons 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
J ython, a.k.a. the J LI when using the BLCLI. If installed properly on the
BladeLogic Application Server, we can use the J LI as an NSH Script J ob, 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 _i nf o. 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 ki l l - 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 J ava classes, with the
package name com. bl adel ogi c. cl i . These J ava classes load the XML files in
the <bl i nst al l _di r >/ br / xml / cl i / 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 / cl i
directory. These files contain commands and hooks into the API. The file
naming convention for these XML files is NameSpace- CommandTypes. xml . The
Addi t i onal 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-
PSAddi t i onal . 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 J ava codes J avadoc 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
BLCLIs 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 J ava 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 Ut i l i t y set Tar get Obj ect to complete the loading
of the object handle into context.

As an example, consider the command Depot Gr oup gr oupNameToI d
</ gr oup/ name>. From the users 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
groups 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 J ava 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 Gr oup would be the abstract class of Depot Gr oup or
Smar t Ser ver Gr oup. In this way, when we create a Smar t Ser ver Gr oup in our
code, we create an object, make it a group of the type Smar t Ser ver Gr oup, give it
a name, and then call Gr oup save, because Smar t Ser ver Gr oup is an
abstraction of the Gr oup 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 / cl i
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_i nvent or y>
The <command_i nvent or y> tag is the wrapper around all the commands in the
XML file. Every BLCLI XML file needs a <command_i nvent or y> tag at the
beginning (after the <xml > and <doct ype> 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.
<compl ex_command r el ease=>
The <compl ex_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.
<descr i pt i on>
The <descr i pt i on> tag wraps around the <aut hor >, <gener al _i nf o>, and
<r esul t > commands.
<aut hor ></ aut hor >
As the first author of a command, one should place ones name between these two
tags.
<gener al _i nf o></ gener al _i nf o>
The <gener al _i nf o> tag is a free form text field, and there can be multiple
<gener al _i nf o> 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.
<r et ur n_val ue_i nf o></ r et ur n_val ue_i nf o>
The <r et ur n_val ue_i nf o> tag tells us which data type or information to expect
as a result of a successful invocation of the command.
</ descr i pt i on>
<ar gument _l i st >
This is the wrapper around the list of arguments expected from the command line.
<ar gument name= desc=></ ar gument >
The <ar gument > 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 $ar gName$
and should follow the same naming conventions as the command name. The
desc property gives a description of the arguments purpose. Between the
<ar gument ></ ar gument > tags we add the argument type, where valid values are
j ava. l ang. St r i ng, i nt , or bool ean.
</ ar gument _l i st >
<commands_t o_execut e>
13 of 18
2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary
The <commands_t o_execut e> tags wrap around the series of
<command_i nvocat i on> elements.
<command_i nvocat i on>
These <command_i nvocat i on> commands each invoke a BLCLI command, and
wrap around the command input.
<namespace_r ef ></ namespace_r ef >
The <namespace_r ef > 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.
<i nput ></ i nput > [ <i nput / >]
The <i nput > 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
<i nput / > tag.
<st or e_r esul t ><name></ name><st or e_r esul t >
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 <i nput > tags, we place these <st or e_r esul t ><name>
tags and place the name of the new named object between them. This variable is
referenced later as NAMED_OBJ ECT=obj ect Name.
</ command_i nvocat i on>
</ commands_t o_execut e>
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 Smar t Ser ver Gr oup. This file contains three commands:
cr eat eNewGr oup, addCondi t i onToGr oup, and set Mat chAl l OnGr oup.
cr eat eNewGr oup creates a smart server group with no conditions.
addConditionToGroup adds conditions and set Mat chAl l OnGr oup sets the Match-
All / Match-Any via t r ue or f al se.

This section will investigate the command Smar t Ser ver Gr oup cr eat eNewGr oup.
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:

bl cl i Smar t Ser ver Gr oup cr eat eNewGr oup / Ser ver s by OS Wi ndows
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
Smar t Ser ver Gr oup- PSAddi t i onal . 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
cr eat eNewGr oup. The description lists Brad J acobs 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
par ent Gr oupName and the other is the gr oupName.

The first command is Ser ver Gr oup gr oupNameToI d and takes the
$par ent Gr oupName$ argument as input, returning the parent group database Id
and storing that group Id as NAMED_OBJ ECT=par ent Gr oupI d.

Next, we create a Model Object with the Ut i l i t y command of type
Smar t Ser ver Gr oup. We next set the name of the newly created smart server
group. The command takes as input the $gr oupName$ variable from the
command line argument, but sets the name on the group object stored in the
BLCLI context.

We use the NAMED_OBJ ECT that we set in the first command invocation to set the
parent Id of the new smart server group. Because a Smar t Ser ver Gr oup is just an
abstraction of the Gr oup object, we call the Gr oup save command next.
Finally, we call Smar t Ser ver Gr oup get Gr oupI d, 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
<compl ex_command r el ease=" yes" >
<name>cr eat eNewGr oup</ name>
<descr i pt i on>
<aut hor >Br ad J acobs</ aut hor >
<gener al _i nf o>Cr eat e Smar t Ser ver Gr oup wi t h zer o condi t i ons. Need addCondi t i on
command bel ow t o add condi t i ons. </ gener al _i nf o>
<r et ur n_val ue_i nf o>I nt eger of Gr oup I d</ r et ur n_val ue_i nf o>
</ descr i pt i on>
<ar gument _l i st >
<ar gument name=" par ent Gr oupName" desc=" Qual i f i ed name of par ent
gr oup. " >j ava. l ang. St r i ng</ ar gument >
<ar gument name=" gr oupName" desc=" Name of Smar t Ser ver
Gr oup. " >j ava. l ang. St r i ng</ ar gument >
</ ar gument _l i st >
<commands_t o_execut e>
<command_i nvocat i on>
<namespace_r ef >Ser ver Gr oup</ namespace_r ef >
<name>gr oupNameToI d</ name>
<i nput >$par ent Gr oupName$</ i nput >
<st or e_r esul t ><name>par ent Gr oupI d</ name></ st or e_r esul t >
</ command_i nvocat i on>
<command_i nvocat i on>
<namespace_r ef >Ut i l i t y</ namespace_r ef >
<name>cr eat eModel Obj ect </ name>
<i nput >Smar t Ser ver Gr oup</ i nput >
</ command_i nvocat i on>
<command_i nvocat i on>
<namespace_r ef >Smar t Ser ver Gr oup</ namespace_r ef >
<name>set Name</ name>
<i nput >$gr oupName$</ i nput >
</ command_i nvocat i on>
<command_i nvocat i on>
<namespace_r ef >Smar t Ser ver Gr oup</ namespace_r ef >
<name>set Par ent Gr oupI d</ name>
<i nput >NAMED_OBJ ECT=par ent Gr oupI d</ i nput >
</ command_i nvocat i on>
<command_i nvocat i on>
<namespace_r ef >Gr oup</ namespace_r ef >
<name>save</ name>
<i nput / >
</ command_i nvocat i on>
<command_i nvocat i on>
<namespace_r ef >Smar t Ser ver Gr oup</ namespace_r ef >
<name>get Gr oupI d</ name>
<i nput / >
</ command_i nvocat i on>
</ commands_t o_execut e>
</ compl ex_command>
16 of 18
2004 BladeLogic, Inc. All rights reserved.
Confidential and Proprietary

4. Appendices
4.1. BLCLI Usage and Flags
- D<j vmopt >
Pass a single D flag to the J VM
- X<j vmopt >
Pass a single X flag to the J VM
- a <appser ver >
Specifies against which Application Server the BLCLI should run.
- c <por t >
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 <r ol e>
Assume the specified role upon execution.
- i <user _i nf o. 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.

bl cl i 2. exe Dcom. bl adel ogi c. cl i . debug. r el ease- onl y=f al se m
subshel l
4.3. Compiling Unreleased API Documentation
The batch file below compiles the full API documentation, both released and unreleased commands.

@echo of f
set l ocal

SET PATH=C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ bi n; C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ bi n; C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b;

SET CLASSPATH=" C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ j r e\ l i b\ r t . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b" ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l og4j -
1. 2. 4. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ act i vat i on. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ j axp. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mai l api . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ par ser . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mysql . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xer ces. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ xml -
wr i t er . j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ or acl e. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msbase. j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ mssql ser ver . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ msut i l . j ar " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ smt p. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br " ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ bl adel ogi c. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ l ooks-
1. 1. 2. j ar " ; " C: \ Pr ogr amFi l es\ Bl adeLogi c\ OM\ bi n" ; " C: \ Pr ogr am
Fi l es\ Bl adeLogi c\ OM\ br \ st dl i b\ r bachel p. j ar "
set J AVA_PROPERTI ES=- Dcom. bl adel ogi c. cl i . por t =5555
set MAI N_CLASS=com. bl adel ogi c. cl i . hel p. Hel pGener at or

set XML_COMMANDS_DI RECTORY=C: \ pr ogr a~1\ bl adel ogi c\ om\ br \ xml \ cl i
set XML_OUTPUT_DI RECTORY=C: \ com. bl adel ogi c\ cl i - docs

j ava - cp %CLASSPATH%%J AVA_PROPERTI ES%%MAI N_CLASS%%XML_COMMANDS_DI RECTORY%
%XML_OUTPUT_DI RECTORY%

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