 |
Index for
Section 8 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
caa_profile(8)
NAME
caa_profile - Creates, validates, deletes, and updates a Cluster
Application Availability (CAA) resource profile
SYNOPSIS
To create an application resource profile:
/usr/sbin/caa_profile -create resource_name -t application [-a
action_script] [-B executable_pathname] [-d description] [-p
placement_policy] [-h hosting_members] [-r required_resources] [-l
optional_resources] [-o option,[...]] [attribute_flag attribute_value]
[...] [-f] [-q]
To create a network resource profile:
/usr/sbin/caa_profile -create resource_name -t network -s subnet_addr [-d
description] [-o option,[...]] [-f] [-q]
To create a tape resource profile:
/usr/sbin/caa_profile -create resource_name -t tape -n device_name [-d
description] [-o option,[...]] [-f] [-q]
To create a media changer resource profile:
/usr/sbin/caa_profile -create resource_name -t changer -n device_name [-d
description] [-o option,[...]] [-f] [-q]
To create a resource profile from a resource profile template:
/usr/sbin/caa_profile -create resource_name -I template_file [-f] [-q]
To create a resource profile template for a resource type:
/usr/sbin/caa_profile -template -t resource_type [-O template_file]
To create a resource profile template from an existing resource profile:
/usr/sbin/caa_profile -template resource_name [-O template_file] [-q]
To update a resource profile:
/usr/sbin/caa_profile -update resource_name [option [...]] [-q]
To delete a resource profile and its associated action script:
/usr/sbin/caa_profile -delete resource_name [-q]
To list one or more resource profiles:
/usr/sbin/caa_profile -print [resource_name [...]] [-q]
To validate a resource profile:
/usr/sbin/caa_profile -validate resource_name [-q]
OPTIONS
To create an application resource profile:
-create resource_name
Creates a resource profile for the indicated resource type according to
the specified options. A resource_name is a string containing a
combination of characters [a-z, A-Z, 0-9, '.','_']. The resource name
may not start with a period (.). The maxmimum length for a resource
name is 128 characters.
Resource profiles are created in the /var/cluster/caa/profile
directory.
-t application
Indicates an application resource type.
[-a action_script]
Specifies the action script for the application resource. An action
script has start, stop, and check entry points that are called by CAA.
You can specify either a full pathname for the script file, or its
filename (in which case the caa_profile command looks for the file in
the /var/cluster/caa/script directory).
If you specify neither the -a nor -B option, the profile is created
with no action script 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, the action script specified must
exist at the specified location or in the /var/cluster/caa/script/
directory if no path is specified, or the command fails. If the action
script file does not exist, or does not have read and execute
permissions, the caa_profile command fails. See caa(4) for a
description of the contents and function of the action script file.
[-B executable_pathname]
Specifies the location of the application executable and causes the
caa_profile command to generate an action script file that contains the
application executable pathname.
You may use the -a option with the -B option to specify the name for
the action script that is created.
If you specify the -B option alone, the caa_profile command creates an
action script named /var/cluster/caa/script/resource_name.scr.
If you specify neither the -a nor -B option, the profile is created
with no action script value. You should create a readable, executable
script and update the profile with this script's value before
attempting to start the application.
[-d description]
Specifies the description of the resource. Enclose the description in
double quotation marks ("") if it contains white space. If you do not
specify a resource description, CAA uses the resource name.
[-p placement_policy]
Specifies the policy according to which CAA selects the member on which
to start or restart the application resource. You can specify any one
of the following as a placement policy: balanced, favored, or
restricted. All policies except for balanced require you to also
specify the -h flag. See caa(4) for a discussion of how CAA manages
application resources according to each of these placement policies.
If you do not specify the -p option, caa_profile creates an application
resource profile with a balanced placement policy.
[-h hosting_members]
Specifies an ordered list of members, separated by white space, that
can host the application resource. If there are more than one member,
the list must be enclosed in double quotation marks (""). If you
specify the -p option with a placement policy of favored or restricted,
you must also specify the -h option. The -h option can not be specified
with a placement policy of balanced.
The hosting members list is used in conjunction with the application
resource's failover policy, as discussed in caa(4). In general, when
starting or restarting an application resource, CAA considers hosts in
the order in which they are listed in the hosting members list.
[-r required_resources]
Specifies an ordered list of resources, separated by white space, on
which the application depends. These resources must be active on any
member on which the application is running. If there are multiple
required resources, the list must be enclosed in double quotation marks
(""). If you do not specify a required resources list, CAA imposes no
required dependencies upon the application resource.
CAA uses the required resources list, in conjunction with the failover
policy and hosting members list, to determine which members are
eligible to host the application resource. A required resource must be
avalable to a cluster member for an application resource to be started
on the member. A failure of a required resource on the hosting member
will cause CAA to initiate failover of the application. This may cause
CAA to fail the application resource over to another member that
provides the resource or to stop the application. In the latter case,
CAA continues to monitor the required resources list and restarts the
application when the resource is again available in the cluster.
Application resources that are required by another application resource
are started automatically. If caa_start is called with the the -f
option, required resources may be relocated from other members.
[-l optional_resources]
Specifies an ordered list of optional resources, separated by white
space. If there are multiple optional resource specified, the list must
be enclosed in double quotation marks ("").
CAA uses the optional resources list, in conjunction with the required
resources list, failover policy, and hosting members list, to determine
the optimal member to host the application resource when more than one
member is eligible to host the resource. Optional resources must be in
the state ONLINE on a cluster member to affect resource placement. The
cluster member with the most optional resources is used to run the
application. If the hosting members list is not empty, the cluster
member in the list with the most optional resources is used. If the
number of optional resources on cluster members is equal, the member
running the resource with the earliest placement in the list is used to
run the application. The number of optional resources is limited to 58
resources.
A failure of an optional resource on the hosting member does not
initiate application failover.
[-o option[,...]]
Specifies a list of comma-separated options. No white space is allowed.
The following options may be specified for an application resource. See
caa(4) for more information on these options.
st=script_timeout
Sets the maximum time for an action script to execute. The
CAA commands and the CAA daemon return an error message and
post an event to EVM, when they invoke action script entry
points and the script does not complete execution within this
time. The default is 60 seconds.
ap=active_placement
When set to 1, re-evaluates the placement policy when a new
cluster member becomes available. With, placement policies of
favored and restricted a highly available application will
relocate to a more highly favored cluster member. The default
is 0.
as=auto_start
When set to 1, the application resource automatically starts
after a cluster reboot, regardless of whether it had been
stopped or running before the reboot. When set to 0,
automatically starts the application resource only if it had
been running before the reboot. The default is 0.
ci=check_interval
Sets the time (in seconds) at which the check entry point of
the application's action script runs. The check interval is
the maximum amount of time an application can be unavailable
to clients before CAA attempts to restart it. The default
check interval is 60 seconds.
ft=failure_threshold
Specifies the number of times CAA may detect a resource
failure within the failure interval before it marks the
resource as unavailable and stops monitoring it. The value
must be in the range 0-20. Setting the value to 0 (zero)
turns off failure threshold monitoring. If you do not
specify a failure threshold, CAA uses a default failure
threshold of 0 (zero).
fi=failure_interval
Specify the time (in seconds) during which the failure
threshold is tallied and applied. The default failure
interval is 0 (zero). CAA uses a default failure interval of
0, which turns off monitoring of failure threshold and
failure intervals. Specifying a nonzero failure interval is
meaningless unless failure threshold is also nonzero.
ra=restart_attempts
Specifies the number of times CAA attempts to restart the
resource on the current member before attempting to relocate
it elsewhere. The default number of restart attempts is 1.
fd=failover_delay
Specifies the number of seconds CAA waits before attempting
to relocate the application resource. An application
resource that was running on a cluster member that failed
will restart immediately on that member if it becomes
available again within the failover delay period.
If application resources are dependent on each other due to
required resources defined in resource profiles, all
interdependent application resources wait for the largest
failover delay defined for any of the resources.
The default failover delay is 0 (zero) seconds.
-attribute_flag attribute_value
User-defined attributes defined in the application.tdf file can have
their value in the profile defined using the user-defined attribute
flag. For more information on user-defined attributes see caa(4).
-f Forces the creation of the resource profile, even if a profile of the
same name already exists. If the profile already exists, the
caa_profile command moves the existing profile to a file with a .bak
suffix.
-q Runs the command in quiet mode; no messages are displayed on the
console.
To create a network resource profile from an options list:
-create resource_name
Creates a resource profile for the indicated resource type according to
the specified options. A resource_name is a string containing a
combination of characters [a-z, A-Z, 0-9, '.','_']. The resource name
may not start with a period (.). The maxmimum length for a resource
name is 128 characters.
Resource profiles are created in the /var/cluster/caa/profile
directory.
-t network
Indicates a network resource type.
-s subnet_addr
Specifies the subnet address of the network resource. Specify the
subnet address in xxx.xxx.xxx.xxx format (for example, 16.140.112.0).
[-d description]
Specifies the description of the resource. Enclose the description in
double quotation marks ("") if it contains white space. If you do not
specify a resource description, CAA uses the resource name.
[-o option[,...]]
Specifies a list of comma-separated options. No white space is allowed.
The following options may be specified for an application resource. See
caa(4) for more information on these options.
ft=failure_threshold
Specifies the number of times CAA may detect a resource
failure within the failure interval before it marks the
resource as unavailable and stops monitoring it. The value
must be in the range 0-20. Setting the value to 0 (zero)
turns off failure threshold monitoring. If you do not
specify a failure threshold, CAA uses a default failure
threshold of 0 (zero).
fi=failure_interval
Specifies the time (in seconds) during which the failure
threshold is tallied
and applied. The default failure interval is 0 (zero). You
must set the failure interval if the failure threshold is
set. Otherwise, it is optional.
-f Forces the creation of the resource profile, even if a profile of the
the same name already exists. If the profile already exists, the
caa_profile command moves the existing profile to a file with a .bak
suffix.
-q Runs the command in quiet mode; no messages are displayed on the
console.
To create a tape resource profile from an options list:
-create resource_name
Creates a resource profile for the indicated resource type according to
the specified options. A resource_name is a string containing a
combination of characters [a-z, A-Z, 0-9, '.','_']. The resource name
may not start with a period (.). The maxmimum length for a resource
name is 128 characters.
Resource profiles are created in the /var/cluster/caa/profile
directory.
-t tape
Indicates a tape resource type.
-n device_name
Specifies the tape device name. Specify the full path to the device
(for example, /dev/tape/tape1) or just the device name.
[-d description]
Specifies the description of the resource. Enclose the description in
double quotation marks ("") if it contains white space. If you do not
specify a resource description, CAA uses the resource name.
[-o option[,...]]
Specifies a list of comma-separated options. No white space is allowed.
The following options may be specified for an application resource. See
caa(4) for more information on these options.
ft=failure_threshold
Specifies the number of times CAA may detect a resource
failure within the failure interval before it marks the
resource as unavailable and stops monitoring it. The value
must be in the range 0-20. Setting the value to 0 (zero)
turns off failure threshold monitoring. If you do not
specify a failure threshold, CAA uses a default failure
threshold of 0 (zero).
fi=failure_interval
Specifies the time (in seconds) during which the failure
threshold is tallied
and applied. The default failure interval is 0 (zero). You
must set the failure interval if the failure threshold is
set. Otherwise, it is optional.
-f Forces the creation of the resource profile, even if a profile of the
the same name already exists. If the profile already exists, the
caa_profile command moves the existing profile to a file with a .bak
suffix.
-q Runs the command in quiet mode; no messages are displayed on the
console.
To create a media changer resource profile from an options list:
-create resource_name
Creates a resource profile for the indicated resource type according to
the specified options. A resource_name is a string containing
a combination of characters [a-z, A-Z, 0-9, '.','_']. The resource
name may not start with a period (.). The maxmimum length for a
resource name is 128 characters.
Resource profiles are created in the /var/cluster/caa/profile
directory.
-t changer
Indicates a tape resource type.
-n device_name
Specifies the tape device name. Specify the full path to the device
(for example, /dev/changer/mc0) or just the device name.
[-d description]
Specifies the description of the resource. Enclose the description in
double quotation marks ("") if it contains white space. If you do not
specify a resource description, CAA uses the resource name.
[-o option[,...]]
Specifies a list of comma-separated options. No white space is allowed.
The following options may be specified for an application resource. See
caa(4) for more information on these options.
ft=failure_threshold
Specifies the number of times CAA may detect a resource
failure within the failure interval before it marks the
resource as unavailable and stops monitoring it. The value
must be in the range 0-20. Setting the value to 0 (zero)
turns off failure threshold monitoring. If you do not
specify a failure threshold, CAA uses a default failure
threshold of 0 (zero).
fi=failure_interval
Specifies the time (in seconds) during which the failure
threshold is tallied
and applied. The default failure interval is 0 (zero). You
must set the failure interval if the failure threshold is
set. Otherwise, it is optional.
-f Forces the creation of the resource profile, even if a profile of the
the same name already exists. If the profile already exists, the
caa_profile command moves the existing profile to a file with a .bak
suffix.
-q Runs the command in quiet mode; no messages are displayed on the
console.
To create a resource profile from a resource profile template:
-create resource_name
Creates a resource profile from the indicated resource profile
template. All values in the profile come from the values in the
template except for the resource name and the action script value. A
resource_name is a string containing
a combination of characters [a-z, A-Z, 0-9, '.','_']. The resource
name may not start with a period (.). The maxmimum length for a
resource name is 128 characters.
Resource profiles are created in the /var/cluster/caa/profile
directory.
-I template_file
Specifies the location of the resource profile template file from which
the caa_profile command is to create the resource profile. If a full
path is not specified, the command will try to find the file in
/var/cluster/caa/profile/template. Use the -template option to the
caa_profile command to create a profile template file.
-f Forces the creation of the resource profile, even if a profile of the
same name already exists. If the profile already exists, the
caa_profile command moves the existing profile to a file with a .bak
suffix.
-q Runs the command in quiet mode; no messages are displayed on the
console.
To create a resource profile template:
-template -t resource_type
Creates a resource template for the specified resource type
(application tape, changer or network).
-template resource_name
Creates a resource template from the specified resource profile. CAA
looks for the resource profile in the /var/cluster/caa/profile
directory.
-O template-file
Name of the profile template file to be created. CAA writes this file
to the local directory. You can edit the template file and later use it
to create resource profiles using a minimal number of caa_profile
command-line options.
If you do not specify the -O option, caa_profile uses template.cap as
the name of the profile template file.
To update a resource profile:
-update resource_name
Updates the resource profile indicated by resource_name. CAA looks for
the resource profile in the /var/cluster/caa/profile directory. To
prevent inconsistencies across cluster members, or between boot
sessions of the same cluster member, use the caa_register -u command
immediately after the caa_profile -update command. This will cause the
changes to take place immediately.
[option [...]]
Specifies the list of options to be updated.
You cannot update the resource name or resource type for any type of
resource. You cannot update the subnet address of a network resource.
You can update:
-a action_script
Changes to the action script location and contents take
effect the next time CAA uses the script.
-d description
Changes to the description take place immediately.
-h hosting_members
Changes to the hosting members list take place the next time
the placement policy is executed.
-r required_resources
Changes to the required resource list take place the next
time the placement policy is executed.
-l optional_resources
Changes to the optional resource list take place the next
time the placement policy is executed.
-p placement_policy
Changes to the placement policy take place the next time the
placement policy is executed.
-attribute_flag attribute_value
User-defined attributes defined in the application.tdf file
can have their value in the profile updated using the user-
defined attribute flag. For more information on user-defined
attributes see caa(4). Changes to user-defined attribute
values take place the next execution of the action script.
-o option[,...]
st=script_timeout -- Changes to script timeout take effect
the next time an action script is executed.
ap=active_placement -- Changes to active placement take
effect immediately.
as=auto_start -- Changes to auto-start take effect after the
next cluster reboot.
ci=check_interval -- Changes to the check interval take
effect immediately and reset the check interval timer.
ft=failure_threshold -- Changes to the failure threshold take
effect immediately.
fi=failure_interval -- Changes to the failure interval take
effect immediately.
ra=restart_attempts -- Changes to the restart attempts take
place the next time the failover policy is executed.
fd=failover_delay -- Changes to the failover delay take
effect immediately.
[-q]
Runs the command in quiet mode; no messages are displayed on the
console.
To delete a resource profile and its associated action script:
-delete resource_name
Deletes the resource profile indicated by resource_name. CAA looks for
the resource profile in the /var/cluster/caa/profile directory. You
cannot delete the profile of a resource that is running, or the profile
of a resource upon which active resources depend. Resources must not be
registered in order to be deleted.
[-q]
Runs the command in quiet mode; no messages are displayed on the
console.
To list one or more resource profiles:
-print [resource_name [...]]
Prints the contents of the profiles corresponding to the resource_name
list. Separate each resource_name with a space. If you do not specify a
resource_name, caa_profile lists the contents of all profiles. CAA
looks for the resource profiles in the /var/cluster/caa/profile
directory.
[-q]
Runs the command in quiet mode; no messages are displayed on the
console.
To validate a resource profile:
-validate resource_name
Validates the syntax of the resource profile indicated by
resource_name. CAA looks for the resource profile in the
/var/cluster/caa/profile directory.
[-q]
Runs the command in quiet mode; no messages are displayed on the
console.
DESCRIPTION
The caa_profile command creates new resource profiles and validates,
updates, deletes, or lists existing ones.
A resource profile assigns values to attributes that define how a resource
should be managed or monitored in a cluster. Profiles are written to the
/var/cluster/caa/profile directory by caa_profile. Values in the profile
that are left blank are ignored and may be omitted if not required for the
resource type. Omitted profile variables that are required for a resource
type will cause validation and/or registration to fail.
After you have created a resource profile and registered the resource with
CAA using the caa_register command, you can use other CAA commands (such as
caa_stat, caa_start, caa_stop, caa_relocate and caa_unregister) on the
resource. Resources must be registered using the caa_register command
before the other CAA commands are available to manage the resource.
The caa_profile command may have other options available for defining
user-defined attributes in a profile. The other options possible are
defined in the /var/cluster/caa/template/[type].tdf files. These options
can be used with the -create flag or the -update flag. For details on
user-defined attributes, see caa(4).
EXAMPLES
1. The following example creates an application resource:
/usr/sbin/caa_profile -create xclock -t application -B /usr/bin/X11/xclock
-p favored -d "xclock application" -h "skydiving" -r network1
-a xclock.scr -o ci=5,ft=2,fi=12
2. The following example shows the contents of the application resource
profile created by the previous example:
NAME=xclock
TYPE=application
ACTION_SCRIPT=xclock.scr
ACTIVE_PLACEMENT=0
AUTO_START=0
CHECK_INTERVAL=5
DESCRIPTION=xclock application
FAILOVER_DELAY=0
FAILURE_INTERVAL=12
FAILURE_THRESHOLD=2
HOSTING_MEMBERS=skydiving
OPTIONAL_RESOURCES=
PLACEMENT=favored
REQUIRED_RESOURCES=network1
RESTART_ATTEMPTS=1
SCRIPT_TIMEOUT=60
3. The following example creates an application resource, including a
user-defined attribute. This will succeed only if the user-defined
attribute with a flag -o d was previously defined in the application
type definition file. For more information see caa(4):
/usr/sbin/caa_profile -create xclock -t application -B /usr/bin/X11/xclock
-o d=true
4. The following example creates a profile for a network resource. The
network is the bitwise AND of the IP address and the netmask. If you
consider IP address of 16.69.225.12 and a netmask of 255.255.255.0 the
subnet will be 16.69.225.0:
/usr/sbin/caa_profile -create network1 -t network -s 16.69.225.0
5. The following shows the contents of the profile created by the
previous example:
TYPE=network
NAME=ln0
DESCRIPTION=network1
FAILURE_INTERVAL=0
FAILURE_THRESHOLD=0
SUBNET=16.69.225.0
EXIT VALUES
The following exit values are returned:
0 Successful completion.
non-zero 0
A failure has occurred.
FILES
/usr/sbin/caa_profile
Executable file
/var/cluster/caa/profile
Location of profile files
/var/cluster/caa/script
Location of action script files
SEE ALSO
Commands: caa_stat(1), caa_register(8), caa_unregister(8), caa_start(8),
caa_stop(8), caa_relocate(8)
Daemon: caad(8)
File: caa(4)
TruCluster Server Cluster Administration
|
Index for
Section 8 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|