News, tips, partners, and perspectives for the Oracle Solaris operating system

A New Command Set for Solaris Cluster 3.2

Guest Author

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

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

Join the discussion

Comments ( 5 )
  • Jeroen Friday, January 12, 2007
    What do the += and -= for clrs set -p propname do ?
  • guest Monday, January 15, 2007
    My guess is += adds a extra value to a existing property value.
    For example,
    foo = hello,
    Now after,
    foo += world
    foo becomes,
    foo = hello, world.
    += saves you from typing a property's current value. Very useful for properties that have value with many characters.
    -= operator must be a way to remove a value.
  • Martin Rattner Tuesday, January 16, 2007
    The conjecture in the above comment is basically correct. The += and -= operators apply to properties that have 'stringarray' values, i.e., values represented as a comma-delimited sequence of strings. For example, the Nodelist property of a resource group contains a comma-separated list of nodenames. Another example is the resource property Resource_dependencies, which is a comma-delimited list of resource names. If the list is long, and you only want to delete or add one element, it used to be the case that you had to re-type the entire list. With += or -= you can easily add or delete a single element in the list.
  • nimesh.anil@gmail.com Thursday, February 12, 2009


  • Subhash Singh Friday, March 12, 2010

    no comment

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.