D High Availability Oracle Clusterware Command-Line Reference and C API

Syntax and Options for crs_getperm

Use the crs_getperm command with the following syntax:

crs_getperm resource_name [-u user|-g group] [-q]

To obtain the permissions associated with a resource, use the following syntax:

crs_getperm resource_name

Example of crs_getperm

To list the permissions associated with the postman application, use the following command:

crs_getperm postman

====================
Name: postman
owner:root:rwx,pgrp:oinstall:r-x,other::r--,user:oracle:r-x,
=====================

Syntax and Options for the crs_profile Command

Use the crs_profile command with the following syntax to create an application profile template:

crs_profile -create resource_name -t application [-a action_script] [-B
 executable_pathname] [-dir directory] [-d description] [-p placement_policy] [-h
 hosting_nodes] [-r required_resources] [-l optional_resources]  [-o option,[...]]
 [attribute_flag attribute_value] [...] [-f] [-q]

crs_profile -create resource_name -t application
          [-dir directory_path] [-a action_script] [-B binary_pathname]
          [-d description] [-h hosting_members] [-r required_resources]
          [-l optional_resources] [-p placement_policy]
          [-o as=auto_start,ci=check_interval,ft=failure_threshold,
          fi=failure_interval,ra=restart_attempts,fd=failover_delay,
          st=script_timeout,ap=active_placement,bt=rebalance,
          ut=uptime_threshold,rt=start_timeout,pt=stop_timeout] [-f] [-q]

To create an application profile from an application profile template you use crs_profile to create a template (a cap) file. This file is then read automatically by the crs_register command which reads the data from the cap file and puts it in the OCR. For example:

crs_profile -create resource_name -I template_file [-f] [-q]

To validate the application profile syntax of a profile, enter the following command:

crs_profile -validate resource_name [-q]

To list one or more application profiles:

crs_profile -print [resource_name [...]] [-q]

To create an application profile template from an existing application profile:

crs_profile -template resource_name [-O template_file] [-q]

To update an application profile:

crs_profile -update resource_name [option [...]] [-q]

To delete an application profile and its associated action program:

crs_profile -delete resource_name [-q]

crs_profile attribute_flag attribute_value

crs_profile -validate resource_name

Examples of the crs_profile Command

The following is an example of using the crs_profile command to create the application profile for the postman application:

crs_profile -create postman \
-t application \
-a postman.sh \
-o ci=5,ra=2"

The following is an example of using the crs_profile command to validate the application profile named dtcalc:

crs_profile -validate dtcalc

If you do not specify either the -a or -B options, then the profile is created without an action program value. You should create a readable, executable script and update the profile with this script's value before attempting to start the application. If you specify the -a option alone, then the action program specified must exist at the specified location or in the default directory if no path is specified. Otherwise, the command fails.

Syntax and Options for the crs_register Command

You can use the crs_register command to register and update applications. Use the following crs_register syntax to register an application:

crs_register resource_name [-dir directory_path] [...] [-u] [-f] [-q]

crs_register resource_name -update [-a action_script]
[-d description] [-h hosting_members] [-r required_resources]
[-l optional_resources] [-p placement_policy]
[-o as=auto_start,ci=check_interval,ft=failure_threshold,
fi=failure_interval,ra=restart_attempts,fd=failover_delay,
st=script_timeout,ap=active_placement,bt=rebalance,
ut=uptime_threshold,rt=start_timeout,pt=stop_timeout] [-q]

The resource_name [...] parameter can be the name of one or more application resources as specified in an application profile. If you do not specify any options, then the crs_relocate command relocates each specified application resource according to its placement policy and required resource lists. Oracle Clusterware does not relocate a resource if there are interdependent application resources unless you specify the -f option. A profile must exist for the application that you are registering.

crs_profile attribute_flag attribute_value

crs_profile -validate resource_name

Use the following crs_register command syntax to update a registered application:

crs_register resource_name -update [option ...] [-o option,...] [-q]

Example of the crs_register Command

The following example registers an application named postman for which an application profile exists in the CRS_home/crs/profile directory:

CRS_home/bin/crs_register postman

Related Commands for the crs_register Command

crs_stat, crs_profile, crs_relocate, crs_start, crs_stop, crs_unregister

Syntax and Options for the crs_relocate Command

Use the crs_relocate command with the following syntax:

crs_relocate resource_name [...] [-c cluster_node] [-f] [-q]

crs_relocate resource_name [-c cluster_node] [-q]

crs_relocate [USR_attribute_name=value] [...] resource_name [-c cluster_node] [-q]

crs_relocate -s source_node [-c cluster_node] [-q]

Example of the crs_relocate Command

The following example relocates an application resource to the node known as rac1:

crs_relocate postman -c rac1
Attempting to stop `postman` on node `rac2`
Stop of `postman` on node `rac1` succeeded
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded

The following example attempts to relocate all application resources from node rac2 to node rac1:

crs_relocate -s rac2 -c rac1
Attempting to stop `postman` on node `rac2`
Stop of `postman` on node `rac2` succeeded.
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded.
Attempting to stop `calc` on node `rac2`
Stop of `calc` on node `rac2` succeeded.
Attempting to start `calc` on node `rac1`
Start of `calc` on node `rac1` succeeded.

If a user-defined attribute USR_DEBUG has been defined, then the following example runs the stop and start entry point of the action program with the USR_DEBUG environment variable set to FALSE. This overrides any value set in the application profile. In the corresponding action program, if you add the following line to the appropriate section of the action program, then you can view the value:

echo $USR_DEBUG

Then issue the following command:

# crs_relocate USR_DEBUG=false database

Syntax and Options for the crs_setperm Command

Use the crs_setperm command with the following syntax:

crs_setperm resource_name -u aclstring [-q]

crs_setperm resource_name -x aclstring [-q]

crs_setperm resource_name -o user_name [-q]

crs_setperm resource_name -g group_name [-q]

Example of the crs_setperm Command

The following example modifies the permissions on the admin1 user for the postman application:

crs_setperm postman -u user:admin1:r-x

Syntax and Options for the crs_stat Command

Use the crs_stat command with the following syntax:

crs_stat [resource_name [...]] [-v] [-l] [-q] [-c cluster_node]

crs_stat [resource_name [...]] -t [-v] [-q] [-c cluster_node]

crs_stat -p [resource_name [...]] [-q]

crs_stat [-a] resource_name -g

crs_stat [-a] resource_name -r [-c cluster_node]

crs_stat -f [resource_name [...]] [-q] [-c cluster_node]

crs_stat -ls resource_name

To view information about all resources, enter the command with no arguments.

Examples of the crs_stat Command

The following example displays the status information for the postman application:

crs_stat postman

NAME=postman
TYPE=application
TARGET=ONLINE
STATE=ONLINE on rac2

The following example displays the status information in a tabular form:

crs_stat -t

Name         Type        Target      State     Host
----------------------------------------------------------------
cluster_lockd application ONLINE    ONLINE     rac2
dhcp          application OFFLINE   OFFLINE

The following example shows the output for the crs_stat command with the -v option for the node rac2:

crs_stat -v

NAME=cluster_lockd
TYPE=application
RESTART_ATTEMPTS=30
RESTART_COUNT=0
FAILURE_THRESHOLD=0
FAILURE_COUNT=0
TARGET=ONLINE
STATE=ONLINE on rac2

Syntax and Options for the crs_start Command

Use the crs_start command with the following syntax:

crs_start resource_name  [...] [-c cluster_node] [-q] [-f]

crs_start -all [-q]

crs_start [USR_attribute_name=value] [...] resource_name [-c node_name] [-q]

For resource_name [...], the names are as specified in an application profile of one or more resources to be started. The resource must be registered with Oracle Clusterware.

Examples of the crs_start Command

The following example starts an application named postman:

crs_start postman
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded.

The following example starts the application on a specific cluster node rac2:

crs_start -c rac2 postman
Attempting to start `postman` on node `rac2`
Start of `postman` on node `rac2` succeeded.

Syntax and Options for the crs_stop Command

Use the crs_stop command with the following syntax:

crs_stop resource_name [...] [-f] [-q]

crs_stop -c cluster_node [...] [-q]

crs_stop -all [-q]

crs_stop [USR_attribute_name=value] [...] resource_name [-q]

-c cluster_node [...]

Specifies one or more active cluster nodes on which to stop all of the applications or application resources. You can use the options described in Table D-11:

Examples of the crs_stop Command

To stop an application named dtcalc, enter the following command:

crs_stop dtcalc

Status Messages for the crs_stop Command

Oracle Clusterware displays the following status messages:

Attempting to stop `dtcalc` on node `rac2`
Stop of `dtcalc` on node `rac2` succeeded.

Syntax and Options for the crs_unregister Command

Use the crs_unregister command with the following syntax:

crs_unregister resource_name [...] [-f] [-q]

You can use the options described in Table D-12:

Example of the crs_unregister Command

The following example unregisters a highly available application called postman:

crs_unregister postman

The following example forcefully unregisters the listener:

crs_unregister ora.LISTENER_node-name.lsnr -f

Parameters

• ctx—Context to initialize, caller allocated storage

• errf—A Callback function for the error info, or NULL

• errCtx—Context for the error callback func, or NULL

• flags—CLSCRS_FLAG_TRACE, to enable tracing of lower layers

• CLSCRS_FLAG_USETHREADS—Enables using the clscrs context in multiple threads

Returns

Status enum.

Syntax

CLSCRS_STAT clscrs_init_crs(clscrs_ctx **ctx, clscrs_msgf errf, void *errCtx, ub4 flags);

Parameter

ctx—Context previously initialized with clscrs_init_crs.

Returns

status enum

Syntax

CLSCRS_STAT clscrs_term_crs( clscrs_ctx **ctx);

Parameters

• ctx—Context previously initialized with clscrs_init

• node_name—Filled in node name

Syntax

CLSCRS_STAT clscrs_getnodename(clscrs_ctx *ctx, oratext *node_name);

Parameters

• context—Input context

• env—Output environment pointer

Returns

status enum

Syntax

CLSCRS_STAT clscrs_env_create( clscrs_ctx *ctx, clscrs_env *env );

Parameters

• env—Previously created environment

• attr—Attribute name

• val—Attribute value, may be NULL pointer

Returns

environment status enum

Syntax

CLSCRS_ENVCODE clscrs_env_set(clscrs_env env, const  oratext *attr, const oratext *val);

Parameters

• env—The environment whose contents are deleted

Returns

environment status enum.

Syntax

CLSCRS_ENVCODE clscrs_env_delete(clscrs_env env);

Parameters

• env—Env to dump

• msgf—Callback function

• msgp—Argument to msgp, uninterpreted

Returns

None.

Syntax

void clscrs_env_format( clscrs_env env, clscrs_msgf msgf, void *msgp );

Parameters

• ctx—The context

• names—The resource(s) to start

• num_names—The number of resources in names[] to start

• host—The host name on which to start the resource, may be NULL

• env—Environment arguments to start

• msgf—User message callback, may be NULL

• msgp—User callback argument, may be NULL

• msgf—Callback function

• msgf—Callback function

Returns

status enum

Syntax

CLSCRS_STAT clscrs_start_resource( clscrs_ctx *ctx, const oratext *name[], sword
 num_names, const oratext *host, clscrs_env env, clscrs_msgf msgf, void *msgp,
 uword flag );

Parameters

• ctx— the context

• names—The resource(s) to stop

• num_names—Number of resources in names[] to stop

• flag—Async, force options

Returns

status enum

Syntax

clscrs_stop_resource( clscrs_ctx *ctx, const oratext *names[], sword num_names,
clscrs_env env, clscrs_msgf msgf, void *msgarg, uword flag );

Parameters

• in_splist [in]—List of resources to check

• delay_secs [in]—Time to wait before the check is run, as appropriate to the resource

• flags [in]—None

• op_status [out]—Resource list structure holding the status of the check operation for each resource

Returns

status enum.

Syntax

clscrs_check_resource( clscrs_splist *in_splist, ub4 delay_seconds, uword flags,
 clscrs_reslist *op_status);

Parameters

• in_reslist [in]—List of resources to be registered

• flags [in]—CLSCRS_FLAG_REG_UPDATE or 0

• op_status [out]—Resource list holding the status of the register operation for each resource

Returns

• CLSCRS_STAT_SUCCESS—If all input resources are successfully registered

• CLSCRS_STAT_FAIL—If atleast one resource could not be registered

• CLSCRS_STAT_CONNECTION—If there is a communication error with the crsd process

Syntax

clscrs_register_resource(clscrs_reslist *in_reslist, uword flags, clscrs_reslist *op_status);

Parameters

• rqlist [in]—List of resources names to be unregistered

• flags [in]—Option flags

• op_status [out]—Resource list holding the status of the unregister operation for each resource

Returns

• CLSCRS_STAT_SUCCESS—If all input resources are successfully unregistered

• CLSCRS_STAT_FAIL—If atleast one resource could not be unregistered

• CLSCRS_STAT_CONNECTION—If there is a communication error with the crsd process

Syntax

clscrs_unregister_resource(clscrs_splist *rqlist, uword flags, clscrs_reslist *op_status);

Parameters

• rqlist [in]—List of resource names to query

• nodename [in]—Query resources running only on the given node (optional, may be NULL)

• res_attrs [in]—List to specify the attributes to be returned for each resource

• res_flags [in]—Flags to restrict the resources being matched

• out_reslist [out]—List holding the returned resource information

Returns

• CLSCRS_STAT_SUCCESS if information is obtained for all input resources

• CLSCRS_STAT_FAIL if no information is available for atleast one resource

• CLSCRS_STAT_CONNECTION if there is an error communicating with the crsd process

Syntax

clscrs_stat(clscrs_splist *rqlist, oratext *nodename, uword res_flags, clscrs_
splist *res_attrs, clscrs_reslist *out_reslist);

Stringpair Operations

This section describes the stringpair operations.

clscrsret clscrs_sp_set(clscrs_sp *sp, const oratext *value);

clscrsret clscrs_sp_get(clscrs_sp *sp, oratext **name, oratext **value);

clscrsret clscrs_sp_get_value(clscrs_sp *sp, oratext **value);

Splist Operations

This section describes the splist operations.

clscrsret clscrs_splist_create(clscrs_ctx *ctx, clscrs_splist **splist);

clscrsret clscrs_splist_create_and_set(clscrs_ctx *ctx, const oratext 
*name, const oratext *value, clscrs_splist **splist);

clscrsret clscrs_splist_append(clscrs_splist *splist, const oratext *name, const oratext *value);

clscrsret clscrs_splist_first(clscrs_splist *splist, clscrs_sp **sp);

clscrsret clscrs_splist_next(clscrs_splist *splist, clscrs_sp **sp);

clscrsret clscrs_splist_replace(clscrs_splist *splist, const oratext *name, const oratext *value);

clscrsret clscrs_splist_delete_sp(clscrs_splist *splist, const oratext *name);

clscrsret clscrs_splist_find(clscrs_splist *splist, const oratext *name, oratext **value);

clscrsret clscrs_splist_count(clscrs_splist *splist, ub4 *count);

clscrsret clscrs_splist_destroy(clscrs_splist **splist);

clscrsret clscrs_res_create(clscrs_ctx *ctx, const oratext *resname, clscrs_res **res);

clscrsret clscrs_res_get_name(clscrs_res *res, oratext **name);

clscrsret clscrs_res_set_attr(clscrs_res *res, const oratext *attrname, const oratext *value);

clscrsret clscrs_res_get_attr(clscrs_res *res, const oratext *attrname, oratext **value);

clscrsret clscrs_res_get_attr_list(clscrs_res *res, clscrs_splist **attrlist);

clscrsret clscrs_res_set_attr_list(clscrs_res *res, clscrs_splist *attrlist);

clscrsret clscrs_res_attr_count(clscrs_res *res, ub4 *count);

clscrsret clscrs_res_get_op_status(clscrs_res *res, CLSCRS_STAT *status, oratext **msg);

clscrsret clscrs_res_get_registered(clscrs_res *res, boolean *registered);

clscrsret clscrs_res_get_node_list(clscrs_res *res, clscrs_splist **nodelist);

clscrsret clscrs_res_destroy(clscrs_res **res);

clscrsret clscrs_reslist_create(clscrs_ctx *ctx, clscrs_reslist **reslist);

clscrsret clscrs_reslist_append(clscrs_reslist *reslist, clscrs_res *res);

clscrsret clscrs_reslist_first(clscrs_reslist *reslist, clscrs_res **res);

clscrsret clscrs_reslist_next(clscrs_reslist *reslist, clscrs_res **res);

clscrsret clscrs_reslist_find(clscrs_reslist *reslist, const oratext *name, clscrs_res **res);

clscrsret clscrs_reslist_count(clscrs_reslist *reslist, ub4 *count);

clscrsret clscrs_reslist_delete_res(clscrs_reslist *reslist, 

clscrsret clscrs_reslist_destroy(clscrs_reslist **reslist);

clscrsret clscrs_get_error_message(clscrs_ctx *ctx, clscrsret err_code, oratext *msg, sb4 msg_len);

clscrs_splist* clscrs_get_fixed_attrlist(clscrs_ctx *ctx, clscrs_attr_grp attrgrp);

Resource Operations

This section describes resource functions. The clscrs_res resource abstraction contains the name of a resource and additional data appropriate to the context in which it is used. Sometimes it carries status and error return information about an operation. Other times it contains attribute data as input to an operation. A resource may be in exactly one resource list. If so, its successor may be found with the NEXT operation.

CLSCRSRET clscrs_res_create(clscrs_cts *ctx, const oratext *resname, clscrs_res **res)

Creates a single resource and fills in a handle to it. The resname must be provided, and cannot be NULL.

CLSCRSRET clscrs_res_get_name (clscrs_res *res, oratext **name);

Returns a pointer to the name of a resource. The returned name pointer is only valid as long as the resource exists.

CLSCRSRET clscrs_res_get_op_status (clscrs_res *res, CLSCRS_STAT *stat, oratext **msg)

If there is a valid operation error value in the resource, fills in the stat and the pointer to an error message and returns SUCCESS. May fill in a NULL for the msg. If there is no valid operation status, returns INVALID.

clscrs_splist *clscrs_res_get_node_list(clscrs_res *res);

Returns an splist holding the nodes currently hosting the resource, or NULL if there is no host for the resource or there are no attributes. The count of the list may obtained and the list iterated. The list is owned by the resource and will be destroyed when the resource is destroyed. This operation is a special case, interpreting the semantics of the attribute or attributes that may hold the current hosting member list. There is no specified ordering of the list.

CLSCRSRET clscrs_res_get_attr(clscrs_res *res, const oratext *attrname, oratext **value);

Fills in a pointer to the value of the attribute with the given name and returns SUCCESS if found, or FAILURE if the name is not present in the attribute set of the resource, and INVALID if there is no attribute list in the resource. May assert if given an invalid resource handle.

CLSCRSRET clscrs_res_set_attr(clscrs_res *res, oratext *attrname, oratext *value);

Sets the value of the attribute with the given name and returns SUCCESS or FAILURE if the name is not present in the attribute set of the resource. If the attribute already exists, then its current value will be replaced. On return, the memory for the name and value may be recycled.

CLSCRSRET clscrs_res_attr_count(clscrs_res *res, ub4 *count);

Fills in the number of attributes that will be returned with a scan using an attrIter. Returns SUCCESS if there are attributes. If there are no attributes, returns INVALID, but still sets the count to zero.

CLSCRSRET clscrs_res_get_attr_list(clscrs_res *res, clscrs_splist **attrlist);

Returns an splist for the attributes of the resource, allowing next() operations for a scan. The list is owned by the resource, which will destroy it when the resource is destroyed. Returns SUCCESS if there is an attribute list, or INVALID if there is not one in the resource. There is no specified ordering of the list.

Resource List Operations

This section describes the resource list operations. The clscrs_reslist resource list is an abstraction that contains information about zero or more resources. A list is created, appended, iterated over, and destroyed.

CLSCRSRET clscrs_reslist_create(clscrs_ctx *ctx, clscrs_reslist **reslist)

Creates a resource list and fills a handle.

CLSCRSRET clscrs_reslist_count(clscrs_reslist *reslist, ub4 *count)

Fills a count of the number of resources in a list.

CLSCRSRET clscrs_reslist_first(clscrs_reslist *reslist, clscrs_res **first)

Fills a handle to the first resource in the list of resources. If the list is empty, fill in NULL.

CLSCRSRET clscrs_reslist_next(clscrs_reslist *reslist, clscrs_res **next)

Fills a handle to the next resource in the list of resources. If the list is empty, fill in NULL.

CLSCRSRET clscrs_reslist_find(clscrs_reslist *reslist, const oratext *name, clscrs_res **res)

Finds a resource by name in a reslist, and fill in a handle to the one located. If the resource is not found, fill in NULL. Does an exact match lookup with no pattern matching.

CLSCRS_RES *clscrs_reslist_destroy(clscrs_res *res)

Deletes a resource list and all of the resources that it currently contains.