Chapter 41 Shell Script

Waveset provides the Shell Script resource adapter to manage a resource that is controlled by shell scripts running on the system hosting the resource. This adapter is a general purpose adapter, and is therefore highly configurable.

This adapter is defined in the com.waveset.adapter.ShellScriptResourceAdapter class.

Adapter Details

Resource Configuration Notes

You can use the ERROR_CODE_LIMIT attribute to define which error codes can represent errors. A code that exceeds the value specified here indicates an error. Any code that is less than this value should be used for informative or warning codes. If you do not set this value, then Waveset defaults to standard behavior, in which any non-zero return code indicates an error. You can add this optional attribute to the resource definition.

Waveset Installation Notes

To add this resource to the Waveset resources list, you must add the following value in the Custom Resources section of the Configure Managed Resources page.

Usage Notes

Do not use control characters (for example, 0x00, 0x7f) in user passwords.

Resource Actions

The Shell Script adapter allows you to create a set of actions that perform basic provisioning functions such as creating, updating, deleting, and retrieving user accounts. Each of these actions is defined in a shell script. The Shell Script adapter works by running resource actions as a UNIX resource adapter. To run resource actions, this adapter must

• Run its create, delete, and update operations under its /tmp directory.

• Have the ability to run commands such as mkdir, umask, touch, cat, chmod, rm - f, rmdir, find, set, and use operators such as <, <<, >, >>.

The adapter supports the provisioning actions listed in the following table:

The $WSHOME/sample/ShellScript directory contains a set of sample resource action definitions that could be used to provision users to a theoretical shell script-based host application. You must customize these definitions to your environment.

For general information about resource actions, see Chapter 51, Adding Actions to Resources.

Scripts

The Shell Script adapter implements actions as shell script files that execute on the resource host. These scripts must be written to run on the shell that has been configured for the account running the scripts on the resource host.

Scripts should follow conventions and exit with a return code of 0, which indicates success. Returning a non-zero code (chosen by the script writer) indicates the operation may not have been correctly completed.

Scripts may output text to the standard error or standard output stream. Depending on the nature of the operation, the context of the operation, and the type of failure, the text may be displayed in the results for that operation.

For the getUser and getAllUsers operations, this text is parsed in the standard output stream to determine the attributes of each user.

The following types of environment variables can be exported to the scripts:

• Any account attribute defined in the Identity System Resource Attribute column of the schema map can be made available to the script by prefixing the account attribute with WSUSER_. For example, if an account attribute is named Full Name, the environment variable is named WSUSER_Full_Name. (Spaces are replaced with underscores.)

• Adapter configuration settings can be passed with environment variables that begin with WSRSRC_. The most important variable is WSRSRC_Name, which defines the name of the adapter. If you are running the same script on different resources, this variable can be implemented to avoid maintaining multiple copies of scripts that do the same thing on different hosts.

The following code example illustrates an example-generated environment:

WSRSRC_Host=’129.153.147.151’; export WSRSRC_Host
WSRSRC_Port=’22’; export WSRSRC_Port
WSRSRC_Login_User=’root’; export WSRSRC_Login_User
WSRSRC_password=’074B7E28F5927C90:1C65216:108540A69DE:-7FFD|zGEBDGD3VRs=’; export WSRSRC_password
WSRSRC_Login_Shell_Prompt=’]#’; export WSRSRC_Login_Shell_Prompt
WSRSRC_Root_User=’root’; export WSRSRC_Root_User
WSRSRC_credentials=’074B7E28F5927C90:1C65216:108540A69DE:-7FFD|zGEBDGD3VRs=’; export WSRSRC_credentials
WSRSRC_Root_Shell_Prompt=’]#’; export WSRSRC_Root_Shell_Prompt"
WSRSRC_Connection_Type=’SSH’; export WSRSRC_Connection_Type"
WSRSRC_Maximum_Connections=’10’; export WSRSRC_Maximum_Connections"
WSRSRC_Connection_Idle_Timeout=’900’; export WSRSRC_Connection_Idle_Timeout"
WSRSRC_Display_Name_Attribute=’accountId’; export WSRSRC_Display_Name_Attribute"
WSRSRC_NAME=’ShellTest’; export WSRSRC_NAME"
WSRSRC_ID=’#ID#074B7E28F5927C90:B122A1:108E3E4CFAA:-7FFC’; export WSRSRC_ID"
WSRSRC_TYPE=’Resource’; export WSRSRC_TYPE"
WSRSRC_CLASS=’class com.waveset.object.Resource’; export WSRSRC_CLASS"

Generally, if an attribute’s value is null, you can omit the corresponding environment variable instead of having the value of a zero-length string.

For more information about the variables available in a script, see Chapter 51, Adding Actions to Resources.

Result Handling

The AttrParse mechanism processes the results returned by the getUser and getAllUsers actions through the standard output stream. See Chapter 50, Implementing the AttrParse Object for more information about this mechanism.

For getUser actions, AttrParse returns a map of user attributes. For the getAllUsers action, it generates a map of maps. Each entry for the returned map contains the following.

• A value that is a map of user attributes similar to those typically returned by AttrParse.

• A key that is the account ID, or if that is not known, the name.

The collectCsvHeader and collectCsvLines AttrParse tokens can be used to determine attributes and values.

Security Notes

This section provides information about supported connections and privilege requirements.

Supported Connections

Waveset uses the following connections to communicate with the shell script adapter:

• Telnet

• SSH (SSH must be installed independently on the resource.)

• SSHPubKey

For SSHPubKey connections, the private key must be specified on the Resource Parameters page. The key must include comment lines such as --- BEGIN PRIVATE KEY --- and --- END PRIVATE KEY --. The public key must be placed in the /.ssh/authorized_keys file on the server.

Required Administrative Privileges

The administrative account that the script runs under must be authorized for all operations defined in the scripts.

Provisioning Notes

The following table summarizes the provisioning capabilities of the Shell Script adapter.

Account Attributes

The Shell Script adapter does not provide default account attributes because the account attributes vary greatly.

The account must have an account attribute in which the Identity System user attribute is named accountId.

Resource Object Management

Not supported.

Identity Template

None. You must supply the identity template with a valid value.

Sample Forms

There are no sample user forms, but an example resource and AttrParse definition are provided in the following location:

$WSHOME/sample/ShellScript/ShellScriptResourceObjects55.xml

Troubleshooting

Use the Waveset debug pages to set trace options on the following class:

com.waveset.adapter.ShellScriptResouceAdapter