Monday Jul 30, 2007

Introducing: The Intro(1CL) Man Page

John Cumming's blog A New Command Set for Solaris Cluster 3.2 provides a great tour of the new object-oriented command line that was introduced in the Sun Cluster 3.2 release. Another aid to understanding this new command set is the Intro(1CL) man page. This man page gives you the following information about the new command set:


  • A description of the structure of the new command set and some shortcuts you can use.
  • A list of all the new command names with their descriptions.
  • A mapping of some of the more commonly used original commands to the new commands. For example, it tells you what new commands you can use instead of scrgadm.
  • A list and explanation of all exit codes used within the new command set.
There is one gotcha: Because the Solaris Intro(1) man page also exists, when you use the man command to display the Sun Cluster Intro(1CL) man page, you have to specify the man-page section number (otherwise, the Intro(1) man page is displayed instead):
% man -s 1CL intro

You can also view Intro(1CL) in the Sun Cluster Refence Manual on docs.sun.com, where it serves as the Introduction.

Take a look at this man page for ways to get the most out of the new command set.

Lisa Shepherd
Sun Cluster Technical Publications
"We're the M in RTFM"

Tuesday Jan 09, 2007

A New Command Set for Solaris Cluster 3.2

The 3.2 release of Solaris Cluster introduces an all-new Command Line Interface (CLI) for managing the cluster. The new command set includes many features that make it both easier to use and more powerful than the command set found in earlier releases of the product.

Of course, the familiar command set from earlier releases is still there in 3.2 and is still fully supported for those users who are not ready to switch. All commands are still located in /usr/cluster/bin, so users need not modify their PATH settings to find commands from either set. Command names in the older command set all begin with the prefix "sc", and command names in the new CLI all begin with the prefix "cl". The two command sets are fully compatible with one another, so users can intermix commands from both sets in the same shell script or on the command line.

Early response from users of the new command set has been overwhelmingly positive. But, we are sometimes asked, "Why a new CLI for Solaris Cluster? What was wrong with the old one?" Not too long ago, Sun conducted a comprehensive survey of Solaris Cluster system administrators. The study revealed that the top set of issues which administrators had with the cluster were mostly to do with the command set. Sun felt that the best solution to the issues raised in the study was to introduce an altogether new command set. Data from that study, along with other customer feedback, was used to begin design of a new CLI. The design underwent several phases of refinement as we went back to customers with our ideas. And, finally, in-depth usability studies were conducted before the final design was ready for implementation.

The new command set is "object-oriented". That is, there is a different command for each type of cluster object that an administrator might need to manage. For example, a user managing just resource groups need only use the new "clresourcegroup" command to manage groups. The "clresourcegroup" command can be used to create/delete groups, set group properties, perform resource group switchovers, print configuration and status reports, etc... Each new command supports full management of all objects of the type that it controls.

The new command interfaces all use the same basic format:

cl<object_type> [<subcommand>] [<options>] [<objects>]

So, for example, to create a new resource group "rg1", one might use either one of the following commands:

clresourcegroup create rg1
clresourcegroup create --property Description="My rg" rg1

Users will rely on subcommands for most things, although some options, such as --help and --version, can be used without subcommands.

Most of the new commands also have built-in "aliases", or "short names". Our customers told us that they wanted command names that were descriptive and meaningful. But, they also told us that they wanted command names that were short and easy to type. The Solaris Cluster team felt that the best solution was to provide both. So, most commands actually have two names to choose from, a descriptive name and a short name. For example, "clrg" is the same as "clresourcegroup":

clresourcegroup create rg1
clrg create rg1

From the examples above, you might have noticed that the new commands accept long option names (e.g., --property, --help, --version, ...). Long option names are useful, especially in shell scripts, as they tend to be self-documenting. But, they can also get in the way when issuing commands directly from the command line. All of the new commands support both long-names and single-letters for options. When specifying options, users may either use long option names, with a double dash (--), or short option letters, with a single dash (-). As an example, the following two commands do exactly the same thing:

clrg create --property Description="My rg" rg1
clrg create -p Description="My rg" rg1

By now, you may thinking that this is pretty basic stuff and is very similar to other commands that you have used. And, that is exactly what we intended. The new Solaris Cluster command line interface is designed to present a familiar interface. Commands are GNU-like, but actually conform to the slightly stricter conventions of Sun's "Command Line Interface Paradigm" (CLIP).

There isn't enough space here to describe all of the useful features packed into the new command set. But, let's use a couple of simple examples to quickly illustrate some of the other features that we haven't yet touched upon.

Our first example deletes, then re-creates, all resources and groups in a cluster:

# cluster export >clusterconfig.xml
# clrg delete --force +
# clrg create --input clusterconfig.xml +
# clrs create --input clusterconfig.xml +
# clrg online +

The first command in this example is "cluster export". Most of the new commands support an "export" subcommand for exporting a copy of selected cluster configuration data in XML format. The "cluster" command is something of an "umbrella" command and can, among other things, generate status and configuration reports for the entire cluster by using it with its "status", "show", or "export" subcommands.

Next, "clrg delete --force +" is used to delete all resources and resource groups from the cluster. The force option tells the command to delete all resource groups, even if groups still contain resources. The "+" symbol can be used as an operand to most commands as a sort of "wildcard character", to indicate all objects of the type managed by the command.

The next two commands, "clrg create" and "clrs create" are used to re-create all of the resource groups and resources described in the "clusterconfig.xml" file created in the first step. As a different approach, we could have actually left out this "clrg" step and used the "--automatic" option in the "clrs" step to automatically create any groups needed by the new resources.

Finally, all resource groups in the cluster are brought online using "clrg online +".

This next example shows how a "string array" resource property can be updated:

# clrs list-props --verbose myresource
Property Name       Description
-------------  -----------
myuserlist          This is a list of user names
# clrs set -p myuserlist+=user9,user10 myresource

"list-props" is a fairly helpful subcommand. It is used to list property names and, if used with --verbose, their descriptions. With "clrs", the default is to just list extension properties; but, options are available to list standard properties as well. In this example, we have used "clrs list-props" to list descriptions of all extension properties for the resource called "myresource".

Finally, "clrs set" is used to update the "myuserlist" extension property of resource "myresource". Notice that it is no longer necessary to distinguish between "extension" and "standard" properties when updating them on the command line (unless a resource type uses an "extension" property name which collides with a "standard" property name). Another useful feature is that "string array" properties can now be updated without having to re-specify the unchanged portion of the array. The --property (-p) option to "clrs" supports all of the following syntax for updating a "string array" resource property:

--property <property name>=<property value list>
--property <property name>+=<property value list>
--property <property name>-=<property value list>

Online man pages for the the new Solaris Cluster CLI can be found in the "1CL" section of the Sun Cluster Reference Manual for Solaris OS.

There are many more powerful features in the new command set that we have not been able to touch on here. Let us know what you like best about the new command set. And, of course, send us your suggestions for improvements, too.


John Cummings
Sr. Staff Engineer
Solaris Cluster Engineering

About

mkb

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today