Maintanance Commands vxamfcmd(1M)
vxamfcmd(1M)
NAME
vxamfcmd - Command line interface to the Asynchronous Monitoring
Framework (VxAMF).
SYNOPSIS
/opt/VRTSamf/vxamfcmd subcommand [ subcommand_options ]
DESCRIPTION
The vxamfcmd command line interface (CLI) provides script based
agents a similar level of functionality available to C/C++ agents
that uses the VxAMF library API (see vxamf_intro(3VXAMF)).
The VxAMF framework consists of reaper objects (which can relate to a
clustering agent, for example) with an associated set of registered
resource objects of interest that are being monitored for changes in
their states. The resource objects may be sub-divided into groups,
allowing action such as un-registration to be performed on a per group
basis.
The CLI itself is built on top of the VxAMF library API.
SUBCOMMANDS
The following subcommands are supported:
init -reaper_name <name> -reaper_pid <pid>
The init subcommand initializies a new reaper object for
monitoring resource objects. This subcommand must be invoke
prior to any attempt to register or monitor resources.
-reaper_name The name of the reaper object. This name must be a
unique name having a maximum length of 63 characters
or less.
-reaper_pid The ID of the process representing the reaper. The
pid does not necessary have to belong to the caller,
but it must be for a valid, existing process, and must
be unique (not already part of another reaper’s
initialization). Also, the pid cannot belong to that
of a kernel level process. Otherwise no other test
is performed for the validity of the pid.
When the reaper process terminates, all supporting
system resources allocated will be automatically
freed. Note: If user passes in a pid belonging to
a process which has no intention to terminate, for
example a system daemon, the user will need to
explicitly de-initialize the reaper in order for
the VxAMF framework to remove any associated data.
The following are the exit values for the init subcommand:
0 Successful initialization
1 An invalid or missing reaper name or process ID arguments
2 The reaper named exists, or the process ID has already been
initialized for another reaper.
3 User must have super-user permission
4 Encountered an error which prevented initialization
deinit -reaper_name <name>
The deinit subcommand removes and frees any data associated with
the named reaper, including any registered resource objects. Any
user waiting for notification will returned back with an exit
value indicating the cancellation of the notification (see the
getnotification subcommand below).
-reaper_name The name of the reaper.
The following are the exit values for the deinit subcommand:
0 Successful de-initialization
1 An invalid or missing reaper name argument
2 An non-existent reaper name
3 User must have super-user permission
4 Encountered an error which prevented de-initialization
register -reaper_name <name> [ -group_name <name> ]
-restype <resource_type>
-resstate <monitoring_type>
-resattr <attributes_list>
The register subcommand registers a resource object for monitoring.
-reaper_name The name of the reaper this resource object will be
registered under. The reaper must have been previously
initialized using the init subcommand.
-group_name An optional argument indicating the group in which
this resource object will be associated with. The
group name must be unique within a particular reaper,
and must have a length less than 257 characters.
This group name can be used for un-registration or in
the getnotification subcommand for aggregate operations
on resource objects.
-restype The resource types. VxAMF currently supports the
following two resource types:
process Process resources
mount Filesystem mount resources
-resstate Indicates the monitoring type. The following is supported:
online For online monitoring
offline For offline monitoring
-resattr The set of attributes associated with the resource
object. The contents of the set is resource type
specific. The attributes arguments are entered as
comma seperated name=value pairs.
The following are the defined attribute names:
For process online:
pid The ID of the process to be monitored
For process offline (only pathname is required, the
others are optional:
pathname Executable path name
argv0 Argv[0] parameter
argv Argument list
container Container name (Solaris 10 only)
projectid Project ID (Solaris 10 only)
uid User ID
euid Effective user ID
gid Group ID
egid Effective group ID
pcv Prevention of concurrency violation
Values are "on" or "off"
For mount online and offline:
blockdev Filesystem block device
mountpoint Mounting point directory
fstype The filesystem type
container Container name (Solaris 10 only)
For mount offline:
pcv Prevention of concurrency violation.
Values are "on" or "off". This is an
optional attribute.
The attributes are verified for validity based on the
resource monitoring type. Please see the NOTES section
for vxamf_register(3VXAMF) for the requirements of each
corresponding attribute, and also for the default values
assigned to those attributes that are optional.
Upon successful registration, a unique RID integer value is returned
back via standard output. Otherwise, a (-1) is return and the exit
status indicating the error. This RID can be used for un-registration
or for identifying the event that has occur in getnotification.
The following are the exit values for the register subcommand:
0 Successful registration
1 An invalid, or non-existent reaper name
An invalid group name, resource or monitoring type
2 One or more attributes are invalid
3 A similar resource object has already been registered (e.g.
identical attributes)
4 User must have super-user permission
5 Encountered an error which prevented de-initialization
unregister -reapername <name> -groupname <name>
unregister -reapername <name> -groupname <name> -rid <RID>
unregister -reapername <name> -rid <RID>
The unregister subcommand removes and frees a resource object from
monitoring. All the data associated with the resource object within
VxAMF is destroyed.
-reaper_name The name of the reaper this resource object will be
registered under. The reaper must have been previously
initialized using the init subcommand.
-group_name An optional argument indicating the group in which
its resource objects will be un-registered. The group
name must exist within the reaper (e.g. must have
resources previously registered with that group).
-rid An optional parameter indicating the specific RID to
be un-registered. The RID msut exist as part of the
resoources registered under the reaper.
If only the group_name is given, then all resource objects in the
group is un-registeered.
If both the group_name and the RID is given, then only that resource
object corresponding to that RID is un-registered. The RID must have
been previously registered with the group name.
If only the RID is given, then only the resource object corresponding
to that RID will be unregistered, regardless of the group association.
However, the RID must registered under this reaper.
Note: After getting notification, the user must explicitly remove those
resource objects using the un-registration subcommand.
The following are the exit values for the unregister subcommand:
0 Successful un-registration
1 An invalid, or non-existent reaper, group, or RID
2 User must have super-user permission
3 Encountered an error which prevented unregistration
getnotification -reapername <name> [ -groupname <name> ]
[ -count <number> ] [ -flags <notification_flag> ]
The getnotification subcommand allows user to wait for and receive
notifications for events related to state changes for monitored
resources. The user is blocked until an event of interest occurs
(but a non-blocking flag option is available).
If the group name is given, then the getnotification only waits for
those events that are associated with that particular group. Other
events that occur are queued until an appropriate getnotification is
invoked.
-reaper_name The name of the reaper whose resource objects are to
be waited on for state changes. The reaper must have
been previously initialized using the init subcommand.
-group_name An optional argument indicating a particular group in
which the resource objects are associated with. The
group name must exist within the reaper (e.g. must have
resources previously registered with that group). If not
given, all the resources registered under the reaper will
be considered.
-count A integer value indicating the maximum number of events
that can be return. If not given, the default is 1.
-flag Passes notification value options to VxAMF. Currently,
The following flag value is supported:
noblock For non-blocking getnotifications. If there are
no events of interest, the notification call
returns immediately and no output is printed on
the standard out. This flag option can be used
to peek into VxAMF for events.
Upon successful return, up to the maximum number of events are printed
to the standard output, one line per event, and in the following
colon seperated format:
<RID>:group_name:restype:resstate
For example, event with RID 100, group Ora1, process resource, and
online monitoring:
100:Ora1:process:online
Another example for a event with RID 200, no group association,
mount resource type, and offline monitoring:
200::mount:offline
Future releases may add additional event details.
The following are the exit values for the getnotification subcommand:
0 Successful notification
1 An invalid argument (reaper, group, count or flags parameter)
2 Getnotification was canceled due to deinitialization
3 User must have super-user permission
4 Encountered an error which prevented de-initialization
EXAMPLE USAGE
The following is a simple shell script example:
#!/usr/bin/sh
name=$0
reaper=$1
pid=$2
#
# Initialize the reaper
#
vxamfcmd init -reaper_name $reaper -reaper_pid=$pid
if [ $? -ne 0 ]
then
echo "$name: initialization failed for reaper $reaper with error $?"
exit -1
fi
#
# Register pids for monitoring
#
cnt=0
monitor_pids=‘ps -e | grep OraTest | grep -v grep | awk ’{ print $1 }’‘
for i in $monitor_pids
do
rid$cnt=‘vxamfcmd register -reaper_name $reaper -group_name OraTest
-restype process -resstate online -resattr pid=$i‘
if [ $? -ne 0 ]
then
echo "$name: registration failed for pid $i with error $?"
exit -1
fi
cnt=‘expr $cnt + 1‘
done
#
# Wait for notifications.
#
events=‘vxamfcmd -getnotification -group_name OraTest‘
if [ $? -ne 0 ]
then
echo "$name: getnotification failed with error $?"
exit -1
fi
#
# Go through the events and unregister each resource object
#
rids=‘echo $events | cut -d’:’ -f1‘
for i in $rids
do
echo "$name: event with RID $i has occurred"
vxamfcmd -unregister -group_name OraTest -rid $i
if [ $? -ne 0 ]
then
echo "$name: un-registration failed for RID $i with error $?"
exit -1
fi
done
SEE ALSO
vxamf_init(3VXAMF), vxamf_deinit(3VXAMF), vxamf_register(3VXAMF)
vxamf_unregister(3VXAMF), vxamf_getnotification(3VXAMF)
Copyright (c) 2016 Veritas.