Best Practice - BLCLI [Internal] v3.2005

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. 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.



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.



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.



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.



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:

$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



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



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



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



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.



<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>



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 " 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.



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>.



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>



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%



Best Practice - BLCLI [Internal] v3.2005

Documents

Transcript of Best Practice - BLCLI [Internal] v3.2005