Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### clpstring

### , clps

- manage Oracle Solaris Cluster private strings

### Synopsis

    /usr/cluster/bin/clpstring  -V

    /usr/cluster/bin/clpstring subcommand -?

    /usr/cluster/bin/clpstring subcommand
     [options] -v  [pstring-name[...]

    /usr/cluster/bin/clpstring create -b object-instance [-f stringvalue-file]
         [-t object-type] [-Z {zoneclustername | global}] pstring-name

    /usr/cluster/bin/clpstring delete [-F]
         [-Z {zoneclustername[,...] | global | all}] + | pstring-name ...

    /usr/cluster/bin/clpstring list [-b object-instance[,...]] [-t type[,...]]
         [-Z {zoneclustername[,...] | global | all}] [+ | pstring-name[ ...]]

    /usr/cluster/bin/clpstring set [-f stringvalue-file] [-Z {zoneclustername | global}] pstring-name

    /usr/cluster/bin/clpstring show [-b object-instance[,...]] [-t type[,...]]
         [-Z {zoneclustername[,...] | global | all}] [+ | pstring-name[ ...]]

## Description

The `clpstring` command manages Oracle Solaris Cluster private strings. A private string is identified with a unique name, and has an encoded value that can only be obtained by using the `scha_cluster_get`(1HA) command.

Private strings are used by cluster objects such as resources to store and retrieve private values securely. A typical use might be for an internal password used by an agent.

The `clps` command is the short form of the `clpstring` command. The `clpstring` command and the `clps` command are identical. You can use either form of the command.

The general form of this command is as follows:

    clpstring  [subcommand] [options] [operands]

You can omit subcommand only if options specifies the `-?` option or the `-V` option.

Each option of this command has a long form and a short form. Both forms of each option are provided with the description of the option in the OPTIONS section of this man page.

Use the `clpstring` command for the following administrative tasks:

- To create a private string that is intended to be used by a cluster object instance that may or may not yet exist

- To update the value of private string

- To delete private strings from the cluster configuration

- To display the specifications of private strings

The `clpstring` command can be run only on an active cluster node. The result of running the command is always the same regardless of the node on which you run it.

All the subcommands of the `clpstring` command can be run in both the global zone and a zone cluster. When you run it in a global zone, you can use the `-Z` option to specify the name of a particular zone cluster to which you want to restrict an operation.

You can access all zone cluster information from a global cluster node, but a particular zone cluster is not aware of other zone clusters. If you do not restrict an operation to a particular zone cluster, the subcommand you use operates in the current cluster only.

## SUBCOMMANDS

The following subcommands are supported:

`create`

  Create a private string that is intended to be used by an Oracle Solaris Cluster object instance.

  Use the `-b` option to specify the cluster object instance that intends to use this private string. The object instance does not have to exist in the cluster configuration when you create the private string for the instance. Use the `-t` option to indicate the type of the cluster object instance. The default object type is `resource`.

  Use the `-f` option to specify a file that contains the private string value. The command prompts for the private string value if `-f` is not specified. Details can be found in the OPTIONS section.

  Users other than superuser require `solaris.cluster.modify` role-based access control (RBAC) authorization to use the `create` subcommand. See the `rbac`(5) man page for more information.

  See also the description of the `delete` subcommand.

`delete`

  Delete the specified private strings for the Oracle Solaris Cluster configuration.

  If you do not specify the force option `-F`, you must have already removed the cluster object instance for which the private string was created. If you specify the `-F` option, the command removes the private strings even if the associated object instance still exists in the cluster configuration and uses the private string. See `-F` in OPTIONS for more information.

  Users other than superuser require `solaris.cluster.modify` RBAC authorization to use the `delete` subcommand.

  See also the description of the `create` subcommand.

`list`

  Displays the names of all private strings created in the cluster, but not their values.

  Users other than superuser require `solaris.cluster.read` RBAC authorization to use this subcommand.

`set`

  Sets the value of the specified private string. You can use the `-f` option to specify the source of the private string value. The command prompts for the value if `-f` is not specified. See the description of `-f` option in the OPTIONS section for information about the private string value.

  Users other than superuser require `solaris.cluster.modify` RBAC authorization to use this subcommand.

`show`

  Displays the specifications of private strings, but not their values. The specifications include the private string names, their associated object instances, and the object type of the instances.

  Users other than superuser require `solaris.cluster.read` RBAC authorization to use this subcommand.

## Options

The following options are supported:

`-?`
`--help`

  Displays help information. When this option is used, no other processing is performed.

  You can specify this option without a subcommand or with a subcommand.

  If you specify this option without a subcommand, the list of subcommands for this command is displayed.

  If you specify this option with a subcommand, the usage options for the subcommand are displayed.

`-b` object-instance
`--object-instance=`object-instance
`--object-instance` object-instance

  Specifies the name of an object instance which uses or intends to use the private string. Only object instances whose object type is `resource` are supported currently.

`-F`
`--force`

  Forces the removal of the specified private strings. You can specify this option only with the `delete` subcommand.

  When you use this option with the `delete` subcommand, you delete the specified private strings even if the object instance that uses the private string still exists in the cluster. You would normally remove the object instance from the cluster before removing its private strings.

`-f` stringvalue-file
`--stringvalue-file=`stringvalue-file
`--stringvalue-file` stringvalue-file

  Specifies the file that contains the value of a private string. The filename must be a full path that can be accessed from the node where you run the command.

  For security reasons, the private string value cannot be specified in command-line options. To keep the value secure, place it in a plain text file and specify the full path to the file by using the `-f` option. Make root the owner of the string value file, and set permissions of the file to be readable by root and prohibit any access by group and world. For even greater security, you can delete the file after you run the command to set the value in the private string.

  If you do not specify the `-f` option, the command prompts for the private string value twice to confirm that it is entered the same. It reads the value from the controlling terminal with echoing disabled.

  You can specify `-f -` (a space and dash following the `-f`) to read the private string value directly from standard input just once. The private string value is echoed on screen as it is typed, or will appear in a script if the command is scripted; so you should be careful when setting the private string value this way.

  The private string value input has the following requirements:

  - The length of the string must be less than or equal to 257 characters.

  - The string cannot include NUL characters.

`-t` object-type
`--object-type=`object-type
`--object-type` object-type

  Specifies the type of the object instance. The default type is `resource` and is currently the only object type that can use private strings, so the `-t` option is not required.

`-V`
`--version`

  Displays the version of the command.

  Do not specify this option with subcommands, operands, or other options. The subcommands, operands, or other options are ignored. The `-V` option displays only the version of the command. No other operations are performed.

`-v`
`--verbose`

  Displays verbose messages to the standard output.

  You can specify this option with any form of the command.

`-Z` {zoneclustername | `global` | `all` }
`--zoneclustername=`{zoneclustername | `global` | `all` }

  Specifies the cluster where the private string is to be created or where it exists.

  This option is supported by all subcommands.

  If you specify this option, you must also specify one argument from the following list:

  zoneclustername

    Specifies that the command with which you use this option is to operate on all specified private strings in the zone cluster named zoneclustername only.

  `global`

    Specifies that the command with which you use this option is to operate on all specified private strings in the global cluster only.

  `all`

    If you use this argument in the global cluster, it specifies that the command with which you use it is to operate on all specified resources in all clusters, including the global cluster and all zone clusters.

## Operands

Only the following operand is supported:

pstring-name

  Specifies the name of a private string. When you create a private string, the name you give must be unique across the cluster. If the subcommand accepts more than one private string, you can use the plus sign (`+`) in place of the pstring-name to specify all private strings.

## Exit Status

If the command is successful for all specified operands, it returns zero (`CL_NOERR`). If an error occurs for an operand, the command processes the next operand in the operand list. The returned exit code always reflects the error that occurred first.

The following exit codes can be returned:

`0` `CL_NOERR`

  No error

  The command that you issued completed successfully.

`1` `CL_ENOMEM`

  Not enough swap space

  A cluster node ran out of swap memory or ran out of other operating system resources.

`3` `CL_EINVAL`

  Invalid argument

  You typed the command incorrectly, or the syntax of the cluster configuration information that you supplied with the `-i` option was incorrect.

`6` `CL_EACCESS`

  Permission denied

  The object that you specified is inaccessible. You might need superuser or RBAC access to issue the command. See the `su`(1M) and `rbac`(5) man pages for more information.

`18` `CL_EINTERNAL`

  Internal error was encountered

  An internal error indicates a software defect or other defect.

`36` `CL_ENOENT`

  No such object

  The object that you specified cannot be found for one of the following reasons:

  - The object does not exist.

  - A directory in the path to the configuration file that you attempted to create with the `-o` option does not exist.

  - The configuration file that you attempted to access with the `-i` option contains errors.

`37` `CL_EOP`

  Operation not allowed

  You tried to perform an operation on an unsupported configuration, or you performed an unsupported operation.

`39` `CL_EEXIST`

  Object exists

  The device, device group, cluster interconnect component, node, cluster, resource, resource type, resource group, or private string that you specified already exists.

`41` `CL_ETYPE`

  Invalid type

  The type that you specified with the `-t` or `-p` option does not exist.

These exit values are compatible with the return codes that are described in the `scha_calls`(3HA) man page.

## Examples

Example 1 Creating a Private String for a Resource in the Global Cluster or Zone Cluster

The following command creates a private string for a resource instance in the global cluster.

    # clpstring create -b resource1 -t resource -v pstring1
    Enter string value:
    Enter string value again:
    Private string "pstring1" is created for the global cluster.

The following command is run in the global zone and creates a private string to the zone cluster named `zc1`. The value of the private string is specified in file `/pvalue.file`.

    # clpstring create -Z zc1 -b resource2 -f /pvalue.file pstring2

Example 2 Deleting the Private Strings from the Global Cluster or Zone Cluster Configuration

The following command deletes all the private strings from the cluster configuration, whether the object instances still exist in the cluster or not.

    # clpstring delete -F +

The following command deletes the specified private string from a zone cluster named zc1.

    # clpstring delete -Z zc1 pstring1

Example 3 Displaying the specifications of private strings created in the cluster

The following command displays the private strings in the cluster.

    # clpstring show
    === Private Strings ===

    Pstring Name:                                   pstring1
      Object Instance:                                 resource1
      Object Type:                                     resource

    Pstring Name:                                   pstring2
      Object Instance:                                 object2
      Object Type:                                     resource

Example 4 Listing the Private Strings in the Global Cluster and Zone Clusters

The following command displays the private string names in the global cluster and all the zone clusters.

    # clpstring list -Z all
    global:pstring1
    global:pstring2
    zc1:pstring1
    zc1:pstring2
    zc2:pstring

## Attributes

See `attributes`(5) for descriptions of the following attributes:

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | ha-cluster/system/core
Interface Stability | Evolving

## See Also

`Intro`(1CL), `cluster`(1CL), `scha_calls`(3HA), `attributes`(5), `rbac`(5)

## Notes

The superuser can run all forms of this command.

Any user can run this command with the following options:

- `-?` option

- `-V` option

To run this command with subcommands, users other than superuser require RBAC authorizations. See the following table.

Subcommand | RBAC Authorization
--- | ---
`create` | `solaris.cluster.modify`
`delete` | `solaris.cluster.modify`
`list` | `solaris.cluster.read`
`set` | `solaris.cluster.modify`
`show` | `solaris.cluster.read`

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |