mksensor Command

Purpose

Defines a sensor or a microsensor to the resource monitoring and control (RMC) subsystem.

Syntax

To define a sensor:

mksensor [ –n host1[,host2…] | –N { node_file | "–" } ] [ –i seconds ] [ –c n ] [ –e 0 | 1 | 2 ] [ –u user-ID ] [–h] [ –v | –V ] sensor_name ["]sensor_command["]

To define a microsensor:

mksensor -m [ –n host1[,host2…] | –N { node_file | "–" } ] [ –i seconds ] [–h] [ –v | –V ] microsensor_name microsensor_module [ ["]microsensor_arguments["] ]

Description

The mksensor command defines a sensor resource to the resource monitoring and control (RMC) subsystem. A sensor is an RMC resource with attributes that you can monitor. You can use the event-response resource manager (ERRM) commands to set up monitoring of the sensor attributes. The response actions defined will run when a monitored sensor event occurs. This enables administrators to extend RMC monitoring capabilities without having to write a resource manager.

For sensors, the sensor_command parameter specifies the command or script that the sensor resource manager will run to set (and then later, update) the sensor attribute values. After the sensor attributes have been monitored, the sensor resource manager sets the attribute values. Then, at defined intervals, the sensor resource manager updates these values.

For microsensors, the microsensor_module parameter specifies the path name to the loadable module that the microsensor resource manager will call to set (and then later, update) the microsensor attribute values. After the microsensor attributes have been monitored, the microsensor resource manager sets the attribute values. Then, at defined intervals, the microsensor resource manager updates these values. Use the -m flag to create a microsensor.

Alternatively, you can use chsensor or refsensor to update the sensor or microsensor attribute values. The lssensor command displays values for sensor or microsensor attributes that you can set using a sensor command or a microsensor module, if the attributes are monitored. If the attributes are not monitored, lssensor does not display their values. To remove a sensor or a microsensor, use the rmsensor command.

The mksensor command runs on any node. To define a sensor or a microsensor on one or more nodes in a management domain or a peer domain, use the -n flag. Instead of specifying multiple node names using the -n flag, you can use the -N node_file flag to indicate that the node names are in a file. Use -N "–" to read the node names from standard input.

If Cluster Systems Management (CSM) is installed on your system, you can use CSM defined node groups as node name values to refer to more than one node. For information about working with CSM node groups and using the CSM nodegrp command, see the CSM: Administration Guide and the CSM: Command and Technical Reference.

A sensor consists of the following attributes, which can be set using a sensor command: :

Float32: The type float32 attribute for this sensor resource.
Float64: The type float64 attribute for this sensor resource.
Int32: The type int32 attribute for this sensor resource.
Int64: The type int64 attribute for this sensor resource.
Quantum: The type quantum attribute for this sensor resource.
String: The type string attribute for this sensor resource.
Uint32: The type uint32 attribute for this sensor resource.
Uint64: The type uint64 attribute for this sensor resource.

A sensor command sets attribute values by sending the values to standard output in a format that the sensor resource manager can parse. The format is attr=value. For example, if the sensor command sets the Int32 attribute to 57, it writes Int32=57 to standard output. To set more than one attribute value, the sensor command can write multiple attr=value pairs to standard output. The attr=value pairs can be on one or more lines. If the sensor command output is not in attr=value form, it is assumed to be a string and the value is placed in the String attribute.

The sensor command runs using the user ID that creates the sensor resource. Once a sensor resource is monitored, the sensor command is run at intervals specified by the -i flag, which is expressed in seconds. The default interval is 60 seconds. Specify a value of 0 to indicate that the sensor command is not to run at intervals. In this case, the refsensor command is typically used to update the sensor values.

Use the -e flag to control how the exit values from sensor_command are interpreted. Depending on this setting, when the exit value of the sensor_command is considered to be an error, the sensor attributes are not set and information is written to the audit log.

A microsensor consists of the following attributes, which can be set using a microsensor load module:

Float32: The type float32 attribute for this microsensor resource
Float32Array: The type float32 array attribute for this microsensor resource
Float64: The type float64 attribute for this microsensor resource
Float64Array: The type float64 array attribute for this microsensor resource
Int32: The type int32 attribute for this microsensor resource
Int32Array: The type int32 array attribute for this microsensor resource
Int64: The type int64 attribute for this microsensor resource
Int64Array: The type int64 array attribute for this microsensor resource
Quantum: The type quantum attribute for this microsensor resource.
String: The type string attribute for this microsensor resource.
StringArray: The type string array attribute for this microsensor resource.
UInt32: The type uint32 attribute for this microsensor resource.
UInt32Array: The type uint32 array attribute for this microsensor resource.
UInt64: The type uint64 attribute for this microsensor resource.
UInt64Array: The type uint64 array attribute for this microsensor resource.

The microsensor resource manager will make calls to the microsensor load module to set the values of the microsensor attributes. See the Administering RSCT for information about how to use microsensors.

Flags

–m

Specifies that the resource to be defined is a microsensor resource.

–n host1[,host2…]

Specifies one or more nodes on which the sensor should be defined. By default, the sensor is defined on the local node. This flag is only appropriate in a management domain or a peer domain.

–N { node_file | "–" }

Specifies that node names are read from a file or from standard input.

Use -N node_file to indicate that the node names are in a file.

There is one node name per line in node_file
A number sign (#) in column 1 indicates that the line is a comment
Any blank characters to the left of a node name are ignored
Any characters to the right of a node name are ignored

Use -N "–" in a management domain or a peer domain to read the node names from standard input.

–i seconds

Specifies the interval at which a sensor command is run to update a sensor's attribute values or a microsensor module is run to update a microsensor's attribute valuesyup. seconds, which is an integer value, must be greater than or equal to 10. The default interval is 60 seconds.

The sensor command is run at the specified interval only when the sensor resource is monitored. The microsensor module is run at the specified interval only when the microsensor resource is monitored. If the interval is set to 0, the sensor command or microsensor module will not run automatically.

Using this flag is independent of using the refsensor command to refresh a sensor.

–c n

Specifies whether special handling is required for this sensor. n can be one of these values:

0: Indicates that no special handling is required. This is the default.
The sensor command will run at the interval that is defined for sensor_name. The sensor command will not run when monitoring begins or when the lssensor command is run.
1: Indicates that the sensor command will run when monitoring begins. The sensor command will also run at the interval that is defined for sensor_name. The sensor command will not run when the lssensor command is run.
Specfiying this value is not recommended, unless you expect the sensor command to run quickly. If the sensor command does not run quickly, it could block other requests to the sensor resource manager. These requests will not be processed until the sensor command finishes running.
2: Indicates that output from the command in the SavedData field is not saved permanently to SavedData persistent resource attributes. If this value is not specified, the sensor resource manager updates data in the registry's resource table whenever the command's standard output contains the line: SavedData="any-string".
3: Indicates a combination of values 1 and 2.
4: Indicates that the sensor resource manager will run the sensor command after monitoring has stopped.
5: Indicates a combination of values 1 and 4.
6: Indicates a combination of values 2 and 4.
7: Indicates a combination of values 1, 2, and 4.

–e 0 | 1 | 2

Specifies how the sensor resource manager interprets the exit values of sensor_command, as follows:

0: No exit value from sensor_command is an error.
1: An exit value other than 0 from sensor_command is an error.
2: An exit value of 0 from sensor_command is an error.

The default value is 1. The sensor attributes are not updated when the exit value is interpreted as an error. For an error, information is written to the audit log.

–u user-ID

Specifies the name of a user whose privileges will be used to run the sensor command. The user should already be defined on the system. The default value for user-ID is the user name that is associated with the current effective user ID.

–h

Writes the command's usage statement to standard output.

–v | –V

Writes the command's verbose messages to standard output.

Parameters

["]microsensor_argument["]

Specifies a string that will be passed to the microsensor module callback function. The microsensor resource manager will break the string into an array of strings based on blank characters in the microsensor argument. The microsensor argument cannot be changed once the microsensor is defined.

If the microsensor argument contains any blank characters or any special characters that can be interepreted by the shell, it must be enclosed in double quotation marks. When the microsensor argument is enclosed in double quotation marks, you must include a backslash escape character (\) before an "inner" double quotation mark. You must also include a \ before a dollar sign ($).

microsensor_module

Specifies the path name to the loadable microsensor module. A signature for the module is stored by the microsensor resource manager and is verified when the module is used. The microsensor module cannot be changed once the microsensor is defined.

microsensor_name

Specifies the name of the microsensor that is to be defined.

["]sensor_command["]

Specifies a command or script that the sensor resource manager will use to set the attribute values of the sensor. You should not call any of the sensor resource manager commands (chsensor, lssensor, mksensor, refsensor, or rmsensor) as part of this parameter.

If sensor_command contains any blank characters, or any special characters that can be interpreted by the shell, it must be enclosed in double quotation marks.

When sensor_command is enclosed in double quotation marks, you must include a backslash escape character (\) before an "inner" double quotation mark. You must also include a \ before a dollar sign ($). See Example 2 for more information.

sensor_name

Specifies the name of the sensor that is to be defined.

Security

To create sensors using this command, you need write permission for the IBM.Sensor resource class.

To create microsensors using this command, you need write permission for the IBM.MicroSensor resource class.

Permissions are specified in the access control list (ACL) file on the contacted system. See the Administering RSCT for details on the ACL file and how to modify it.

Exit Status

0: The command has run successfully.
1: An incorrect combination of flags and parameters has been entered.
n: Based on other errors that can be returned by the RMC subsystem.

Environment Variables

CT_CONTACT

When the CT_CONTACT environment variable is set to a host name or IP address, the command contacts the resource monitoring and control (RMC) daemon on the specified host. If this environment variable is not set, the command contacts the RMC daemon on the local system where the command is being run. The resource class or resources that are displayed or modified by the command are located on the system to which the connection is established.

CT_IP_AUTHENT

When the CT_IP_AUTHENT environment variable exists, the RMC daemon uses IP-based network authentication to contact the RMC daemon on the system that is specified by the IP address to which the CT_CONTACT environment variable is set. CT_IP_AUTHENT only has meaning if CT_CONTACT is set to an IP address; it does not rely on the domain name system (DNS) service.

CT_MANAGEMENT_SCOPE

Determines the management scope that is used for the session with the RMC daemon to monitor and control the resources and resource classes. The management scope determines the set of possible target nodes where the resources and resource classes can be monitored and controlled.

The valid values are:

0: Specifies local scope.
1: Specifies local scope.
2: Specifies peer domain scope.
3: Specifies management domain scope.

If this environment variable is not set, local scope is used.

Restrictions

You should not call any of the sensor resource manager commands (chsensor, lssensor, mksensor, refsensor, or rmsensor) as part of the sensor_command parameter, as this could cause a deadlock.

Implementation Specifics

This command is part of the rsct fileset for the AIX® operating system and rsct-3.1.0.0-0.platform.rpm package for the Linux®, Solaris, and Windows platforms, where platform is i386, ppc, ppc64, s390, or x86_64.

Examples

To create a new sensor called Sensor1 that runs the script /usr/bin/updateSensor1, which will update the sensor attributes every 30 seconds (once monitored), enter:

mksensor -i 30 Sensor1 "/usr/bin/updateSensor1"

The contents of /usr/bin/updateSensor1 may be like:

#!/usr/bin/perl
my $int32 = some_fn_that_generates_i32_value;
my $string = some_fn_that_generates_string_value;
print "Int32=$int32 String=$string";
exit 0;

A sample condition could be:

mkcondition -r IBM.Sensor -s "Name==Sensor1" -e "Int32 > 100" Sensor1Int32

Using the response "E-mail root anytime", a start monitoring command may be:

startcondresp Sensor1Int32 "E-mail root anytime"

To create a sensor called Sensor1 with a sensor_command value of
df -m /var | sed '1d' | sed 's/%//g' | /bin/awk '{ print "Int32="$4}',
enter:
```
mksensor Sensor1 "df -m /var | sed '1d' | sed 's/%//g' | /bin/awk \ 
'{ print \"Int32=\"\$4}'"
```
When sensor_command is enclosed in double quotation marks, you must include a backslash escape character (\) before an "inner" double quotation mark. You must also include a \ before a dollar sign ($). So in this example, the sensor command substring "Int32="$4 becomes \"Int32=\"\$4 when it is part of mksensor command.
To create a sensor called Sensor3 that runs the /usr/bin/checkhealth script on the nodes that are listed in the /u/joe/common_nodes file, enter:
```
mksensor -N /u/joe/common_nodes Sensor3 "/usr/bin/checkhealth"
```
where /u/joe/common_nodes contains:
```
# common node file
#
node1.myhost.com    main node
node2.myhost.com    backup node
```
To create a microsensor called IBM.msensorq that uses the shared module /usr/lib/msensors/msensorq and requires the parameters db=abc, confirm=yes, retry=yes, and mirror=no, enter:
```
mksensor -m IBM.msensorq /usr/lib/msensors/msensorq \ 
"db=abc confirm=yes retry=yes mirror=no"
```

Location

/opt/rsct/bin/mksensor