You are here: Administration > Man Pages > LCDI-instances(1M)

LCDI-instances(1M)

NAME

LCDI-instances(1M) — access to resource instance data

SYNOPSIS

ins_gettag [-d dest] -i id

ins_create [-d dest] -a app -r restyp [-I {AUTORES_ISP|INIT_ISP|INIT_OSU}][-v info] [-s {INTELLIGENT|AUTOMATIC}] -t tag -i id

ins_remove [-d dest] [-R roottag] [-a app] [-r restyp] [-t tag] [-i id][-v] [-I] [-N] [ -G] [-U]

ins_setas [-d dest] -t tag -s {INTELLIGENT|AUTOMATIC}

ins_setinfo [-d dest] -t tag [-v info]

ins_setinit [-d dest] -t tag -I {AUTORES_ISP|INIT_ISP|INIT_OSU}

ins_setstate [-d dest] -t tag -S {ISP|ISU|OSU} [-R reason] [-A]

ins_list [-d dest] [-fC] [-R top] [-a app] [-r typ] [-t tag] [-i id]

DESCRIPTION

Resources are used by LifeKeeper to represent peripherals, applications, or system objects known by the system. Resource types are classifications of resources; resource instances are actual instances. For example, resource types would include SCSI disk partitions, TCP/IP endpoints, and processes. Resource instances would include a SCSI disk partition, /dev/sda1; TCP/IP endpoint, uname; and process, 14931—a database process. Multiple instances may exist for a resource type.

Resource instances may exist in a number of states. These states may take on the following values and meanings:

ISP

In service with local and remote protection. The resource is operational and protected where a fault may be corrected by a local recovery action, and if that fails, a failover operation to a backup server.

ISU

In service with remote protection, but locally unprotected. The resource is operational and protected, where a fault is corrected by a failover operation to a backup server.

OSF

Out of service from a failure. The resource is not available on this server because a failure has occurred trying to restore the object. It also is used on objects with equivalencies to indicate the object has experienced an interruption in service.

OSU

Out of service, unimpaired. The resource is not available on this server because it was brought out of service by executing its remove script. The OSU state also is used for objects that have dependencies on children in the OSF state or when the equivalent object on a backup server is in the ISP or ISU state.

 

Resource instances can be set up so that they are initialized at system boot time using different strategies:

 

AUTORES_ISP

The resource will automatically have its restore program run; if it succeeds, the resource is placed into the ISP state.

INIT_ISP

The resource will be initialized into ISP state during LCD initialization.

INIT_OSU

The resource will be initialized into OSU state during LCD initialization.

 

Resource switchback strategy can be set to determine the recovery behavior of a server which was running the resource when it failed:

 

INTELLIGENT

Act as backup for the resource.

AUTOMATIC

Attempt to bring the resource back into service on this server, removing it from service on any other server which has lower priority than this one.

SYNTAX

The resource instance interface provides the following commands. All commands exit 0 if successful, and a nonzero code (see EXIT CODES section) and prints to stderr for failure:

ins_gettag [-d dest] -i id

Prints to stdout the tag name that corresponds to the internal identifier provided in id on the server with name dest. If dest is not specified, the current server is assumed. Note that the tag name and id name for a resource are unique on a server,  but may be reused to indicate different resource instances on different servers. The resource tag provides an understandable handle for a resource instance, for example, user-partition, whereas the id is an internal descriptor. The resource name id is used by the application software associated with the resource to uniquely describe the resource.

ins_create [-d dest] -a app -r restyp [-I {AUTORES_ISP| INIT_ISP|INIT_OSU}][-v info] [-s {INTELLIGENT|AUTOMATIC}] -t tag -i id

Defines a new resource instance on server dest in the configuration database. The resource instance is described by the arguments given. If dest is not specified, the current server is assumed. The string tag specified by the -t option is a string that names the resource instance and is unique on a server. It is a string that is meaningful externally to LifeKeeper. The string id specified by the -i option is also unique per server, but may be meaningful only internally to LifeKeeper. The optional string info specified by the -v option is a field that can contain additional resource type specific information and does not necessarily have to be unique per resource type. The initialization type field specified by the -I option indicates how the resource instance should be initialized if the system reboots. The automatic switchback field specified by the -s option indicates the resource instance recovery strategy following server failure. The -a and -r options indicate which preexisting application and resource type this new instance isassociated with.

ins_remove [-d dest] [-R roottag] [-a app] [-r restyp] [-t tag] [-i id][-v] [-I] [-N] [-G] [-U]

Removes resource instance(s) on server dest from the configuration database. Associated dependencies and equivalencies will also be removed. If dest is not specified, the current server is assumed. If the -t option or -i option is specified, the instance with the matching tag or id will be removed along with the resources that depend on them.

Otherwise, if the -r option is specified, all resources of the specified resource type will be removed. In addition, if the -a option is specified, only resources from that application will be removed. The -R option is for removing entire sub-hierarchies and the resources that depend on them. The root tag string defines a list of instance tag names (separated by the ^A character) for which these resources and the resources below on the hierarchy will be recursively removed, until a resource is encountered for which a resource not being removed depends. Finally, if the -v option (verbose) is specified, the function will print a message to stdout including the tag names of all the resource instances that were removed.

Note that all resources that depend on any of the selected resources directly or indirectly will also be removed before the selected resource is removed. Note that when a resource instance is removed, and if a delete action was defined for the resource type of the instance being removed, the delete action is run before the instance is removed.

The -I option initializes the resource hierarchy so that ins_remove will work properly. This option should be used by the "highest-level" recursive call to ins_remove, but not necessarily in a lower-level recursive call such as inside a delete script. The -N option tells ins_remove NOT to reinitialize the resource hierarchy. The assumption when using this option is that a higher level call of ins_remove will perform the -I option.

The -I option should NOT be used by a recursive call to ins_remove from inside a delete script. The -N option MUST be used inside a delete script,since a delete script is being called from a parent invocation of ins_remove and the -N option prevents hierarchy cycles from occurring.

The -G option indicates that the predelete and postdelete scripts [see LCD(1M)] should not be performed as part of this call to ins_remove. This option is useful if one wishes to perform multiple top-level calls to ins_remove and have the predelete and postdelete run manually [using lcdrecover -g delete of LCD(1M)] before and after (respectively) the calls to ins_remove. It would also be wise to use the -G option in the delete scripts since the highest-level ins_remove should perform the predelete and postdelete scripts.

The -U option is used to unextend a hierarchy. This option should only be used on hierarchies where all resources support the unextend feature. The -U parameter is passed to each resource’s delete script. The delete script must not call ins_remove for its related resource on another server when unextending.

ins_setas [-d dest] -t tag -s {INTELLIGENT|AUTOMATIC}

Indicates to LifeKeeper the strategy it should adopt on recovery following a server failure. INTELLIGENT is the default strategy and will cause the recovered server to do nothing other than act as a possible backup for the resource in question. AUTOMATIC is an active strategy and will cause the server to attempt to bring the resource back into service locally, providing the following conditions are satisfied:

  1. The resource hierarchy must have been in-service on this server when it failed.
  2. he resource hierarcy must currently be in-service on a server with lower priority than this server.

ins_setinfo [-d dest] -t tag [-v info]

The string info specified by the -v option is a field that can contain additional resource type specific information and does not necessarily have to be unique per resource type. For example, a resource instance of resource type file-sys may have an identifier of /usr which must be unique to all resource instances on a server, but the info value may be a string like ufs to indicate that the resource instance is a UFS file system resource. Any number of resource instances on a server may have the same info value. If info is not specified, the field is blanked out.

ins_setinit [-d dest] -t tag -I {AUTORES_ISP|INIT_ISP| INIT_OSU}

Indicates to LifeKeeper how it should initialize the state of a resource when LifeKeeper itself initializes (for example, at system boot time). If resource initialization is set to AUTORES_ISP, the resource is first set to the OSU state, then the restore action is performed and, if successful, the resource is put into the ISP state. If restore fails, the resource is placed into the OSF state. If INIT_ISP is set, LifeKeeper assumes the resource was initialized by some other means and places the resource into the ISP state. If INIT_OSU is set, LifeKeeper assumes the resource is not started up during initialization and that the system administrator will manually start up the resource.

ins_setstate [-d dest] -t tag -S {ISP|ISU|OSU} [-R reason][-A]

Sets the resource state on server dest with tag name tag to the state specified in the -S option. Additional text explaining the reason for the change of state may be provided by the -R option. If dest is not specified, the current server is assumed. The -A option sets the state of the specified resource and all the resources that depend on it, recursively up the hierarchy. Use this command cautiously because the resource state will not bechanged by the resource’s action script (e.g. remove or restore script) as is not executed. The caller is responsible for making sure the new state reflects the actual state of the application the resource is protecting.

ins_list [-d dest] [-fC] [-R top] [-a app] [-r typ] [-t tag] [-i id]

This command prints lines relating to a set of resource instances to stdout. Each line contains all of the current information known about a particular resource instance. Examples of the lines are:

<servername>:scsi:hostadp:hostadp18823:sda::ISP:restore action hassucceeded: INIT_ISP:RECOVER:17208:17208::INTELLIGENT

Each line contains fields separated by a delimiter character. The default delimiter character is ^A ( 01). If the -f option is specified, the delimiteris changed to C. The above example shows a colon (:) as a delimiter. The fields are as follows:

       

1

Name of system resource instance resides on.

2

Application name of resource type.

3

Resource type name.

4

End-customer understandable resource instance tag identifier.

5

LifeKeeper internal identifier for resource instance.

6

Additional information pertaining to the instance (type dependent).

7

Current state of resource instance ISP, ISU, OSU, or OSF.

8

Reason for last state change.

9

Resource initialization AUTORES_ISP, INIT_ISP, INIT_OSU, SEC_ISP, or AUTOSEC_ISP.

10

If field is not empty, indicates that the resource is currently being reserved for:

RESTORE: restoring the resource to service

REMOVE:  removing the resource from service

RECOVER: performing local recovery on resource

11

Unix process ID of process that has reserved resource.

12

Unix process group ID of process that has reserved resource.

13

A list of sendevent events that have occurred on resource. Each event has four sub-fields separated by the ^B (\002) character. Multiple events are also separated by the ^B (\002) character:

 

i. event class (-C argument passed to sendevent)

 

ii. event type (-E argument passed to sendevent)

 

iii. time event was posted (represented as number of seconds since Jan 1,1970)

 

iv. timeout seconds used for event "throttling" [see mo(5)].

14

The switchback state of the resource, either INTELLIGENT or AUTOMATIC

The other arguments limit the number of resource instances included into the list. If dest is not specified, the current server is assumed; otherwise, data from the remote server is printed. If tag or id is specified, the resource instance associated with that tag or id is printed. Otherwise, if app is specified, all resource instances associated with all resource types defined by this application will be printed. If app is not specified, all resource instances for all applications defined on the server will be printed. If type is specified, then all resource instances of type, typ, in application app will be printed. If top is the space string "", only the root resources will be printed. If top is specified (but not the space string), then the report lists the top resource and all children resources below it, recursively.

EXIT CODES

The following exit codes could be returned by these commands:

0

The operation has succeeded.

1

A Unix system call or library call has internally returned failure.

2

A user-specified syntax error occurred.

3

LifeKeeper internal error.

4

A request to perform an operation on an object that already exists.

5

An argument specified is illegal.

6

Index out-of-range.

7

A request has been made on an object that does not exist.

8

A request was made to delete a resource instance on which another non-deleted resource instance depends.

9

An attempt to communicate with another server failed.

© 2012 SIOS Technology Corp., the industry's leading provider of business continuity solutions, data replication for continuous data protection.